System.Data.SQLite
Hex Artifact Content
Not logged in

Artifact 2028b13918440cb3ca6444cd68e7fbb02300155f:


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 32 2e 20 20 42  ersion 3.8.2.  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 32  ON        "3.8.2
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 32 0a 23 64 65 66 69 6e 65 20  3008002.#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 31 2d 31        "2014-01-1
1630: 35 20 30 30 3a 32 34 3a 32 32 20 63 36 39 37 64  5 00:24:22 c697d
1640: 32 66 38 33 63 32 64 38 65 61 30 61 31 30 30 62  2f83c2d8ea0a100b
1650: 38 34 62 30 64 65 62 62 36 61 33 32 32 63 33 61  84b0debb6a322c3a
1660: 38 37 36 22 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  876"../*.** 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 41 42 4f 52 54 5f  ne SQLITE_ABORT_
5fd0: 52 4f 4c 4c 42 41 43 4b 20 20 20 20 20 20 20 20  ROLLBACK        
5fe0: 20 20 28 53 51 4c 49 54 45 5f 41 42 4f 52 54 20    (SQLITE_ABORT 
5ff0: 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (2<<8)).#defin
6000: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
6010: 49 4e 54 5f 43 48 45 43 4b 20 20 20 20 20 20 20  INT_CHECK       
6020: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
6030: 49 4e 54 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64  INT | (1<<8)).#d
6040: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
6050: 53 54 52 41 49 4e 54 5f 43 4f 4d 4d 49 54 48 4f  STRAINT_COMMITHO
6060: 4f 4b 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e  OK   (SQLITE_CON
6070: 53 54 52 41 49 4e 54 20 7c 20 28 32 3c 3c 38 29  STRAINT | (2<<8)
6080: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
6090: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46 4f 52 45  _CONSTRAINT_FORE
60a0: 49 47 4e 4b 45 59 20 20 20 28 53 51 4c 49 54 45  IGNKEY   (SQLITE
60b0: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 33  _CONSTRAINT | (3
60c0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
60d0: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
60e0: 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 28 53 51  FUNCTION     (SQ
60f0: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
6100: 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (4<<8)).#defin
6110: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
6120: 49 4e 54 5f 4e 4f 54 4e 55 4c 4c 20 20 20 20 20  INT_NOTNULL     
6130: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
6140: 49 4e 54 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64  INT | (5<<8)).#d
6150: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
6160: 53 54 52 41 49 4e 54 5f 50 52 49 4d 41 52 59 4b  STRAINT_PRIMARYK
6170: 45 59 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e  EY   (SQLITE_CON
6180: 53 54 52 41 49 4e 54 20 7c 20 28 36 3c 3c 38 29  STRAINT | (6<<8)
6190: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
61a0: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 54 52 49 47  _CONSTRAINT_TRIG
61b0: 47 45 52 20 20 20 20 20 20 28 53 51 4c 49 54 45  GER      (SQLITE
61c0: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 37  _CONSTRAINT | (7
61d0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
61e0: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
61f0: 55 4e 49 51 55 45 20 20 20 20 20 20 20 28 53 51  UNIQUE       (SQ
6200: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
6210: 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (8<<8)).#defin
6220: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
6230: 49 4e 54 5f 56 54 41 42 20 20 20 20 20 20 20 20  INT_VTAB        
6240: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
6250: 49 4e 54 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64  INT | (9<<8)).#d
6260: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
6270: 53 54 52 41 49 4e 54 5f 52 4f 57 49 44 20 20 20  STRAINT_ROWID   
6280: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e       (SQLITE_CON
6290: 53 54 52 41 49 4e 54 20 7c 28 31 30 3c 3c 38 29  STRAINT |(10<<8)
62a0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
62b0: 5f 4e 4f 54 49 43 45 5f 52 45 43 4f 56 45 52 5f  _NOTICE_RECOVER_
62c0: 57 41 4c 20 20 20 20 20 20 28 53 51 4c 49 54 45  WAL      (SQLITE
62d0: 5f 4e 4f 54 49 43 45 20 7c 20 28 31 3c 3c 38 29  _NOTICE | (1<<8)
62e0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
62f0: 5f 4e 4f 54 49 43 45 5f 52 45 43 4f 56 45 52 5f  _NOTICE_RECOVER_
6300: 52 4f 4c 4c 42 41 43 4b 20 28 53 51 4c 49 54 45  ROLLBACK (SQLITE
6310: 5f 4e 4f 54 49 43 45 20 7c 20 28 32 3c 3c 38 29  _NOTICE | (2<<8)
6320: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
6330: 5f 57 41 52 4e 49 4e 47 5f 41 55 54 4f 49 4e 44  _WARNING_AUTOIND
6340: 45 58 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  EX       (SQLITE
6350: 5f 57 41 52 4e 49 4e 47 20 7c 20 28 31 3c 3c 38  _WARNING | (1<<8
6360: 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  ))../*.** CAPI3R
6370: 45 46 3a 20 46 6c 61 67 73 20 46 6f 72 20 46 69  EF: Flags For Fi
6380: 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61 74 69 6f  le Open Operatio
6390: 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 62  ns.**.** These b
63a0: 69 74 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e  it values are in
63b0: 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69  tended for use i
63c0: 6e 20 74 68 65 0a 2a 2a 20 33 72 64 20 70 61 72  n the.** 3rd par
63d0: 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ameter to the [s
63e0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
63f0: 5d 20 69 6e 74 65 72 66 61 63 65 20 61 6e 64 0a  ] interface and.
6400: 2a 2a 20 69 6e 20 74 68 65 20 34 74 68 20 70 61  ** in the 4th pa
6410: 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b  rameter to the [
6420: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65  sqlite3_vfs.xOpe
6430: 6e 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 23 64  n] method..*/.#d
6440: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
6450: 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 20  N_READONLY      
6460: 20 20 20 30 78 30 30 30 30 30 30 30 31 20 20 2f     0x00000001  /
6470: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33  * Ok for sqlite3
6480: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64  _open_v2() */.#d
6490: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
64a0: 4e 5f 52 45 41 44 57 52 49 54 45 20 20 20 20 20  N_READWRITE     
64b0: 20 20 20 30 78 30 30 30 30 30 30 30 32 20 20 2f     0x00000002  /
64c0: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33  * Ok for sqlite3
64d0: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64  _open_v2() */.#d
64e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
64f0: 4e 5f 43 52 45 41 54 45 20 20 20 20 20 20 20 20  N_CREATE        
6500: 20 20 20 30 78 30 30 30 30 30 30 30 34 20 20 2f     0x00000004  /
6510: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33  * Ok for sqlite3
6520: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64  _open_v2() */.#d
6530: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
6540: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 20  N_DELETEONCLOSE 
6550: 20 20 20 30 78 30 30 30 30 30 30 30 38 20 20 2f     0x00000008  /
6560: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64  * VFS only */.#d
6570: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
6580: 4e 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 20  N_EXCLUSIVE     
6590: 20 20 20 30 78 30 30 30 30 30 30 31 30 20 20 2f     0x00000010  /
65a0: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64  * VFS only */.#d
65b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
65c0: 4e 5f 41 55 54 4f 50 52 4f 58 59 20 20 20 20 20  N_AUTOPROXY     
65d0: 20 20 20 30 78 30 30 30 30 30 30 32 30 20 20 2f     0x00000020  /
65e0: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64  * VFS only */.#d
65f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
6600: 4e 5f 55 52 49 20 20 20 20 20 20 20 20 20 20 20  N_URI           
6610: 20 20 20 30 78 30 30 30 30 30 30 34 30 20 20 2f     0x00000040  /
6620: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33  * Ok for sqlite3
6630: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64  _open_v2() */.#d
6640: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
6650: 4e 5f 4d 45 4d 4f 52 59 20 20 20 20 20 20 20 20  N_MEMORY        
6660: 20 20 20 30 78 30 30 30 30 30 30 38 30 20 20 2f     0x00000080  /
6670: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33  * Ok for sqlite3
6680: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64  _open_v2() */.#d
6690: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
66a0: 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20 20 20 20  N_MAIN_DB       
66b0: 20 20 20 30 78 30 30 30 30 30 31 30 30 20 20 2f     0x00000100  /
66c0: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64  * VFS only */.#d
66d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
66e0: 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20 20 20 20  N_TEMP_DB       
66f0: 20 20 20 30 78 30 30 30 30 30 32 30 30 20 20 2f     0x00000200  /
6700: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64  * VFS only */.#d
6710: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
6720: 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 20 20  N_TRANSIENT_DB  
6730: 20 20 20 30 78 30 30 30 30 30 34 30 30 20 20 2f     0x00000400  /
6740: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64  * VFS only */.#d
6750: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
6760: 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20 20  N_MAIN_JOURNAL  
6770: 20 20 20 30 78 30 30 30 30 30 38 30 30 20 20 2f     0x00000800  /
6780: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64  * VFS only */.#d
6790: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
67a0: 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20 20  N_TEMP_JOURNAL  
67b0: 20 20 20 30 78 30 30 30 30 31 30 30 30 20 20 2f     0x00001000  /
67c0: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64  * VFS only */.#d
67d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
67e0: 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 20 20 20 20  N_SUBJOURNAL    
67f0: 20 20 20 30 78 30 30 30 30 32 30 30 30 20 20 2f     0x00002000  /
6800: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64  * VFS only */.#d
6810: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
6820: 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c  N_MASTER_JOURNAL
6830: 20 20 20 30 78 30 30 30 30 34 30 30 30 20 20 2f     0x00004000  /
6840: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64  * VFS only */.#d
6850: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
6860: 4e 5f 4e 4f 4d 55 54 45 58 20 20 20 20 20 20 20  N_NOMUTEX       
6870: 20 20 20 30 78 30 30 30 30 38 30 30 30 20 20 2f     0x00008000  /
6880: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33  * Ok for sqlite3
6890: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64  _open_v2() */.#d
68a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
68b0: 4e 5f 46 55 4c 4c 4d 55 54 45 58 20 20 20 20 20  N_FULLMUTEX     
68c0: 20 20 20 30 78 30 30 30 31 30 30 30 30 20 20 2f     0x00010000  /
68d0: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33  * Ok for sqlite3
68e0: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64  _open_v2() */.#d
68f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
6900: 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20  N_SHAREDCACHE   
6910: 20 20 20 30 78 30 30 30 32 30 30 30 30 20 20 2f     0x00020000  /
6920: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33  * Ok for sqlite3
6930: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64  _open_v2() */.#d
6940: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
6950: 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 20  N_PRIVATECACHE  
6960: 20 20 20 30 78 30 30 30 34 30 30 30 30 20 20 2f     0x00040000  /
6970: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33  * Ok for sqlite3
6980: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64  _open_v2() */.#d
6990: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
69a0: 4e 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20 20  N_WAL           
69b0: 20 20 20 30 78 30 30 30 38 30 30 30 30 20 20 2f     0x00080000  /
69c0: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f  * VFS only */../
69d0: 2a 20 52 65 73 65 72 76 65 64 3a 20 20 20 20 20  * Reserved:     
69e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
69f0: 20 20 20 20 30 78 30 30 46 30 30 30 30 30 20 2a      0x00F00000 *
6a00: 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
6a10: 46 3a 20 44 65 76 69 63 65 20 43 68 61 72 61 63  F: Device Charac
6a20: 74 65 72 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20  teristics.**.** 
6a30: 54 68 65 20 78 44 65 76 69 63 65 43 68 61 72 61  The xDeviceChara
6a40: 63 74 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f  cteristics metho
6a50: 64 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  d of the [sqlite
6a60: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a  3_io_methods].**
6a70: 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 73 20   object returns 
6a80: 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68  an integer which
6a90: 20 69 73 20 61 20 76 65 63 74 6f 72 20 6f 66 20   is a vector of 
6aa0: 74 68 65 73 65 0a 2a 2a 20 62 69 74 20 76 61 6c  these.** bit val
6ab0: 75 65 73 20 65 78 70 72 65 73 73 69 6e 67 20 49  ues expressing I
6ac0: 2f 4f 20 63 68 61 72 61 63 74 65 72 69 73 74 69  /O characteristi
6ad0: 63 73 20 6f 66 20 74 68 65 20 6d 61 73 73 20 73  cs of the mass s
6ae0: 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76 69 63 65  torage.** device
6af0: 20 74 68 61 74 20 68 6f 6c 64 73 20 74 68 65 20   that holds the 
6b00: 66 69 6c 65 20 74 68 61 74 20 74 68 65 20 5b 73  file that the [s
6b10: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
6b20: 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20 74 6f 2e  s].** refers to.
6b30: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54  .**.** The SQLIT
6b40: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70  E_IOCAP_ATOMIC p
6b50: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68  roperty means th
6b60: 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66  at all writes of
6b70: 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65  .** any size are
6b80: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51   atomic.  The SQ
6b90: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6ba0: 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d  Cnnn values.** m
6bb0: 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20  ean that writes 
6bc0: 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61  of blocks that a
6bd0: 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20  re nnn bytes in 
6be0: 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20  size and.** are 
6bf0: 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64  aligned to an ad
6c00: 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61  dress which is a
6c10: 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70  n integer multip
6c20: 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65  le of.** nnn are
6c30: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51   atomic.  The SQ
6c40: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f  LITE_IOCAP_SAFE_
6c50: 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61  APPEND value mea
6c60: 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20  ns.** that when 
6c70: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64  data is appended
6c80: 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20   to a file, the 
6c90: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64  data is appended
6ca0: 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74  .** first then t
6cb0: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66  he size of the f
6cc0: 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c  ile is extended,
6cd0: 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72   never the other
6ce0: 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20  .** way around. 
6cf0: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
6d00: 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f  P_SEQUENTIAL pro
6d10: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
6d20: 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  .** information 
6d30: 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69  is written to di
6d40: 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f  sk in the same o
6d50: 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a  rder as calls.**
6d60: 20 74 6f 20 78 57 72 69 74 65 28 29 2e 20 20 54   to xWrite().  T
6d70: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
6d80: 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52  POWERSAFE_OVERWR
6d90: 49 54 45 20 70 72 6f 70 65 72 74 79 20 6d 65 61  ITE property mea
6da0: 6e 73 20 74 68 61 74 0a 2a 2a 20 61 66 74 65 72  ns that.** after
6db0: 20 72 65 62 6f 6f 74 20 66 6f 6c 6c 6f 77 69 6e   reboot followin
6dc0: 67 20 61 20 63 72 61 73 68 20 6f 72 20 70 6f 77  g a crash or pow
6dd0: 65 72 20 6c 6f 73 73 2c 20 74 68 65 20 6f 6e 6c  er loss, the onl
6de0: 79 20 62 79 74 65 73 20 69 6e 20 61 0a 2a 2a 20  y bytes in a.** 
6df0: 66 69 6c 65 20 74 68 61 74 20 77 65 72 65 20 77  file that were w
6e00: 72 69 74 74 65 6e 20 61 74 20 74 68 65 20 61 70  ritten at the ap
6e10: 70 6c 69 63 61 74 69 6f 6e 20 6c 65 76 65 6c 20  plication level 
6e20: 6d 69 67 68 74 20 68 61 76 65 20 63 68 61 6e 67  might have chang
6e30: 65 64 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 61  ed.** and that a
6e40: 64 6a 61 63 65 6e 74 20 62 79 74 65 73 2c 20 65  djacent bytes, e
6e50: 76 65 6e 20 62 79 74 65 73 20 77 69 74 68 69 6e  ven bytes within
6e60: 20 74 68 65 20 73 61 6d 65 20 73 65 63 74 6f 72   the same sector
6e70: 20 61 72 65 0a 2a 2a 20 67 75 61 72 61 6e 74 65   are.** guarante
6e80: 65 64 20 74 6f 20 62 65 20 75 6e 63 68 61 6e 67  ed to be unchang
6e90: 65 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ed..*/.#define S
6ea0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
6eb0: 49 43 20 20 20 20 20 20 20 20 20 20 20 20 20 20  IC              
6ec0: 20 20 20 30 78 30 30 30 30 30 30 30 31 0a 23 64     0x00000001.#d
6ed0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
6ee0: 41 50 5f 41 54 4f 4d 49 43 35 31 32 20 20 20 20  AP_ATOMIC512    
6ef0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
6f00: 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c  0002.#define SQL
6f10: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6f20: 31 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  1K              
6f30: 20 30 78 30 30 30 30 30 30 30 34 0a 23 64 65 66   0x00000004.#def
6f40: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6f50: 5f 41 54 4f 4d 49 43 32 4b 20 20 20 20 20 20 20  _ATOMIC2K       
6f60: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6f70: 30 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  08.#define SQLIT
6f80: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b  E_IOCAP_ATOMIC4K
6f90: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
6fa0: 78 30 30 30 30 30 30 31 30 0a 23 64 65 66 69 6e  x00000010.#defin
6fb0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
6fc0: 54 4f 4d 49 43 38 4b 20 20 20 20 20 20 20 20 20  TOMIC8K         
6fd0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32 30        0x00000020
6fe0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6ff0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 20  IOCAP_ATOMIC16K 
7000: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
7010: 30 30 30 30 30 34 30 0a 23 64 65 66 69 6e 65 20  0000040.#define 
7020: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
7030: 4d 49 43 33 32 4b 20 20 20 20 20 20 20 20 20 20  MIC32K          
7040: 20 20 20 20 30 78 30 30 30 30 30 30 38 30 0a 23      0x00000080.#
7050: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
7060: 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 20 20 20  CAP_ATOMIC64K   
7070: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
7080: 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00100.#define SQ
7090: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f  LITE_IOCAP_SAFE_
70a0: 41 50 50 45 4e 44 20 20 20 20 20 20 20 20 20 20  APPEND          
70b0: 20 20 30 78 30 30 30 30 30 32 30 30 0a 23 64 65    0x00000200.#de
70c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
70d0: 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 20 20 20  P_SEQUENTIAL    
70e0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
70f0: 34 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  400.#define SQLI
7100: 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54  TE_IOCAP_UNDELET
7110: 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 20 20  ABLE_WHEN_OPEN  
7120: 30 78 30 30 30 30 30 38 30 30 0a 23 64 65 66 69  0x00000800.#defi
7130: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
7140: 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52  POWERSAFE_OVERWR
7150: 49 54 45 20 20 20 20 30 78 30 30 30 30 31 30 30  ITE    0x0000100
7160: 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  0../*.** CAPI3RE
7170: 46 3a 20 46 69 6c 65 20 4c 6f 63 6b 69 6e 67 20  F: File Locking 
7180: 4c 65 76 65 6c 73 0a 2a 2a 0a 2a 2a 20 53 51 4c  Levels.**.** SQL
7190: 69 74 65 20 75 73 65 73 20 6f 6e 65 20 6f 66 20  ite uses one of 
71a0: 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61  these integer va
71b0: 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f  lues as the seco
71c0: 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74  nd.** argument t
71d0: 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61 6b 65 73  o calls it makes
71e0: 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b 28 29 20   to the xLock() 
71f0: 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 6d 65  and xUnlock() me
7200: 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b  thods.** of an [
7210: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
7220: 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23  ds] object..*/.#
7230: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
7240: 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 20 20 20  CK_NONE         
7250: 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   0.#define SQLIT
7260: 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 20 20 20  E_LOCK_SHARED   
7270: 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
7280: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52  QLITE_LOCK_RESER
7290: 56 45 44 20 20 20 20 20 20 32 0a 23 64 65 66 69  VED      2.#defi
72a0: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50  ne SQLITE_LOCK_P
72b0: 45 4e 44 49 4e 47 20 20 20 20 20 20 20 33 0a 23  ENDING       3.#
72c0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
72d0: 43 4b 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20  CK_EXCLUSIVE    
72e0: 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52   4../*.** CAPI3R
72f0: 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69 7a 61 74  EF: Synchronizat
7300: 69 6f 6e 20 54 79 70 65 20 46 6c 61 67 73 0a 2a  ion Type Flags.*
7310: 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c 69 74 65  *.** When SQLite
7320: 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 78 53 79   invokes the xSy
7330: 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 61  nc() method of a
7340: 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f  n.** [sqlite3_io
7350: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
7360: 20 69 74 20 75 73 65 73 20 61 20 63 6f 6d 62 69   it uses a combi
7370: 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65  nation of.** the
7380: 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65  se integer value
7390: 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  s as the second 
73a0: 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
73b0: 57 68 65 6e 20 74 68 65 20 53 51 4c 49 54 45 5f  When the SQLITE_
73c0: 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 66 6c  SYNC_DATAONLY fl
73d0: 61 67 20 69 73 20 75 73 65 64 2c 20 69 74 20 6d  ag is used, it m
73e0: 65 61 6e 73 20 74 68 61 74 20 74 68 65 0a 2a 2a  eans that the.**
73f0: 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 20   sync operation 
7400: 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 66 6c  only needs to fl
7410: 75 73 68 20 64 61 74 61 20 74 6f 20 6d 61 73 73  ush data to mass
7420: 20 73 74 6f 72 61 67 65 2e 20 20 49 6e 6f 64 65   storage.  Inode
7430: 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  .** information 
7440: 6e 65 65 64 20 6e 6f 74 20 62 65 20 66 6c 75 73  need not be flus
7450: 68 65 64 2e 20 49 66 20 74 68 65 20 6c 6f 77 65  hed. If the lowe
7460: 72 20 66 6f 75 72 20 62 69 74 73 20 6f 66 20 74  r four bits of t
7470: 68 65 20 66 6c 61 67 0a 2a 2a 20 65 71 75 61 6c  he flag.** equal
7480: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52   SQLITE_SYNC_NOR
7490: 4d 41 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 20  MAL, that means 
74a0: 74 6f 20 75 73 65 20 6e 6f 72 6d 61 6c 20 66 73  to use normal fs
74b0: 79 6e 63 28 29 20 73 65 6d 61 6e 74 69 63 73 2e  ync() semantics.
74c0: 0a 2a 2a 20 49 66 20 74 68 65 20 6c 6f 77 65 72  .** If the lower
74d0: 20 66 6f 75 72 20 62 69 74 73 20 65 71 75 61 6c   four bits equal
74e0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c   SQLITE_SYNC_FUL
74f0: 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a  L, that means.**
7500: 20 74 6f 20 75 73 65 20 4d 61 63 20 4f 53 20 58   to use Mac OS X
7510: 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 20   style fullsync 
7520: 69 6e 73 74 65 61 64 20 6f 66 20 66 73 79 6e 63  instead of fsync
7530: 28 29 2e 0a 2a 2a 0a 2a 2a 20 44 6f 20 6e 6f 74  ()..**.** Do not
7540: 20 63 6f 6e 66 75 73 65 20 74 68 65 20 53 51 4c   confuse the SQL
7550: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20  ITE_SYNC_NORMAL 
7560: 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  and SQLITE_SYNC_
7570: 46 55 4c 4c 20 66 6c 61 67 73 0a 2a 2a 20 77 69  FULL flags.** wi
7580: 74 68 20 74 68 65 20 5b 50 52 41 47 4d 41 20 73  th the [PRAGMA s
7590: 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 4e 4f 52 4d  ynchronous]=NORM
75a0: 41 4c 20 61 6e 64 20 5b 50 52 41 47 4d 41 20 73  AL and [PRAGMA s
75b0: 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 46 55 4c 4c  ynchronous]=FULL
75c0: 0a 2a 2a 20 73 65 74 74 69 6e 67 73 2e 20 20 54  .** settings.  T
75d0: 68 65 20 5b 73 79 6e 63 68 72 6f 6e 6f 75 73 20  he [synchronous 
75e0: 70 72 61 67 6d 61 5d 20 64 65 74 65 72 6d 69 6e  pragma] determin
75f0: 65 73 20 77 68 65 6e 20 63 61 6c 6c 73 20 74 6f  es when calls to
7600: 20 74 68 65 0a 2a 2a 20 78 53 79 6e 63 20 56 46   the.** xSync VF
7610: 53 20 6d 65 74 68 6f 64 20 6f 63 63 75 72 20 61  S method occur a
7620: 6e 64 20 61 70 70 6c 69 65 73 20 75 6e 69 66 6f  nd applies unifo
7630: 72 6d 6c 79 20 61 63 72 6f 73 73 20 61 6c 6c 20  rmly across all 
7640: 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2a 20 54 68  platforms..** Th
7650: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f  e SQLITE_SYNC_NO
7660: 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f  RMAL and SQLITE_
7670: 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73 20  SYNC_FULL flags 
7680: 64 65 74 65 72 6d 69 6e 65 20 68 6f 77 0a 2a 2a  determine how.**
7690: 20 65 6e 65 72 67 65 74 69 63 20 6f 72 20 72 69   energetic or ri
76a0: 67 6f 72 6f 75 73 20 6f 72 20 66 6f 72 63 65 66  gorous or forcef
76b0: 75 6c 20 74 68 65 20 73 79 6e 63 20 6f 70 65 72  ul the sync oper
76c0: 61 74 69 6f 6e 73 20 61 72 65 20 61 6e 64 0a 2a  ations are and.*
76d0: 2a 20 6f 6e 6c 79 20 6d 61 6b 65 20 61 20 64 69  * only make a di
76e0: 66 66 65 72 65 6e 63 65 20 6f 6e 20 4d 61 63 20  fference on Mac 
76f0: 4f 53 58 20 66 6f 72 20 74 68 65 20 64 65 66 61  OSX for the defa
7700: 75 6c 74 20 53 51 4c 69 74 65 20 63 6f 64 65 2e  ult SQLite code.
7710: 0a 2a 2a 20 28 54 68 69 72 64 2d 70 61 72 74 79  .** (Third-party
7720: 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
7730: 69 6f 6e 73 20 6d 69 67 68 74 20 61 6c 73 6f 20  ions might also 
7740: 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e 63  make the distinc
7750: 74 69 6f 6e 0a 2a 2a 20 62 65 74 77 65 65 6e 20  tion.** between 
7760: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d  SQLITE_SYNC_NORM
7770: 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59  AL and SQLITE_SY
7780: 4e 43 5f 46 55 4c 4c 2c 20 62 75 74 20 61 6d 6f  NC_FULL, but amo
7790: 6e 67 20 74 68 65 0a 2a 2a 20 6f 70 65 72 61 74  ng the.** operat
77a0: 69 6e 67 20 73 79 73 74 65 6d 73 20 6e 61 74 69  ing systems nati
77b0: 76 65 6c 79 20 73 75 70 70 6f 72 74 65 64 20 62  vely supported b
77c0: 79 20 53 51 4c 69 74 65 2c 20 6f 6e 6c 79 20 4d  y SQLite, only M
77d0: 61 63 20 4f 53 58 0a 2a 2a 20 63 61 72 65 73 20  ac OSX.** cares 
77e0: 61 62 6f 75 74 20 74 68 65 20 64 69 66 66 65 72  about the differ
77f0: 65 6e 63 65 2e 29 0a 2a 2f 0a 23 64 65 66 69 6e  ence.).*/.#defin
7800: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f  e SQLITE_SYNC_NO
7810: 52 4d 41 4c 20 20 20 20 20 20 20 20 30 78 30 30  RMAL        0x00
7820: 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  002.#define SQLI
7830: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 20 20 20  TE_SYNC_FULL    
7840: 20 20 20 20 20 20 30 78 30 30 30 30 33 0a 23 64        0x00003.#d
7850: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e  efine SQLITE_SYN
7860: 43 5f 44 41 54 41 4f 4e 4c 59 20 20 20 20 20 20  C_DATAONLY      
7870: 30 78 30 30 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43  0x00010../*.** C
7880: 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65  API3REF: OS Inte
7890: 72 66 61 63 65 20 4f 70 65 6e 20 46 69 6c 65 20  rface Open File 
78a0: 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 41 6e 20  Handle.**.** An 
78b0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
78c0: 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73  bject represents
78d0: 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 69 6e   an open file in
78e0: 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65   the .** [sqlite
78f0: 33 5f 76 66 73 20 7c 20 4f 53 20 69 6e 74 65 72  3_vfs | OS inter
7900: 66 61 63 65 20 6c 61 79 65 72 5d 2e 20 20 49 6e  face layer].  In
7910: 64 69 76 69 64 75 61 6c 20 4f 53 20 69 6e 74 65  dividual OS inte
7920: 72 66 61 63 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65  rface.** impleme
7930: 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a  ntations will.**
7940: 20 77 61 6e 74 20 74 6f 20 73 75 62 63 6c 61 73   want to subclas
7950: 73 20 74 68 69 73 20 6f 62 6a 65 63 74 20 62 79  s this object by
7960: 20 61 70 70 65 6e 64 69 6e 67 20 61 64 64 69 74   appending addit
7970: 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a 2a 2a 20  ional fields.** 
7980: 66 6f 72 20 74 68 65 69 72 20 6f 77 6e 20 75 73  for their own us
7990: 65 2e 20 20 54 68 65 20 70 4d 65 74 68 6f 64 73  e.  The pMethods
79a0: 20 65 6e 74 72 79 20 69 73 20 61 20 70 6f 69 6e   entry is a poin
79b0: 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71  ter to an.** [sq
79c0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
79d0: 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65  ] object that de
79e0: 66 69 6e 65 73 20 6d 65 74 68 6f 64 73 20 66 6f  fines methods fo
79f0: 72 20 70 65 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20  r performing.** 
7a00: 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 6f  I/O operations o
7a10: 6e 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 2e  n the open file.
7a20: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
7a30: 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20  ct sqlite3_file 
7a40: 73 71 6c 69 74 65 33 5f 66 69 6c 65 3b 0a 73 74  sqlite3_file;.st
7a50: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c  ruct sqlite3_fil
7a60: 65 20 7b 0a 20 20 63 6f 6e 73 74 20 73 74 72 75  e {.  const stru
7a70: 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  ct sqlite3_io_me
7a80: 74 68 6f 64 73 20 2a 70 4d 65 74 68 6f 64 73 3b  thods *pMethods;
7a90: 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72    /* Methods for
7aa0: 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 2a 2f   an open file */
7ab0: 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .};../*.** CAPI3
7ac0: 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63  REF: OS Interfac
7ad0: 65 20 46 69 6c 65 20 56 69 72 74 75 61 6c 20 4d  e File Virtual M
7ae0: 65 74 68 6f 64 73 20 4f 62 6a 65 63 74 0a 2a 2a  ethods Object.**
7af0: 0a 2a 2a 20 45 76 65 72 79 20 66 69 6c 65 20 6f  .** Every file o
7b00: 70 65 6e 65 64 20 62 79 20 74 68 65 20 5b 73 71  pened by the [sq
7b10: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
7b20: 20 6d 65 74 68 6f 64 20 70 6f 70 75 6c 61 74 65   method populate
7b30: 73 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  s an.** [sqlite3
7b40: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 28 6f  _file] object (o
7b50: 72 2c 20 6d 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79  r, more commonly
7b60: 2c 20 61 20 73 75 62 63 6c 61 73 73 20 6f 66 20  , a subclass of 
7b70: 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
7b80: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 29 20 77 69  file] object) wi
7b90: 74 68 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  th a pointer to 
7ba0: 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
7bb0: 68 69 73 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54  his object..** T
7bc0: 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e  his object defin
7bd0: 65 73 20 74 68 65 20 6d 65 74 68 6f 64 73 20 75  es the methods u
7be0: 73 65 64 20 74 6f 20 70 65 72 66 6f 72 6d 20 76  sed to perform v
7bf0: 61 72 69 6f 75 73 20 6f 70 65 72 61 74 69 6f 6e  arious operation
7c00: 73 0a 2a 2a 20 61 67 61 69 6e 73 74 20 74 68 65  s.** against the
7c10: 20 6f 70 65 6e 20 66 69 6c 65 20 72 65 70 72 65   open file repre
7c20: 73 65 6e 74 65 64 20 62 79 20 74 68 65 20 5b 73  sented by the [s
7c30: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
7c40: 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ect..**.** If th
7c50: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  e [sqlite3_vfs.x
7c60: 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 73 65 74  Open] method set
7c70: 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69  s the sqlite3_fi
7c80: 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d  le.pMethods elem
7c90: 65 6e 74 20 0a 2a 2a 20 74 6f 20 61 20 6e 6f 6e  ent .** to a non
7ca0: 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74  -NULL pointer, t
7cb0: 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hen the sqlite3_
7cc0: 69 6f 5f 6d 65 74 68 6f 64 73 2e 78 43 6c 6f 73  io_methods.xClos
7cd0: 65 20 6d 65 74 68 6f 64 0a 2a 2a 20 6d 61 79 20  e method.** may 
7ce0: 62 65 20 69 6e 76 6f 6b 65 64 20 65 76 65 6e 20  be invoked even 
7cf0: 69 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  if the [sqlite3_
7d00: 76 66 73 2e 78 4f 70 65 6e 5d 20 72 65 70 6f 72  vfs.xOpen] repor
7d10: 74 65 64 20 74 68 61 74 20 69 74 20 66 61 69 6c  ted that it fail
7d20: 65 64 2e 20 20 54 68 65 0a 2a 2a 20 6f 6e 6c 79  ed.  The.** only
7d30: 20 77 61 79 20 74 6f 20 70 72 65 76 65 6e 74 20   way to prevent 
7d40: 61 20 63 61 6c 6c 20 74 6f 20 78 43 6c 6f 73 65  a call to xClose
7d50: 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69   following a fai
7d60: 6c 65 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  led [sqlite3_vfs
7d70: 2e 78 4f 70 65 6e 5d 0a 2a 2a 20 69 73 20 66 6f  .xOpen].** is fo
7d80: 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  r the [sqlite3_v
7d90: 66 73 2e 78 4f 70 65 6e 5d 20 74 6f 20 73 65 74  fs.xOpen] to set
7da0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c   the sqlite3_fil
7db0: 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65  e.pMethods eleme
7dc0: 6e 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 0a 2a  nt.** to NULL..*
7dd0: 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61  *.** The flags a
7de0: 72 67 75 6d 65 6e 74 20 74 6f 20 78 53 79 6e 63  rgument to xSync
7df0: 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66 20 5b   may be one of [
7e00: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d  SQLITE_SYNC_NORM
7e10: 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54  AL] or.** [SQLIT
7e20: 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54  E_SYNC_FULL].  T
7e30: 68 65 20 66 69 72 73 74 20 63 68 6f 69 63 65 20  he first choice 
7e40: 69 73 20 74 68 65 20 6e 6f 72 6d 61 6c 20 66 73  is the normal fs
7e50: 79 6e 63 28 29 2e 0a 2a 2a 20 54 68 65 20 73 65  ync()..** The se
7e60: 63 6f 6e 64 20 63 68 6f 69 63 65 20 69 73 20 61  cond choice is a
7e70: 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20   Mac OS X style 
7e80: 66 75 6c 6c 73 79 6e 63 2e 20 20 54 68 65 20 5b  fullsync.  The [
7e90: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41  SQLITE_SYNC_DATA
7ea0: 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 67 20 6d 61  ONLY].** flag ma
7eb0: 79 20 62 65 20 4f 52 65 64 20 69 6e 20 74 6f 20  y be ORed in to 
7ec0: 69 6e 64 69 63 61 74 65 20 74 68 61 74 20 6f 6e  indicate that on
7ed0: 6c 79 20 74 68 65 20 64 61 74 61 20 6f 66 20 74  ly the data of t
7ee0: 68 65 20 66 69 6c 65 0a 2a 2a 20 61 6e 64 20 6e  he file.** and n
7ef0: 6f 74 20 69 74 73 20 69 6e 6f 64 65 20 6e 65 65  ot its inode nee
7f00: 64 73 20 74 6f 20 62 65 20 73 79 6e 63 65 64 2e  ds to be synced.
7f10: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65 67  .**.** The integ
7f20: 65 72 20 76 61 6c 75 65 73 20 74 6f 20 78 4c 6f  er values to xLo
7f30: 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b  ck() and xUnlock
7f40: 28 29 20 61 72 65 20 6f 6e 65 20 6f 66 0a 2a 2a  () are one of.**
7f50: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53   <ul>.** <li> [S
7f60: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d  QLITE_LOCK_NONE]
7f70: 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ,.** <li> [SQLIT
7f80: 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a  E_LOCK_SHARED],.
7f90: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
7fa0: 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 0a  LOCK_RESERVED],.
7fb0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
7fc0: 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f  LOCK_PENDING], o
7fd0: 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  r.** <li> [SQLIT
7fe0: 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45  E_LOCK_EXCLUSIVE
7ff0: 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 78  ]..** </ul>.** x
8000: 4c 6f 63 6b 28 29 20 69 6e 63 72 65 61 73 65 73  Lock() increases
8010: 20 74 68 65 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f   the lock. xUnlo
8020: 63 6b 28 29 20 64 65 63 72 65 61 73 65 73 20 74  ck() decreases t
8030: 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 54 68 65 20  he lock..** The 
8040: 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f  xCheckReservedLo
8050: 63 6b 28 29 20 6d 65 74 68 6f 64 20 63 68 65 63  ck() method chec
8060: 6b 73 20 77 68 65 74 68 65 72 20 61 6e 79 20 64  ks whether any d
8070: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
8080: 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65 72 20 69 6e  on,.** either in
8090: 20 74 68 69 73 20 70 72 6f 63 65 73 73 20 6f 72   this process or
80a0: 20 69 6e 20 73 6f 6d 65 20 6f 74 68 65 72 20 70   in some other p
80b0: 72 6f 63 65 73 73 2c 20 69 73 20 68 6f 6c 64 69  rocess, is holdi
80c0: 6e 67 20 61 20 52 45 53 45 52 56 45 44 2c 0a 2a  ng a RESERVED,.*
80d0: 2a 20 50 45 4e 44 49 4e 47 2c 20 6f 72 20 45 58  * PENDING, or EX
80e0: 43 4c 55 53 49 56 45 20 6c 6f 63 6b 20 6f 6e 20  CLUSIVE lock on 
80f0: 74 68 65 20 66 69 6c 65 2e 20 20 49 74 20 72 65  the file.  It re
8100: 74 75 72 6e 73 20 74 72 75 65 0a 2a 2a 20 69 66  turns true.** if
8110: 20 73 75 63 68 20 61 20 6c 6f 63 6b 20 65 78 69   such a lock exi
8120: 73 74 73 20 61 6e 64 20 66 61 6c 73 65 20 6f 74  sts and false ot
8130: 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 54  herwise..**.** T
8140: 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28  he xFileControl(
8150: 29 20 6d 65 74 68 6f 64 20 69 73 20 61 20 67 65  ) method is a ge
8160: 6e 65 72 69 63 20 69 6e 74 65 72 66 61 63 65 20  neric interface 
8170: 74 68 61 74 20 61 6c 6c 6f 77 73 20 63 75 73 74  that allows cust
8180: 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d 70 6c 65 6d  om.** VFS implem
8190: 65 6e 74 61 74 69 6f 6e 73 20 74 6f 20 64 69 72  entations to dir
81a0: 65 63 74 6c 79 20 63 6f 6e 74 72 6f 6c 20 61 6e  ectly control an
81b0: 20 6f 70 65 6e 20 66 69 6c 65 20 75 73 69 6e 67   open file using
81c0: 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
81d0: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
81e0: 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68 65   interface.  The
81f0: 20 73 65 63 6f 6e 64 20 22 6f 70 22 20 61 72 67   second "op" arg
8200: 75 6d 65 6e 74 20 69 73 20 61 6e 0a 2a 2a 20 69  ument is an.** i
8210: 6e 74 65 67 65 72 20 6f 70 63 6f 64 65 2e 20 20  nteger opcode.  
8220: 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  The third argume
8230: 6e 74 20 69 73 20 61 20 67 65 6e 65 72 69 63 20  nt is a generic 
8240: 70 6f 69 6e 74 65 72 20 69 6e 74 65 6e 64 65 64  pointer intended
8250: 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20   to.** point to 
8260: 61 20 73 74 72 75 63 74 75 72 65 20 74 68 61 74  a structure that
8270: 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 61 72 67   may contain arg
8280: 75 6d 65 6e 74 73 20 6f 72 20 73 70 61 63 65 20  uments or space 
8290: 69 6e 20 77 68 69 63 68 20 74 6f 0a 2a 2a 20 77  in which to.** w
82a0: 72 69 74 65 20 72 65 74 75 72 6e 20 76 61 6c 75  rite return valu
82b0: 65 73 2e 20 20 50 6f 74 65 6e 74 69 61 6c 20 75  es.  Potential u
82c0: 73 65 73 20 66 6f 72 20 78 46 69 6c 65 43 6f 6e  ses for xFileCon
82d0: 74 72 6f 6c 28 29 20 6d 69 67 68 74 20 62 65 0a  trol() might be.
82e0: 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 20  ** functions to 
82f0: 65 6e 61 62 6c 65 20 62 6c 6f 63 6b 69 6e 67 20  enable blocking 
8300: 6c 6f 63 6b 73 20 77 69 74 68 20 74 69 6d 65 6f  locks with timeo
8310: 75 74 73 2c 20 74 6f 20 63 68 61 6e 67 65 20 74  uts, to change t
8320: 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67 20 73 74  he.** locking st
8330: 72 61 74 65 67 79 20 28 66 6f 72 20 65 78 61 6d  rategy (for exam
8340: 70 6c 65 20 74 6f 20 75 73 65 20 64 6f 74 2d 66  ple to use dot-f
8350: 69 6c 65 20 6c 6f 63 6b 73 29 2c 20 74 6f 20 69  ile locks), to i
8360: 6e 71 75 69 72 65 0a 2a 2a 20 61 62 6f 75 74 20  nquire.** about 
8370: 74 68 65 20 73 74 61 74 75 73 20 6f 66 20 61 20  the status of a 
8380: 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20 62 72 65 61  lock, or to brea
8390: 6b 20 73 74 61 6c 65 20 6c 6f 63 6b 73 2e 20 20  k stale locks.  
83a0: 54 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20 63 6f  The SQLite.** co
83b0: 72 65 20 72 65 73 65 72 76 65 73 20 61 6c 6c 20  re reserves all 
83c0: 6f 70 63 6f 64 65 73 20 6c 65 73 73 20 74 68 61  opcodes less tha
83d0: 6e 20 31 30 30 20 66 6f 72 20 69 74 73 20 6f 77  n 100 for its ow
83e0: 6e 20 75 73 65 2e 0a 2a 2a 20 41 20 5b 53 51 4c  n use..** A [SQL
83f0: 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54  ITE_FCNTL_LOCKST
8400: 41 54 45 20 7c 20 6c 69 73 74 20 6f 66 20 6f 70  ATE | list of op
8410: 63 6f 64 65 73 5d 20 6c 65 73 73 20 74 68 61 6e  codes] less than
8420: 20 31 30 30 20 69 73 20 61 76 61 69 6c 61 62 6c   100 is availabl
8430: 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f  e..** Applicatio
8440: 6e 73 20 74 68 61 74 20 64 65 66 69 6e 65 20 61  ns that define a
8450: 20 63 75 73 74 6f 6d 20 78 46 69 6c 65 43 6f 6e   custom xFileCon
8460: 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73 68 6f 75  trol method shou
8470: 6c 64 20 75 73 65 20 6f 70 63 6f 64 65 73 0a 2a  ld use opcodes.*
8480: 2a 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 31  * greater than 1
8490: 30 30 20 74 6f 20 61 76 6f 69 64 20 63 6f 6e 66  00 to avoid conf
84a0: 6c 69 63 74 73 2e 20 20 56 46 53 20 69 6d 70 6c  licts.  VFS impl
84b0: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75  ementations shou
84c0: 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51  ld.** return [SQ
84d0: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 20 66  LITE_NOTFOUND] f
84e0: 6f 72 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  or file control 
84f0: 6f 70 63 6f 64 65 73 20 74 68 61 74 20 74 68 65  opcodes that the
8500: 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 72 65 63 6f  y do not.** reco
8510: 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  gnize..**.** The
8520: 20 78 53 65 63 74 6f 72 53 69 7a 65 28 29 20 6d   xSectorSize() m
8530: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 74 68  ethod returns th
8540: 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 6f 66  e sector size of
8550: 20 74 68 65 0a 2a 2a 20 64 65 76 69 63 65 20 74   the.** device t
8560: 68 61 74 20 75 6e 64 65 72 6c 69 65 73 20 74 68  hat underlies th
8570: 65 20 66 69 6c 65 2e 20 20 54 68 65 20 73 65 63  e file.  The sec
8580: 74 6f 72 20 73 69 7a 65 20 69 73 20 74 68 65 0a  tor size is the.
8590: 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72 69 74 65  ** minimum write
85a0: 20 74 68 61 74 20 63 61 6e 20 62 65 20 70 65 72   that can be per
85b0: 66 6f 72 6d 65 64 20 77 69 74 68 6f 75 74 20 64  formed without d
85c0: 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20 6f 74 68  isturbing.** oth
85d0: 65 72 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  er bytes in the 
85e0: 66 69 6c 65 2e 20 20 54 68 65 20 78 44 65 76 69  file.  The xDevi
85f0: 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63  ceCharacteristic
8600: 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65  s().** method re
8610: 74 75 72 6e 73 20 61 20 62 69 74 20 76 65 63 74  turns a bit vect
8620: 6f 72 20 64 65 73 63 72 69 62 69 6e 67 20 62 65  or describing be
8630: 68 61 76 69 6f 72 73 20 6f 66 20 74 68 65 0a 2a  haviors of the.*
8640: 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 64 65 76  * underlying dev
8650: 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ice:.**.** <ul>.
8660: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
8670: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d 0a 2a 2a  IOCAP_ATOMIC].**
8680: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
8690: 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 5d 0a 2a  CAP_ATOMIC512].*
86a0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
86b0: 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 5d 0a 2a  OCAP_ATOMIC1K].*
86c0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
86d0: 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 5d 0a 2a  OCAP_ATOMIC2K].*
86e0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
86f0: 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 5d 0a 2a  OCAP_ATOMIC4K].*
8700: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
8710: 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 5d 0a 2a  OCAP_ATOMIC8K].*
8720: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
8730: 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 5d 0a  OCAP_ATOMIC16K].
8740: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
8750: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 5d  IOCAP_ATOMIC32K]
8760: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
8770: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b  _IOCAP_ATOMIC64K
8780: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
8790: 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50  E_IOCAP_SAFE_APP
87a0: 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  END].** <li> [SQ
87b0: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
87c0: 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a  NTIAL].** </ul>.
87d0: 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  **.** The SQLITE
87e0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72  _IOCAP_ATOMIC pr
87f0: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61  operty means tha
8800: 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a  t all writes of.
8810: 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20  ** any size are 
8820: 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c  atomic.  The SQL
8830: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
8840: 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65  nnn values.** me
8850: 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 6f  an that writes o
8860: 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72  f blocks that ar
8870: 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73  e nnn bytes in s
8880: 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61  ize and.** are a
8890: 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64  ligned to an add
88a0: 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61 6e  ress which is an
88b0: 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c   integer multipl
88c0: 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20  e of.** nnn are 
88d0: 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c  atomic.  The SQL
88e0: 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41  ITE_IOCAP_SAFE_A
88f0: 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e  PPEND value mean
8900: 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64  s.** that when d
8910: 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 20  ata is appended 
8920: 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64  to a file, the d
8930: 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a  ata is appended.
8940: 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 68  ** first then th
8950: 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69  e size of the fi
8960: 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20  le is extended, 
8970: 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a  never the other.
8980: 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20  ** way around.  
8990: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
89a0: 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70  _SEQUENTIAL prop
89b0: 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a  erty means that.
89c0: 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  ** information i
89d0: 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73  s written to dis
89e0: 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72  k in the same or
89f0: 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20  der as calls.** 
8a00: 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2a 0a  to xWrite()..**.
8a10: 2a 2a 20 49 66 20 78 52 65 61 64 28 29 20 72 65  ** If xRead() re
8a20: 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 49 4f 45  turns SQLITE_IOE
8a30: 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 69 74  RR_SHORT_READ it
8a40: 20 6d 75 73 74 20 61 6c 73 6f 20 66 69 6c 6c 0a   must also fill.
8a50: 2a 2a 20 69 6e 20 74 68 65 20 75 6e 72 65 61 64  ** in the unread
8a60: 20 70 6f 72 74 69 6f 6e 73 20 6f 66 20 74 68 65   portions of the
8a70: 20 62 75 66 66 65 72 20 77 69 74 68 20 7a 65 72   buffer with zer
8a80: 6f 73 2e 20 20 41 20 56 46 53 20 74 68 61 74 0a  os.  A VFS that.
8a90: 2a 2a 20 66 61 69 6c 73 20 74 6f 20 7a 65 72 6f  ** fails to zero
8aa0: 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 64  -fill short read
8ab0: 73 20 6d 69 67 68 74 20 73 65 65 6d 20 74 6f 20  s might seem to 
8ac0: 77 6f 72 6b 2e 20 20 48 6f 77 65 76 65 72 2c 0a  work.  However,.
8ad0: 2a 2a 20 66 61 69 6c 75 72 65 20 74 6f 20 7a 65  ** failure to ze
8ae0: 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65  ro-fill short re
8af0: 61 64 73 20 77 69 6c 6c 20 65 76 65 6e 74 75 61  ads will eventua
8b00: 6c 6c 79 20 6c 65 61 64 20 74 6f 0a 2a 2a 20 64  lly lead to.** d
8b10: 61 74 61 62 61 73 65 20 63 6f 72 72 75 70 74 69  atabase corrupti
8b20: 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  on..*/.typedef s
8b30: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f  truct sqlite3_io
8b40: 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33  _methods sqlite3
8b50: 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72  _io_methods;.str
8b60: 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  uct sqlite3_io_m
8b70: 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20 69  ethods {.  int i
8b80: 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28  Version;.  int (
8b90: 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33  *xClose)(sqlite3
8ba0: 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28  _file*);.  int (
8bb0: 2a 78 52 65 61 64 29 28 73 71 6c 69 74 65 33 5f  *xRead)(sqlite3_
8bc0: 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e  file*, void*, in
8bd0: 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f  t iAmt, sqlite3_
8be0: 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20  int64 iOfst);.  
8bf0: 69 6e 74 20 28 2a 78 57 72 69 74 65 29 28 73 71  int (*xWrite)(sq
8c00: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63 6f 6e  lite3_file*, con
8c10: 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41  st void*, int iA
8c20: 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  mt, sqlite3_int6
8c30: 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20  4 iOfst);.  int 
8c40: 28 2a 78 54 72 75 6e 63 61 74 65 29 28 73 71 6c  (*xTruncate)(sql
8c50: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69  ite3_file*, sqli
8c60: 74 65 33 5f 69 6e 74 36 34 20 73 69 7a 65 29 3b  te3_int64 size);
8c70: 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29 28  .  int (*xSync)(
8c80: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
8c90: 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e 74  nt flags);.  int
8ca0: 20 28 2a 78 46 69 6c 65 53 69 7a 65 29 28 73 71   (*xFileSize)(sq
8cb0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c  lite3_file*, sql
8cc0: 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 53 69 7a  ite3_int64 *pSiz
8cd0: 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c 6f 63  e);.  int (*xLoc
8ce0: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  k)(sqlite3_file*
8cf0: 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a  , int);.  int (*
8d00: 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 65 33  xUnlock)(sqlite3
8d10: 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20  _file*, int);.  
8d20: 69 6e 74 20 28 2a 78 43 68 65 63 6b 52 65 73 65  int (*xCheckRese
8d30: 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69 74 65  rvedLock)(sqlite
8d40: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a 70 52  3_file*, int *pR
8d50: 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a  esOut);.  int (*
8d60: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 73 71  xFileControl)(sq
8d70: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
8d80: 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72 67 29   op, void *pArg)
8d90: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65 63 74 6f  ;.  int (*xSecto
8da0: 72 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66  rSize)(sqlite3_f
8db0: 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  ile*);.  int (*x
8dc0: 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69  DeviceCharacteri
8dd0: 73 74 69 63 73 29 28 73 71 6c 69 74 65 33 5f 66  stics)(sqlite3_f
8de0: 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4d 65 74 68  ile*);.  /* Meth
8df0: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 61  ods above are va
8e00: 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20  lid for version 
8e10: 31 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 68  1 */.  int (*xSh
8e20: 6d 4d 61 70 29 28 73 71 6c 69 74 65 33 5f 66 69  mMap)(sqlite3_fi
8e30: 6c 65 2a 2c 20 69 6e 74 20 69 50 67 2c 20 69 6e  le*, int iPg, in
8e40: 74 20 70 67 73 7a 2c 20 69 6e 74 2c 20 76 6f 69  t pgsz, int, voi
8e50: 64 20 76 6f 6c 61 74 69 6c 65 2a 2a 29 3b 0a 20  d volatile**);. 
8e60: 20 69 6e 74 20 28 2a 78 53 68 6d 4c 6f 63 6b 29   int (*xShmLock)
8e70: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8e80: 69 6e 74 20 6f 66 66 73 65 74 2c 20 69 6e 74 20  int offset, int 
8e90: 6e 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20  n, int flags);. 
8ea0: 20 76 6f 69 64 20 28 2a 78 53 68 6d 42 61 72 72   void (*xShmBarr
8eb0: 69 65 72 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ier)(sqlite3_fil
8ec0: 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68  e*);.  int (*xSh
8ed0: 6d 55 6e 6d 61 70 29 28 73 71 6c 69 74 65 33 5f  mUnmap)(sqlite3_
8ee0: 66 69 6c 65 2a 2c 20 69 6e 74 20 64 65 6c 65 74  file*, int delet
8ef0: 65 46 6c 61 67 29 3b 0a 20 20 2f 2a 20 4d 65 74  eFlag);.  /* Met
8f00: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 76  hods above are v
8f10: 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e  alid for version
8f20: 20 32 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 46   2 */.  int (*xF
8f30: 65 74 63 68 29 28 73 71 6c 69 74 65 33 5f 66 69  etch)(sqlite3_fi
8f40: 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  le*, sqlite3_int
8f50: 36 34 20 69 4f 66 73 74 2c 20 69 6e 74 20 69 41  64 iOfst, int iA
8f60: 6d 74 2c 20 76 6f 69 64 20 2a 2a 70 70 29 3b 0a  mt, void **pp);.
8f70: 20 20 69 6e 74 20 28 2a 78 55 6e 66 65 74 63 68    int (*xUnfetch
8f80: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8f90: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69   sqlite3_int64 i
8fa0: 4f 66 73 74 2c 20 76 6f 69 64 20 2a 70 29 3b 0a  Ofst, void *p);.
8fb0: 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f    /* Methods abo
8fc0: 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72  ve are valid for
8fd0: 20 76 65 72 73 69 6f 6e 20 33 20 2a 2f 0a 20 20   version 3 */.  
8fe0: 2f 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65  /* Additional me
8ff0: 74 68 6f 64 73 20 6d 61 79 20 62 65 20 61 64 64  thods may be add
9000: 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
9010: 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a  eases */.};../*.
9020: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 74 61  ** CAPI3REF: Sta
9030: 6e 64 61 72 64 20 46 69 6c 65 20 43 6f 6e 74 72  ndard File Contr
9040: 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a 0a 2a 2a  ol Opcodes.**.**
9050: 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63   These integer c
9060: 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 6f 70 63  onstants are opc
9070: 6f 64 65 73 20 66 6f 72 20 74 68 65 20 78 46 69  odes for the xFi
9080: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
9090: 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  .** of the [sqli
90a0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
90b0: 6f 62 6a 65 63 74 20 61 6e 64 20 66 6f 72 20 74  object and for t
90c0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
90d0: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69  _control()].** i
90e0: 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
90f0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
9100: 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63  L_LOCKSTATE] opc
9110: 6f 64 65 20 69 73 20 75 73 65 64 20 66 6f 72 20  ode is used for 
9120: 64 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73  debugging.  This
9130: 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65  .** opcode cause
9140: 73 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72  s the xFileContr
9150: 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 69  ol method to wri
9160: 74 65 20 74 68 65 20 63 75 72 72 65 6e 74 20 73  te the current s
9170: 74 61 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c  tate of.** the l
9180: 6f 63 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c  ock (one of [SQL
9190: 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20  ITE_LOCK_NONE], 
91a0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41  [SQLITE_LOCK_SHA
91b0: 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  RED],.** [SQLITE
91c0: 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c  _LOCK_RESERVED],
91d0: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45   [SQLITE_LOCK_PE
91e0: 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49  NDING], or [SQLI
91f0: 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56  TE_LOCK_EXCLUSIV
9200: 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69  E]).** into an i
9210: 6e 74 65 67 65 72 20 74 68 61 74 20 74 68 65 20  nteger that the 
9220: 70 41 72 67 20 61 72 67 75 6d 65 6e 74 20 70 6f  pArg argument po
9230: 69 6e 74 73 20 74 6f 2e 20 54 68 69 73 20 63 61  ints to. This ca
9240: 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75  pability.** is u
9250: 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69  sed during testi
9260: 6e 67 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64  ng and only need
9270: 73 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65  s to be supporte
9280: 64 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 54 45  d when SQLITE_TE
9290: 53 54 0a 2a 2a 20 69 73 20 64 65 66 69 6e 65 64  ST.** is defined
92a0: 2e 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  ..** <ul>.** <li
92b0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
92c0: 53 49 5a 45 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 54  SIZE_HINT]].** T
92d0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
92e0: 5f 53 49 5a 45 5f 48 49 4e 54 5d 20 6f 70 63 6f  _SIZE_HINT] opco
92f0: 64 65 20 69 73 20 75 73 65 64 20 62 79 20 53 51  de is used by SQ
9300: 4c 69 74 65 20 74 6f 20 67 69 76 65 20 74 68 65  Lite to give the
9310: 20 56 46 53 0a 2a 2a 20 6c 61 79 65 72 20 61 20   VFS.** layer a 
9320: 68 69 6e 74 20 6f 66 20 68 6f 77 20 6c 61 72 67  hint of how larg
9330: 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  e the database f
9340: 69 6c 65 20 77 69 6c 6c 20 67 72 6f 77 20 74 6f  ile will grow to
9350: 20 62 65 20 64 75 72 69 6e 67 20 74 68 65 0a 2a   be during the.*
9360: 2a 20 63 75 72 72 65 6e 74 20 74 72 61 6e 73 61  * current transa
9370: 63 74 69 6f 6e 2e 20 20 54 68 69 73 20 68 69 6e  ction.  This hin
9380: 74 20 69 73 20 6e 6f 74 20 67 75 61 72 61 6e 74  t is not guarant
9390: 65 65 64 20 74 6f 20 62 65 20 61 63 63 75 72 61  eed to be accura
93a0: 74 65 20 62 75 74 20 69 74 0a 2a 2a 20 69 73 20  te but it.** is 
93b0: 6f 66 74 65 6e 20 63 6c 6f 73 65 2e 20 20 54 68  often close.  Th
93c0: 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 56 46 53  e underlying VFS
93d0: 20 6d 69 67 68 74 20 63 68 6f 6f 73 65 20 74 6f   might choose to
93e0: 20 70 72 65 61 6c 6c 6f 63 61 74 65 20 64 61 74   preallocate dat
93f0: 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 73 70  abase.** file sp
9400: 61 63 65 20 62 61 73 65 64 20 6f 6e 20 74 68 69  ace based on thi
9410: 73 20 68 69 6e 74 20 69 6e 20 6f 72 64 65 72 20  s hint in order 
9420: 74 6f 20 68 65 6c 70 20 77 72 69 74 65 73 20 74  to help writes t
9430: 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  o the database.*
9440: 2a 20 66 69 6c 65 20 72 75 6e 20 66 61 73 74 65  * file run faste
9450: 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  r..**.** <li>[[S
9460: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e  QLITE_FCNTL_CHUN
9470: 4b 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20  K_SIZE]].** The 
9480: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48  [SQLITE_FCNTL_CH
9490: 55 4e 4b 5f 53 49 5a 45 5d 20 6f 70 63 6f 64 65  UNK_SIZE] opcode
94a0: 20 69 73 20 75 73 65 64 20 74 6f 20 72 65 71 75   is used to requ
94b0: 65 73 74 20 74 68 61 74 20 74 68 65 20 56 46 53  est that the VFS
94c0: 0a 2a 2a 20 65 78 74 65 6e 64 73 20 61 6e 64 20  .** extends and 
94d0: 74 72 75 6e 63 61 74 65 73 20 74 68 65 20 64 61  truncates the da
94e0: 74 61 62 61 73 65 20 66 69 6c 65 20 69 6e 20 63  tabase file in c
94f0: 68 75 6e 6b 73 20 6f 66 20 61 20 73 69 7a 65 20  hunks of a size 
9500: 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20  specified.** by 
9510: 74 68 65 20 75 73 65 72 2e 20 54 68 65 20 66 6f  the user. The fo
9520: 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f  urth argument to
9530: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
9540: 6f 6e 74 72 6f 6c 28 29 5d 20 73 68 6f 75 6c 64  ontrol()] should
9550: 20 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 6e   .** point to an
9560: 20 69 6e 74 65 67 65 72 20 28 74 79 70 65 20 69   integer (type i
9570: 6e 74 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  nt) containing t
9580: 68 65 20 6e 65 77 20 63 68 75 6e 6b 2d 73 69 7a  he new chunk-siz
9590: 65 20 74 6f 20 75 73 65 0a 2a 2a 20 66 6f 72 20  e to use.** for 
95a0: 74 68 65 20 6e 6f 6d 69 6e 61 74 65 64 20 64 61  the nominated da
95b0: 74 61 62 61 73 65 2e 20 41 6c 6c 6f 63 61 74 69  tabase. Allocati
95c0: 6e 67 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  ng database file
95d0: 20 73 70 61 63 65 20 69 6e 20 6c 61 72 67 65 0a   space in large.
95e0: 2a 2a 20 63 68 75 6e 6b 73 20 28 73 61 79 20 31  ** chunks (say 1
95f0: 4d 42 20 61 74 20 61 20 74 69 6d 65 29 2c 20 6d  MB at a time), m
9600: 61 79 20 72 65 64 75 63 65 20 66 69 6c 65 2d 73  ay reduce file-s
9610: 79 73 74 65 6d 20 66 72 61 67 6d 65 6e 74 61 74  ystem fragmentat
9620: 69 6f 6e 20 61 6e 64 0a 2a 2a 20 69 6d 70 72 6f  ion and.** impro
9630: 76 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6f  ve performance o
9640: 6e 20 73 6f 6d 65 20 73 79 73 74 65 6d 73 2e 0a  n some systems..
9650: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
9660: 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f  TE_FCNTL_FILE_PO
9670: 49 4e 54 45 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b  INTER]].** The [
9680: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c  SQLITE_FCNTL_FIL
9690: 45 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64  E_POINTER] opcod
96a0: 65 20 69 73 20 75 73 65 64 20 74 6f 20 6f 62 74  e is used to obt
96b0: 61 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a  ain a pointer.**
96c0: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
96d0: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73  _file] object as
96e0: 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20  sociated with a 
96f0: 70 61 72 74 69 63 75 6c 61 72 20 64 61 74 61 62  particular datab
9700: 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
9710: 6e 2e 20 20 53 65 65 20 74 68 65 20 5b 73 71 6c  n.  See the [sql
9720: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
9730: 6c 28 29 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69  l()] documentati
9740: 6f 6e 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69  on for.** additi
9750: 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
9760: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
9770: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f  LITE_FCNTL_SYNC_
9780: 4f 4d 49 54 54 45 44 5d 5d 0a 2a 2a 20 5e 28 54  OMITTED]].** ^(T
9790: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
97a0: 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 20 6f  _SYNC_OMITTED] o
97b0: 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61 74  pcode is generat
97c0: 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79  ed internally by
97d0: 0a 2a 2a 20 53 51 4c 69 74 65 20 61 6e 64 20 73  .** SQLite and s
97e0: 65 6e 74 20 74 6f 20 61 6c 6c 20 56 46 53 65 73  ent to all VFSes
97f0: 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 61 20 63   in place of a c
9800: 61 6c 6c 20 74 6f 20 74 68 65 20 78 53 79 6e 63  all to the xSync
9810: 20 6d 65 74 68 6f 64 0a 2a 2a 20 77 68 65 6e 20   method.** when 
9820: 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
9830: 6e 65 63 74 69 6f 6e 20 68 61 73 20 5b 50 52 41  nection has [PRA
9840: 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d  GMA synchronous]
9850: 20 73 65 74 20 74 6f 20 4f 46 46 2e 29 5e 0a 2a   set to OFF.)^.*
9860: 2a 20 53 6f 6d 65 20 73 70 65 63 69 61 6c 69 7a  * Some specializ
9870: 65 64 20 56 46 53 65 73 20 6e 65 65 64 20 74 68  ed VFSes need th
9880: 69 73 20 73 69 67 6e 61 6c 20 69 6e 20 6f 72 64  is signal in ord
9890: 65 72 20 74 6f 20 6f 70 65 72 61 74 65 20 63 6f  er to operate co
98a0: 72 72 65 63 74 6c 79 0a 2a 2a 20 77 68 65 6e 20  rrectly.** when 
98b0: 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e  [PRAGMA synchron
98c0: 6f 75 73 20 7c 20 50 52 41 47 4d 41 20 73 79 6e  ous | PRAGMA syn
98d0: 63 68 72 6f 6e 6f 75 73 3d 4f 46 46 5d 20 69 73  chronous=OFF] is
98e0: 20 73 65 74 2c 20 62 75 74 20 6d 6f 73 74 20 0a   set, but most .
98f0: 2a 2a 20 56 46 53 65 73 20 64 6f 20 6e 6f 74 20  ** VFSes do not 
9900: 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e 61 6c  need this signal
9910: 20 61 6e 64 20 73 68 6f 75 6c 64 20 73 69 6c 65   and should sile
9920: 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 73  ntly ignore this
9930: 20 6f 70 63 6f 64 65 2e 0a 2a 2a 20 41 70 70 6c   opcode..** Appl
9940: 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20  ications should 
9950: 6e 6f 74 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65  not call [sqlite
9960: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
9970: 5d 20 77 69 74 68 20 74 68 69 73 0a 2a 2a 20 6f  ] with this.** o
9980: 70 63 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73  pcode as doing s
9990: 6f 20 6d 61 79 20 64 69 73 72 75 70 74 20 74 68  o may disrupt th
99a0: 65 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20 74  e operation of t
99b0: 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20 56  he specialized V
99c0: 46 53 65 73 0a 2a 2a 20 74 68 61 74 20 64 6f 20  FSes.** that do 
99d0: 72 65 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a  require it.  .**
99e0: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
99f0: 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f  _FCNTL_WIN32_AV_
9a00: 52 45 54 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65 20  RETRY]].** ^The 
9a10: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49  [SQLITE_FCNTL_WI
9a20: 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d 20 6f 70  N32_AV_RETRY] op
9a30: 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20  code is used to 
9a40: 63 6f 6e 66 69 67 75 72 65 20 61 75 74 6f 6d 61  configure automa
9a50: 74 69 63 0a 2a 2a 20 72 65 74 72 79 20 63 6f 75  tic.** retry cou
9a60: 6e 74 73 20 61 6e 64 20 69 6e 74 65 72 76 61 6c  nts and interval
9a70: 73 20 66 6f 72 20 63 65 72 74 61 69 6e 20 64 69  s for certain di
9a80: 73 6b 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e  sk I/O operation
9a90: 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 77 69 6e  s for the.** win
9aa0: 64 6f 77 73 20 5b 56 46 53 5d 20 69 6e 20 6f 72  dows [VFS] in or
9ab0: 64 65 72 20 74 6f 20 70 72 6f 76 69 64 65 20 72  der to provide r
9ac0: 6f 62 75 73 74 6e 65 73 73 20 69 6e 20 74 68 65  obustness in the
9ad0: 20 70 72 65 73 65 6e 63 65 20 6f 66 0a 2a 2a 20   presence of.** 
9ae0: 61 6e 74 69 2d 76 69 72 75 73 20 70 72 6f 67 72  anti-virus progr
9af0: 61 6d 73 2e 20 20 42 79 20 64 65 66 61 75 6c 74  ams.  By default
9b00: 2c 20 74 68 65 20 77 69 6e 64 6f 77 73 20 56 46  , the windows VF
9b10: 53 20 77 69 6c 6c 20 72 65 74 72 79 20 66 69 6c  S will retry fil
9b20: 65 20 72 65 61 64 2c 0a 2a 2a 20 66 69 6c 65 20  e read,.** file 
9b30: 77 72 69 74 65 2c 20 61 6e 64 20 66 69 6c 65 20  write, and file 
9b40: 64 65 6c 65 74 65 20 6f 70 65 72 61 74 69 6f 6e  delete operation
9b50: 73 20 75 70 20 74 6f 20 31 30 20 74 69 6d 65 73  s up to 10 times
9b60: 2c 20 77 69 74 68 20 61 20 64 65 6c 61 79 0a 2a  , with a delay.*
9b70: 2a 20 6f 66 20 32 35 20 6d 69 6c 6c 69 73 65 63  * of 25 millisec
9b80: 6f 6e 64 73 20 62 65 66 6f 72 65 20 74 68 65 20  onds before the 
9b90: 66 69 72 73 74 20 72 65 74 72 79 20 61 6e 64 20  first retry and 
9ba0: 77 69 74 68 20 74 68 65 20 64 65 6c 61 79 20 69  with the delay i
9bb0: 6e 63 72 65 61 73 69 6e 67 0a 2a 2a 20 62 79 20  ncreasing.** by 
9bc0: 61 6e 20 61 64 64 69 74 69 6f 6e 61 6c 20 32 35  an additional 25
9bd0: 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 77 69   milliseconds wi
9be0: 74 68 20 65 61 63 68 20 73 75 62 73 65 71 75 65  th each subseque
9bf0: 6e 74 20 72 65 74 72 79 2e 20 20 54 68 69 73 0a  nt retry.  This.
9c00: 2a 2a 20 6f 70 63 6f 64 65 20 61 6c 6c 6f 77 73  ** opcode allows
9c10: 20 74 68 65 73 65 20 74 77 6f 20 76 61 6c 75 65   these two value
9c20: 73 20 28 31 30 20 72 65 74 72 69 65 73 20 61 6e  s (10 retries an
9c30: 64 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  d 25 millisecond
9c40: 73 20 6f 66 20 64 65 6c 61 79 29 0a 2a 2a 20 74  s of delay).** t
9c50: 6f 20 62 65 20 61 64 6a 75 73 74 65 64 2e 20 20  o be adjusted.  
9c60: 54 68 65 20 76 61 6c 75 65 73 20 61 72 65 20 63  The values are c
9c70: 68 61 6e 67 65 64 20 66 6f 72 20 61 6c 6c 20 64  hanged for all d
9c80: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
9c90: 6f 6e 73 0a 2a 2a 20 77 69 74 68 69 6e 20 74 68  ons.** within th
9ca0: 65 20 73 61 6d 65 20 70 72 6f 63 65 73 73 2e 20  e same process. 
9cb0: 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73   The argument is
9cc0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
9cd0: 20 61 72 72 61 79 20 6f 66 20 74 77 6f 0a 2a 2a   array of two.**
9ce0: 20 69 6e 74 65 67 65 72 73 20 77 68 65 72 65 20   integers where 
9cf0: 74 68 65 20 66 69 72 73 74 20 69 6e 74 65 67 65  the first intege
9d00: 72 20 69 20 74 68 65 20 6e 65 77 20 72 65 74 72  r i the new retr
9d10: 79 20 63 6f 75 6e 74 20 61 6e 64 20 74 68 65 20  y count and the 
9d20: 73 65 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67 65  second.** intege
9d30: 72 20 69 73 20 74 68 65 20 64 65 6c 61 79 2e 20  r is the delay. 
9d40: 20 49 66 20 65 69 74 68 65 72 20 69 6e 74 65 67   If either integ
9d50: 65 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  er is negative, 
9d60: 74 68 65 6e 20 74 68 65 20 73 65 74 74 69 6e 67  then the setting
9d70: 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67  .** is not chang
9d80: 65 64 20 62 75 74 20 69 6e 73 74 65 61 64 20 74  ed but instead t
9d90: 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f  he prior value o
9da0: 66 20 74 68 61 74 20 73 65 74 74 69 6e 67 20 69  f that setting i
9db0: 73 20 77 72 69 74 74 65 6e 0a 2a 2a 20 69 6e 74  s written.** int
9dc0: 6f 20 74 68 65 20 61 72 72 61 79 20 65 6e 74 72  o the array entr
9dd0: 79 2c 20 61 6c 6c 6f 77 69 6e 67 20 74 68 65 20  y, allowing the 
9de0: 63 75 72 72 65 6e 74 20 72 65 74 72 79 20 73 65  current retry se
9df0: 74 74 69 6e 67 73 20 74 6f 20 62 65 0a 2a 2a 20  ttings to be.** 
9e00: 69 6e 74 65 72 72 6f 67 61 74 65 64 2e 20 20 54  interrogated.  T
9e10: 68 65 20 7a 44 62 4e 61 6d 65 20 70 61 72 61 6d  he zDbName param
9e20: 65 74 65 72 20 69 73 20 69 67 6e 6f 72 65 64 2e  eter is ignored.
9e30: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
9e40: 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53  ITE_FCNTL_PERSIS
9e50: 54 5f 57 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 65 20  T_WAL]].** ^The 
9e60: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45  [SQLITE_FCNTL_PE
9e70: 52 53 49 53 54 5f 57 41 4c 5d 20 6f 70 63 6f 64  RSIST_WAL] opcod
9e80: 65 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74  e is used to set
9e90: 20 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a   or query the.**
9ea0: 20 70 65 72 73 69 73 74 65 6e 74 20 5b 57 41 4c   persistent [WAL
9eb0: 20 7c 20 57 72 69 74 65 20 41 68 65 61 64 20 4c   | Write Ahead L
9ec0: 6f 67 5d 20 73 65 74 74 69 6e 67 2e 20 20 42 79  og] setting.  By
9ed0: 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20 61 75   default, the au
9ee0: 78 69 6c 69 61 72 79 0a 2a 2a 20 77 72 69 74 65  xiliary.** write
9ef0: 20 61 68 65 61 64 20 6c 6f 67 20 61 6e 64 20 73   ahead log and s
9f00: 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c  hared memory fil
9f10: 65 73 20 75 73 65 64 20 66 6f 72 20 74 72 61 6e  es used for tran
9f20: 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 0a  saction control.
9f30: 2a 2a 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63  ** are automatic
9f40: 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 77 68 65  ally deleted whe
9f50: 6e 20 74 68 65 20 6c 61 74 65 73 74 20 63 6f 6e  n the latest con
9f60: 6e 65 63 74 69 6f 6e 20 74 6f 20 74 68 65 20 64  nection to the d
9f70: 61 74 61 62 61 73 65 0a 2a 2a 20 63 6c 6f 73 65  atabase.** close
9f80: 73 2e 20 20 53 65 74 74 69 6e 67 20 70 65 72 73  s.  Setting pers
9f90: 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20  istent WAL mode 
9fa0: 63 61 75 73 65 73 20 74 68 6f 73 65 20 66 69 6c  causes those fil
9fb0: 65 73 20 74 6f 20 70 65 72 73 69 73 74 20 61 66  es to persist af
9fc0: 74 65 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20 50  ter.** close.  P
9fd0: 65 72 73 69 73 74 69 6e 67 20 74 68 65 20 66 69  ersisting the fi
9fe0: 6c 65 73 20 69 73 20 75 73 65 66 75 6c 20 77 68  les is useful wh
9ff0: 65 6e 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73  en other process
a000: 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 0a 2a  es that do not.*
a010: 2a 20 68 61 76 65 20 77 72 69 74 65 20 70 65 72  * have write per
a020: 6d 69 73 73 69 6f 6e 20 6f 6e 20 74 68 65 20 64  mission on the d
a030: 69 72 65 63 74 6f 72 79 20 63 6f 6e 74 61 69 6e  irectory contain
a040: 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65  ing the database
a050: 20 66 69 6c 65 20 77 61 6e 74 0a 2a 2a 20 74 6f   file want.** to
a060: 20 72 65 61 64 20 74 68 65 20 64 61 74 61 62 61   read the databa
a070: 73 65 20 66 69 6c 65 2c 20 61 73 20 74 68 65 20  se file, as the 
a080: 57 41 4c 20 61 6e 64 20 73 68 61 72 65 64 20 6d  WAL and shared m
a090: 65 6d 6f 72 79 20 66 69 6c 65 73 20 6d 75 73 74  emory files must
a0a0: 20 65 78 69 73 74 0a 2a 2a 20 69 6e 20 6f 72 64   exist.** in ord
a0b0: 65 72 20 66 6f 72 20 74 68 65 20 64 61 74 61 62  er for the datab
a0c0: 61 73 65 20 74 6f 20 62 65 20 72 65 61 64 61 62  ase to be readab
a0d0: 6c 65 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20  le.  The fourth 
a0e0: 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
a0f0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
a100: 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69  ntrol()] for thi
a110: 73 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20  s opcode should 
a120: 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  be a pointer to 
a130: 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54  an integer..** T
a140: 68 61 74 20 69 6e 74 65 67 65 72 20 69 73 20 30  hat integer is 0
a150: 20 74 6f 20 64 69 73 61 62 6c 65 20 70 65 72 73   to disable pers
a160: 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20  istent WAL mode 
a170: 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 70  or 1 to enable p
a180: 65 72 73 69 73 74 65 6e 74 0a 2a 2a 20 57 41 4c  ersistent.** WAL
a190: 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69   mode.  If the i
a1a0: 6e 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68  nteger is -1, th
a1b0: 65 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72 69  en it is overwri
a1c0: 74 74 65 6e 20 77 69 74 68 20 74 68 65 20 63 75  tten with the cu
a1d0: 72 72 65 6e 74 0a 2a 2a 20 57 41 4c 20 70 65 72  rrent.** WAL per
a1e0: 73 69 73 74 65 6e 63 65 20 73 65 74 74 69 6e 67  sistence setting
a1f0: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
a200: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52  LITE_FCNTL_POWER
a210: 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 5d  SAFE_OVERWRITE]]
a220: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
a230: 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45  _FCNTL_POWERSAFE
a240: 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f  _OVERWRITE] opco
a250: 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 73 65  de is used to se
a260: 74 20 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a  t or query the.*
a270: 2a 20 70 65 72 73 69 73 74 65 6e 74 20 22 70 6f  * persistent "po
a280: 77 65 72 73 61 66 65 2d 6f 76 65 72 77 72 69 74  wersafe-overwrit
a290: 65 22 20 6f 72 20 22 50 53 4f 57 22 20 73 65 74  e" or "PSOW" set
a2a0: 74 69 6e 67 2e 20 20 54 68 65 20 50 53 4f 57 20  ting.  The PSOW 
a2b0: 73 65 74 74 69 6e 67 0a 2a 2a 20 64 65 74 65 72  setting.** deter
a2c0: 6d 69 6e 65 73 20 74 68 65 20 5b 53 51 4c 49 54  mines the [SQLIT
a2d0: 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46  E_IOCAP_POWERSAF
a2e0: 45 5f 4f 56 45 52 57 52 49 54 45 5d 20 62 69 74  E_OVERWRITE] bit
a2f0: 20 6f 66 20 74 68 65 0a 2a 2a 20 78 44 65 76 69   of the.** xDevi
a300: 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63  ceCharacteristic
a310: 73 20 6d 65 74 68 6f 64 73 2e 20 54 68 65 20 66  s methods. The f
a320: 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
a330: 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  to.** [sqlite3_f
a340: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66  ile_control()] f
a350: 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73  or this opcode s
a360: 68 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74  hould be a point
a370: 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  er to an integer
a380: 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65  ..** That intege
a390: 72 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c  r is 0 to disabl
a3a0: 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f  e zero-damage mo
a3b0: 64 65 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c  de or 1 to enabl
a3c0: 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65 0a 2a 2a  e zero-damage.**
a3d0: 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69   mode.  If the i
a3e0: 6e 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68  nteger is -1, th
a3f0: 65 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72 69  en it is overwri
a400: 74 74 65 6e 20 77 69 74 68 20 74 68 65 20 63 75  tten with the cu
a410: 72 72 65 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64 61  rrent.** zero-da
a420: 6d 61 67 65 20 6d 6f 64 65 20 73 65 74 74 69 6e  mage mode settin
a430: 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  g..**.** <li>[[S
a440: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52  QLITE_FCNTL_OVER
a450: 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20  WRITE]].** ^The 
a460: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56  [SQLITE_FCNTL_OV
a470: 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20  ERWRITE] opcode 
a480: 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51  is invoked by SQ
a490: 4c 69 74 65 20 61 66 74 65 72 20 6f 70 65 6e 69  Lite after openi
a4a0: 6e 67 0a 2a 2a 20 61 20 77 72 69 74 65 20 74 72  ng.** a write tr
a4b0: 61 6e 73 61 63 74 69 6f 6e 20 74 6f 20 69 6e 64  ansaction to ind
a4c0: 69 63 61 74 65 20 74 68 61 74 2c 20 75 6e 6c 65  icate that, unle
a4d0: 73 73 20 69 74 20 69 73 20 72 6f 6c 6c 65 64 20  ss it is rolled 
a4e0: 62 61 63 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a 2a  back for some.**
a4f0: 20 72 65 61 73 6f 6e 2c 20 74 68 65 20 65 6e 74   reason, the ent
a500: 69 72 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  ire database fil
a510: 65 20 77 69 6c 6c 20 62 65 20 6f 76 65 72 77 72  e will be overwr
a520: 69 74 74 65 6e 20 62 79 20 74 68 65 20 63 75 72  itten by the cur
a530: 72 65 6e 74 20 0a 2a 2a 20 74 72 61 6e 73 61 63  rent .** transac
a540: 74 69 6f 6e 2e 20 54 68 69 73 20 69 73 20 75 73  tion. This is us
a550: 65 64 20 62 79 20 56 41 43 55 55 4d 20 6f 70 65  ed by VACUUM ope
a560: 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c  rations..**.** <
a570: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
a580: 4c 5f 56 46 53 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e  L_VFSNAME]].** ^
a590: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
a5a0: 4c 5f 56 46 53 4e 41 4d 45 5d 20 6f 70 63 6f 64  L_VFSNAME] opcod
a5b0: 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  e can be used to
a5c0: 20 6f 62 74 61 69 6e 20 74 68 65 20 6e 61 6d 65   obtain the name
a5d0: 73 20 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46 53  s of.** all [VFS
a5e0: 65 73 5d 20 69 6e 20 74 68 65 20 56 46 53 20 73  es] in the VFS s
a5f0: 74 61 63 6b 2e 20 20 54 68 65 20 6e 61 6d 65 73  tack.  The names
a600: 20 61 72 65 20 6f 66 20 61 6c 6c 20 56 46 53 20   are of all VFS 
a610: 73 68 69 6d 73 20 61 6e 64 20 74 68 65 0a 2a 2a  shims and the.**
a620: 20 66 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c 65   final bottom-le
a630: 76 65 6c 20 56 46 53 20 61 72 65 20 77 72 69 74  vel VFS are writ
a640: 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20  ten into memory 
a650: 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a  obtained from .*
a660: 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  * [sqlite3_mallo
a670: 63 28 29 5d 20 61 6e 64 20 74 68 65 20 72 65 73  c()] and the res
a680: 75 6c 74 20 69 73 20 73 74 6f 72 65 64 20 69 6e  ult is stored in
a690: 20 74 68 65 20 63 68 61 72 2a 20 76 61 72 69 61   the char* varia
a6a0: 62 6c 65 0a 2a 2a 20 74 68 61 74 20 74 68 65 20  ble.** that the 
a6b0: 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
a6c0: 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c   of [sqlite3_fil
a6d0: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f 69  e_control()] poi
a6e0: 6e 74 73 20 74 6f 2e 0a 2a 2a 20 54 68 65 20 63  nts to..** The c
a6f0: 61 6c 6c 65 72 20 69 73 20 72 65 73 70 6f 6e 73  aller is respons
a700: 69 62 6c 65 20 66 6f 72 20 66 72 65 65 69 6e 67  ible for freeing
a710: 20 74 68 65 20 6d 65 6d 6f 72 79 20 77 68 65 6e   the memory when
a720: 20 64 6f 6e 65 2e 20 20 41 73 20 77 69 74 68 0a   done.  As with.
a730: 2a 2a 20 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e 74  ** all file-cont
a740: 72 6f 6c 20 61 63 74 69 6f 6e 73 2c 20 74 68 65  rol actions, the
a750: 72 65 20 69 73 20 6e 6f 20 67 75 61 72 61 6e 74  re is no guarant
a760: 65 65 20 74 68 61 74 20 74 68 69 73 20 77 69 6c  ee that this wil
a770: 6c 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 64 6f  l actually.** do
a780: 20 61 6e 79 74 68 69 6e 67 2e 20 20 43 61 6c 6c   anything.  Call
a790: 65 72 73 20 73 68 6f 75 6c 64 20 69 6e 69 74 69  ers should initi
a7a0: 61 6c 69 7a 65 20 74 68 65 20 63 68 61 72 2a 20  alize the char* 
a7b0: 76 61 72 69 61 62 6c 65 20 74 6f 20 61 20 4e 55  variable to a NU
a7c0: 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e  LL.** pointer in
a7d0: 20 63 61 73 65 20 74 68 69 73 20 66 69 6c 65 2d   case this file-
a7e0: 63 6f 6e 74 72 6f 6c 20 69 73 20 6e 6f 74 20 69  control is not i
a7f0: 6d 70 6c 65 6d 65 6e 74 65 64 2e 20 20 54 68 69  mplemented.  Thi
a800: 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a  s file-control.*
a810: 2a 20 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f  * is intended fo
a820: 72 20 64 69 61 67 6e 6f 73 74 69 63 20 75 73 65  r diagnostic use
a830: 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69   only..**.** <li
a840: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
a850: 50 52 41 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68 65  PRAGMA]].** ^Whe
a860: 6e 65 76 65 72 20 61 20 5b 50 52 41 47 4d 41 5d  never a [PRAGMA]
a870: 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 70 61   statement is pa
a880: 72 73 65 64 2c 20 61 6e 20 5b 53 51 4c 49 54 45  rsed, an [SQLITE
a890: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 0a  _FCNTL_PRAGMA] .
a8a0: 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  ** file control 
a8b0: 69 73 20 73 65 6e 74 20 74 6f 20 74 68 65 20 6f  is sent to the o
a8c0: 70 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  pen [sqlite3_fil
a8d0: 65 5d 20 6f 62 6a 65 63 74 20 63 6f 72 72 65 73  e] object corres
a8e0: 70 6f 6e 64 69 6e 67 0a 2a 2a 20 74 6f 20 74 68  ponding.** to th
a8f0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
a900: 74 6f 20 77 68 69 63 68 20 74 68 65 20 70 72 61  to which the pra
a910: 67 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 72 65  gma statement re
a920: 66 65 72 73 2e 20 5e 54 68 65 20 61 72 67 75 6d  fers. ^The argum
a930: 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 53  ent.** to the [S
a940: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
a950: 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  MA] file control
a960: 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 0a   is an array of.
a970: 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73  ** pointers to s
a980: 74 72 69 6e 67 73 20 28 63 68 61 72 2a 2a 29 20  trings (char**) 
a990: 69 6e 20 77 68 69 63 68 20 74 68 65 20 73 65 63  in which the sec
a9a0: 6f 6e 64 20 65 6c 65 6d 65 6e 74 20 6f 66 20 74  ond element of t
a9b0: 68 65 20 61 72 72 61 79 0a 2a 2a 20 69 73 20 74  he array.** is t
a9c0: 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 70  he name of the p
a9d0: 72 61 67 6d 61 20 61 6e 64 20 74 68 65 20 74 68  ragma and the th
a9e0: 69 72 64 20 65 6c 65 6d 65 6e 74 20 69 73 20 74  ird element is t
a9f0: 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  he argument to t
aa00: 68 65 0a 2a 2a 20 70 72 61 67 6d 61 20 6f 72 20  he.** pragma or 
aa10: 4e 55 4c 4c 20 69 66 20 74 68 65 20 70 72 61 67  NULL if the prag
aa20: 6d 61 20 68 61 73 20 6e 6f 20 61 72 67 75 6d 65  ma has no argume
aa30: 6e 74 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65  nt.  ^The handle
aa40: 72 20 66 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c  r for an.** [SQL
aa50: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
aa60: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 63  ] file control c
aa70: 61 6e 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d 61  an optionally ma
aa80: 6b 65 20 74 68 65 20 66 69 72 73 74 20 65 6c 65  ke the first ele
aa90: 6d 65 6e 74 0a 2a 2a 20 6f 66 20 74 68 65 20 63  ment.** of the c
aaa0: 68 61 72 2a 2a 20 61 72 67 75 6d 65 6e 74 20 70  har** argument p
aab0: 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67  oint to a string
aac0: 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
aad0: 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
aae0: 29 5d 0a 2a 2a 20 6f 72 20 74 68 65 20 65 71 75  )].** or the equ
aaf0: 69 76 61 6c 65 6e 74 20 61 6e 64 20 74 68 61 74  ivalent and that
ab00: 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 63   string will bec
ab10: 6f 6d 65 20 74 68 65 20 72 65 73 75 6c 74 20 6f  ome the result o
ab20: 66 20 74 68 65 20 70 72 61 67 6d 61 20 6f 72 0a  f the pragma or.
ab30: 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  ** the error mes
ab40: 73 61 67 65 20 69 66 20 74 68 65 20 70 72 61 67  sage if the prag
ab50: 6d 61 20 66 61 69 6c 73 2e 20 5e 49 66 20 74 68  ma fails. ^If th
ab60: 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e  e.** [SQLITE_FCN
ab70: 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20  TL_PRAGMA] file 
ab80: 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20  control returns 
ab90: 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44  [SQLITE_NOTFOUND
aba0: 5d 2c 20 74 68 65 6e 20 6e 6f 72 6d 61 6c 20 0a  ], then normal .
abb0: 2a 2a 20 5b 50 52 41 47 4d 41 5d 20 70 72 6f 63  ** [PRAGMA] proc
abc0: 65 73 73 69 6e 67 20 63 6f 6e 74 69 6e 75 65 73  essing continues
abd0: 2e 20 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49  .  ^If the [SQLI
abe0: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
abf0: 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  .** file control
ac00: 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
ac10: 5f 4f 4b 5d 2c 20 74 68 65 6e 20 74 68 65 20 70  _OK], then the p
ac20: 61 72 73 65 72 20 61 73 73 75 6d 65 73 20 74 68  arser assumes th
ac30: 61 74 20 74 68 65 0a 2a 2a 20 56 46 53 20 68 61  at the.** VFS ha
ac40: 73 20 68 61 6e 64 6c 65 64 20 74 68 65 20 50 52  s handled the PR
ac50: 41 47 4d 41 20 69 74 73 65 6c 66 20 61 6e 64 20  AGMA itself and 
ac60: 74 68 65 20 70 61 72 73 65 72 20 67 65 6e 65 72  the parser gener
ac70: 61 74 65 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a 20  ates a no-op.** 
ac80: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
ac90: 6e 74 2e 20 20 5e 49 66 20 74 68 65 20 5b 53 51  nt.  ^If the [SQ
aca0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
acb0: 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  A] file control 
acc0: 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 72  returns.** any r
acd0: 65 73 75 6c 74 20 63 6f 64 65 20 6f 74 68 65 72  esult code other
ace0: 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b   than [SQLITE_OK
acf0: 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 4f 54  ] or [SQLITE_NOT
ad00: 46 4f 55 4e 44 5d 2c 20 74 68 61 74 20 6d 65 61  FOUND], that mea
ad10: 6e 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 56  ns.** that the V
ad20: 46 53 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 61  FS encountered a
ad30: 6e 20 65 72 72 6f 72 20 77 68 69 6c 65 20 68 61  n error while ha
ad40: 6e 64 6c 69 6e 67 20 74 68 65 20 5b 50 52 41 47  ndling the [PRAG
ad50: 4d 41 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20 63  MA] and the.** c
ad60: 6f 6d 70 69 6c 61 74 69 6f 6e 20 6f 66 20 74 68  ompilation of th
ad70: 65 20 50 52 41 47 4d 41 20 66 61 69 6c 73 20 77  e PRAGMA fails w
ad80: 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e  ith an error.  ^
ad90: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
ada0: 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c  L_PRAGMA].** fil
adb0: 65 20 63 6f 6e 74 72 6f 6c 20 6f 63 63 75 72 73  e control occurs
adc0: 20 61 74 20 74 68 65 20 62 65 67 69 6e 6e 69 6e   at the beginnin
add0: 67 20 6f 66 20 70 72 61 67 6d 61 20 73 74 61 74  g of pragma stat
ade0: 65 6d 65 6e 74 20 61 6e 61 6c 79 73 69 73 20 61  ement analysis a
adf0: 6e 64 20 73 6f 0a 2a 2a 20 69 74 20 69 73 20 61  nd so.** it is a
ae00: 62 6c 65 20 74 6f 20 6f 76 65 72 72 69 64 65 20  ble to override 
ae10: 62 75 69 6c 74 2d 69 6e 20 5b 50 52 41 47 4d 41  built-in [PRAGMA
ae20: 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  ] statements..**
ae30: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
ae40: 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c  _FCNTL_BUSYHANDL
ae50: 45 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  ER]].** ^The [SQ
ae60: 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48  LITE_FCNTL_BUSYH
ae70: 41 4e 44 4c 45 52 5d 0a 2a 2a 20 66 69 6c 65 2d  ANDLER].** file-
ae80: 63 6f 6e 74 72 6f 6c 20 6d 61 79 20 62 65 20 69  control may be i
ae90: 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c 69 74 65  nvoked by SQLite
aea0: 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65   on the database
aeb0: 20 66 69 6c 65 20 68 61 6e 64 6c 65 0a 2a 2a 20   file handle.** 
aec0: 73 68 6f 72 74 6c 79 20 61 66 74 65 72 20 69 74  shortly after it
aed0: 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 6f 72   is opened in or
aee0: 64 65 72 20 74 6f 20 70 72 6f 76 69 64 65 20 61  der to provide a
aef0: 20 63 75 73 74 6f 6d 20 56 46 53 20 77 69 74 68   custom VFS with
af00: 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 74 68   access.** to th
af10: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 62 75  e connections bu
af20: 73 79 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62  sy-handler callb
af30: 61 63 6b 2e 20 54 68 65 20 61 72 67 75 6d 65 6e  ack. The argumen
af40: 74 20 69 73 20 6f 66 20 74 79 70 65 20 28 76 6f  t is of type (vo
af50: 69 64 20 2a 2a 29 0a 2a 2a 20 2d 20 61 6e 20 61  id **).** - an a
af60: 72 72 61 79 20 6f 66 20 74 77 6f 20 28 76 6f 69  rray of two (voi
af70: 64 20 2a 29 20 76 61 6c 75 65 73 2e 20 54 68 65  d *) values. The
af80: 20 66 69 72 73 74 20 28 76 6f 69 64 20 2a 29 20   first (void *) 
af90: 61 63 74 75 61 6c 6c 79 20 70 6f 69 6e 74 73 0a  actually points.
afa0: 2a 2a 20 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e  ** to a function
afb0: 20 6f 66 20 74 79 70 65 20 28 69 6e 74 20 28 2a   of type (int (*
afc0: 29 28 76 6f 69 64 20 2a 29 29 2e 20 49 6e 20 6f  )(void *)). In o
afd0: 72 64 65 72 20 74 6f 20 69 6e 76 6f 6b 65 20 74  rder to invoke t
afe0: 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a  he connections.*
aff0: 2a 20 62 75 73 79 2d 68 61 6e 64 6c 65 72 2c 20  * busy-handler, 
b000: 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 73 68  this function sh
b010: 6f 75 6c 64 20 62 65 20 69 6e 76 6f 6b 65 64 20  ould be invoked 
b020: 77 69 74 68 20 74 68 65 20 73 65 63 6f 6e 64 20  with the second 
b030: 28 76 6f 69 64 20 2a 29 20 69 6e 0a 2a 2a 20 74  (void *) in.** t
b040: 68 65 20 61 72 72 61 79 20 61 73 20 74 68 65 20  he array as the 
b050: 6f 6e 6c 79 20 61 72 67 75 6d 65 6e 74 2e 20 49  only argument. I
b060: 66 20 69 74 20 72 65 74 75 72 6e 73 20 6e 6f 6e  f it returns non
b070: 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20  -zero, then the 
b080: 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f  operation.** sho
b090: 75 6c 64 20 62 65 20 72 65 74 72 69 65 64 2e 20  uld be retried. 
b0a0: 49 66 20 69 74 20 72 65 74 75 72 6e 73 20 7a 65  If it returns ze
b0b0: 72 6f 2c 20 74 68 65 20 63 75 73 74 6f 6d 20 56  ro, the custom V
b0c0: 46 53 20 73 68 6f 75 6c 64 20 61 62 61 6e 64 6f  FS should abando
b0d0: 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74  n the.** current
b0e0: 20 6f 70 65 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a   operation..**.*
b0f0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
b100: 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d  CNTL_TEMPFILENAM
b110: 45 5d 5d 0a 2a 2a 20 5e 41 70 70 6c 69 63 61 74  E]].** ^Applicat
b120: 69 6f 6e 20 63 61 6e 20 69 6e 76 6f 6b 65 20 74  ion can invoke t
b130: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
b140: 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 20 66  _TEMPFILENAME] f
b150: 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 74  ile-control.** t
b160: 6f 20 68 61 76 65 20 53 51 4c 69 74 65 20 67 65  o have SQLite ge
b170: 6e 65 72 61 74 65 20 61 0a 2a 2a 20 74 65 6d 70  nerate a.** temp
b180: 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d 65 20 75  orary filename u
b190: 73 69 6e 67 20 74 68 65 20 73 61 6d 65 20 61 6c  sing the same al
b1a0: 67 6f 72 69 74 68 6d 20 74 68 61 74 20 69 73 20  gorithm that is 
b1b0: 66 6f 6c 6c 6f 77 65 64 20 74 6f 20 67 65 6e 65  followed to gene
b1c0: 72 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72  rate.** temporar
b1d0: 79 20 66 69 6c 65 6e 61 6d 65 73 20 66 6f 72 20  y filenames for 
b1e0: 54 45 4d 50 20 74 61 62 6c 65 73 20 61 6e 64 20  TEMP tables and 
b1f0: 6f 74 68 65 72 20 69 6e 74 65 72 6e 61 6c 20 75  other internal u
b200: 73 65 73 2e 20 20 54 68 65 0a 2a 2a 20 61 72 67  ses.  The.** arg
b210: 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20  ument should be 
b220: 61 20 63 68 61 72 2a 2a 20 77 68 69 63 68 20 77  a char** which w
b230: 69 6c 6c 20 62 65 20 66 69 6c 6c 65 64 20 77 69  ill be filled wi
b240: 74 68 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 0a  th the filename.
b250: 2a 2a 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  ** written into 
b260: 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20  memory obtained 
b270: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
b280: 6c 6c 6f 63 28 29 5d 2e 20 20 54 68 65 20 63 61  lloc()].  The ca
b290: 6c 6c 65 72 20 73 68 6f 75 6c 64 0a 2a 2a 20 69  ller should.** i
b2a0: 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66  nvoke [sqlite3_f
b2b0: 72 65 65 28 29 5d 20 6f 6e 20 74 68 65 20 72 65  ree()] on the re
b2c0: 73 75 6c 74 20 74 6f 20 61 76 6f 69 64 20 61 20  sult to avoid a 
b2d0: 6d 65 6d 6f 72 79 20 6c 65 61 6b 2e 0a 2a 2a 0a  memory leak..**.
b2e0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
b2f0: 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d  FCNTL_MMAP_SIZE]
b300: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
b310: 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45  _FCNTL_MMAP_SIZE
b320: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69  ] file control i
b330: 73 20 75 73 65 64 20 74 6f 20 71 75 65 72 79 20  s used to query 
b340: 6f 72 20 73 65 74 20 74 68 65 0a 2a 2a 20 6d 61  or set the.** ma
b350: 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
b360: 62 79 74 65 73 20 74 68 61 74 20 77 69 6c 6c 20  bytes that will 
b370: 62 65 20 75 73 65 64 20 66 6f 72 20 6d 65 6d 6f  be used for memo
b380: 72 79 2d 6d 61 70 70 65 64 20 49 2f 4f 2e 0a 2a  ry-mapped I/O..*
b390: 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69  * The argument i
b3a0: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
b3b0: 20 76 61 6c 75 65 20 6f 66 20 74 79 70 65 20 73   value of type s
b3c0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 74 68 61  qlite3_int64 tha
b3d0: 74 0a 2a 2a 20 69 73 20 61 6e 20 61 64 76 69 73  t.** is an advis
b3e0: 6f 72 79 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  ory maximum numb
b3f0: 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
b400: 68 65 20 66 69 6c 65 20 74 6f 20 6d 65 6d 6f 72  he file to memor
b410: 79 20 6d 61 70 2e 20 20 54 68 65 0a 2a 2a 20 70  y map.  The.** p
b420: 6f 69 6e 74 65 72 20 69 73 20 6f 76 65 72 77 72  ointer is overwr
b430: 69 74 74 65 6e 20 77 69 74 68 20 74 68 65 20 6f  itten with the o
b440: 6c 64 20 76 61 6c 75 65 2e 20 20 54 68 65 20 6c  ld value.  The l
b450: 69 6d 69 74 20 69 73 20 6e 6f 74 20 63 68 61 6e  imit is not chan
b460: 67 65 64 20 69 66 0a 2a 2a 20 74 68 65 20 76 61  ged if.** the va
b470: 6c 75 65 20 6f 72 69 67 69 6e 61 6c 6c 79 20 70  lue originally p
b480: 6f 69 6e 74 65 64 20 74 6f 20 69 73 20 6e 65 67  ointed to is neg
b490: 61 74 69 76 65 2c 20 61 6e 64 20 73 6f 20 74 68  ative, and so th
b4a0: 65 20 63 75 72 72 65 6e 74 20 6c 69 6d 69 74 20  e current limit 
b4b0: 0a 2a 2a 20 63 61 6e 20 62 65 20 71 75 65 72 69  .** can be queri
b4c0: 65 64 20 62 79 20 70 61 73 73 69 6e 67 20 69 6e  ed by passing in
b4d0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
b4e0: 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2e  negative number.
b4f0: 20 20 54 68 69 73 0a 2a 2a 20 66 69 6c 65 2d 63    This.** file-c
b500: 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 20 69  ontrol is used i
b510: 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 69 6d 70  nternally to imp
b520: 6c 65 6d 65 6e 74 20 5b 50 52 41 47 4d 41 20 6d  lement [PRAGMA m
b530: 6d 61 70 5f 73 69 7a 65 5d 2e 0a 2a 2a 0a 2a 2a  map_size]..**.**
b540: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
b550: 4e 54 4c 5f 54 52 41 43 45 5d 5d 0a 2a 2a 20 54  NTL_TRACE]].** T
b560: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
b570: 5f 54 52 41 43 45 5d 20 66 69 6c 65 20 63 6f 6e  _TRACE] file con
b580: 74 72 6f 6c 20 70 72 6f 76 69 64 65 73 20 61 64  trol provides ad
b590: 76 69 73 6f 72 79 20 69 6e 66 6f 72 6d 61 74 69  visory informati
b5a0: 6f 6e 0a 2a 2a 20 74 6f 20 74 68 65 20 56 46 53  on.** to the VFS
b5b0: 20 61 62 6f 75 74 20 77 68 61 74 20 74 68 65 20   about what the 
b5c0: 68 69 67 68 65 72 20 6c 61 79 65 72 73 20 6f 66  higher layers of
b5d0: 20 74 68 65 20 53 51 4c 69 74 65 20 73 74 61 63   the SQLite stac
b5e0: 6b 20 61 72 65 20 64 6f 69 6e 67 2e 0a 2a 2a 20  k are doing..** 
b5f0: 54 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f  This file contro
b600: 6c 20 69 73 20 75 73 65 64 20 62 79 20 73 6f 6d  l is used by som
b610: 65 20 56 46 53 20 61 63 74 69 76 69 74 79 20 74  e VFS activity t
b620: 72 61 63 69 6e 67 20 5b 73 68 69 6d 73 5d 2e 0a  racing [shims]..
b630: 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20  ** The argument 
b640: 69 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  is a zero-termin
b650: 61 74 65 64 20 73 74 72 69 6e 67 2e 20 20 48 69  ated string.  Hi
b660: 67 68 65 72 20 6c 61 79 65 72 73 20 69 6e 20 74  gher layers in t
b670: 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 73 74 61  he.** SQLite sta
b680: 63 6b 20 6d 61 79 20 67 65 6e 65 72 61 74 65 20  ck may generate 
b690: 69 6e 73 74 61 6e 63 65 73 20 6f 66 20 74 68 69  instances of thi
b6a0: 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69  s file control i
b6b0: 66 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  f.** the [SQLITE
b6c0: 5f 55 53 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45  _USE_FCNTL_TRACE
b6d0: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
b6e0: 70 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64  ption is enabled
b6f0: 2e 0a 2a 2a 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f  ..**.** </ul>.*/
b700: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
b710: 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20  FCNTL_LOCKSTATE 
b720: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 0a                1.
b730: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 47  #define SQLITE_G
b740: 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45  ET_LOCKPROXYFILE
b750: 20 20 20 20 20 20 20 20 20 20 20 20 20 32 0a 23               2.#
b760: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45  define SQLITE_SE
b770: 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20  T_LOCKPROXYFILE 
b780: 20 20 20 20 20 20 20 20 20 20 20 20 33 0a 23 64              3.#d
b790: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 41 53  efine SQLITE_LAS
b7a0: 54 5f 45 52 52 4e 4f 20 20 20 20 20 20 20 20 20  T_ERRNO         
b7b0: 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65             4.#de
b7c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
b7d0: 4c 5f 53 49 5a 45 5f 48 49 4e 54 20 20 20 20 20  L_SIZE_HINT     
b7e0: 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66            5.#def
b7f0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
b800: 5f 43 48 55 4e 4b 5f 53 49 5a 45 20 20 20 20 20  _CHUNK_SIZE     
b810: 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69           6.#defi
b820: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
b830: 46 49 4c 45 5f 50 4f 49 4e 54 45 52 20 20 20 20  FILE_POINTER    
b840: 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e          7.#defin
b850: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53  e SQLITE_FCNTL_S
b860: 59 4e 43 5f 4f 4d 49 54 54 45 44 20 20 20 20 20  YNC_OMITTED     
b870: 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65         8.#define
b880: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49   SQLITE_FCNTL_WI
b890: 4e 33 32 5f 41 56 5f 52 45 54 52 59 20 20 20 20  N32_AV_RETRY    
b8a0: 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20        9.#define 
b8b0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52  SQLITE_FCNTL_PER
b8c0: 53 49 53 54 5f 57 41 4c 20 20 20 20 20 20 20 20  SIST_WAL        
b8d0: 20 20 20 20 31 30 0a 23 64 65 66 69 6e 65 20 53      10.#define S
b8e0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52  QLITE_FCNTL_OVER
b8f0: 57 52 49 54 45 20 20 20 20 20 20 20 20 20 20 20  WRITE           
b900: 20 20 20 31 31 0a 23 64 65 66 69 6e 65 20 53 51     11.#define SQ
b910: 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41  LITE_FCNTL_VFSNA
b920: 4d 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ME              
b930: 20 20 31 32 0a 23 64 65 66 69 6e 65 20 53 51 4c    12.#define SQL
b940: 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53  ITE_FCNTL_POWERS
b950: 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20  AFE_OVERWRITE   
b960: 20 31 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   13.#define SQLI
b970: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 20  TE_FCNTL_PRAGMA 
b980: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
b990: 31 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  14.#define SQLIT
b9a0: 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44  E_FCNTL_BUSYHAND
b9b0: 4c 45 52 20 20 20 20 20 20 20 20 20 20 20 20 31  LER            1
b9c0: 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  5.#define SQLITE
b9d0: 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e  _FCNTL_TEMPFILEN
b9e0: 41 4d 45 20 20 20 20 20 20 20 20 20 20 20 31 36  AME           16
b9f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
ba00: 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 20  FCNTL_MMAP_SIZE 
ba10: 20 20 20 20 20 20 20 20 20 20 20 20 20 31 38 0a               18.
ba20: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
ba30: 43 4e 54 4c 5f 54 52 41 43 45 20 20 20 20 20 20  CNTL_TRACE      
ba40: 20 20 20 20 20 20 20 20 20 20 20 20 31 39 0a 0a              19..
ba50: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
ba60: 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a  Mutex Handle.**.
ba70: 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 6d 6f 64  ** The mutex mod
ba80: 75 6c 65 20 77 69 74 68 69 6e 20 53 51 4c 69 74  ule within SQLit
ba90: 65 20 64 65 66 69 6e 65 73 20 5b 73 71 6c 69 74  e defines [sqlit
baa0: 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65 20  e3_mutex] to be 
bab0: 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74 20 74  an.** abstract t
bac0: 79 70 65 20 66 6f 72 20 61 20 6d 75 74 65 78 20  ype for a mutex 
bad0: 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 53 51 4c  object.  The SQL
bae0: 69 74 65 20 63 6f 72 65 20 6e 65 76 65 72 20 6c  ite core never l
baf0: 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20 69  ooks.** at the i
bb00: 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e  nternal represen
bb10: 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71  tation of an [sq
bb20: 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49  lite3_mutex].  I
bb30: 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20  t only.** deals 
bb40: 77 69 74 68 20 70 6f 69 6e 74 65 72 73 20 74 6f  with pointers to
bb50: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75   the [sqlite3_mu
bb60: 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a  tex] object..**.
bb70: 2a 2a 20 4d 75 74 65 78 65 73 20 61 72 65 20 63  ** Mutexes are c
bb80: 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71  reated using [sq
bb90: 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f  lite3_mutex_allo
bba0: 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  c()]..*/.typedef
bbb0: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
bbc0: 6d 75 74 65 78 20 73 71 6c 69 74 65 33 5f 6d 75  mutex sqlite3_mu
bbd0: 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  tex;../*.** CAPI
bbe0: 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61  3REF: OS Interfa
bbf0: 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20  ce Object.**.** 
bc00: 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  An instance of t
bc10: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f  he sqlite3_vfs o
bc20: 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68  bject defines th
bc30: 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 77  e interface betw
bc40: 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74  een.** the SQLit
bc50: 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65 20 75  e core and the u
bc60: 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61 74  nderlying operat
bc70: 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 68 65  ing system.  The
bc80: 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65   "vfs".** in the
bc90: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a   name of the obj
bca0: 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72 20 22  ect stands for "
bcb0: 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73  virtual file sys
bcc0: 74 65 6d 22 2e 20 20 53 65 65 0a 2a 2a 20 74 68  tem".  See.** th
bcd0: 65 20 5b 56 46 53 20 7c 20 56 46 53 20 64 6f 63  e [VFS | VFS doc
bce0: 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20  umentation] for 
bcf0: 66 75 72 74 68 65 72 20 69 6e 66 6f 72 6d 61 74  further informat
bd00: 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76  ion..**.** The v
bd10: 61 6c 75 65 20 6f 66 20 74 68 65 20 69 56 65 72  alue of the iVer
bd20: 73 69 6f 6e 20 66 69 65 6c 64 20 69 73 20 69 6e  sion field is in
bd30: 69 74 69 61 6c 6c 79 20 31 20 62 75 74 20 6d 61  itially 1 but ma
bd40: 79 20 62 65 20 6c 61 72 67 65 72 20 69 6e 0a 2a  y be larger in.*
bd50: 2a 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e  * future version
bd60: 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 64  s of SQLite.  Ad
bd70: 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20  ditional fields 
bd80: 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20  may be appended 
bd90: 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63  to this.** objec
bda0: 74 20 77 68 65 6e 20 74 68 65 20 69 56 65 72 73  t when the iVers
bdb0: 69 6f 6e 20 76 61 6c 75 65 20 69 73 20 69 6e 63  ion value is inc
bdc0: 72 65 61 73 65 64 2e 20 20 4e 6f 74 65 20 74 68  reased.  Note th
bdd0: 61 74 20 74 68 65 20 73 74 72 75 63 74 75 72 65  at the structure
bde0: 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74  .** of the sqlit
bdf0: 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 63 68  e3_vfs object ch
be00: 61 6e 67 65 73 20 69 6e 20 74 68 65 20 74 72 61  anges in the tra
be10: 6e 73 61 63 74 69 6f 6e 20 62 65 74 77 65 65 6e  nsaction between
be20: 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69  .** SQLite versi
be30: 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e 36  on 3.5.9 and 3.6
be40: 2e 30 20 61 6e 64 20 79 65 74 20 74 68 65 20 69  .0 and yet the i
be50: 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 77 61  Version field wa
be60: 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69 65  s not.** modifie
be70: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f  d..**.** The szO
be80: 73 46 69 6c 65 20 66 69 65 6c 64 20 69 73 20 74  sFile field is t
be90: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 73  he size of the s
bea0: 75 62 63 6c 61 73 73 65 64 20 5b 73 71 6c 69 74  ubclassed [sqlit
beb0: 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75  e3_file].** stru
bec0: 63 74 75 72 65 20 75 73 65 64 20 62 79 20 74 68  cture used by th
bed0: 69 73 20 56 46 53 2e 20 20 6d 78 50 61 74 68 6e  is VFS.  mxPathn
bee0: 61 6d 65 20 69 73 20 74 68 65 20 6d 61 78 69 6d  ame is the maxim
bef0: 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20  um length of.** 
bf00: 61 20 70 61 74 68 6e 61 6d 65 20 69 6e 20 74 68  a pathname in th
bf10: 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65  is VFS..**.** Re
bf20: 67 69 73 74 65 72 65 64 20 73 71 6c 69 74 65 33  gistered sqlite3
bf30: 5f 76 66 73 20 6f 62 6a 65 63 74 73 20 61 72 65  _vfs objects are
bf40: 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65   kept on a linke
bf50: 64 20 6c 69 73 74 20 66 6f 72 6d 65 64 20 62 79  d list formed by
bf60: 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74 20 70 6f  .** the pNext po
bf70: 69 6e 74 65 72 2e 20 20 54 68 65 20 5b 73 71 6c  inter.  The [sql
bf80: 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65  ite3_vfs_registe
bf90: 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c  r()].** and [sql
bfa0: 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73  ite3_vfs_unregis
bfb0: 74 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ter()] interface
bfc0: 73 20 6d 61 6e 61 67 65 20 74 68 69 73 20 6c 69  s manage this li
bfd0: 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65 61  st.** in a threa
bfe0: 64 2d 73 61 66 65 20 77 61 79 2e 20 20 54 68 65  d-safe way.  The
bff0: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69   [sqlite3_vfs_fi
c000: 6e 64 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a  nd()] interface.
c010: 2a 2a 20 73 65 61 72 63 68 65 73 20 74 68 65 20  ** searches the 
c020: 6c 69 73 74 2e 20 20 4e 65 69 74 68 65 72 20 74  list.  Neither t
c030: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63  he application c
c040: 6f 64 65 20 6e 6f 72 20 74 68 65 20 56 46 53 0a  ode nor the VFS.
c050: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
c060: 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 74 68 65  n should use the
c070: 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a   pNext pointer..
c080: 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74 20  **.** The pNext 
c090: 66 69 65 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c  field is the onl
c0a0: 79 20 66 69 65 6c 64 20 69 6e 20 74 68 65 20 73  y field in the s
c0b0: 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74  qlite3_vfs.** st
c0c0: 72 75 63 74 75 72 65 20 74 68 61 74 20 53 51 4c  ructure that SQL
c0d0: 69 74 65 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f  ite will ever mo
c0e0: 64 69 66 79 2e 20 20 53 51 4c 69 74 65 20 77 69  dify.  SQLite wi
c0f0: 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a  ll only access.*
c100: 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73  * or modify this
c110: 20 66 69 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c   field while hol
c120: 64 69 6e 67 20 61 20 70 61 72 74 69 63 75 6c 61  ding a particula
c130: 72 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e 0a  r static mutex..
c140: 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
c150: 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20  on should never 
c160: 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 6e 67 20  modify anything 
c170: 77 69 74 68 69 6e 20 74 68 65 20 73 71 6c 69 74  within the sqlit
c180: 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74  e3_vfs.** object
c190: 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65 63 74   once the object
c1a0: 20 68 61 73 20 62 65 65 6e 20 72 65 67 69 73 74   has been regist
c1b0: 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ered..**.** The 
c1c0: 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64  zName field hold
c1d0: 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
c1e0: 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54  e VFS module.  T
c1f0: 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20  he name must.** 
c200: 62 65 20 75 6e 69 71 75 65 20 61 63 72 6f 73 73  be unique across
c210: 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73   all VFS modules
c220: 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65  ..**.** [[sqlite
c230: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a  3_vfs.xOpen]].**
c240: 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74   ^SQLite guarant
c250: 65 65 73 20 74 68 61 74 20 74 68 65 20 7a 46 69  ees that the zFi
c260: 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72  lename parameter
c270: 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20   to xOpen.** is 
c280: 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f  either a NULL po
c290: 69 6e 74 65 72 20 6f 72 20 73 74 72 69 6e 67 20  inter or string 
c2a0: 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d  obtained.** from
c2b0: 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29   xFullPathname()
c2c0: 20 77 69 74 68 20 61 6e 20 6f 70 74 69 6f 6e 61   with an optiona
c2d0: 6c 20 73 75 66 66 69 78 20 61 64 64 65 64 2e 0a  l suffix added..
c2e0: 2a 2a 20 5e 49 66 20 61 20 73 75 66 66 69 78 20  ** ^If a suffix 
c2f0: 69 73 20 61 64 64 65 64 20 74 6f 20 74 68 65 20  is added to the 
c300: 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65  zFilename parame
c310: 74 65 72 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a 20  ter, it will.** 
c320: 63 6f 6e 73 69 73 74 20 6f 66 20 61 20 73 69 6e  consist of a sin
c330: 67 6c 65 20 22 2d 22 20 63 68 61 72 61 63 74 65  gle "-" characte
c340: 72 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 6e 6f  r followed by no
c350: 20 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a 20 31 31   more than.** 11
c360: 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 61 6e   alphanumeric an
c370: 64 2f 6f 72 20 22 2d 22 20 63 68 61 72 61 63 74  d/or "-" charact
c380: 65 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ers..** ^SQLite 
c390: 66 75 72 74 68 65 72 20 67 75 61 72 61 6e 74 65  further guarante
c3a0: 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 73  es that.** the s
c3b0: 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 76 61  tring will be va
c3c0: 6c 69 64 20 61 6e 64 20 75 6e 63 68 61 6e 67 65  lid and unchange
c3d0: 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29  d until xClose()
c3e0: 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42   is.** called. B
c3f0: 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72  ecause of the pr
c400: 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 2c  evious sentence,
c410: 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33  .** the [sqlite3
c420: 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c  _file] can safel
c430: 79 20 73 74 6f 72 65 20 61 20 70 6f 69 6e 74 65  y store a pointe
c440: 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65  r to the.** file
c450: 6e 61 6d 65 20 69 66 20 69 74 20 6e 65 65 64 73  name if it needs
c460: 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 68 65   to remember the
c470: 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f   filename for so
c480: 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66  me reason..** If
c490: 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70   the zFilename p
c4a0: 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65  arameter to xOpe
c4b0: 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  n is a NULL poin
c4c0: 74 65 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a  ter then xOpen.*
c4d0: 2a 20 6d 75 73 74 20 69 6e 76 65 6e 74 20 69 74  * must invent it
c4e0: 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79 20  s own temporary 
c4f0: 6e 61 6d 65 20 66 6f 72 20 74 68 65 20 66 69 6c  name for the fil
c500: 65 2e 20 20 5e 57 68 65 6e 65 76 65 72 20 74 68  e.  ^Whenever th
c510: 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20  e .** xFilename 
c520: 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c  parameter is NUL
c530: 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62  L it will also b
c540: 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74 20  e the case that 
c550: 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72  the.** flags par
c560: 61 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c  ameter will incl
c570: 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  ude [SQLITE_OPEN
c580: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e  _DELETEONCLOSE].
c590: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73  .**.** The flags
c5a0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70   argument to xOp
c5b0: 65 6e 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c  en() includes al
c5c0: 6c 20 62 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a  l bits set in.**
c5d0: 20 74 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d   the flags argum
c5e0: 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ent to [sqlite3_
c5f0: 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20  open_v2()].  Or 
c600: 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  if [sqlite3_open
c610: 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74  ()].** or [sqlit
c620: 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73 20  e3_open16()] is 
c630: 75 73 65 64 2c 20 74 68 65 6e 20 66 6c 61 67 73  used, then flags
c640: 20 69 6e 63 6c 75 64 65 73 20 61 74 20 6c 65 61   includes at lea
c650: 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  st.** [SQLITE_OP
c660: 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20  EN_READWRITE] | 
c670: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45  [SQLITE_OPEN_CRE
c680: 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f 70  ATE]. .** If xOp
c690: 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 66 69 6c  en() opens a fil
c6a0: 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e  e read-only then
c6b0: 20 69 74 20 73 65 74 73 20 2a 70 4f 75 74 46 6c   it sets *pOutFl
c6c0: 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64  ags to.** includ
c6d0: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  e [SQLITE_OPEN_R
c6e0: 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72  EADONLY].  Other
c6f0: 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c   bits in *pOutFl
c700: 61 67 73 20 6d 61 79 20 62 65 20 73 65 74 2e 0a  ags may be set..
c710: 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 20 77  **.** ^(SQLite w
c720: 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65  ill also add one
c730: 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   of the followin
c740: 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78  g flags to the x
c750: 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20  Open().** call, 
c760: 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65  depending on the
c770: 20 6f 62 6a 65 63 74 20 62 65 69 6e 67 20 6f 70   object being op
c780: 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ened:.**.** <ul>
c790: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
c7a0: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a  E_OPEN_MAIN_DB].
c7b0: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
c7c0: 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e  _OPEN_MAIN_JOURN
c7d0: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  AL].** <li>  [SQ
c7e0: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44  LITE_OPEN_TEMP_D
c7f0: 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  B].** <li>  [SQL
c800: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f  ITE_OPEN_TEMP_JO
c810: 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  URNAL].** <li>  
c820: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41  [SQLITE_OPEN_TRA
c830: 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c  NSIENT_DB].** <l
c840: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
c850: 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20  _SUBJOURNAL].** 
c860: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
c870: 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41  EN_MASTER_JOURNA
c880: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  L].** <li>  [SQL
c890: 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a 2a  ITE_OPEN_WAL].**
c8a0: 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54   </ul>)^.**.** T
c8b0: 68 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c  he file I/O impl
c8c0: 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75  ementation can u
c8d0: 73 65 20 74 68 65 20 6f 62 6a 65 63 74 20 74 79  se the object ty
c8e0: 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63  pe flags to.** c
c8f0: 68 61 6e 67 65 20 74 68 65 20 77 61 79 20 69 74  hange the way it
c900: 20 64 65 61 6c 73 20 77 69 74 68 20 66 69 6c 65   deals with file
c910: 73 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c  s.  For example,
c920: 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a   an application.
c930: 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74  ** that does not
c940: 20 63 61 72 65 20 61 62 6f 75 74 20 63 72 61 73   care about cras
c950: 68 20 72 65 63 6f 76 65 72 79 20 6f 72 20 72 6f  h recovery or ro
c960: 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b  llback might mak
c970: 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66  e.** the open of
c980: 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20   a journal file 
c990: 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73  a no-op.  Writes
c9a0: 20 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c   to this journal
c9b0: 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62   would.** also b
c9c0: 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e  e no-ops, and an
c9d0: 79 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65 61  y attempt to rea
c9e0: 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f  d the journal wo
c9f0: 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51  uld return.** SQ
ca00: 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20  LITE_IOERR.  Or 
ca10: 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  the implementati
ca20: 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e 69  on might recogni
ca30: 7a 65 20 74 68 61 74 20 61 20 64 61 74 61 62 61  ze that a databa
ca40: 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20  se.** file will 
ca50: 62 65 20 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c  be doing page-al
ca60: 69 67 6e 65 64 20 73 65 63 74 6f 72 20 72 65 61  igned sector rea
ca70: 64 73 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e  ds and writes in
ca80: 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64   a random.** ord
ca90: 65 72 20 61 6e 64 20 73 65 74 20 75 70 20 69 74  er and set up it
caa0: 73 20 49 2f 4f 20 73 75 62 73 79 73 74 65 6d 20  s I/O subsystem 
cab0: 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a  accordingly..**.
cac0: 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20  ** SQLite might 
cad0: 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20  also add one of 
cae0: 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c  the following fl
caf0: 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e  ags to the xOpen
cb00: 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c   method:.**.** <
cb10: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  ul>.** <li> [SQL
cb20: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
cb30: 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20  NCLOSE].** <li> 
cb40: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43  [SQLITE_OPEN_EXC
cb50: 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e  LUSIVE].** </ul>
cb60: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  .**.** The [SQLI
cb70: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
cb80: 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e  CLOSE] flag mean
cb90: 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c  s the file shoul
cba0: 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20  d be.** deleted 
cbb0: 77 68 65 6e 20 69 74 20 69 73 20 63 6c 6f 73 65  when it is close
cbc0: 64 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  d.  ^The [SQLITE
cbd0: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
cbe0: 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20  OSE].** will be 
cbf0: 73 65 74 20 66 6f 72 20 54 45 4d 50 20 64 61 74  set for TEMP dat
cc00: 61 62 61 73 65 73 20 61 6e 64 20 74 68 65 69 72  abases and their
cc10: 20 6a 6f 75 72 6e 61 6c 73 2c 20 74 72 61 6e 73   journals, trans
cc20: 69 65 6e 74 0a 2a 2a 20 64 61 74 61 62 61 73 65  ient.** database
cc30: 73 2c 20 61 6e 64 20 73 75 62 6a 6f 75 72 6e 61  s, and subjourna
cc40: 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b  ls..**.** ^The [
cc50: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
cc60: 55 53 49 56 45 5d 20 66 6c 61 67 20 69 73 20 61  USIVE] flag is a
cc70: 6c 77 61 79 73 20 75 73 65 64 20 69 6e 20 63 6f  lways used in co
cc80: 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74  njunction.** wit
cc90: 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  h the [SQLITE_OP
cca0: 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61 67 2c  EN_CREATE] flag,
ccb0: 20 77 68 69 63 68 20 61 72 65 20 62 6f 74 68 20   which are both 
ccc0: 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c  directly.** anal
ccd0: 6f 67 6f 75 73 20 74 6f 20 74 68 65 20 4f 5f 45  ogous to the O_E
cce0: 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41 54 20  XCL and O_CREAT 
ccf0: 66 6c 61 67 73 20 6f 66 20 74 68 65 20 50 4f 53  flags of the POS
cd00: 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 49  IX open().** API
cd10: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 50  .  The SQLITE_OP
cd20: 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 66 6c 61  EN_EXCLUSIVE fla
cd30: 67 2c 20 77 68 65 6e 20 70 61 69 72 65 64 20 77  g, when paired w
cd40: 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49  ith the .** SQLI
cd50: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2c 20  TE_OPEN_CREATE, 
cd60: 69 73 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63  is used to indic
cd70: 61 74 65 20 74 68 61 74 20 66 69 6c 65 20 73 68  ate that file sh
cd80: 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a 20 62  ould always.** b
cd90: 65 20 63 72 65 61 74 65 64 2c 20 61 6e 64 20 74  e created, and t
cda0: 68 61 74 20 69 74 20 69 73 20 61 6e 20 65 72 72  hat it is an err
cdb0: 6f 72 20 69 66 20 69 74 20 61 6c 72 65 61 64 79  or if it already
cdc0: 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74 20 69   exists..** It i
cdd0: 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65  s <i>not</i> use
cde0: 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68  d to indicate th
cdf0: 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65  e file should be
ce00: 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 20   opened .** for 
ce10: 65 78 63 6c 75 73 69 76 65 20 61 63 63 65 73 73  exclusive access
ce20: 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61 73  ..**.** ^At leas
ce30: 74 20 73 7a 4f 73 46 69 6c 65 20 62 79 74 65 73  t szOsFile bytes
ce40: 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65 20 61   of memory are a
ce50: 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c 69  llocated by SQLi
ce60: 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68  te.** to hold th
ce70: 65 20 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  e  [sqlite3_file
ce80: 5d 20 73 74 72 75 63 74 75 72 65 20 70 61 73 73  ] structure pass
ce90: 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64 0a  ed as the third.
cea0: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78  ** argument to x
ceb0: 4f 70 65 6e 2e 20 20 54 68 65 20 78 4f 70 65 6e  Open.  The xOpen
cec0: 20 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74   method does not
ced0: 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f   have to.** allo
cee0: 63 61 74 65 20 74 68 65 20 73 74 72 75 63 74 75  cate the structu
cef0: 72 65 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a 75  re; it should ju
cf00: 73 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e 20 20  st fill it in.  
cf10: 4e 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74 68 65  Note that.** the
cf20: 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6d 75   xOpen method mu
cf30: 73 74 20 73 65 74 20 74 68 65 20 73 71 6c 69 74  st set the sqlit
cf40: 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73  e3_file.pMethods
cf50: 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 61 20   to either.** a 
cf60: 76 61 6c 69 64 20 5b 73 71 6c 69 74 65 33 5f 69  valid [sqlite3_i
cf70: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  o_methods] objec
cf80: 74 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 78  t or to NULL.  x
cf90: 4f 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a 20  Open must do.** 
cfa0: 74 68 69 73 20 65 76 65 6e 20 69 66 20 74 68 65  this even if the
cfb0: 20 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20 53 51   open fails.  SQ
cfc0: 4c 69 74 65 20 65 78 70 65 63 74 73 20 74 68 61  Lite expects tha
cfd0: 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69  t the sqlite3_fi
cfe0: 6c 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 65  le.pMethods.** e
cff0: 6c 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 76  lement will be v
d000: 61 6c 69 64 20 61 66 74 65 72 20 78 4f 70 65 6e  alid after xOpen
d010: 20 72 65 74 75 72 6e 73 20 72 65 67 61 72 64 6c   returns regardl
d020: 65 73 73 20 6f 66 20 74 68 65 20 73 75 63 63 65  ess of the succe
d030: 73 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75 72 65  ss.** or failure
d040: 20 6f 66 20 74 68 65 20 78 4f 70 65 6e 20 63 61   of the xOpen ca
d050: 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69  ll..**.** [[sqli
d060: 74 65 33 5f 76 66 73 2e 78 41 63 63 65 73 73 5d  te3_vfs.xAccess]
d070: 5d 0a 2a 2a 20 5e 54 68 65 20 66 6c 61 67 73 20  ].** ^The flags 
d080: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 41 63 63  argument to xAcc
d090: 65 73 73 28 29 20 6d 61 79 20 62 65 20 5b 53 51  ess() may be [SQ
d0a0: 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53  LITE_ACCESS_EXIS
d0b0: 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 66  TS].** to test f
d0c0: 6f 72 20 74 68 65 20 65 78 69 73 74 65 6e 63 65  or the existence
d0d0: 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72 20 5b   of a file, or [
d0e0: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
d0f0: 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a 20 74  ADWRITE] to.** t
d100: 65 73 74 20 77 68 65 74 68 65 72 20 61 20 66 69  est whether a fi
d110: 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 20 61  le is readable a
d120: 6e 64 20 77 72 69 74 61 62 6c 65 2c 20 6f 72 20  nd writable, or 
d130: 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52  [SQLITE_ACCESS_R
d140: 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20  EAD].** to test 
d150: 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 69  whether a file i
d160: 73 20 61 74 20 6c 65 61 73 74 20 72 65 61 64 61  s at least reada
d170: 62 6c 65 2e 20 20 20 54 68 65 20 66 69 6c 65 20  ble.   The file 
d180: 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69 72 65  can be a.** dire
d190: 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51  ctory..**.** ^SQ
d1a0: 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 61 79 73  Lite will always
d1b0: 20 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c 65 61   allocate at lea
d1c0: 73 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b 31 20  st mxPathname+1 
d1d0: 62 79 74 65 73 20 66 6f 72 20 74 68 65 0a 2a 2a  bytes for the.**
d1e0: 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 20 78   output buffer x
d1f0: 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20 20 54  FullPathname.  T
d200: 68 65 20 65 78 61 63 74 20 73 69 7a 65 20 6f 66  he exact size of
d210: 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66   the output buff
d220: 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20 70 61  er.** is also pa
d230: 73 73 65 64 20 61 73 20 61 20 70 61 72 61 6d 65  ssed as a parame
d240: 74 65 72 20 74 6f 20 62 6f 74 68 20 20 6d 65 74  ter to both  met
d250: 68 6f 64 73 2e 20 49 66 20 74 68 65 20 6f 75 74  hods. If the out
d260: 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73  put buffer.** is
d270: 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f 75 67   not large enoug
d280: 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f  h, [SQLITE_CANTO
d290: 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65 20 72  PEN] should be r
d2a0: 65 74 75 72 6e 65 64 2e 20 53 69 6e 63 65 20 74  eturned. Since t
d2b0: 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64 6c 65  his is.** handle
d2c0: 64 20 61 73 20 61 20 66 61 74 61 6c 20 65 72 72  d as a fatal err
d2d0: 6f 72 20 62 79 20 53 51 4c 69 74 65 2c 20 76 66  or by SQLite, vf
d2e0: 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  s implementation
d2f0: 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 61 76 6f  s should endeavo
d300: 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e 74 20  r.** to prevent 
d310: 74 68 69 73 20 62 79 20 73 65 74 74 69 6e 67 20  this by setting 
d320: 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f 20 61 20  mxPathname to a 
d330: 73 75 66 66 69 63 69 65 6e 74 6c 79 20 6c 61 72  sufficiently lar
d340: 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20  ge value..**.** 
d350: 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28  The xRandomness(
d360: 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 78 43 75  ), xSleep(), xCu
d370: 72 72 65 6e 74 54 69 6d 65 28 29 2c 20 61 6e 64  rrentTime(), and
d380: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74   xCurrentTimeInt
d390: 36 34 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  64().** interfac
d3a0: 65 73 20 61 72 65 20 6e 6f 74 20 73 74 72 69 63  es are not stric
d3b0: 74 6c 79 20 61 20 70 61 72 74 20 6f 66 20 74 68  tly a part of th
d3c0: 65 20 66 69 6c 65 73 79 73 74 65 6d 2c 20 62 75  e filesystem, bu
d3d0: 74 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e  t they are.** in
d3e0: 63 6c 75 64 65 64 20 69 6e 20 74 68 65 20 56 46  cluded in the VF
d3f0: 53 20 73 74 72 75 63 74 75 72 65 20 66 6f 72 20  S structure for 
d400: 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a  completeness..**
d410: 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73   The xRandomness
d420: 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 74 74 65  () function atte
d430: 6d 70 74 73 20 74 6f 20 72 65 74 75 72 6e 20 6e  mpts to return n
d440: 42 79 74 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f  Bytes bytes.** o
d450: 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72  f good-quality r
d460: 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a  andomness into z
d470: 4f 75 74 2e 20 20 54 68 65 20 72 65 74 75 72 6e  Out.  The return
d480: 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65   value is.** the
d490: 20 61 63 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f   actual number o
d4a0: 66 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f  f bytes of rando
d4b0: 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a  mness obtained..
d4c0: 2a 2a 20 54 68 65 20 78 53 6c 65 65 70 28 29 20  ** The xSleep() 
d4d0: 6d 65 74 68 6f 64 20 63 61 75 73 65 73 20 74 68  method causes th
d4e0: 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61 64  e calling thread
d4f0: 20 74 6f 20 73 6c 65 65 70 20 66 6f 72 20 61 74   to sleep for at
d500: 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65 20 6e 75  .** least the nu
d510: 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f 73 65 63  mber of microsec
d520: 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20 5e 54 68  onds given.  ^Th
d530: 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29  e xCurrentTime()
d540: 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72  .** method retur
d550: 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44 61 79 20  ns a Julian Day 
d560: 4e 75 6d 62 65 72 20 66 6f 72 20 74 68 65 20 63  Number for the c
d570: 75 72 72 65 6e 74 20 64 61 74 65 20 61 6e 64 20  urrent date and 
d580: 74 69 6d 65 20 61 73 0a 2a 2a 20 61 20 66 6c 6f  time as.** a flo
d590: 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75  ating point valu
d5a0: 65 2e 0a 2a 2a 20 5e 54 68 65 20 78 43 75 72 72  e..** ^The xCurr
d5b0: 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 6d  entTimeInt64() m
d5c0: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 2c 20 61  ethod returns, a
d5d0: 73 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 68  s an integer, th
d5e0: 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44 61 79 20  e Julian.** Day 
d5f0: 4e 75 6d 62 65 72 20 6d 75 6c 74 69 70 6c 69 65  Number multiplie
d600: 64 20 62 79 20 38 36 34 30 30 30 30 30 20 28 74  d by 86400000 (t
d610: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c  he number of mil
d620: 6c 69 73 65 63 6f 6e 64 73 20 69 6e 20 0a 2a 2a  liseconds in .**
d630: 20 61 20 32 34 2d 68 6f 75 72 20 64 61 79 29 2e   a 24-hour day).
d640: 20 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69    .** ^SQLite wi
d650: 6c 6c 20 75 73 65 20 74 68 65 20 78 43 75 72 72  ll use the xCurr
d660: 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 6d  entTimeInt64() m
d670: 65 74 68 6f 64 20 74 6f 20 67 65 74 20 74 68 65  ethod to get the
d680: 20 63 75 72 72 65 6e 74 0a 2a 2a 20 64 61 74 65   current.** date
d690: 20 61 6e 64 20 74 69 6d 65 20 69 66 20 74 68 61   and time if tha
d6a0: 74 20 6d 65 74 68 6f 64 20 69 73 20 61 76 61 69  t method is avai
d6b0: 6c 61 62 6c 65 20 28 69 66 20 69 56 65 72 73 69  lable (if iVersi
d6c0: 6f 6e 20 69 73 20 32 20 6f 72 20 0a 2a 2a 20 67  on is 2 or .** g
d6d0: 72 65 61 74 65 72 20 61 6e 64 20 74 68 65 20 66  reater and the f
d6e0: 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20  unction pointer 
d6f0: 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 61 6e 64  is not NULL) and
d700: 20 77 69 6c 6c 20 66 61 6c 6c 20 62 61 63 6b 0a   will fall back.
d710: 2a 2a 20 74 6f 20 78 43 75 72 72 65 6e 74 54 69  ** to xCurrentTi
d720: 6d 65 28 29 20 69 66 20 78 43 75 72 72 65 6e 74  me() if xCurrent
d730: 54 69 6d 65 49 6e 74 36 34 28 29 20 69 73 20 75  TimeInt64() is u
d740: 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a  navailable..**.*
d750: 2a 20 5e 54 68 65 20 78 53 65 74 53 79 73 74 65  * ^The xSetSyste
d760: 6d 43 61 6c 6c 28 29 2c 20 78 47 65 74 53 79 73  mCall(), xGetSys
d770: 74 65 6d 43 61 6c 6c 28 29 2c 20 61 6e 64 20 78  temCall(), and x
d780: 4e 65 73 74 53 79 73 74 65 6d 43 61 6c 6c 28 29  NestSystemCall()
d790: 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 61   interfaces.** a
d7a0: 72 65 20 6e 6f 74 20 75 73 65 64 20 62 79 20 74  re not used by t
d7b0: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 2e 20  he SQLite core. 
d7c0: 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 61 6c 20   These optional 
d7d0: 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 70  interfaces are p
d7e0: 72 6f 76 69 64 65 64 0a 2a 2a 20 62 79 20 73 6f  rovided.** by so
d7f0: 6d 65 20 56 46 53 65 73 20 74 6f 20 66 61 63 69  me VFSes to faci
d800: 6c 69 74 61 74 65 20 74 65 73 74 69 6e 67 20 6f  litate testing o
d810: 66 20 74 68 65 20 56 46 53 20 63 6f 64 65 2e 20  f the VFS code. 
d820: 42 79 20 6f 76 65 72 72 69 64 69 6e 67 20 0a 2a  By overriding .*
d830: 2a 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 77  * system calls w
d840: 69 74 68 20 66 75 6e 63 74 69 6f 6e 73 20 75 6e  ith functions un
d850: 64 65 72 20 69 74 73 20 63 6f 6e 74 72 6f 6c 2c  der its control,
d860: 20 61 20 74 65 73 74 20 70 72 6f 67 72 61 6d 20   a test program 
d870: 63 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61 74 65 20  can.** simulate 
d880: 66 61 75 6c 74 73 20 61 6e 64 20 65 72 72 6f 72  faults and error
d890: 20 63 6f 6e 64 69 74 69 6f 6e 73 20 74 68 61 74   conditions that
d8a0: 20 77 6f 75 6c 64 20 6f 74 68 65 72 77 69 73 65   would otherwise
d8b0: 20 62 65 20 64 69 66 66 69 63 75 6c 74 0a 2a 2a   be difficult.**
d8c0: 20 6f 72 20 69 6d 70 6f 73 73 69 62 6c 65 20 74   or impossible t
d8d0: 6f 20 69 6e 64 75 63 65 2e 20 20 54 68 65 20 73  o induce.  The s
d8e0: 65 74 20 6f 66 20 73 79 73 74 65 6d 20 63 61 6c  et of system cal
d8f0: 6c 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 6f  ls that can be o
d900: 76 65 72 72 69 64 64 65 6e 0a 2a 2a 20 76 61 72  verridden.** var
d910: 69 65 73 20 66 72 6f 6d 20 6f 6e 65 20 56 46 53  ies from one VFS
d920: 20 74 6f 20 61 6e 6f 74 68 65 72 2c 20 61 6e 64   to another, and
d930: 20 66 72 6f 6d 20 6f 6e 65 20 76 65 72 73 69 6f   from one versio
d940: 6e 20 6f 66 20 74 68 65 20 73 61 6d 65 20 56 46  n of the same VF
d950: 53 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65 78 74  S to the.** next
d960: 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  .  Applications 
d970: 74 68 61 74 20 75 73 65 20 74 68 65 73 65 20 69  that use these i
d980: 6e 74 65 72 66 61 63 65 73 20 6d 75 73 74 20 62  nterfaces must b
d990: 65 20 70 72 65 70 61 72 65 64 20 66 6f 72 20 61  e prepared for a
d9a0: 6e 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20 6f 66 20  ny.** or all of 
d9b0: 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73  these interfaces
d9c0: 20 74 6f 20 62 65 20 4e 55 4c 4c 20 6f 72 20 66   to be NULL or f
d9d0: 6f 72 20 74 68 65 69 72 20 62 65 68 61 76 69 6f  or their behavio
d9e0: 72 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 66  r to change.** f
d9f0: 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73 65 20  rom one release 
da00: 74 6f 20 74 68 65 20 6e 65 78 74 2e 20 20 41 70  to the next.  Ap
da10: 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73 74 20  plications must 
da20: 6e 6f 74 20 61 74 74 65 6d 70 74 20 74 6f 20 61  not attempt to a
da30: 63 63 65 73 73 0a 2a 2a 20 61 6e 79 20 6f 66 20  ccess.** any of 
da40: 74 68 65 73 65 20 6d 65 74 68 6f 64 73 20 69 66  these methods if
da50: 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 6f 66   the iVersion of
da60: 20 74 68 65 20 56 46 53 20 69 73 20 6c 65 73 73   the VFS is less
da70: 20 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74 79 70 65   than 3..*/.type
da80: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
da90: 65 33 5f 76 66 73 20 73 71 6c 69 74 65 33 5f 76  e3_vfs sqlite3_v
daa0: 66 73 3b 0a 74 79 70 65 64 65 66 20 76 6f 69 64  fs;.typedef void
dab0: 20 28 2a 73 71 6c 69 74 65 33 5f 73 79 73 63 61   (*sqlite3_sysca
dac0: 6c 6c 5f 70 74 72 29 28 76 6f 69 64 29 3b 0a 73  ll_ptr)(void);.s
dad0: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66  truct sqlite3_vf
dae0: 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69  s {.  int iVersi
daf0: 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f  on;            /
db00: 2a 20 53 74 72 75 63 74 75 72 65 20 76 65 72 73  * Structure vers
db10: 69 6f 6e 20 6e 75 6d 62 65 72 20 28 63 75 72 72  ion number (curr
db20: 65 6e 74 6c 79 20 33 29 20 2a 2f 0a 20 20 69 6e  ently 3) */.  in
db30: 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20  t szOsFile;     
db40: 20 20 20 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f         /* Size o
db50: 66 20 73 75 62 63 6c 61 73 73 65 64 20 73 71 6c  f subclassed sql
db60: 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69  ite3_file */.  i
db70: 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20  nt mxPathname;  
db80: 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
db90: 75 6d 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65  um file pathname
dba0: 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c   length */.  sql
dbb0: 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b  ite3_vfs *pNext;
dbc0: 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 20 72 65        /* Next re
dbd0: 67 69 73 74 65 72 65 64 20 56 46 53 20 2a 2f 0a  gistered VFS */.
dbe0: 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e    const char *zN
dbf0: 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61  ame;       /* Na
dc00: 6d 65 20 6f 66 20 74 68 69 73 20 76 69 72 74 75  me of this virtu
dc10: 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 20 2a  al file system *
dc20: 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61  /.  void *pAppDa
dc30: 74 61 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ta;          /* 
dc40: 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 70 6c 69  Pointer to appli
dc50: 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 69 63 20  cation-specific 
dc60: 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  data */.  int (*
dc70: 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76  xOpen)(sqlite3_v
dc80: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
dc90: 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f  *zName, sqlite3_
dca0: 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20 20  file*,.         
dcb0: 20 20 20 20 20 20 69 6e 74 20 66 6c 61 67 73 2c        int flags,
dcc0: 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73 29   int *pOutFlags)
dcd0: 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c 65 74  ;.  int (*xDelet
dce0: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  e)(sqlite3_vfs*,
dcf0: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
dd00: 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 69 72 29  me, int syncDir)
dd10: 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 63 65 73  ;.  int (*xAcces
dd20: 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  s)(sqlite3_vfs*,
dd30: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
dd40: 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c 20 69  me, int flags, i
dd50: 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20  nt *pResOut);.  
dd60: 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e  int (*xFullPathn
dd70: 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ame)(sqlite3_vfs
dd80: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
dd90: 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20  Name, int nOut, 
dda0: 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76  char *zOut);.  v
ddb0: 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28  oid *(*xDlOpen)(
ddc0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
ddd0: 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e  nst char *zFilen
dde0: 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78  ame);.  void (*x
ddf0: 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33  DlError)(sqlite3
de00: 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65  _vfs*, int nByte
de10: 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 29  , char *zErrMsg)
de20: 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78 44 6c  ;.  void (*(*xDl
de30: 53 79 6d 29 28 73 71 6c 69 74 65 33 5f 76 66 73  Sym)(sqlite3_vfs
de40: 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63  *,void*, const c
de50: 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29 28 76  har *zSymbol))(v
de60: 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78  oid);.  void (*x
de70: 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33  DlClose)(sqlite3
de80: 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20  _vfs*, void*);. 
de90: 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e 65   int (*xRandomne
dea0: 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ss)(sqlite3_vfs*
deb0: 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61  , int nByte, cha
dec0: 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20  r *zOut);.  int 
ded0: 28 2a 78 53 6c 65 65 70 29 28 73 71 6c 69 74 65  (*xSleep)(sqlite
dee0: 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72  3_vfs*, int micr
def0: 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74  oseconds);.  int
df00: 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 29   (*xCurrentTime)
df10: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64  (sqlite3_vfs*, d
df20: 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28  ouble*);.  int (
df30: 2a 78 47 65 74 4c 61 73 74 45 72 72 6f 72 29 28  *xGetLastError)(
df40: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e  sqlite3_vfs*, in
df50: 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20 2f 2a  t, char *);.  /*
df60: 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64  .  ** The method
df70: 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76  s above are in v
df80: 65 72 73 69 6f 6e 20 31 20 6f 66 20 74 68 65 20  ersion 1 of the 
df90: 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63  sqlite_vfs objec
dfa0: 74 0a 20 20 2a 2a 20 64 65 66 69 6e 69 74 69 6f  t.  ** definitio
dfb0: 6e 2e 20 20 54 68 6f 73 65 20 74 68 61 74 20 66  n.  Those that f
dfc0: 6f 6c 6c 6f 77 20 61 72 65 20 61 64 64 65 64 20  ollow are added 
dfd0: 69 6e 20 76 65 72 73 69 6f 6e 20 32 20 6f 72 20  in version 2 or 
dfe0: 6c 61 74 65 72 0a 20 20 2a 2f 0a 20 20 69 6e 74  later.  */.  int
dff0: 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 49   (*xCurrentTimeI
e000: 6e 74 36 34 29 28 73 71 6c 69 74 65 33 5f 76 66  nt64)(sqlite3_vf
e010: 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  s*, sqlite3_int6
e020: 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54  4*);.  /*.  ** T
e030: 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65  he methods above
e040: 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73   are in versions
e050: 20 31 20 61 6e 64 20 32 20 6f 66 20 74 68 65 20   1 and 2 of the 
e060: 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63  sqlite_vfs objec
e070: 74 2e 0a 20 20 2a 2a 20 54 68 6f 73 65 20 62 65  t..  ** Those be
e080: 6c 6f 77 20 61 72 65 20 66 6f 72 20 76 65 72 73  low are for vers
e090: 69 6f 6e 20 33 20 61 6e 64 20 67 72 65 61 74 65  ion 3 and greate
e0a0: 72 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  r..  */.  int (*
e0b0: 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28  xSetSystemCall)(
e0c0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
e0d0: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
e0e0: 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c   sqlite3_syscall
e0f0: 5f 70 74 72 29 3b 0a 20 20 73 71 6c 69 74 65 33  _ptr);.  sqlite3
e100: 5f 73 79 73 63 61 6c 6c 5f 70 74 72 20 28 2a 78  _syscall_ptr (*x
e110: 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73  GetSystemCall)(s
e120: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
e130: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b  st char *zName);
e140: 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 28  .  const char *(
e150: 2a 78 4e 65 78 74 53 79 73 74 65 6d 43 61 6c 6c  *xNextSystemCall
e160: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
e170: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
e180: 65 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68  e);.  /*.  ** Th
e190: 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  e methods above 
e1a0: 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20  are in versions 
e1b0: 31 20 74 68 72 6f 75 67 68 20 33 20 6f 66 20 74  1 through 3 of t
e1c0: 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62  he sqlite_vfs ob
e1d0: 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e 65 77 20 66  ject..  ** New f
e1e0: 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70  ields may be app
e1f0: 65 6e 64 65 64 20 69 6e 20 66 69 67 75 72 65 20  ended in figure 
e200: 76 65 72 73 69 6f 6e 73 2e 20 20 54 68 65 20 69  versions.  The i
e210: 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c  Version.  ** val
e220: 75 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e  ue will incremen
e230: 74 20 77 68 65 6e 65 76 65 72 20 74 68 69 73 20  t whenever this 
e240: 68 61 70 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a 7d  happens. .  */.}
e250: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
e260: 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65  F: Flags for the
e270: 20 78 41 63 63 65 73 73 20 56 46 53 20 6d 65 74   xAccess VFS met
e280: 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  hod.**.** These 
e290: 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74  integer constant
e2a0: 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 61 73  s can be used as
e2b0: 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
e2c0: 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78  eter to.** the x
e2d0: 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 6f 66  Access method of
e2e0: 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73   an [sqlite3_vfs
e2f0: 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 79 20  ] object.  They 
e300: 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61  determine.** wha
e310: 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69 73  t kind of permis
e320: 73 69 6f 6e 73 20 74 68 65 20 78 41 63 63 65 73  sions the xAcces
e330: 73 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b  s method is look
e340: 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 68  ing for..** With
e350: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45   SQLITE_ACCESS_E
e360: 58 49 53 54 53 2c 20 74 68 65 20 78 41 63 63 65  XISTS, the xAcce
e370: 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d  ss method.** sim
e380: 70 6c 79 20 63 68 65 63 6b 73 20 77 68 65 74 68  ply checks wheth
e390: 65 72 20 74 68 65 20 66 69 6c 65 20 65 78 69 73  er the file exis
e3a0: 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49  ts..** With SQLI
e3b0: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52  TE_ACCESS_READWR
e3c0: 49 54 45 2c 20 74 68 65 20 78 41 63 63 65 73 73  ITE, the xAccess
e3d0: 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b   method.** check
e3e0: 73 20 77 68 65 74 68 65 72 20 74 68 65 20 6e 61  s whether the na
e3f0: 6d 65 64 20 64 69 72 65 63 74 6f 72 79 20 69 73  med directory is
e400: 20 62 6f 74 68 20 72 65 61 64 61 62 6c 65 20 61   both readable a
e410: 6e 64 20 77 72 69 74 61 62 6c 65 0a 2a 2a 20 28  nd writable.** (
e420: 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  in other words, 
e430: 69 66 20 66 69 6c 65 73 20 63 61 6e 20 62 65 20  if files can be 
e440: 61 64 64 65 64 2c 20 72 65 6d 6f 76 65 64 2c 20  added, removed, 
e450: 61 6e 64 20 72 65 6e 61 6d 65 64 20 77 69 74 68  and renamed with
e460: 69 6e 0a 2a 2a 20 74 68 65 20 64 69 72 65 63 74  in.** the direct
e470: 6f 72 79 29 2e 0a 2a 2a 20 54 68 65 20 53 51 4c  ory)..** The SQL
e480: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
e490: 52 49 54 45 20 63 6f 6e 73 74 61 6e 74 20 69 73  RITE constant is
e4a0: 20 63 75 72 72 65 6e 74 6c 79 20 75 73 65 64 20   currently used 
e4b0: 6f 6e 6c 79 20 62 79 20 74 68 65 0a 2a 2a 20 5b  only by the.** [
e4c0: 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63  temp_store_direc
e4d0: 74 6f 72 79 20 70 72 61 67 6d 61 5d 2c 20 74 68  tory pragma], th
e4e0: 6f 75 67 68 20 74 68 69 73 20 63 6f 75 6c 64 20  ough this could 
e4f0: 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75 74 75  change in a futu
e500: 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66  re.** release of
e510: 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 57 69 74 68   SQLite..** With
e520: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
e530: 45 41 44 2c 20 74 68 65 20 78 41 63 63 65 73 73  EAD, the xAccess
e540: 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b   method.** check
e550: 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69  s whether the fi
e560: 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 2e 20  le is readable. 
e570: 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45   The SQLITE_ACCE
e580: 53 53 5f 52 45 41 44 20 63 6f 6e 73 74 61 6e 74  SS_READ constant
e590: 20 69 73 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79   is.** currently
e5a0: 20 75 6e 75 73 65 64 2c 20 74 68 6f 75 67 68 20   unused, though 
e5b0: 69 74 20 6d 69 67 68 74 20 62 65 20 75 73 65 64  it might be used
e5c0: 20 69 6e 20 61 20 66 75 74 75 72 65 20 72 65 6c   in a future rel
e5d0: 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74  ease of.** SQLit
e5e0: 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  e..*/.#define SQ
e5f0: 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53  LITE_ACCESS_EXIS
e600: 54 53 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20  TS    0.#define 
e610: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
e620: 41 44 57 52 49 54 45 20 31 20 20 20 2f 2a 20 55  ADWRITE 1   /* U
e630: 73 65 64 20 62 79 20 50 52 41 47 4d 41 20 74 65  sed by PRAGMA te
e640: 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f  mp_store_directo
e650: 72 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ry */.#define SQ
e660: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
e670: 20 20 20 20 20 20 32 20 20 20 2f 2a 20 55 6e 75        2   /* Unu
e680: 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  sed */../*.** CA
e690: 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f  PI3REF: Flags fo
e6a0: 72 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20 56  r the xShmLock V
e6b0: 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20  FS method.**.** 
e6c0: 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f  These integer co
e6d0: 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 74  nstants define t
e6e0: 68 65 20 76 61 72 69 6f 75 73 20 6c 6f 63 6b 69  he various locki
e6f0: 6e 67 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a  ng operations.**
e700: 20 61 6c 6c 6f 77 65 64 20 62 79 20 74 68 65 20   allowed by the 
e710: 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20  xShmLock method 
e720: 6f 66 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  of [sqlite3_io_m
e730: 65 74 68 6f 64 73 5d 2e 20 20 54 68 65 0a 2a 2a  ethods].  The.**
e740: 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 72 65 20 74   following are t
e750: 68 65 20 6f 6e 6c 79 20 6c 65 67 61 6c 20 63 6f  he only legal co
e760: 6d 62 69 6e 61 74 69 6f 6e 73 20 6f 66 20 66 6c  mbinations of fl
e770: 61 67 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53  ags to the.** xS
e780: 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a 2a  hmLock method:.*
e790: 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
e7a0: 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f  >  SQLITE_SHM_LO
e7b0: 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f  CK | SQLITE_SHM_
e7c0: 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20  SHARED.** <li>  
e7d0: 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20  SQLITE_SHM_LOCK 
e7e0: 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43  | SQLITE_SHM_EXC
e7f0: 4c 55 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20  LUSIVE.** <li>  
e800: 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43  SQLITE_SHM_UNLOC
e810: 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53  K | SQLITE_SHM_S
e820: 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53  HARED.** <li>  S
e830: 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b  QLITE_SHM_UNLOCK
e840: 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58   | SQLITE_SHM_EX
e850: 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c 3e  CLUSIVE.** </ul>
e860: 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c 6f  .**.** When unlo
e870: 63 6b 69 6e 67 2c 20 74 68 65 20 73 61 6d 65 20  cking, the same 
e880: 53 48 41 52 45 44 20 6f 72 20 45 58 43 4c 55 53  SHARED or EXCLUS
e890: 49 56 45 20 66 6c 61 67 20 6d 75 73 74 20 62 65  IVE flag must be
e8a0: 20 73 75 70 70 6c 69 65 64 20 61 73 0a 2a 2a 20   supplied as.** 
e8b0: 77 61 73 20 67 69 76 65 6e 20 6e 6f 20 74 68 65  was given no the
e8c0: 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6c   corresponding l
e8d0: 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65  ock.  .**.** The
e8e0: 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64   xShmLock method
e8f0: 20 63 61 6e 20 74 72 61 6e 73 69 74 69 6f 6e 20   can transition 
e900: 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64  between unlocked
e910: 20 61 6e 64 20 53 48 41 52 45 44 20 6f 72 0a 2a   and SHARED or.*
e920: 2a 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b  * between unlock
e930: 65 64 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45  ed and EXCLUSIVE
e940: 2e 20 20 49 74 20 63 61 6e 6e 6f 74 20 74 72 61  .  It cannot tra
e950: 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20  nsition between 
e960: 53 48 41 52 45 44 0a 2a 2a 20 61 6e 64 20 45 58  SHARED.** and EX
e970: 43 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23 64 65 66  CLUSIVE..*/.#def
e980: 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55  ine SQLITE_SHM_U
e990: 4e 4c 4f 43 4b 20 20 20 20 20 20 20 31 0a 23 64  NLOCK       1.#d
e9a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d  efine SQLITE_SHM
e9b0: 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 32 0a  _LOCK         2.
e9c0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
e9d0: 48 4d 5f 53 48 41 52 45 44 20 20 20 20 20 20 20  HM_SHARED       
e9e0: 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
e9f0: 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 20 20  _SHM_EXCLUSIVE  
ea00: 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33    8../*.** CAPI3
ea10: 52 45 46 3a 20 4d 61 78 69 6d 75 6d 20 78 53 68  REF: Maximum xSh
ea20: 6d 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a 2a  mLock index.**.*
ea30: 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d  * The xShmLock m
ea40: 65 74 68 6f 64 20 6f 6e 20 5b 73 71 6c 69 74 65  ethod on [sqlite
ea50: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d 61  3_io_methods] ma
ea60: 79 20 75 73 65 20 76 61 6c 75 65 73 0a 2a 2a 20  y use values.** 
ea70: 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68  between 0 and th
ea80: 69 73 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61  is upper bound a
ea90: 73 20 69 74 73 20 22 6f 66 66 73 65 74 22 20 61  s its "offset" a
eaa0: 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20  rgument..** The 
eab0: 53 51 4c 69 74 65 20 63 6f 72 65 20 77 69 6c 6c  SQLite core will
eac0: 20 6e 65 76 65 72 20 61 74 74 65 6d 70 74 20 74   never attempt t
ead0: 6f 20 61 63 71 75 69 72 65 20 6f 72 20 72 65 6c  o acquire or rel
eae0: 65 61 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20 6f  ease a.** lock o
eaf0: 75 74 73 69 64 65 20 6f 66 20 74 68 69 73 20 72  utside of this r
eb00: 61 6e 67 65 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ange.*/.#define 
eb10: 53 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43 4b  SQLITE_SHM_NLOCK
eb20: 20 20 20 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a 2a          8.../*.*
eb30: 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 69 74  * CAPI3REF: Init
eb40: 69 61 6c 69 7a 65 20 54 68 65 20 53 51 4c 69 74  ialize The SQLit
eb50: 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20  e Library.**.** 
eb60: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  ^The sqlite3_ini
eb70: 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e  tialize() routin
eb80: 65 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68  e initializes th
eb90: 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69 62 72  e.** SQLite libr
eba0: 61 72 79 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  ary.  ^The sqlit
ebb0: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 72 6f  e3_shutdown() ro
ebc0: 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63  utine.** dealloc
ebd0: 61 74 65 73 20 61 6e 79 20 72 65 73 6f 75 72 63  ates any resourc
ebe0: 65 73 20 74 68 61 74 20 77 65 72 65 20 61 6c 6c  es that were all
ebf0: 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69 74 65  ocated by sqlite
ec00: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a  3_initialize()..
ec10: 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
ec20: 73 20 61 72 65 20 64 65 73 69 67 6e 65 64 20 74  s are designed t
ec30: 6f 20 61 69 64 20 69 6e 20 70 72 6f 63 65 73 73  o aid in process
ec40: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
ec50: 61 6e 64 0a 2a 2a 20 73 68 75 74 64 6f 77 6e 20  and.** shutdown 
ec60: 6f 6e 20 65 6d 62 65 64 64 65 64 20 73 79 73 74  on embedded syst
ec70: 65 6d 73 2e 20 20 57 6f 72 6b 73 74 61 74 69 6f  ems.  Workstatio
ec80: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 75  n applications u
ec90: 73 69 6e 67 0a 2a 2a 20 53 51 4c 69 74 65 20 6e  sing.** SQLite n
eca0: 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 6e  ormally do not n
ecb0: 65 65 64 20 74 6f 20 69 6e 76 6f 6b 65 20 65 69  eed to invoke ei
ecc0: 74 68 65 72 20 6f 66 20 74 68 65 73 65 20 72 6f  ther of these ro
ecd0: 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20  utines..**.** A 
ece0: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
ecf0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20  initialize() is 
ed00: 61 6e 20 22 65 66 66 65 63 74 69 76 65 22 20 63  an "effective" c
ed10: 61 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a 2a 20  all if it is.** 
ed20: 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73  the first time s
ed30: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
ed40: 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 64  e() is invoked d
ed50: 75 72 69 6e 67 20 74 68 65 20 6c 69 66 65 74 69  uring the lifeti
ed60: 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70 72 6f  me of.** the pro
ed70: 63 65 73 73 2c 20 6f 72 20 69 66 20 69 74 20 69  cess, or if it i
ed80: 73 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65  s the first time
ed90: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
eda0: 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ize() is invoked
edb0: 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20  .** following a 
edc0: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
edd0: 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 5e 28 4f  shutdown().  ^(O
ede0: 6e 6c 79 20 61 6e 20 65 66 66 65 63 74 69 76 65  nly an effective
edf0: 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69   call.** of sqli
ee00: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
ee10: 20 64 6f 65 73 20 61 6e 79 20 69 6e 69 74 69 61   does any initia
ee20: 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f  lization.  All o
ee30: 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 72  ther calls.** ar
ee40: 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70  e harmless no-op
ee50: 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c  s.)^.**.** A cal
ee60: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75  l to sqlite3_shu
ee70: 74 64 6f 77 6e 28 29 20 69 73 20 61 6e 20 22 65  tdown() is an "e
ee80: 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69  ffective" call i
ee90: 66 20 69 74 20 69 73 20 74 68 65 20 66 69 72 73  f it is the firs
eea0: 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 71 6c  t.** call to sql
eeb0: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
eec0: 73 69 6e 63 65 20 74 68 65 20 6c 61 73 74 20 73  since the last s
eed0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
eee0: 65 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a 20  e().  ^(Only.** 
eef0: 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61 6c  an effective cal
ef00: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75  l to sqlite3_shu
ef10: 74 64 6f 77 6e 28 29 20 64 6f 65 73 20 61 6e 79  tdown() does any
ef20: 20 64 65 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f   deinitializatio
ef30: 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65 72 20  n..** All other 
ef40: 76 61 6c 69 64 20 63 61 6c 6c 73 20 74 6f 20 73  valid calls to s
ef50: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
ef60: 29 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e  ) are harmless n
ef70: 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54  o-ops.)^.**.** T
ef80: 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  he sqlite3_initi
ef90: 61 6c 69 7a 65 28 29 20 69 6e 74 65 72 66 61 63  alize() interfac
efa0: 65 20 69 73 20 74 68 72 65 61 64 73 61 66 65 2c  e is threadsafe,
efb0: 20 62 75 74 20 73 71 6c 69 74 65 33 5f 73 68 75   but sqlite3_shu
efc0: 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 73 20 6e 6f  tdown().** is no
efd0: 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  t.  The sqlite3_
efe0: 73 68 75 74 64 6f 77 6e 28 29 20 69 6e 74 65 72  shutdown() inter
eff0: 66 61 63 65 20 6d 75 73 74 20 6f 6e 6c 79 20 62  face must only b
f000: 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 0a  e called from a.
f010: 2a 2a 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64  ** single thread
f020: 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 5b 64 61 74  .  All open [dat
f030: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
f040: 73 5d 20 6d 75 73 74 20 62 65 20 63 6c 6f 73 65  s] must be close
f050: 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74 68  d and all.** oth
f060: 65 72 20 53 51 4c 69 74 65 20 72 65 73 6f 75 72  er SQLite resour
f070: 63 65 73 20 6d 75 73 74 20 62 65 20 64 65 61 6c  ces must be deal
f080: 6c 6f 63 61 74 65 64 20 70 72 69 6f 72 20 74 6f  located prior to
f090: 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c   invoking.** sql
f0a0: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e  ite3_shutdown().
f0b0: 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68  .**.** Among oth
f0c0: 65 72 20 74 68 69 6e 67 73 2c 20 5e 73 71 6c 69  er things, ^sqli
f0d0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
f0e0: 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20   will invoke.** 
f0f0: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
f100: 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c 20 5e  ).  Similarly, ^
f110: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
f120: 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f 6b  ().** will invok
f130: 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  e sqlite3_os_end
f140: 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ()..**.** ^The s
f150: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
f160: 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  e() routine retu
f170: 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  rns [SQLITE_OK] 
f180: 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a 20 5e  on success..** ^
f190: 49 66 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73  If for some reas
f1a0: 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  on, sqlite3_init
f1b0: 69 61 6c 69 7a 65 28 29 20 69 73 20 75 6e 61 62  ialize() is unab
f1c0: 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65  le to initialize
f1d0: 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61 72 79 20  .** the library 
f1e0: 28 70 65 72 68 61 70 73 20 69 74 20 69 73 20 75  (perhaps it is u
f1f0: 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74  nable to allocat
f200: 65 20 61 20 6e 65 65 64 65 64 20 72 65 73 6f 75  e a needed resou
f210: 72 63 65 20 73 75 63 68 0a 2a 2a 20 61 73 20 61  rce such.** as a
f220: 20 6d 75 74 65 78 29 20 69 74 20 72 65 74 75 72   mutex) it retur
f230: 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64  ns an [error cod
f240: 65 5d 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  e] other than [S
f250: 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a  QLITE_OK]..**.**
f260: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
f270: 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69  itialize() routi
f280: 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 69 6e 74  ne is called int
f290: 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20  ernally by many 
f2a0: 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20  other.** SQLite 
f2b0: 69 6e 74 65 72 66 61 63 65 73 20 73 6f 20 74 68  interfaces so th
f2c0: 61 74 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  at an applicatio
f2d0: 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e  n usually does n
f2e0: 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e  ot need to.** in
f2f0: 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  voke sqlite3_ini
f300: 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74  tialize() direct
f310: 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65  ly.  For example
f320: 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  , [sqlite3_open(
f330: 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69  )].** calls sqli
f340: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
f350: 20 73 6f 20 74 68 65 20 53 51 4c 69 74 65 20 6c   so the SQLite l
f360: 69 62 72 61 72 79 20 77 69 6c 6c 20 62 65 20 61  ibrary will be a
f370: 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20  utomatically.** 
f380: 69 6e 69 74 69 61 6c 69 7a 65 64 20 77 68 65 6e  initialized when
f390: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
f3a0: 5d 20 69 73 20 63 61 6c 6c 65 64 20 69 66 20 69  ] is called if i
f3b0: 74 20 68 61 73 20 6e 6f 74 20 62 65 20 69 6e 69  t has not be ini
f3c0: 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65  tialized.** alre
f3d0: 61 64 79 2e 20 20 5e 48 6f 77 65 76 65 72 2c 20  ady.  ^However, 
f3e0: 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  if SQLite is com
f3f0: 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 20 5b  piled with the [
f400: 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f  SQLITE_OMIT_AUTO
f410: 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65  INIT].** compile
f420: 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 68  -time option, th
f430: 65 6e 20 74 68 65 20 61 75 74 6f 6d 61 74 69 63  en the automatic
f440: 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
f450: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a  3_initialize().*
f460: 2a 20 61 72 65 20 6f 6d 69 74 74 65 64 20 61 6e  * are omitted an
f470: 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  d the applicatio
f480: 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73 71 6c 69  n must call sqli
f490: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
f4a0: 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70 72 69   directly.** pri
f4b0: 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20  or to using any 
f4c0: 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74  other SQLite int
f4d0: 65 72 66 61 63 65 2e 20 20 46 6f 72 20 6d 61 78  erface.  For max
f4e0: 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69 74 79  imum portability
f4f0: 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65 63 6f 6d  ,.** it is recom
f500: 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c  mended that appl
f510: 69 63 61 74 69 6f 6e 73 20 61 6c 77 61 79 73 20  ications always 
f520: 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69  invoke sqlite3_i
f530: 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 64  nitialize().** d
f540: 69 72 65 63 74 6c 79 20 70 72 69 6f 72 20 74 6f  irectly prior to
f550: 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72   using any other
f560: 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
f570: 65 2e 20 20 46 75 74 75 72 65 20 72 65 6c 65 61  e.  Future relea
f580: 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65  ses.** of SQLite
f590: 20 6d 61 79 20 72 65 71 75 69 72 65 20 74 68 69   may require thi
f5a0: 73 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  s.  In other wor
f5b0: 64 73 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72  ds, the behavior
f5c0: 20 65 78 68 69 62 69 74 65 64 0a 2a 2a 20 77 68   exhibited.** wh
f5d0: 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  en SQLite is com
f5e0: 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49  piled with [SQLI
f5f0: 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54  TE_OMIT_AUTOINIT
f600: 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d 65 20 74  ] might become t
f610: 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20 62 65  he.** default be
f620: 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65 20 66  havior in some f
f630: 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66  uture release of
f640: 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54   SQLite..**.** T
f650: 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  he sqlite3_os_in
f660: 69 74 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65  it() routine doe
f670: 73 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74  s operating-syst
f680: 65 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 69  em specific.** i
f690: 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66  nitialization of
f6a0: 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72   the SQLite libr
f6b0: 61 72 79 2e 20 20 54 68 65 20 73 71 6c 69 74 65  ary.  The sqlite
f6c0: 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f  3_os_end().** ro
f6d0: 75 74 69 6e 65 20 75 6e 64 6f 65 73 20 74 68 65  utine undoes the
f6e0: 20 65 66 66 65 63 74 20 6f 66 20 73 71 6c 69 74   effect of sqlit
f6f0: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 54  e3_os_init().  T
f700: 79 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a 2a 20  ypical tasks.** 
f710: 70 65 72 66 6f 72 6d 65 64 20 62 79 20 74 68 65  performed by the
f720: 73 65 20 72 6f 75 74 69 6e 65 73 20 69 6e 63 6c  se routines incl
f730: 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f  ude allocation o
f740: 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  r deallocation.*
f750: 2a 20 6f 66 20 73 74 61 74 69 63 20 72 65 73 6f  * of static reso
f760: 75 72 63 65 73 2c 20 69 6e 69 74 69 61 6c 69 7a  urces, initializ
f770: 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c 20  ation of global 
f780: 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 65  variables,.** se
f790: 74 74 69 6e 67 20 75 70 20 61 20 64 65 66 61 75  tting up a defau
f7a0: 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  lt [sqlite3_vfs]
f7b0: 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65 74 74   module, or sett
f7c0: 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65 66 61  ing up.** a defa
f7d0: 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ult configuratio
f7e0: 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  n using [sqlite3
f7f0: 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a  _config()]..**.*
f800: 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
f810: 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 69  n should never i
f820: 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 73 71 6c  nvoke either sql
f830: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a  ite3_os_init().*
f840: 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f  * or sqlite3_os_
f850: 65 6e 64 28 29 20 64 69 72 65 63 74 6c 79 2e 20  end() directly. 
f860: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
f870: 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e 76   should only inv
f880: 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69  oke.** sqlite3_i
f890: 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 20  nitialize() and 
f8a0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
f8b0: 28 29 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  ().  The sqlite3
f8c0: 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 6e  _os_init().** in
f8d0: 74 65 72 66 61 63 65 20 69 73 20 63 61 6c 6c 65  terface is calle
f8e0: 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  d automatically 
f8f0: 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  by sqlite3_initi
f900: 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 73  alize() and.** s
f910: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20  qlite3_os_end() 
f920: 69 73 20 63 61 6c 6c 65 64 20 62 79 20 73 71 6c  is called by sql
f930: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e  ite3_shutdown().
f940: 20 20 41 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a    Appropriate.**
f950: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
f960: 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f   for sqlite3_os_
f970: 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74  init() and sqlit
f980: 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 61  e3_os_end().** a
f990: 72 65 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51  re built into SQ
f9a0: 4c 69 74 65 20 77 68 65 6e 20 69 74 20 69 73 20  Lite when it is 
f9b0: 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 55 6e 69  compiled for Uni
f9c0: 78 2c 20 57 69 6e 64 6f 77 73 2c 20 6f 72 20 4f  x, Windows, or O
f9d0: 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63 75  S/2..** When [cu
f9e0: 73 74 6f 6d 20 62 75 69 6c 64 73 20 7c 20 62 75  stom builds | bu
f9f0: 69 6c 74 20 66 6f 72 20 6f 74 68 65 72 20 70 6c  ilt for other pl
fa00: 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73 69  atforms].** (usi
fa10: 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  ng the [SQLITE_O
fa20: 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f 6d 70 69  S_OTHER=1] compi
fa30: 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f  le-time.** optio
fa40: 6e 29 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  n) the applicati
fa50: 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c 79 20 61  on must supply a
fa60: 20 73 75 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d   suitable implem
fa70: 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20  entation for.** 
fa80: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
fa90: 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73  ) and sqlite3_os
faa0: 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61 70 70 6c  _end().  An appl
fab0: 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64  ication-supplied
fac0: 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
fad0: 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73  on of sqlite3_os
fae0: 5f 69 6e 69 74 28 29 20 6f 72 20 73 71 6c 69 74  _init() or sqlit
faf0: 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d  e3_os_end().** m
fb00: 75 73 74 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  ust return [SQLI
fb10: 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73  TE_OK] on succes
fb20: 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72  s and some other
fb30: 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 75 70   [error code] up
fb40: 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a  on.** failure..*
fb50: 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
fb60: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
fb70: 69 7a 65 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54  ize(void);.SQLIT
fb80: 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
fb90: 33 5f 73 68 75 74 64 6f 77 6e 28 76 6f 69 64 29  3_shutdown(void)
fba0: 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
fbb0: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
fbc0: 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41  (void);.SQLITE_A
fbd0: 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  PI int sqlite3_o
fbe0: 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a  s_end(void);../*
fbf0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
fc00: 6e 66 69 67 75 72 69 6e 67 20 54 68 65 20 53 51  nfiguring The SQ
fc10: 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a  Lite Library.**.
fc20: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63  ** The sqlite3_c
fc30: 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63  onfig() interfac
fc40: 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b  e is used to mak
fc50: 65 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75  e global configu
fc60: 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65  ration.** change
fc70: 73 20 74 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f  s to SQLite in o
fc80: 72 64 65 72 20 74 6f 20 74 75 6e 65 20 53 51 4c  rder to tune SQL
fc90: 69 74 65 20 74 6f 20 74 68 65 20 73 70 65 63 69  ite to the speci
fca0: 66 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20  fic needs of.** 
fcb0: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e  the application.
fcc0: 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 63 6f    The default co
fcd0: 6e 66 69 67 75 72 61 74 69 6f 6e 20 69 73 20 72  nfiguration is r
fce0: 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d  ecommended for m
fcf0: 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69  ost.** applicati
fd00: 6f 6e 73 20 61 6e 64 20 73 6f 20 74 68 69 73 20  ons and so this 
fd10: 72 6f 75 74 69 6e 65 20 69 73 20 75 73 75 61 6c  routine is usual
fd20: 6c 79 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 79  ly not necessary
fd30: 2e 20 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76  .  It is.** prov
fd40: 69 64 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20  ided to support 
fd50: 72 61 72 65 20 61 70 70 6c 69 63 61 74 69 6f 6e  rare application
fd60: 73 20 77 69 74 68 20 75 6e 75 73 75 61 6c 20 6e  s with unusual n
fd70: 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  eeds..**.** The 
fd80: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
fd90: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f   interface is no
fda0: 74 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 54  t threadsafe.  T
fdb0: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a  he application.*
fdc0: 2a 20 6d 75 73 74 20 69 6e 73 75 72 65 20 74 68  * must insure th
fdd0: 61 74 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69  at no other SQLi
fde0: 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  te interfaces ar
fdf0: 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68  e invoked by oth
fe00: 65 72 0a 2a 2a 20 74 68 72 65 61 64 73 20 77 68  er.** threads wh
fe10: 69 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ile sqlite3_conf
fe20: 69 67 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e  ig() is running.
fe30: 20 20 46 75 72 74 68 65 72 6d 6f 72 65 2c 20 73    Furthermore, s
fe40: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 0a  qlite3_config().
fe50: 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 69  ** may only be i
fe60: 6e 76 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f 20  nvoked prior to 
fe70: 6c 69 62 72 61 72 79 20 69 6e 69 74 69 61 6c 69  library initiali
fe80: 7a 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20  zation using.** 
fe90: 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c  [sqlite3_initial
fea0: 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20  ize()] or after 
feb0: 73 68 75 74 64 6f 77 6e 20 62 79 20 5b 73 71 6c  shutdown by [sql
fec0: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d  ite3_shutdown()]
fed0: 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33  ..** ^If sqlite3
fee0: 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 63 61 6c  _config() is cal
fef0: 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74  led after [sqlit
ff00: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d  e3_initialize()]
ff10: 20 61 6e 64 20 62 65 66 6f 72 65 0a 2a 2a 20 5b   and before.** [
ff20: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
ff30: 28 29 5d 20 74 68 65 6e 20 69 74 20 77 69 6c 6c  ()] then it will
ff40: 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d   return SQLITE_M
ff50: 49 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20  ISUSE..** Note, 
ff60: 68 6f 77 65 76 65 72 2c 20 74 68 61 74 20 5e 73  however, that ^s
ff70: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
ff80: 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 73  can be called as
ff90: 20 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20   part of the.** 
ffa0: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
ffb0: 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  f an application
ffc0: 2d 64 65 66 69 6e 65 64 20 5b 73 71 6c 69 74 65  -defined [sqlite
ffd0: 33 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a  3_os_init()]..**
ffe0: 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
fff0: 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
10000 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 61 6e  3_config() is an
10010 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 63 6f 6e   integer.** [con
10020 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
10030 6e 5d 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e  n] that determin
10040 65 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f 70 65  es.** what prope
10050 72 74 79 20 6f 66 20 53 51 4c 69 74 65 20 69 73  rty of SQLite is
10060 20 74 6f 20 62 65 20 63 6f 6e 66 69 67 75 72 65   to be configure
10070 64 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 61  d.  Subsequent a
10080 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 72 79  rguments.** vary
10090 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68   depending on th
100a0 65 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  e [configuration
100b0 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74   option].** in t
100c0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
100d0 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 61  t..**.** ^When a
100e0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
100f0 70 74 69 6f 6e 20 69 73 20 73 65 74 2c 20 73 71  ption is set, sq
10100 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 72  lite3_config() r
10110 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
10120 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6f  K]..** ^If the o
10130 70 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e  ption is unknown
10140 20 6f 72 20 53 51 4c 69 74 65 20 69 73 20 75 6e   or SQLite is un
10150 61 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20  able to set the 
10160 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74  option.** then t
10170 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75  his routine retu
10180 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b  rns a non-zero [
10190 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a  error code]..*/.
101a0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
101b0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 69 6e  qlite3_config(in
101c0 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20  t, ...);../*.** 
101d0 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67  CAPI3REF: Config
101e0 75 72 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ure database con
101f0 6e 65 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54  nections.**.** T
10200 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  he sqlite3_db_co
10210 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65  nfig() interface
10220 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65   is used to make
10230 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a   configuration.*
10240 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 61 20 5b  * changes to a [
10250 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
10260 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65 72  ion].  The inter
10270 66 61 63 65 20 69 73 20 73 69 6d 69 6c 61 72 20  face is similar 
10280 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  to.** [sqlite3_c
10290 6f 6e 66 69 67 28 29 5d 20 65 78 63 65 70 74 20  onfig()] except 
102a0 74 68 61 74 20 74 68 65 20 63 68 61 6e 67 65 73  that the changes
102b0 20 61 70 70 6c 79 20 74 6f 20 61 20 73 69 6e 67   apply to a sing
102c0 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  le.** [database 
102d0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70 65  connection] (spe
102e0 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 66 69  cified in the fi
102f0 72 73 74 20 61 72 67 75 6d 65 6e 74 29 2e 0a 2a  rst argument)..*
10300 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  *.** The second 
10310 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
10320 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44 2c  te3_db_config(D,
10330 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a 2a  V,...)  is the.*
10340 2a 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  * [SQLITE_DBCONF
10350 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 7c 20 63  IG_LOOKASIDE | c
10360 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72  onfiguration ver
10370 62 5d 20 2d 20 61 6e 20 69 6e 74 65 67 65 72 20  b] - an integer 
10380 63 6f 64 65 20 0a 2a 2a 20 74 68 61 74 20 69 6e  code .** that in
10390 64 69 63 61 74 65 73 20 77 68 61 74 20 61 73 70  dicates what asp
103a0 65 63 74 20 6f 66 20 74 68 65 20 5b 64 61 74 61  ect of the [data
103b0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
103c0 20 69 73 20 62 65 69 6e 67 20 63 6f 6e 66 69 67   is being config
103d0 75 72 65 64 2e 0a 2a 2a 20 53 75 62 73 65 71 75  ured..** Subsequ
103e0 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 20 76 61  ent arguments va
103f0 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  ry depending on 
10400 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  the configuratio
10410 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43  n verb..**.** ^C
10420 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
10430 64 62 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75  db_config() retu
10440 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66 20  rn SQLITE_OK if 
10450 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 74  and only if.** t
10460 68 65 20 63 61 6c 6c 20 69 73 20 63 6f 6e 73 69  he call is consi
10470 64 65 72 65 64 20 73 75 63 63 65 73 73 66 75 6c  dered successful
10480 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
10490 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f 63  int sqlite3_db_c
104a0 6f 6e 66 69 67 28 73 71 6c 69 74 65 33 2a 2c 20  onfig(sqlite3*, 
104b0 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f  int op, ...);../
104c0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
104d0 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e  emory Allocation
104e0 20 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20   Routines.**.** 
104f0 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  An instance of t
10500 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e  his object defin
10510 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
10520 20 62 65 74 77 65 65 6e 20 53 51 4c 69 74 65 0a   between SQLite.
10530 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c  ** and low-level
10540 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
10550 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a  on routines..**.
10560 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69  ** This object i
10570 73 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f  s used in only o
10580 6e 65 20 70 6c 61 63 65 20 69 6e 20 74 68 65 20  ne place in the 
10590 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
105a0 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74  ..** A pointer t
105b0 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  o an instance of
105c0 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20   this object is 
105d0 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  the argument to.
105e0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
105f0 69 67 28 29 5d 20 77 68 65 6e 20 74 68 65 20 63  ig()] when the c
10600 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
10610 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54  ion is.** [SQLIT
10620 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d  E_CONFIG_MALLOC]
10630 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   or [SQLITE_CONF
10640 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20  IG_GETMALLOC].  
10650 0a 2a 2a 20 42 79 20 63 72 65 61 74 69 6e 67 20  .** By creating 
10660 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
10670 68 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e  his object.** an
10680 64 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20  d passing it to 
10690 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d  [sqlite3_config]
106a0 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  ([SQLITE_CONFIG_
106b0 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 69  MALLOC]).** duri
106c0 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ng configuration
106d0 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  , an application
106e0 20 63 61 6e 20 73 70 65 63 69 66 79 20 61 6e 20   can specify an 
106f0 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d  alternative.** m
10700 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
10710 20 73 75 62 73 79 73 74 65 6d 20 66 6f 72 20 53   subsystem for S
10720 51 4c 69 74 65 20 74 6f 20 75 73 65 20 66 6f 72  QLite to use for
10730 20 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 64   all of its.** d
10740 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65  ynamic memory ne
10750 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  eds..**.** Note 
10760 74 68 61 74 20 53 51 4c 69 74 65 20 63 6f 6d 65  that SQLite come
10770 73 20 77 69 74 68 20 73 65 76 65 72 61 6c 20 5b  s with several [
10780 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20  built-in memory 
10790 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 74  allocators].** t
107a0 68 61 74 20 61 72 65 20 70 65 72 66 65 63 74 6c  hat are perfectl
107b0 79 20 61 64 65 71 75 61 74 65 20 66 6f 72 20 74  y adequate for t
107c0 68 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20  he overwhelming 
107d0 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70 6c  majority of appl
107e0 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20  ications.** and 
107f0 74 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63 74  that this object
10800 20 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20   is only useful 
10810 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69  to a tiny minori
10820 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f  ty of applicatio
10830 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63 69  ns.** with speci
10840 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c  alized memory al
10850 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72 65  location require
10860 6d 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62 6a  ments.  This obj
10870 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75  ect is.** also u
10880 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69  sed during testi
10890 6e 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e 20  ng of SQLite in 
108a0 6f 72 64 65 72 20 74 6f 20 73 70 65 63 69 66 79  order to specify
108b0 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a   an alternative.
108c0 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ** memory alloca
108d0 74 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74  tor that simulat
108e0 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66  es memory out-of
108f0 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f  -memory conditio
10900 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74  ns in.** order t
10910 6f 20 76 65 72 69 66 79 20 74 68 61 74 20 53 51  o verify that SQ
10920 4c 69 74 65 20 72 65 63 6f 76 65 72 73 20 67 72  Lite recovers gr
10930 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75  acefully from su
10940 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73  ch.** conditions
10950 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c  ..**.** The xMal
10960 6c 6f 63 2c 20 78 52 65 61 6c 6c 6f 63 2c 20 61  loc, xRealloc, a
10970 6e 64 20 78 46 72 65 65 20 6d 65 74 68 6f 64 73  nd xFree methods
10980 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20   must work like 
10990 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 2c  the.** malloc(),
109a0 20 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66   realloc() and f
109b0 72 65 65 28 29 20 66 75 6e 63 74 69 6f 6e 73 20  ree() functions 
109c0 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72  from the standar
109d0 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20  d C library..** 
109e0 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65  ^SQLite guarante
109f0 65 73 20 74 68 61 74 20 74 68 65 20 73 65 63 6f  es that the seco
10a00 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  nd argument to.*
10a10 2a 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 61 6c  * xRealloc is al
10a20 77 61 79 73 20 61 20 76 61 6c 75 65 20 72 65 74  ways a value ret
10a30 75 72 6e 65 64 20 62 79 20 61 20 70 72 69 6f 72  urned by a prior
10a40 20 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 75   call to xRoundu
10a50 70 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 73  p..**.** xSize s
10a60 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65  hould return the
10a70 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20   allocated size 
10a80 6f 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  of a memory allo
10a90 63 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f  cation.** previo
10aa0 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72  usly obtained fr
10ab0 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 52  om xMalloc or xR
10ac0 65 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61 6c 6c  ealloc.  The all
10ad0 6f 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a 20 69  ocated size.** i
10ae0 73 20 61 6c 77 61 79 73 20 61 74 20 6c 65 61 73  s always at leas
10af0 74 20 61 73 20 62 69 67 20 61 73 20 74 68 65 20  t as big as the 
10b00 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 20 62  requested size b
10b10 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72  ut may be larger
10b20 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 6f 75  ..**.** The xRou
10b30 6e 64 75 70 20 6d 65 74 68 6f 64 20 72 65 74 75  ndup method retu
10b40 72 6e 73 20 77 68 61 74 20 77 6f 75 6c 64 20 62  rns what would b
10b50 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20  e the allocated 
10b60 73 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d  size of.** a mem
10b70 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 67  ory allocation g
10b80 69 76 65 6e 20 61 20 70 61 72 74 69 63 75 6c 61  iven a particula
10b90 72 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65  r requested size
10ba0 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a  .  Most memory.*
10bb0 2a 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75  * allocators rou
10bc0 6e 64 20 75 70 20 6d 65 6d 6f 72 79 20 61 6c 6c  nd up memory all
10bd0 6f 63 61 74 69 6f 6e 73 20 61 74 20 6c 65 61 73  ocations at leas
10be0 74 20 74 6f 20 74 68 65 20 6e 65 78 74 20 6d 75  t to the next mu
10bf0 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20  ltiple.** of 8. 
10c00 20 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 73   Some allocators
10c10 20 72 6f 75 6e 64 20 75 70 20 74 6f 20 61 20 6c   round up to a l
10c20 61 72 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f  arger multiple o
10c30 72 20 74 6f 20 61 20 70 6f 77 65 72 20 6f 66 20  r to a power of 
10c40 32 2e 0a 2a 2a 20 45 76 65 72 79 20 6d 65 6d 6f  2..** Every memo
10c50 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65  ry allocation re
10c60 71 75 65 73 74 20 63 6f 6d 69 6e 67 20 69 6e 20  quest coming in 
10c70 74 68 72 6f 75 67 68 20 5b 73 71 6c 69 74 65 33  through [sqlite3
10c80 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72  _malloc()].** or
10c90 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
10ca0 63 28 29 5d 20 66 69 72 73 74 20 63 61 6c 6c 73  c()] first calls
10cb0 20 78 52 6f 75 6e 64 75 70 2e 20 20 49 66 20 78   xRoundup.  If x
10cc0 52 6f 75 6e 64 75 70 20 72 65 74 75 72 6e 73 20  Roundup returns 
10cd0 30 2c 20 0a 2a 2a 20 74 68 61 74 20 63 61 75 73  0, .** that caus
10ce0 65 73 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  es the correspon
10cf0 64 69 6e 67 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ding memory allo
10d00 63 61 74 69 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a  cation to fail..
10d10 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74 20  **.** The xInit 
10d20 6d 65 74 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a  method initializ
10d30 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c  es the memory al
10d40 6c 6f 63 61 74 6f 72 2e 20 20 46 6f 72 20 65 78  locator.  For ex
10d50 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67  ample,.** it mig
10d60 68 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20  ht allocate any 
10d70 72 65 71 75 69 72 65 20 6d 75 74 65 78 65 73 20  require mutexes 
10d80 6f 72 20 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e  or initialize in
10d90 74 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73  ternal data.** s
10da0 74 72 75 63 74 75 72 65 73 2e 20 20 54 68 65 20  tructures.  The 
10db0 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64  xShutdown method
10dc0 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64   is invoked (ind
10dd0 69 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b  irectly) by.** [
10de0 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
10df0 28 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20 64  ()] and should d
10e00 65 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65  eallocate any re
10e10 73 6f 75 72 63 65 73 20 61 63 71 75 69 72 65 64  sources acquired
10e20 0a 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20 20 54  .** by xInit.  T
10e30 68 65 20 70 41 70 70 44 61 74 61 20 70 6f 69 6e  he pAppData poin
10e40 74 65 72 20 69 73 20 75 73 65 64 20 61 73 20 74  ter is used as t
10e50 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65  he only paramete
10e60 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e  r to.** xInit an
10e70 64 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a  d xShutdown..**.
10e80 2a 2a 20 53 51 4c 69 74 65 20 68 6f 6c 64 73 20  ** SQLite holds 
10e90 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45  the [SQLITE_MUTE
10ea0 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 45 52 5d  X_STATIC_MASTER]
10eb0 20 6d 75 74 65 78 20 77 68 65 6e 20 69 74 20 69   mutex when it i
10ec0 6e 76 6f 6b 65 73 0a 2a 2a 20 74 68 65 20 78 49  nvokes.** the xI
10ed0 6e 69 74 20 6d 65 74 68 6f 64 2c 20 73 6f 20 74  nit method, so t
10ee0 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20  he xInit method 
10ef0 6e 65 65 64 20 6e 6f 74 20 62 65 20 74 68 72 65  need not be thre
10f00 61 64 73 61 66 65 2e 20 20 54 68 65 0a 2a 2a 20  adsafe.  The.** 
10f10 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64  xShutdown method
10f20 20 69 73 20 6f 6e 6c 79 20 63 61 6c 6c 65 64 20   is only called 
10f30 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73 68  from [sqlite3_sh
10f40 75 74 64 6f 77 6e 28 29 5d 20 73 6f 20 69 74 20  utdown()] so it 
10f50 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64  does.** not need
10f60 20 74 6f 20 62 65 20 74 68 72 65 61 64 73 61 66   to be threadsaf
10f70 65 20 65 69 74 68 65 72 2e 20 20 46 6f 72 20 61  e either.  For a
10f80 6c 6c 20 6f 74 68 65 72 20 6d 65 74 68 6f 64 73  ll other methods
10f90 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64  , SQLite.** hold
10fa0 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55  s the [SQLITE_MU
10fb0 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 5d 20  TEX_STATIC_MEM] 
10fc0 6d 75 74 65 78 20 61 73 20 6c 6f 6e 67 20 61 73  mutex as long as
10fd0 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
10fe0 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
10ff0 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  ] configuration 
11000 6f 70 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64  option is turned
11010 20 6f 6e 20 28 77 68 69 63 68 0a 2a 2a 20 69 74   on (which.** it
11020 20 69 73 20 62 79 20 64 65 66 61 75 6c 74 29 20   is by default) 
11030 61 6e 64 20 73 6f 20 74 68 65 20 6d 65 74 68 6f  and so the metho
11040 64 73 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63  ds are automatic
11050 61 6c 6c 79 20 73 65 72 69 61 6c 69 7a 65 64 2e  ally serialized.
11060 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 69 66 20  .** However, if 
11070 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
11080 45 4d 53 54 41 54 55 53 5d 20 69 73 20 64 69 73  EMSTATUS] is dis
11090 61 62 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20  abled, then the 
110a0 6f 74 68 65 72 0a 2a 2a 20 6d 65 74 68 6f 64 73  other.** methods
110b0 20 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 73   must be threads
110c0 61 66 65 20 6f 72 20 65 6c 73 65 20 6d 61 6b 65  afe or else make
110d0 20 74 68 65 69 72 20 6f 77 6e 20 61 72 72 61 6e   their own arran
110e0 67 65 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a 20 73  gements for.** s
110f0 65 72 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a  erialization..**
11100 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  .** SQLite will 
11110 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 78 49 6e  never invoke xIn
11120 69 74 28 29 20 6d 6f 72 65 20 74 68 61 6e 20 6f  it() more than o
11130 6e 63 65 20 77 69 74 68 6f 75 74 20 61 6e 20 69  nce without an i
11140 6e 74 65 72 76 65 6e 69 6e 67 0a 2a 2a 20 63 61  ntervening.** ca
11150 6c 6c 20 74 6f 20 78 53 68 75 74 64 6f 77 6e 28  ll to xShutdown(
11160 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  )..*/.typedef st
11170 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d  ruct sqlite3_mem
11180 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33  _methods sqlite3
11190 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74  _mem_methods;.st
111a0 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d  ruct sqlite3_mem
111b0 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69  _methods {.  voi
111c0 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e  d *(*xMalloc)(in
111d0 74 29 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 4d  t);         /* M
111e0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
111f0 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76   function */.  v
11200 6f 69 64 20 28 2a 78 46 72 65 65 29 28 76 6f 69  oid (*xFree)(voi
11210 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a  d*);          /*
11220 20 46 72 65 65 20 61 20 70 72 69 6f 72 20 61 6c   Free a prior al
11230 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f  location */.  vo
11240 69 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28  id *(*xRealloc)(
11250 76 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20  void*,int);  /* 
11260 52 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61  Resize an alloca
11270 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  tion */.  int (*
11280 78 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20  xSize)(void*);  
11290 20 20 20 20 20 20 20 20 20 2f 2a 20 52 65 74 75           /* Retu
112a0 72 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61  rn the size of a
112b0 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a  n allocation */.
112c0 20 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70    int (*xRoundup
112d0 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20  )(int);         
112e0 20 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72 65 71   /* Round up req
112f0 75 65 73 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c  uest size to all
11300 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a  ocation size */.
11310 20 20 69 6e 74 20 28 2a 78 49 6e 69 74 29 28 76    int (*xInit)(v
11320 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20  oid*);          
11330 20 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65 20 74   /* Initialize t
11340 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
11350 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a  tor */.  void (*
11360 78 53 68 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a  xShutdown)(void*
11370 29 3b 20 20 20 20 20 20 2f 2a 20 44 65 69 6e 69  );      /* Deini
11380 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f  tialize the memo
11390 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a  ry allocator */.
113a0 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61    void *pAppData
113b0 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ;               
113c0 20 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74 6f 20   /* Argument to 
113d0 78 49 6e 69 74 28 29 20 61 6e 64 20 78 53 68 75  xInit() and xShu
113e0 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f  tdown() */.};../
113f0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
11400 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74  onfiguration Opt
11410 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ions.** KEYWORDS
11420 3a 20 7b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  : {configuration
11430 20 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54   option}.**.** T
11440 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61  hese constants a
11450 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65  re the available
11460 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75   integer configu
11470 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74  ration options t
11480 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61  hat.** can be pa
11490 73 73 65 64 20 61 73 20 74 68 65 20 66 69 72 73  ssed as the firs
114a0 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
114b0 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  e [sqlite3_confi
114c0 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a  g()] interface..
114d0 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67  **.** New config
114e0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
114f0 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
11500 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
11510 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78  of SQLite..** Ex
11520 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61  isting configura
11530 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67  tion options mig
11540 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75  ht be discontinu
11550 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  ed.  Application
11560 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63  s.** should chec
11570 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64  k the return cod
11580 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  e from [sqlite3_
11590 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b  config()] to mak
115a0 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74  e sure that.** t
115b0 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20  he call worked. 
115c0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
115d0 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63  nfig()] interfac
115e0 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a  e will return a.
115f0 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72  ** non-zero [err
11600 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69  or code] if a di
11610 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e  scontinued or un
11620 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67  supported config
11630 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a  uration option.*
11640 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a  * is invoked..**
11650 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51  .** <dl>.** [[SQ
11660 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
11670 4c 45 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53  LETHREAD]] <dt>S
11680 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
11690 47 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a  GLETHREAD</dt>.*
116a0 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20  * <dd>There are 
116b0 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  no arguments to 
116c0 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54  this option.  ^T
116d0 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20  his option sets 
116e0 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e  the.** [threadin
116f0 67 20 6d 6f 64 65 5d 20 74 6f 20 53 69 6e 67 6c  g mode] to Singl
11700 65 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74  e-thread.  In ot
11710 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69  her words, it di
11720 73 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75  sables.** all mu
11730 74 65 78 69 6e 67 20 61 6e 64 20 70 75 74 73 20  texing and puts 
11740 53 51 4c 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f  SQLite into a mo
11750 64 65 20 77 68 65 72 65 20 69 74 20 63 61 6e 20  de where it can 
11760 6f 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a 2a 20  only be used.** 
11770 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65  by a single thre
11780 61 64 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65  ad.   ^If SQLite
11790 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
117a0 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  h.** the [SQLITE
117b0 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51  _THREADSAFE | SQ
117c0 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
117d0 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  0] compile-time 
117e0 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69  option then.** i
117f0 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c  t is not possibl
11800 65 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20  e to change the 
11810 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
11820 20 66 72 6f 6d 20 69 74 73 20 64 65 66 61 75 6c   from its defaul
11830 74 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 53 69  t.** value of Si
11840 6e 67 6c 65 2d 74 68 72 65 61 64 20 61 6e 64 20  ngle-thread and 
11850 73 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  so [sqlite3_conf
11860 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  ig()] will retur
11870 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52  n .** [SQLITE_ER
11880 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77  ROR] if called w
11890 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43  ith the SQLITE_C
118a0 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
118b0 41 44 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74  AD.** configurat
118c0 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e  ion option.</dd>
118d0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
118e0 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
118f0 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  AD]] <dt>SQLITE_
11900 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
11910 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  AD</dt>.** <dd>T
11920 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75  here are no argu
11930 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70  ments to this op
11940 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74  tion.  ^This opt
11950 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20  ion sets the.** 
11960 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
11970 20 74 6f 20 4d 75 6c 74 69 2d 74 68 72 65 61 64   to Multi-thread
11980 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  .  In other word
11990 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a  s, it disables.*
119a0 2a 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64  * mutexing on [d
119b0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
119c0 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65  on] and [prepare
119d0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a  d statement] obj
119e0 65 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70  ects..** The app
119f0 6c 69 63 61 74 69 6f 6e 20 69 73 20 72 65 73 70  lication is resp
11a00 6f 6e 73 69 62 6c 65 20 66 6f 72 20 73 65 72 69  onsible for seri
11a10 61 6c 69 7a 69 6e 67 20 61 63 63 65 73 73 20 74  alizing access t
11a20 6f 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  o.** [database c
11a30 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20  onnections] and 
11a40 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
11a50 65 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74 68 65  ents].  But othe
11a60 72 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65  r mutexes.** are
11a70 20 65 6e 61 62 6c 65 64 20 73 6f 20 74 68 61 74   enabled so that
11a80 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20   SQLite will be 
11a90 73 61 66 65 20 74 6f 20 75 73 65 20 69 6e 20 61  safe to use in a
11aa0 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 0a   multi-threaded.
11ab0 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 61  ** environment a
11ac0 73 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f  s long as no two
11ad0 20 74 68 72 65 61 64 73 20 61 74 74 65 6d 70 74   threads attempt
11ae0 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65   to use the same
11af0 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
11b00 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 74 68 65  nnection] at the
11b10 20 73 61 6d 65 20 74 69 6d 65 2e 20 20 5e 49 66   same time.  ^If
11b20 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
11b30 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
11b40 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
11b50 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45  FE | SQLITE_THRE
11b60 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c  ADSAFE=0] compil
11b70 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68  e-time option th
11b80 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20  en.** it is not 
11b90 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20  possible to set 
11ba0 74 68 65 20 4d 75 6c 74 69 2d 74 68 72 65 61 64  the Multi-thread
11bb0 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
11bc0 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
11bd0 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c  3_config()] will
11be0 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
11bf0 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64  ERROR] if called
11c00 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c   with the.** SQL
11c10 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49  ITE_CONFIG_MULTI
11c20 54 48 52 45 41 44 20 63 6f 6e 66 69 67 75 72 61  THREAD configura
11c30 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64  tion option.</dd
11c40 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
11c50 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a  _CONFIG_SERIALIZ
11c60 45 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  ED]] <dt>SQLITE_
11c70 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
11c80 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
11c90 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d  ere are no argum
11ca0 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74  ents to this opt
11cb0 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69  ion.  ^This opti
11cc0 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b  on sets the.** [
11cd0 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
11ce0 74 6f 20 53 65 72 69 61 6c 69 7a 65 64 2e 20 49  to Serialized. I
11cf0 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74  n other words, t
11d00 68 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c  his option enabl
11d10 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65  es.** all mutexe
11d20 73 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 65 20  s including the 
11d30 72 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74  recursive.** mut
11d40 65 78 65 73 20 6f 6e 20 5b 64 61 74 61 62 61 73  exes on [databas
11d50 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e  e connection] an
11d60 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
11d70 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a  ement] objects..
11d80 2a 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64 65 20  ** In this mode 
11d90 28 77 68 69 63 68 20 69 73 20 74 68 65 20 64 65  (which is the de
11da0 66 61 75 6c 74 20 77 68 65 6e 20 53 51 4c 69 74  fault when SQLit
11db0 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
11dc0 74 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48  th.** [SQLITE_TH
11dd0 52 45 41 44 53 41 46 45 3d 31 5d 29 20 74 68 65  READSAFE=1]) the
11de0 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20   SQLite library 
11df0 77 69 6c 6c 20 69 74 73 65 6c 66 20 73 65 72 69  will itself seri
11e00 61 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20  alize access.** 
11e10 74 6f 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  to [database con
11e20 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70  nections] and [p
11e30 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
11e40 74 73 5d 20 73 6f 20 74 68 61 74 20 74 68 65 0a  ts] so that the.
11e50 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69  ** application i
11e60 73 20 66 72 65 65 20 74 6f 20 75 73 65 20 74 68  s free to use th
11e70 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65  e same [database
11e80 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20   connection] or 
11e90 74 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65  the.** same [pre
11ea0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
11eb0 20 69 6e 20 64 69 66 66 65 72 65 6e 74 20 74 68   in different th
11ec0 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d  reads at the sam
11ed0 65 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53  e time..** ^If S
11ee0 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
11ef0 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53  d with.** the [S
11f00 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
11f10 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44   | SQLITE_THREAD
11f20 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d  SAFE=0] compile-
11f30 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e  time option then
11f40 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f  .** it is not po
11f50 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68  ssible to set th
11f60 65 20 53 65 72 69 61 6c 69 7a 65 64 20 5b 74 68  e Serialized [th
11f70 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e  reading mode] an
11f80 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d.** [sqlite3_co
11f90 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74  nfig()] will ret
11fa0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  urn [SQLITE_ERRO
11fb0 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74  R] if called wit
11fc0 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f  h the.** SQLITE_
11fd0 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
11fe0 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  D configuration 
11ff0 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a  option.</dd>.**.
12000 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
12010 49 47 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e  IG_MALLOC]] <dt>
12020 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
12030 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  LLOC</dt>.** <dd
12040 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20  > ^(This option 
12050 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
12060 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
12070 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
12080 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20  .** instance of 
12090 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  the [sqlite3_mem
120a0 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
120b0 75 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65  ure.  The argume
120c0 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  nt specifies.** 
120d0 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d  alternative low-
120e0 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c  level memory all
120f0 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
12100 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70   to be used in p
12110 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d  lace of.** the m
12120 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
12130 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20   routines built 
12140 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 5e  into SQLite.)^ ^
12150 53 51 4c 69 74 65 20 6d 61 6b 65 73 0a 2a 2a 20  SQLite makes.** 
12160 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20  its own private 
12170 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74  copy of the cont
12180 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  ent of the [sqli
12190 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
121a0 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 62 65   structure.** be
121b0 66 6f 72 65 20 74 68 65 20 5b 73 71 6c 69 74 65  fore the [sqlite
121c0 33 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6c 6c  3_config()] call
121d0 20 72 65 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a   returns.</dd>.*
121e0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
121f0 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d  NFIG_GETMALLOC]]
12200 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
12210 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74  IG_GETMALLOC</dt
12220 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73  >.** <dd> ^(This
12230 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
12240 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
12250 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74  which is a point
12260 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74  er to an.** inst
12270 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c  ance of the [sql
12280 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
12290 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68  ] structure.  Th
122a0 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  e [sqlite3_mem_m
122b0 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63  ethods].** struc
122c0 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77  ture is filled w
122d0 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c  ith the currentl
122e0 79 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f 72 79  y defined memory
122f0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
12300 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20  ines.)^.** This 
12310 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73  option can be us
12320 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74  ed to overload t
12330 68 65 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72  he default memor
12340 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  y allocation.** 
12350 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20  routines with a 
12360 77 72 61 70 70 65 72 20 74 68 61 74 20 73 69 6d  wrapper that sim
12370 75 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 20  ulations memory 
12380 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75  allocation failu
12390 72 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 20  re or.** tracks 
123a0 6d 65 6d 6f 72 79 20 75 73 61 67 65 2c 20 66 6f  memory usage, fo
123b0 72 20 65 78 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e  r example. </dd>
123c0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
123d0 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
123e0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
123f0 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c 2f  NFIG_MEMSTATUS</
12400 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69  dt>.** <dd> ^Thi
12410 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 73  s option takes s
12420 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f  ingle argument o
12430 66 20 74 79 70 65 20 69 6e 74 2c 20 69 6e 74 65  f type int, inte
12440 72 70 72 65 74 65 64 20 61 73 20 61 20 0a 2a 2a  rpreted as a .**
12450 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20   boolean, which 
12460 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62  enables or disab
12470 6c 65 73 20 74 68 65 20 63 6f 6c 6c 65 63 74 69  les the collecti
12480 6f 6e 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c  on of memory all
12490 6f 63 61 74 69 6f 6e 20 0a 2a 2a 20 73 74 61 74  ocation .** stat
124a0 69 73 74 69 63 73 2e 20 5e 28 57 68 65 6e 20 6d  istics. ^(When m
124b0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
124c0 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20   statistics are 
124d0 64 69 73 61 62 6c 65 64 2c 20 74 68 65 20 0a 2a  disabled, the .*
124e0 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69  * following SQLi
124f0 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 62 65  te interfaces be
12500 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61 74 69  come non-operati
12510 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a  onal:.**   <ul>.
12520 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74  **   <li> [sqlit
12530 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
12540 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c  ].**   <li> [sql
12550 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
12560 77 61 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c  water()].**   <l
12570 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74  i> [sqlite3_soft
12580 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 5d  _heap_limit64()]
12590 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69  .**   <li> [sqli
125a0 74 65 33 5f 73 74 61 74 75 73 28 29 5d 0a 2a 2a  te3_status()].**
125b0 20 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d     </ul>)^.** ^M
125c0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
125d0 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20   statistics are 
125e0 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  enabled by defau
125f0 6c 74 20 75 6e 6c 65 73 73 20 53 51 4c 69 74 65  lt unless SQLite
12600 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20   is.** compiled 
12610 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 45 46  with [SQLITE_DEF
12620 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 5d 3d  AULT_MEMSTATUS]=
12630 30 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20  0 in which case 
12640 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61  memory.** alloca
12650 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20  tion statistics 
12660 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20  are disabled by 
12670 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64  default..** </dd
12680 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
12690 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d  _CONFIG_SCRATCH]
126a0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
126b0 46 49 47 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e  FIG_SCRATCH</dt>
126c0 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f  .** <dd> ^This o
126d0 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20  ption specifies 
126e0 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20  a static memory 
126f0 62 75 66 66 65 72 20 74 68 61 74 20 53 51 4c 69  buffer that SQLi
12700 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a  te can use for.*
12710 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79  * scratch memory
12720 2e 20 20 54 68 65 72 65 20 61 72 65 20 74 68 72  .  There are thr
12730 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 20 41  ee arguments:  A
12740 20 70 6f 69 6e 74 65 72 20 61 6e 20 38 2d 62 79   pointer an 8-by
12750 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 6d 65  te.** aligned me
12760 6d 6f 72 79 20 62 75 66 66 65 72 20 66 72 6f 6d  mory buffer from
12770 20 77 68 69 63 68 20 74 68 65 20 73 63 72 61 74   which the scrat
12780 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 77  ch allocations w
12790 69 6c 6c 20 62 65 0a 2a 2a 20 64 72 61 77 6e 2c  ill be.** drawn,
127a0 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63   the size of eac
127b0 68 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61  h scratch alloca
127c0 74 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e  tion (sz),.** an
127d0 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d the maximum nu
127e0 6d 62 65 72 20 6f 66 20 73 63 72 61 74 63 68 20  mber of scratch 
127f0 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 28 4e 29 2e  allocations (N).
12800 20 20 54 68 65 20 73 7a 0a 2a 2a 20 61 72 67 75    The sz.** argu
12810 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 6d  ment must be a m
12820 75 6c 74 69 70 6c 65 20 6f 66 20 31 36 2e 0a 2a  ultiple of 16..*
12830 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
12840 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 70  ment must be a p
12850 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d 62  ointer to an 8-b
12860 79 74 65 20 61 6c 69 67 6e 65 64 20 62 75 66 66  yte aligned buff
12870 65 72 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73  er.** of at leas
12880 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20  t sz*N bytes of 
12890 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69  memory..** ^SQLi
128a0 74 65 20 77 69 6c 6c 20 75 73 65 20 6e 6f 20 6d  te will use no m
128b0 6f 72 65 20 74 68 61 6e 20 74 77 6f 20 73 63 72  ore than two scr
128c0 61 74 63 68 20 62 75 66 66 65 72 73 20 70 65 72  atch buffers per
128d0 20 74 68 72 65 61 64 2e 20 20 53 6f 0a 2a 2a 20   thread.  So.** 
128e0 4e 20 73 68 6f 75 6c 64 20 62 65 20 73 65 74 20  N should be set 
128f0 74 6f 20 74 77 69 63 65 20 74 68 65 20 65 78 70  to twice the exp
12900 65 63 74 65 64 20 6d 61 78 69 6d 75 6d 20 6e 75  ected maximum nu
12910 6d 62 65 72 20 6f 66 20 74 68 72 65 61 64 73 2e  mber of threads.
12920 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c  .** ^SQLite will
12930 20 6e 65 76 65 72 20 72 65 71 75 69 72 65 20 61   never require a
12940 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72 20   scratch buffer 
12950 74 68 61 74 20 69 73 20 6d 6f 72 65 20 74 68 61  that is more tha
12960 6e 20 36 0a 2a 2a 20 74 69 6d 65 73 20 74 68 65  n 6.** times the
12970 20 64 61 74 61 62 61 73 65 20 70 61 67 65 20 73   database page s
12980 69 7a 65 2e 20 5e 49 66 20 53 51 4c 69 74 65 20  ize. ^If SQLite 
12990 6e 65 65 64 73 20 6e 65 65 64 73 20 61 64 64 69  needs needs addi
129a0 74 69 6f 6e 61 6c 0a 2a 2a 20 73 63 72 61 74 63  tional.** scratc
129b0 68 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e 64 20  h memory beyond 
129c0 77 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64  what is provided
129d0 20 62 79 20 74 68 69 73 20 63 6f 6e 66 69 67 75   by this configu
129e0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2c 20 74  ration option, t
129f0 68 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  hen .** [sqlite3
12a00 5f 6d 61 6c 6c 6f 63 28 29 5d 20 77 69 6c 6c 20  _malloc()] will 
12a10 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69  be used to obtai
12a20 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 6e 65 65  n the memory nee
12a30 64 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ded.</dd>.**.** 
12a40 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
12a50 50 41 47 45 43 41 43 48 45 5d 5d 20 3c 64 74 3e  PAGECACHE]] <dt>
12a60 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
12a70 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20  GECACHE</dt>.** 
12a80 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
12a90 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74  n specifies a st
12aa0 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66  atic memory buff
12ab0 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 63  er that SQLite c
12ac0 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68  an use for.** th
12ad0 65 20 64 61 74 61 62 61 73 65 20 70 61 67 65 20  e database page 
12ae0 63 61 63 68 65 20 77 69 74 68 20 74 68 65 20 64  cache with the d
12af0 65 66 61 75 6c 74 20 70 61 67 65 20 63 61 63 68  efault page cach
12b00 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
12b10 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f 6e 66  .  .** This conf
12b20 69 67 75 72 61 74 69 6f 6e 20 73 68 6f 75 6c 64  iguration should
12b30 20 6e 6f 74 20 62 65 20 75 73 65 64 20 69 66 20   not be used if 
12b40 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  an application-d
12b50 65 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63 61  efine page.** ca
12b60 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  che implementati
12b70 6f 6e 20 69 73 20 6c 6f 61 64 65 64 20 75 73 69  on is loaded usi
12b80 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f  ng the SQLITE_CO
12b90 4e 46 49 47 5f 50 43 41 43 48 45 32 20 6f 70 74  NFIG_PCACHE2 opt
12ba0 69 6f 6e 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72  ion..** There ar
12bb0 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74  e three argument
12bc0 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e  s to this option
12bd0 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 38  : A pointer to 8
12be0 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 0a 2a 2a  -byte aligned.**
12bf0 20 6d 65 6d 6f 72 79 2c 20 74 68 65 20 73 69 7a   memory, the siz
12c00 65 20 6f 66 20 65 61 63 68 20 70 61 67 65 20 62  e of each page b
12c10 75 66 66 65 72 20 28 73 7a 29 2c 20 61 6e 64 20  uffer (sz), and 
12c20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 61  the number of pa
12c30 67 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20  ges (N)..** The 
12c40 73 7a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  sz argument shou
12c50 6c 64 20 62 65 20 74 68 65 20 73 69 7a 65 20 6f  ld be the size o
12c60 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 64 61  f the largest da
12c70 74 61 62 61 73 65 20 70 61 67 65 0a 2a 2a 20 28  tabase page.** (
12c80 61 20 70 6f 77 65 72 20 6f 66 20 74 77 6f 20 62  a power of two b
12c90 65 74 77 65 65 6e 20 35 31 32 20 61 6e 64 20 33  etween 512 and 3
12ca0 32 37 36 38 29 20 70 6c 75 73 20 61 20 6c 69 74  2768) plus a lit
12cb0 74 6c 65 20 65 78 74 72 61 20 66 6f 72 20 65 61  tle extra for ea
12cc0 63 68 0a 2a 2a 20 70 61 67 65 20 68 65 61 64 65  ch.** page heade
12cd0 72 2e 20 20 5e 54 68 65 20 70 61 67 65 20 68 65  r.  ^The page he
12ce0 61 64 65 72 20 73 69 7a 65 20 69 73 20 32 30 20  ader size is 20 
12cf0 74 6f 20 34 30 20 62 79 74 65 73 20 64 65 70 65  to 40 bytes depe
12d00 6e 64 69 6e 67 20 6f 6e 0a 2a 2a 20 74 68 65 20  nding on.** the 
12d10 68 6f 73 74 20 61 72 63 68 69 74 65 63 74 75 72  host architectur
12d20 65 2e 20 20 5e 49 74 20 69 73 20 68 61 72 6d 6c  e.  ^It is harml
12d30 65 73 73 2c 20 61 70 61 72 74 20 66 72 6f 6d 20  ess, apart from 
12d40 74 68 65 20 77 61 73 74 65 64 20 6d 65 6d 6f 72  the wasted memor
12d50 79 2c 0a 2a 2a 20 74 6f 20 6d 61 6b 65 20 73 7a  y,.** to make sz
12d60 20 61 20 6c 69 74 74 6c 65 20 74 6f 6f 20 6c 61   a little too la
12d70 72 67 65 2e 20 20 54 68 65 20 66 69 72 73 74 0a  rge.  The first.
12d80 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  ** argument shou
12d90 6c 64 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61  ld point to an a
12da0 6c 6c 6f 63 61 74 69 6f 6e 20 6f 66 20 61 74 20  llocation of at 
12db0 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73  least sz*N bytes
12dc0 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e   of memory..** ^
12dd0 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20  SQLite will use 
12de0 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69  the memory provi
12df0 64 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  ded by the first
12e00 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 61 74   argument to sat
12e10 69 73 66 79 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f  isfy its.** memo
12e20 72 79 20 6e 65 65 64 73 20 66 6f 72 20 74 68 65  ry needs for the
12e30 20 66 69 72 73 74 20 4e 20 70 61 67 65 73 20 74   first N pages t
12e40 68 61 74 20 69 74 20 61 64 64 73 20 74 6f 20 63  hat it adds to c
12e50 61 63 68 65 2e 20 20 5e 49 66 20 61 64 64 69 74  ache.  ^If addit
12e60 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61  ional.** page ca
12e70 63 68 65 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65  che memory is ne
12e80 65 64 65 64 20 62 65 79 6f 6e 64 20 77 68 61 74  eded beyond what
12e90 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20   is provided by 
12ea0 74 68 69 73 20 6f 70 74 69 6f 6e 2c 20 74 68 65  this option, the
12eb0 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 67 6f 65 73  n.** SQLite goes
12ec0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   to [sqlite3_mal
12ed0 6c 6f 63 28 29 5d 20 66 6f 72 20 74 68 65 20 61  loc()] for the a
12ee0 64 64 69 74 69 6f 6e 61 6c 20 73 74 6f 72 61 67  dditional storag
12ef0 65 20 73 70 61 63 65 2e 0a 2a 2a 20 54 68 65 20  e space..** The 
12f00 70 6f 69 6e 74 65 72 20 69 6e 20 74 68 65 20 66  pointer in the f
12f10 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75  irst argument mu
12f20 73 74 0a 2a 2a 20 62 65 20 61 6c 69 67 6e 65 64  st.** be aligned
12f30 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f   to an 8-byte bo
12f40 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65 71  undary or subseq
12f50 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66  uent behavior of
12f60 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20   SQLite.** will 
12f70 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 3c 2f 64  be undefined.</d
12f80 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
12f90 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 5d 5d 20  E_CONFIG_HEAP]] 
12fa0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
12fb0 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c  G_HEAP</dt>.** <
12fc0 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
12fd0 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61   specifies a sta
12fe0 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  tic memory buffe
12ff0 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69  r that SQLite wi
13000 6c 6c 20 75 73 65 0a 2a 2a 20 66 6f 72 20 61 6c  ll use.** for al
13010 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63  l of its dynamic
13020 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
13030 6f 6e 20 6e 65 65 64 73 20 62 65 79 6f 6e 64 20  on needs beyond 
13040 74 68 6f 73 65 20 70 72 6f 76 69 64 65 64 0a 2a  those provided.*
13050 2a 20 66 6f 72 20 62 79 20 5b 53 51 4c 49 54 45  * for by [SQLITE
13060 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d  _CONFIG_SCRATCH]
13070 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 43 4f 4e   and [SQLITE_CON
13080 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a  FIG_PAGECACHE]..
13090 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 68 72  ** There are thr
130a0 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 41 6e  ee arguments: An
130b0 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20   8-byte aligned 
130c0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d  pointer to the m
130d0 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68 65 20 6e 75  emory,.** the nu
130e0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
130f0 20 74 68 65 20 6d 65 6d 6f 72 79 20 62 75 66 66   the memory buff
13100 65 72 2c 20 61 6e 64 20 74 68 65 20 6d 69 6e 69  er, and the mini
13110 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  mum allocation s
13120 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ize..** ^If the 
13130 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74  first pointer (t
13140 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65  he memory pointe
13150 72 29 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  r) is NULL, then
13160 20 53 51 4c 69 74 65 20 72 65 76 65 72 74 73 0a   SQLite reverts.
13170 2a 2a 20 74 6f 20 75 73 69 6e 67 20 69 74 73 20  ** to using its 
13180 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61  default memory a
13190 6c 6c 6f 63 61 74 6f 72 20 28 74 68 65 20 73 79  llocator (the sy
131a0 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d  stem malloc() im
131b0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a  plementation),.*
131c0 2a 20 75 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72  * undoing any pr
131d0 69 6f 72 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f  ior invocation o
131e0 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  f [SQLITE_CONFIG
131f0 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 5e 49 66 20 74  _MALLOC].  ^If t
13200 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f 69  he.** memory poi
13210 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  nter is not NULL
13220 20 61 6e 64 20 65 69 74 68 65 72 20 5b 53 51 4c   and either [SQL
13230 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59  ITE_ENABLE_MEMSY
13240 53 33 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54  S3] or.** [SQLIT
13250 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 35  E_ENABLE_MEMSYS5
13260 5d 20 61 72 65 20 64 65 66 69 6e 65 64 2c 20 74  ] are defined, t
13270 68 65 6e 20 74 68 65 20 61 6c 74 65 72 6e 61 74  hen the alternat
13280 69 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c  ive memory.** al
13290 6c 6f 63 61 74 6f 72 20 69 73 20 65 6e 67 61 67  locator is engag
132a0 65 64 20 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c  ed to handle all
132b0 20 6f 66 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f   of SQLites memo
132c0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65  ry allocation ne
132d0 65 64 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73  eds..** The firs
132e0 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d  t pointer (the m
132f0 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 6d  emory pointer) m
13300 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74  ust be aligned t
13310 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 62  o an 8-byte.** b
13320 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65  oundary or subse
13330 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f  quent behavior o
13340 66 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65  f SQLite will be
13350 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54   undefined..** T
13360 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63  he minimum alloc
13370 61 74 69 6f 6e 20 73 69 7a 65 20 69 73 20 63 61  ation size is ca
13380 70 70 65 64 20 61 74 20 32 2a 2a 31 32 2e 20 52  pped at 2**12. R
13390 65 61 73 6f 6e 61 62 6c 65 20 76 61 6c 75 65 73  easonable values
133a0 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d 69 6e 69  .** for the mini
133b0 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  mum allocation s
133c0 69 7a 65 20 61 72 65 20 32 2a 2a 35 20 74 68 72  ize are 2**5 thr
133d0 6f 75 67 68 20 32 2a 2a 38 2e 3c 2f 64 64 3e 0a  ough 2**8.</dd>.
133e0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
133f0 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 5d 20 3c 64  ONFIG_MUTEX]] <d
13400 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
13410 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  MUTEX</dt>.** <d
13420 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e  d> ^(This option
13430 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
13440 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
13450 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
13460 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66  n.** instance of
13470 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75   the [sqlite3_mu
13480 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  tex_methods] str
13490 75 63 74 75 72 65 2e 20 20 54 68 65 20 61 72 67  ucture.  The arg
134a0 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a  ument specifies.
134b0 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c  ** alternative l
134c0 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20 72  ow-level mutex r
134d0 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73  outines to be us
134e0 65 64 20 69 6e 20 70 6c 61 63 65 0a 2a 2a 20 74  ed in place.** t
134f0 68 65 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65  he mutex routine
13500 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c  s built into SQL
13510 69 74 65 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20  ite.)^  ^SQLite 
13520 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20  makes a copy of 
13530 74 68 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 6f  the.** content o
13540 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
13550 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74  utex_methods] st
13560 72 75 63 74 75 72 65 20 62 65 66 6f 72 65 20 74  ructure before t
13570 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73  he call to.** [s
13580 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
13590 20 72 65 74 75 72 6e 73 2e 20 5e 49 66 20 53 51   returns. ^If SQ
135a0 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
135b0 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
135c0 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
135d0 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
135e0 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
135f0 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
13600 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75  ** the entire mu
13610 74 65 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d  texing subsystem
13620 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d   is omitted from
13630 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68   the build and h
13640 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  ence calls to.**
13650 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
13660 28 29 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c  ()] with the SQL
13670 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
13680 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
13690 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65  ption will.** re
136a0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52  turn [SQLITE_ERR
136b0 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  OR].</dd>.**.** 
136c0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
136d0 47 45 54 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53  GETMUTEX]] <dt>S
136e0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
136f0 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  MUTEX</dt>.** <d
13700 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e  d> ^(This option
13710 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
13720 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
13730 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
13740 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66  n.** instance of
13750 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75   the [sqlite3_mu
13760 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  tex_methods] str
13770 75 63 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20  ucture.  The.** 
13780 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d  [sqlite3_mutex_m
13790 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63  ethods].** struc
137a0 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77  ture is filled w
137b0 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c  ith the currentl
137c0 79 20 64 65 66 69 6e 65 64 20 6d 75 74 65 78 20  y defined mutex 
137d0 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54  routines.)^.** T
137e0 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62  his option can b
137f0 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f  e used to overlo
13800 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d  ad the default m
13810 75 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a  utex allocation.
13820 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68  ** routines with
13830 20 61 20 77 72 61 70 70 65 72 20 75 73 65 64 20   a wrapper used 
13840 74 6f 20 74 72 61 63 6b 20 6d 75 74 65 78 20 75  to track mutex u
13850 73 61 67 65 20 66 6f 72 20 70 65 72 66 6f 72 6d  sage for perform
13860 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e  ance.** profilin
13870 67 20 6f 72 20 74 65 73 74 69 6e 67 2c 20 66 6f  g or testing, fo
13880 72 20 65 78 61 6d 70 6c 65 2e 20 20 20 5e 49 66  r example.   ^If
13890 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
138a0 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
138b0 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
138c0 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45  FE | SQLITE_THRE
138d0 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c  ADSAFE=0] compil
138e0 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68  e-time option th
138f0 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65  en.** the entire
13900 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79 73   mutexing subsys
13910 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66  tem is omitted f
13920 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e  rom the build an
13930 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f  d hence calls to
13940 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
13950 66 69 67 28 29 5d 20 77 69 74 68 20 74 68 65 20  fig()] with the 
13960 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
13970 54 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61  TMUTEX configura
13980 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c  tion option will
13990 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  .** return [SQLI
139a0 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a  TE_ERROR].</dd>.
139b0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
139c0 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d  ONFIG_LOOKASIDE]
139d0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
139e0 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64  FIG_LOOKASIDE</d
139f0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69  t>.** <dd> ^(Thi
13a00 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74  s option takes t
13a10 77 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61  wo arguments tha
13a20 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20  t determine the 
13a30 64 65 66 61 75 6c 74 0a 2a 2a 20 6d 65 6d 6f 72  default.** memor
13a40 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72  y allocation for
13a50 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d   the lookaside m
13a60 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
13a70 6f 6e 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61  on each.** [data
13a80 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
13a90 2e 20 20 54 68 65 20 66 69 72 73 74 20 61 72 67  .  The first arg
13aa0 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20  ument is the.** 
13ab0 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f  size of each loo
13ac0 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c  kaside buffer sl
13ad0 6f 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e  ot and the secon
13ae0 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  d is the number 
13af0 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f  of.** slots allo
13b00 63 61 74 65 64 20 74 6f 20 65 61 63 68 20 64 61  cated to each da
13b10 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
13b20 6e 2e 29 5e 20 20 5e 28 54 68 69 73 20 6f 70 74  n.)^  ^(This opt
13b30 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20  ion sets the.** 
13b40 3c 69 3e 64 65 66 61 75 6c 74 3c 2f 69 3e 20 6c  <i>default</i> l
13b50 6f 6f 6b 61 73 69 64 65 20 73 69 7a 65 2e 20 54  ookaside size. T
13b60 68 65 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e  he [SQLITE_DBCON
13b70 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a  FIG_LOOKASIDE].*
13b80 2a 20 76 65 72 62 20 74 6f 20 5b 73 71 6c 69 74  * verb to [sqlit
13b90 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
13ba0 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63  can be used to c
13bb0 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73  hange the lookas
13bc0 69 64 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61  ide.** configura
13bd0 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75  tion on individu
13be0 61 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29  al connections.)
13bf0 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  ^ </dd>.**.** [[
13c00 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
13c10 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49  ACHE2]] <dt>SQLI
13c20 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
13c30 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  2</dt>.** <dd> ^
13c40 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  (This option tak
13c50 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
13c60 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20  ment which is a 
13c70 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 61 6e  pointer to.** an
13c80 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65   [sqlite3_pcache
13c90 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63  _methods2] objec
13ca0 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20  t.  This object 
13cb0 73 70 65 63 69 66 69 65 73 20 74 68 65 20 69 6e  specifies the in
13cc0 74 65 72 66 61 63 65 0a 2a 2a 20 74 6f 20 61 20  terface.** to a 
13cd0 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61 63 68  custom page cach
13ce0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
13cf0 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b  .)^  ^SQLite mak
13d00 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  es a copy of the
13d10 0a 2a 2a 20 6f 62 6a 65 63 74 20 61 6e 64 20 75  .** object and u
13d20 73 65 73 20 69 74 20 66 6f 72 20 70 61 67 65 20  ses it for page 
13d30 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  cache memory all
13d40 6f 63 61 74 69 6f 6e 73 2e 3c 2f 64 64 3e 0a 2a  ocations.</dd>.*
13d50 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
13d60 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 5d  NFIG_GETPCACHE2]
13d70 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
13d80 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 3c 2f  FIG_GETPCACHE2</
13d90 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
13da0 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
13db0 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
13dc0 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69  t which is a poi
13dd0 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73  nter to an.** [s
13de0 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65  qlite3_pcache_me
13df0 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20  thods2] object. 
13e00 20 53 51 4c 69 74 65 20 63 6f 70 69 65 73 20 6f   SQLite copies o
13e10 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a  f the current.**
13e20 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c   page cache impl
13e30 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74 6f 20  ementation into 
13e40 74 68 61 74 20 6f 62 6a 65 63 74 2e 29 5e 20 3c  that object.)^ <
13e50 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
13e60 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 5d 5d  ITE_CONFIG_LOG]]
13e70 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
13e80 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c  IG_LOG</dt>.** <
13e90 64 64 3e 20 54 68 65 20 53 51 4c 49 54 45 5f 43  dd> The SQLITE_C
13ea0 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e  ONFIG_LOG option
13eb0 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f 6e 66   is used to conf
13ec0 69 67 75 72 65 20 74 68 65 20 53 51 4c 69 74 65  igure the SQLite
13ed0 0a 2a 2a 20 67 6c 6f 62 61 6c 20 5b 65 72 72 6f  .** global [erro
13ee0 72 20 6c 6f 67 5d 2e 0a 2a 2a 20 28 5e 54 68 65  r log]..** (^The
13ef0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c   SQLITE_CONFIG_L
13f00 4f 47 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  OG option takes 
13f10 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 3a 20 61  two arguments: a
13f20 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a 2a 2a   pointer to a.**
13f30 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61   function with a
13f40 20 63 61 6c 6c 20 73 69 67 6e 61 74 75 72 65 20   call signature 
13f50 6f 66 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  of void(*)(void*
13f60 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a  ,int,const char*
13f70 29 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 70 6f 69  ), .** and a poi
13f80 6e 74 65 72 20 74 6f 20 76 6f 69 64 2e 20 5e 49  nter to void. ^I
13f90 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70  f the function p
13fa0 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55  ointer is not NU
13fb0 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 69 6e 76  LL, it is.** inv
13fc0 6f 6b 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  oked by [sqlite3
13fd0 5f 6c 6f 67 28 29 5d 20 74 6f 20 70 72 6f 63 65  _log()] to proce
13fe0 73 73 20 65 61 63 68 20 6c 6f 67 67 69 6e 67 20  ss each logging 
13ff0 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a  event.  ^If the.
14000 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e  ** function poin
14010 74 65 72 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65  ter is NULL, the
14020 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d   [sqlite3_log()]
14030 20 69 6e 74 65 72 66 61 63 65 20 62 65 63 6f 6d   interface becom
14040 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e  es a no-op..** ^
14050 54 68 65 20 76 6f 69 64 20 70 6f 69 6e 74 65 72  The void pointer
14060 20 74 68 61 74 20 69 73 20 74 68 65 20 73 65 63   that is the sec
14070 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ond argument to 
14080 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
14090 47 20 69 73 0a 2a 2a 20 70 61 73 73 65 64 20 74  G is.** passed t
140a0 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 66 69  hrough as the fi
140b0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
140c0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
140d0 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a  -defined logger.
140e0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 6e  ** function when
140f0 65 76 65 72 20 74 68 61 74 20 66 75 6e 63 74 69  ever that functi
14100 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20  on is invoked.  
14110 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61  ^The second para
14120 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20  meter to.** the 
14130 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 20  logger function 
14140 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  is a copy of the
14150 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
14160 20 74 6f 20 74 68 65 20 63 6f 72 72 65 73 70 6f   to the correspo
14170 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  nding.** [sqlite
14180 33 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c 20 61 6e  3_log()] call an
14190 64 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f  d is intended to
141a0 20 62 65 20 61 20 5b 72 65 73 75 6c 74 20 63 6f   be a [result co
141b0 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 78  de] or an.** [ex
141c0 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
141d0 64 65 5d 2e 20 20 5e 54 68 65 20 74 68 69 72 64  de].  ^The third
141e0 20 70 61 72 61 6d 65 74 65 72 20 70 61 73 73 65   parameter passe
141f0 64 20 74 6f 20 74 68 65 20 6c 6f 67 67 65 72 20  d to the logger 
14200 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73 61 67  is.** log messag
14210 65 20 61 66 74 65 72 20 66 6f 72 6d 61 74 74 69  e after formatti
14220 6e 67 20 76 69 61 20 5b 73 71 6c 69 74 65 33 5f  ng via [sqlite3_
14230 73 6e 70 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a 20  snprintf()]..** 
14240 54 68 65 20 53 51 4c 69 74 65 20 6c 6f 67 67 69  The SQLite loggi
14250 6e 67 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  ng interface is 
14260 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 3b 20 74  not reentrant; t
14270 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69  he logger functi
14280 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20 62  on.** supplied b
14290 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  y the applicatio
142a0 6e 20 6d 75 73 74 20 6e 6f 74 20 69 6e 76 6f 6b  n must not invok
142b0 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74  e any SQLite int
142c0 65 72 66 61 63 65 2e 0a 2a 2a 20 49 6e 20 61 20  erface..** In a 
142d0 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 20 61  multi-threaded a
142e0 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65 20  pplication, the 
142f0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
14300 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75  ned logger.** fu
14310 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 74  nction must be t
14320 68 72 65 61 64 73 61 66 65 2e 20 3c 2f 64 64 3e  hreadsafe. </dd>
14330 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
14340 43 4f 4e 46 49 47 5f 55 52 49 5d 5d 20 3c 64 74  CONFIG_URI]] <dt
14350 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55  >SQLITE_CONFIG_U
14360 52 49 0a 2a 2a 20 3c 64 64 3e 5e 28 54 68 69 73  RI.** <dd>^(This
14370 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
14380 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
14390 6f 66 20 74 79 70 65 20 69 6e 74 2e 20 49 66 20  of type int. If 
143a0 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 0a 2a  non-zero, then.*
143b0 2a 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69  * URI handling i
143c0 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c  s globally enabl
143d0 65 64 2e 20 49 66 20 74 68 65 20 70 61 72 61 6d  ed. If the param
143e0 65 74 65 72 20 69 73 20 7a 65 72 6f 2c 20 74 68  eter is zero, th
143f0 65 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 0a  en URI handling.
14400 2a 2a 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64  ** is globally d
14410 69 73 61 62 6c 65 64 2e 29 5e 20 5e 49 66 20 55  isabled.)^ ^If U
14420 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67  RI handling is g
14430 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2c  lobally enabled,
14440 20 61 6c 6c 20 66 69 6c 65 6e 61 6d 65 73 0a 2a   all filenames.*
14450 2a 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c  * passed to [sql
14460 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
14470 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
14480 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
14490 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 73 70 65 63  16()] or.** spec
144a0 69 66 69 65 64 20 61 73 20 70 61 72 74 20 6f 66  ified as part of
144b0 20 5b 41 54 54 41 43 48 5d 20 63 6f 6d 6d 61 6e   [ATTACH] comman
144c0 64 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74  ds are interpret
144d0 65 64 20 61 73 20 55 52 49 73 2c 20 72 65 67 61  ed as URIs, rega
144e0 72 64 6c 65 73 73 0a 2a 2a 20 6f 66 20 77 68 65  rdless.** of whe
144f0 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20  ther or not the 
14500 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49  [SQLITE_OPEN_URI
14510 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20 77 68  ] flag is set wh
14520 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  en the database.
14530 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  ** connection is
14540 20 6f 70 65 6e 65 64 2e 20 5e 49 66 20 69 74 20   opened. ^If it 
14550 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61  is globally disa
14560 62 6c 65 64 2c 20 66 69 6c 65 6e 61 6d 65 73 20  bled, filenames 
14570 61 72 65 0a 2a 2a 20 6f 6e 6c 79 20 69 6e 74 65  are.** only inte
14580 72 70 72 65 74 65 64 20 61 73 20 55 52 49 73 20  rpreted as URIs 
14590 69 66 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50  if the SQLITE_OP
145a0 45 4e 5f 55 52 49 20 66 6c 61 67 20 69 73 20 73  EN_URI flag is s
145b0 65 74 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 64  et when the.** d
145c0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
145d0 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 5e 28  on is opened. ^(
145e0 42 79 20 64 65 66 61 75 6c 74 2c 20 55 52 49 20  By default, URI 
145f0 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62  handling is glob
14600 61 6c 6c 79 0a 2a 2a 20 64 69 73 61 62 6c 65 64  ally.** disabled
14610 2e 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61  . The default va
14620 6c 75 65 20 6d 61 79 20 62 65 20 63 68 61 6e 67  lue may be chang
14630 65 64 20 62 79 20 63 6f 6d 70 69 6c 69 6e 67 20  ed by compiling 
14640 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  with the.** [SQL
14650 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 73 79 6d  ITE_USE_URI] sym
14660 62 6f 6c 20 64 65 66 69 6e 65 64 2e 29 5e 0a 2a  bol defined.)^.*
14670 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
14680 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e  NFIG_COVERING_IN
14690 44 45 58 5f 53 43 41 4e 5d 5d 20 3c 64 74 3e 53  DEX_SCAN]] <dt>S
146a0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56  QLITE_CONFIG_COV
146b0 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e  ERING_INDEX_SCAN
146c0 0a 2a 2a 20 3c 64 64 3e 5e 54 68 69 73 20 6f 70  .** <dd>^This op
146d0 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
146e0 67 6c 65 20 69 6e 74 65 67 65 72 20 61 72 67 75  gle integer argu
146f0 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 69 6e  ment which is in
14700 74 65 72 70 72 65 74 65 64 20 61 73 0a 2a 2a 20  terpreted as.** 
14710 61 20 62 6f 6f 6c 65 61 6e 20 69 6e 20 6f 72 64  a boolean in ord
14720 65 72 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20  er to enable or 
14730 64 69 73 61 62 6c 65 20 74 68 65 20 75 73 65 20  disable the use 
14740 6f 66 20 63 6f 76 65 72 69 6e 67 20 69 6e 64 69  of covering indi
14750 63 65 73 20 66 6f 72 0a 2a 2a 20 66 75 6c 6c 20  ces for.** full 
14760 74 61 62 6c 65 20 73 63 61 6e 73 20 69 6e 20 74  table scans in t
14770 68 65 20 71 75 65 72 79 20 6f 70 74 69 6d 69 7a  he query optimiz
14780 65 72 2e 20 20 5e 54 68 65 20 64 65 66 61 75 6c  er.  ^The defaul
14790 74 20 73 65 74 74 69 6e 67 20 69 73 20 64 65 74  t setting is det
147a0 65 72 6d 69 6e 65 64 0a 2a 2a 20 62 79 20 74 68  ermined.** by th
147b0 65 20 5b 53 51 4c 49 54 45 5f 41 4c 4c 4f 57 5f  e [SQLITE_ALLOW_
147c0 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53  COVERING_INDEX_S
147d0 43 41 4e 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  CAN] compile-tim
147e0 65 20 6f 70 74 69 6f 6e 2c 20 6f 72 20 69 73 20  e option, or is 
147f0 22 6f 6e 22 0a 2a 2a 20 69 66 20 74 68 61 74 20  "on".** if that 
14800 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
14810 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 2e 0a  ion is omitted..
14820 2a 2a 20 54 68 65 20 61 62 69 6c 69 74 79 20 74  ** The ability t
14830 6f 20 64 69 73 61 62 6c 65 20 74 68 65 20 75 73  o disable the us
14840 65 20 6f 66 20 63 6f 76 65 72 69 6e 67 20 69 6e  e of covering in
14850 64 69 63 65 73 20 66 6f 72 20 66 75 6c 6c 20 74  dices for full t
14860 61 62 6c 65 20 73 63 61 6e 73 0a 2a 2a 20 69 73  able scans.** is
14870 20 62 65 63 61 75 73 65 20 73 6f 6d 65 20 69 6e   because some in
14880 63 6f 72 72 65 63 74 6c 79 20 63 6f 64 65 64 20  correctly coded 
14890 6c 65 67 61 63 79 20 61 70 70 6c 69 63 61 74 69  legacy applicati
148a0 6f 6e 73 20 6d 69 67 68 74 20 6d 61 6c 66 75 6e  ons might malfun
148b0 63 74 69 6f 6e 0a 2a 2a 20 77 68 65 6e 20 74 68  ction.** when th
148c0 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 69  e optimization i
148d0 73 20 65 6e 61 62 6c 65 64 2e 20 20 50 72 6f 76  s enabled.  Prov
148e0 69 64 69 6e 67 20 74 68 65 20 61 62 69 6c 69 74  iding the abilit
148f0 79 20 74 6f 0a 2a 2a 20 64 69 73 61 62 6c 65 20  y to.** disable 
14900 74 68 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e  the optimization
14910 20 61 6c 6c 6f 77 73 20 74 68 65 20 6f 6c 64 65   allows the olde
14920 72 2c 20 62 75 67 67 79 20 61 70 70 6c 69 63 61  r, buggy applica
14930 74 69 6f 6e 20 63 6f 64 65 20 74 6f 20 77 6f 72  tion code to wor
14940 6b 0a 2a 2a 20 77 69 74 68 6f 75 74 20 63 68 61  k.** without cha
14950 6e 67 65 20 65 76 65 6e 20 77 69 74 68 20 6e 65  nge even with ne
14960 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  wer versions of 
14970 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  SQLite..**.** [[
14980 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
14990 41 43 48 45 5d 5d 20 5b 5b 53 51 4c 49 54 45 5f  ACHE]] [[SQLITE_
149a0 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
149b0 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  ]].** <dt>SQLITE
149c0 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 61  _CONFIG_PCACHE a
149d0 6e 64 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  nd SQLITE_CONFIG
149e0 5f 47 45 54 50 43 41 43 48 45 0a 2a 2a 20 3c 64  _GETPCACHE.** <d
149f0 64 3e 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 73  d> These options
14a00 20 61 72 65 20 6f 62 73 6f 6c 65 74 65 20 61 6e   are obsolete an
14a10 64 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20  d should not be 
14a20 75 73 65 64 20 62 79 20 6e 65 77 20 63 6f 64 65  used by new code
14a30 2e 0a 2a 2a 20 54 68 65 79 20 61 72 65 20 72 65  ..** They are re
14a40 74 61 69 6e 65 64 20 66 6f 72 20 62 61 63 6b 77  tained for backw
14a50 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
14a60 74 79 20 62 75 74 20 61 72 65 20 6e 6f 77 20 6e  ty but are now n
14a70 6f 2d 6f 70 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a  o-ops..** </dd>.
14a80 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
14a90 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 5d 5d 0a 2a  ONFIG_SQLLOG]].*
14aa0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
14ab0 46 49 47 5f 53 51 4c 4c 4f 47 0a 2a 2a 20 3c 64  FIG_SQLLOG.** <d
14ac0 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73  d>This option is
14ad0 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20   only available 
14ae0 69 66 20 73 71 6c 69 74 65 20 69 73 20 63 6f 6d  if sqlite is com
14af0 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  piled with the.*
14b00 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  * [SQLITE_ENABLE
14b10 5f 53 51 4c 4c 4f 47 5d 20 70 72 65 2d 70 72 6f  _SQLLOG] pre-pro
14b20 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 64 65 66  cessor macro def
14b30 69 6e 65 64 2e 20 54 68 65 20 66 69 72 73 74 20  ined. The first 
14b40 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 0a  argument should.
14b50 2a 2a 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20  ** be a pointer 
14b60 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66  to a function of
14b70 20 74 79 70 65 20 76 6f 69 64 28 2a 29 28 76 6f   type void(*)(vo
14b80 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 63 6f 6e  id*,sqlite3*,con
14b90 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 29 2e 0a  st char*, int)..
14ba0 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 73 68  ** The second sh
14bb0 6f 75 6c 64 20 62 65 20 6f 66 20 74 79 70 65 20  ould be of type 
14bc0 28 76 6f 69 64 2a 29 2e 20 54 68 65 20 63 61 6c  (void*). The cal
14bd0 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
14be0 20 62 79 20 74 68 65 20 6c 69 62 72 61 72 79 0a   by the library.
14bf0 2a 2a 20 69 6e 20 74 68 72 65 65 20 73 65 70 61  ** in three sepa
14c00 72 61 74 65 20 63 69 72 63 75 6d 73 74 61 6e 63  rate circumstanc
14c10 65 73 2c 20 69 64 65 6e 74 69 66 69 65 64 20 62  es, identified b
14c20 79 20 74 68 65 20 76 61 6c 75 65 20 70 61 73 73  y the value pass
14c30 65 64 20 61 73 20 74 68 65 0a 2a 2a 20 66 6f 75  ed as the.** fou
14c40 72 74 68 20 70 61 72 61 6d 65 74 65 72 2e 20 49  rth parameter. I
14c50 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
14c60 61 6d 65 74 65 72 20 69 73 20 30 2c 20 74 68 65  ameter is 0, the
14c70 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
14c80 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 70 61 73  onnection.** pas
14c90 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  sed as the secon
14ca0 64 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20 6a  d argument has j
14cb0 75 73 74 20 62 65 65 6e 20 6f 70 65 6e 65 64 2e  ust been opened.
14cc0 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d   The third argum
14cd0 65 6e 74 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f  ent.** points to
14ce0 20 61 20 62 75 66 66 65 72 20 63 6f 6e 74 61 69   a buffer contai
14cf0 6e 69 6e 67 20 74 68 65 20 6e 61 6d 65 20 6f 66  ning the name of
14d00 20 74 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61   the main databa
14d10 73 65 20 66 69 6c 65 2e 20 49 66 20 74 68 65 0a  se file. If the.
14d20 2a 2a 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  ** fourth parame
14d30 74 65 72 20 69 73 20 31 2c 20 74 68 65 6e 20 74  ter is 1, then t
14d40 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
14d50 20 74 68 61 74 20 74 68 65 20 74 68 69 72 64 20   that the third 
14d60 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 70 6f 69  parameter.** poi
14d70 6e 74 73 20 74 6f 20 68 61 73 20 6a 75 73 74 20  nts to has just 
14d80 62 65 65 6e 20 65 78 65 63 75 74 65 64 2e 20 4f  been executed. O
14d90 72 2c 20 69 66 20 74 68 65 20 66 6f 75 72 74 68  r, if the fourth
14da0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 32 2c   parameter is 2,
14db0 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6e   then.** the con
14dc0 6e 65 63 74 69 6f 6e 20 62 65 69 6e 67 20 70 61  nection being pa
14dd0 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  ssed as the seco
14de0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
14df0 62 65 69 6e 67 20 63 6c 6f 73 65 64 2e 20 54 68  being closed. Th
14e00 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d  e.** third param
14e10 65 74 65 72 20 69 73 20 70 61 73 73 65 64 20 4e  eter is passed N
14e20 55 4c 4c 20 49 6e 20 74 68 69 73 20 63 61 73 65  ULL In this case
14e30 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 6f 66  .  An example of
14e40 20 75 73 69 6e 67 20 74 68 69 73 0a 2a 2a 20 63   using this.** c
14e50 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
14e60 69 6f 6e 20 63 61 6e 20 62 65 20 73 65 65 6e 20  ion can be seen 
14e70 69 6e 20 74 68 65 20 22 74 65 73 74 5f 73 71 6c  in the "test_sql
14e80 6c 6f 67 2e 63 22 20 73 6f 75 72 63 65 20 66 69  log.c" source fi
14e90 6c 65 20 69 6e 0a 2a 2a 20 74 68 65 20 63 61 6e  le in.** the can
14ea0 6f 6e 69 63 61 6c 20 53 51 4c 69 74 65 20 73 6f  onical SQLite so
14eb0 75 72 63 65 20 74 72 65 65 2e 3c 2f 64 64 3e 0a  urce tree.</dd>.
14ec0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
14ed0 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 5d  ONFIG_MMAP_SIZE]
14ee0 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  ].** <dt>SQLITE_
14ef0 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45  CONFIG_MMAP_SIZE
14f00 0a 2a 2a 20 3c 64 64 3e 5e 53 51 4c 49 54 45 5f  .** <dd>^SQLITE_
14f10 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45  CONFIG_MMAP_SIZE
14f20 20 74 61 6b 65 73 20 74 77 6f 20 36 34 2d 62 69   takes two 64-bi
14f30 74 20 69 6e 74 65 67 65 72 20 28 73 71 6c 69 74  t integer (sqlit
14f40 65 33 5f 69 6e 74 36 34 29 20 76 61 6c 75 65 73  e3_int64) values
14f50 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 74 68 65  .** that are the
14f60 20 64 65 66 61 75 6c 74 20 6d 6d 61 70 20 73 69   default mmap si
14f70 7a 65 20 6c 69 6d 69 74 20 28 74 68 65 20 64 65  ze limit (the de
14f80 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20 66 6f  fault setting fo
14f90 72 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 6d 6d 61  r.** [PRAGMA mma
14fa0 70 5f 73 69 7a 65 5d 29 20 61 6e 64 20 74 68 65  p_size]) and the
14fb0 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64   maximum allowed
14fc0 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69 74   mmap size limit
14fd0 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c  ..** ^The defaul
14fe0 74 20 73 65 74 74 69 6e 67 20 63 61 6e 20 62 65  t setting can be
14ff0 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79 20 65   overridden by e
15000 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ach database con
15010 6e 65 63 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a  nection using.**
15020 20 65 69 74 68 65 72 20 74 68 65 20 5b 50 52 41   either the [PRA
15030 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 20 63  GMA mmap_size] c
15040 6f 6d 6d 61 6e 64 2c 20 6f 72 20 62 79 20 75 73  ommand, or by us
15050 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ing the.** [SQLI
15060 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49  TE_FCNTL_MMAP_SI
15070 5a 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  ZE] file control
15080 2e 20 20 5e 28 54 68 65 20 6d 61 78 69 6d 75 6d  .  ^(The maximum
15090 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69   allowed mmap si
150a0 7a 65 0a 2a 2a 20 63 61 6e 6e 6f 74 20 62 65 20  ze.** cannot be 
150b0 63 68 61 6e 67 65 64 20 61 74 20 72 75 6e 2d 74  changed at run-t
150c0 69 6d 65 2e 20 20 4e 6f 72 20 6d 61 79 20 74 68  ime.  Nor may th
150d0 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65  e maximum allowe
150e0 64 20 6d 6d 61 70 20 73 69 7a 65 0a 2a 2a 20 65  d mmap size.** e
150f0 78 63 65 65 64 20 74 68 65 20 63 6f 6d 70 69 6c  xceed the compil
15100 65 2d 74 69 6d 65 20 6d 61 78 69 6d 75 6d 20 6d  e-time maximum m
15110 6d 61 70 20 73 69 7a 65 20 73 65 74 20 62 79 20  map size set by 
15120 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d  the.** [SQLITE_M
15130 41 58 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 63 6f  AX_MMAP_SIZE] co
15140 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
15150 6e 2e 29 5e 0a 2a 2a 20 5e 49 66 20 65 69 74 68  n.)^.** ^If eith
15160 65 72 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  er argument to t
15170 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6e 65  his option is ne
15180 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 61  gative, then tha
15190 74 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a  t argument is.**
151a0 20 63 68 61 6e 67 65 64 20 74 6f 20 69 74 73 20   changed to its 
151b0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 64 65 66  compile-time def
151c0 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  ault..**.** [[SQ
151d0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33  LITE_CONFIG_WIN3
151e0 32 5f 48 45 41 50 53 49 5a 45 5d 5d 0a 2a 2a 20  2_HEAPSIZE]].** 
151f0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
15200 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45  G_WIN32_HEAPSIZE
15210 0a 2a 2a 20 3c 64 64 3e 5e 54 68 69 73 20 6f 70  .** <dd>^This op
15220 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61  tion is only ava
15230 69 6c 61 62 6c 65 20 69 66 20 53 51 4c 69 74 65  ilable if SQLite
15240 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72   is compiled for
15250 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 77 69 74 68   Windows.** with
15260 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 57 49 4e   the [SQLITE_WIN
15270 33 32 5f 4d 41 4c 4c 4f 43 5d 20 70 72 65 2d 70  32_MALLOC] pre-p
15280 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 64  rocessor macro d
15290 65 66 69 6e 65 64 2e 0a 2a 2a 20 53 51 4c 49 54  efined..** SQLIT
152a0 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48  E_CONFIG_WIN32_H
152b0 45 41 50 53 49 5a 45 20 74 61 6b 65 73 20 61 20  EAPSIZE takes a 
152c0 33 32 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20  32-bit unsigned 
152d0 69 6e 74 65 67 65 72 20 76 61 6c 75 65 0a 2a 2a  integer value.**
152e0 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73 20   that specifies 
152f0 74 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65  the maximum size
15300 20 6f 66 20 74 68 65 20 63 72 65 61 74 65 64 20   of the created 
15310 68 65 61 70 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  heap..** </dl>.*
15320 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
15330 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
15340 52 45 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20  READ  1  /* nil 
15350 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
15360 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48  E_CONFIG_MULTITH
15370 52 45 41 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c  READ   2  /* nil
15380 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
15390 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c  TE_CONFIG_SERIAL
153a0 49 5a 45 44 20 20 20 20 33 20 20 2f 2a 20 6e 69  IZED    3  /* ni
153b0 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  l */.#define SQL
153c0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
153d0 43 20 20 20 20 20 20 20 20 34 20 20 2f 2a 20 73  C        4  /* s
153e0 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
153f0 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ds* */.#define S
15400 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
15410 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a  MALLOC     5  /*
15420 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
15430 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  hods* */.#define
15440 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
15450 43 52 41 54 43 48 20 20 20 20 20 20 20 36 20 20  CRATCH       6  
15460 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a  /* void*, int sz
15470 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69  , int N */.#defi
15480 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
15490 5f 50 41 47 45 43 41 43 48 45 20 20 20 20 20 37  _PAGECACHE     7
154a0 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20    /* void*, int 
154b0 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65  sz, int N */.#de
154c0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
154d0 49 47 5f 48 45 41 50 20 20 20 20 20 20 20 20 20  IG_HEAP         
154e0 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e   8  /* void*, in
154f0 74 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e  t nByte, int min
15500 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
15510 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41  TE_CONFIG_MEMSTA
15520 54 55 53 20 20 20 20 20 39 20 20 2f 2a 20 62 6f  TUS     9  /* bo
15530 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65  olean */.#define
15540 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
15550 55 54 45 58 20 20 20 20 20 20 20 20 31 30 20 20  UTEX        10  
15560 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  /* sqlite3_mutex
15570 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65  _methods* */.#de
15580 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
15590 49 47 5f 47 45 54 4d 55 54 45 58 20 20 20 20 20  IG_GETMUTEX     
155a0 31 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d  11  /* sqlite3_m
155b0 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f  utex_methods* */
155c0 0a 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 53  ./* previously S
155d0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55  QLITE_CONFIG_CHU
155e0 4e 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69 63 68  NKALLOC 12 which
155f0 20 69 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20   is now unused. 
15600 2a 2f 20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  */ .#define SQLI
15610 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  TE_CONFIG_LOOKAS
15620 49 44 45 20 20 20 20 31 33 20 20 2f 2a 20 69 6e  IDE    13  /* in
15630 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65  t int */.#define
15640 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
15650 43 41 43 48 45 20 20 20 20 20 20 20 31 34 20 20  CACHE       14  
15660 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66  /* no-op */.#def
15670 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
15680 47 5f 47 45 54 50 43 41 43 48 45 20 20 20 20 31  G_GETPCACHE    1
15690 35 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23  5  /* no-op */.#
156a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
156b0 4e 46 49 47 5f 4c 4f 47 20 20 20 20 20 20 20 20  NFIG_LOG        
156c0 20 20 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20    16  /* xFunc, 
156d0 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  void* */.#define
156e0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55   SQLITE_CONFIG_U
156f0 52 49 20 20 20 20 20 20 20 20 20 20 31 37 20 20  RI          17  
15700 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e  /* int */.#defin
15710 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
15720 50 43 41 43 48 45 32 20 20 20 20 20 20 31 38 20  PCACHE2      18 
15730 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63   /* sqlite3_pcac
15740 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a  he_methods2* */.
15750 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
15760 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32  ONFIG_GETPCACHE2
15770 20 20 20 31 39 20 20 2f 2a 20 73 71 6c 69 74 65     19  /* sqlite
15780 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73  3_pcache_methods
15790 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  2* */.#define SQ
157a0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45  LITE_CONFIG_COVE
157b0 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20  RING_INDEX_SCAN 
157c0 32 30 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64  20  /* int */.#d
157d0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
157e0 46 49 47 5f 53 51 4c 4c 4f 47 20 20 20 20 20 20  FIG_SQLLOG      
157f0 20 32 31 20 20 2f 2a 20 78 53 71 6c 6c 6f 67 2c   21  /* xSqllog,
15800 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e   void* */.#defin
15810 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
15820 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20 32 32 20  MMAP_SIZE    22 
15830 20 2f 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 36   /* sqlite3_int6
15840 34 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  4, sqlite3_int64
15850 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
15860 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f  TE_CONFIG_WIN32_
15870 48 45 41 50 53 49 5a 45 20 20 20 20 20 20 32 33  HEAPSIZE      23
15880 20 20 2f 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a    /* int nByte *
15890 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
158a0 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e  F: Database Conn
158b0 65 63 74 69 6f 6e 20 43 6f 6e 66 69 67 75 72 61  ection Configura
158c0 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a  tion Options.**.
158d0 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
158e0 74 73 20 61 72 65 20 74 68 65 20 61 76 61 69 6c  ts are the avail
158f0 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  able integer con
15900 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
15910 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62  ns that.** can b
15920 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
15930 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
15940 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
15950 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74  db_config()] int
15960 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65  erface..**.** Ne
15970 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  w configuration 
15980 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61  options may be a
15990 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72  dded in future r
159a0 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74  eleases of SQLit
159b0 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63  e..** Existing c
159c0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
159d0 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69  ions might be di
159e0 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70  scontinued.  App
159f0 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f  lications.** sho
15a00 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 65  uld check the re
15a10 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b  turn code from [
15a20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
15a30 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72  g()] to make sur
15a40 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61  e that.** the ca
15a50 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 5e 54 68 65  ll worked.  ^The
15a60 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
15a70 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  fig()] interface
15a80 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a   will return a.*
15a90 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f  * non-zero [erro
15aa0 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73  r code] if a dis
15ab0 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73  continued or uns
15ac0 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75  upported configu
15ad0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a  ration option.**
15ae0 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a   is invoked..**.
15af0 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53  ** <dl>.** <dt>S
15b00 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
15b10 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a  OOKASIDE</dt>.**
15b20 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69   <dd> ^This opti
15b30 6f 6e 20 74 61 6b 65 73 20 74 68 72 65 65 20 61  on takes three a
15b40 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65  dditional argume
15b50 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d 69  nts that determi
15b60 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b  ne the .** [look
15b70 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  aside memory all
15b80 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72  ocator] configur
15b90 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64  ation for the [d
15ba0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
15bb0 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72  on]..** ^The fir
15bc0 73 74 20 61 72 67 75 6d 65 6e 74 20 28 74 68 65  st argument (the
15bd0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
15be0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f   to [sqlite3_db_
15bf0 63 6f 6e 66 69 67 28 29 5d 20 69 73 20 61 0a 2a  config()] is a.*
15c00 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d  * pointer to a m
15c10 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 6f 20  emory buffer to 
15c20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64  use for lookasid
15c30 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68  e memory..** ^Th
15c40 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
15c50 20 61 66 74 65 72 20 74 68 65 20 53 51 4c 49 54   after the SQLIT
15c60 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
15c70 53 49 44 45 20 76 65 72 62 0a 2a 2a 20 6d 61 79  SIDE verb.** may
15c80 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63   be NULL in whic
15c90 68 20 63 61 73 65 20 53 51 4c 69 74 65 20 77 69  h case SQLite wi
15ca0 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a  ll allocate the.
15cb0 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66  ** lookaside buf
15cc0 66 65 72 20 69 74 73 65 6c 66 20 75 73 69 6e 67  fer itself using
15cd0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
15ce0 28 29 5d 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64  ()]. ^The second
15cf0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
15d00 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68  .** size of each
15d10 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65   lookaside buffe
15d20 72 20 73 6c 6f 74 2e 20 20 5e 54 68 65 20 74 68  r slot.  ^The th
15d30 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ird argument is 
15d40 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
15d50 20 73 6c 6f 74 73 2e 20 20 54 68 65 20 73 69 7a   slots.  The siz
15d60 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20  e of the buffer 
15d70 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67  in the first arg
15d80 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 67 72  ument must be gr
15d90 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72  eater than.** or
15da0 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20 70 72   equal to the pr
15db0 6f 64 75 63 74 20 6f 66 20 74 68 65 20 73 65 63  oduct of the sec
15dc0 6f 6e 64 20 61 6e 64 20 74 68 69 72 64 20 61 72  ond and third ar
15dd0 67 75 6d 65 6e 74 73 2e 20 20 54 68 65 20 62 75  guments.  The bu
15de0 66 66 65 72 0a 2a 2a 20 6d 75 73 74 20 62 65 20  ffer.** must be 
15df0 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d  aligned to an 8-
15e00 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2e 20 20  byte boundary.  
15e10 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61  ^If the second a
15e20 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 51  rgument to.** SQ
15e30 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
15e40 4f 4b 41 53 49 44 45 20 69 73 20 6e 6f 74 20 61  OKASIDE is not a
15e50 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20   multiple of 8, 
15e60 69 74 20 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79  it is internally
15e70 0a 2a 2a 20 72 6f 75 6e 64 65 64 20 64 6f 77 6e  .** rounded down
15e80 20 74 6f 20 74 68 65 20 6e 65 78 74 20 73 6d 61   to the next sma
15e90 6c 6c 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66  ller multiple of
15ea0 20 38 2e 20 20 5e 28 54 68 65 20 6c 6f 6f 6b 61   8.  ^(The looka
15eb0 73 69 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63  side memory.** c
15ec0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72  onfiguration for
15ed0 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e   a database conn
15ee0 65 63 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20  ection can only 
15ef0 62 65 20 63 68 61 6e 67 65 64 20 77 68 65 6e 20  be changed when 
15f00 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  that.** connecti
15f10 6f 6e 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e  on is not curren
15f20 74 6c 79 20 75 73 69 6e 67 20 6c 6f 6f 6b 61 73  tly using lookas
15f30 69 64 65 20 6d 65 6d 6f 72 79 2c 20 6f 72 20 69  ide memory, or i
15f40 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 0a 2a 2a  n other words.**
15f50 20 77 68 65 6e 20 74 68 65 20 22 63 75 72 72 65   when the "curre
15f60 6e 74 20 76 61 6c 75 65 22 20 72 65 74 75 72 6e  nt value" return
15f70 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65  ed by.** [sqlite
15f80 33 5f 64 62 5f 73 74 61 74 75 73 5d 28 44 2c 5b  3_db_status](D,[
15f90 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
15fa0 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29 20 69 73  OKASIDE],...) is
15fb0 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74   zero..** Any at
15fc0 74 65 6d 70 74 20 74 6f 20 63 68 61 6e 67 65 20  tempt to change 
15fd0 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  the lookaside me
15fe0 6d 6f 72 79 20 63 6f 6e 66 69 67 75 72 61 74 69  mory configurati
15ff0 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61 73 69 64  on when lookasid
16000 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69 73 20 69  e.** memory is i
16010 6e 20 75 73 65 20 6c 65 61 76 65 73 20 74 68 65  n use leaves the
16020 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75   configuration u
16030 6e 63 68 61 6e 67 65 64 20 61 6e 64 20 72 65 74  nchanged and ret
16040 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45  urns .** [SQLITE
16050 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a  _BUSY].)^</dd>.*
16060 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
16070 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f  DBCONFIG_ENABLE_
16080 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  FKEY</dt>.** <dd
16090 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69  > ^This option i
160a0 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65  s used to enable
160b0 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65 20   or disable the 
160c0 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 66 0a 2a  enforcement of.*
160d0 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 63  * [foreign key c
160e0 6f 6e 73 74 72 61 69 6e 74 73 5d 2e 20 20 54 68  onstraints].  Th
160f0 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77  ere should be tw
16100 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67  o additional arg
16110 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66  uments..** The f
16120 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73  irst argument is
16130 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63   an integer whic
16140 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c  h is 0 to disabl
16150 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74  e FK enforcement
16160 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f  ,.** positive to
16170 20 65 6e 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72   enable FK enfor
16180 63 65 6d 65 6e 74 20 6f 72 20 6e 65 67 61 74 69  cement or negati
16190 76 65 20 74 6f 20 6c 65 61 76 65 20 46 4b 20 65  ve to leave FK e
161a0 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e  nforcement.** un
161b0 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20 73 65  changed.  The se
161c0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
161d0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
161e0 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77  n integer into w
161f0 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74  hich.** is writt
16200 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64  en 0 or 1 to ind
16210 69 63 61 74 65 20 77 68 65 74 68 65 72 20 46 4b  icate whether FK
16220 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 69 73 20   enforcement is 
16230 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c  off or on.** fol
16240 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c  lowing this call
16250 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  .  The second pa
16260 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61  rameter may be a
16270 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69   NULL pointer, i
16280 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20  n.** which case 
16290 74 68 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65  the FK enforceme
162a0 6e 74 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f  nt setting is no
162b0 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e  t reported back.
162c0 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74   </dd>.**.** <dt
162d0 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  >SQLITE_DBCONFIG
162e0 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 3c  _ENABLE_TRIGGER<
162f0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
16300 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  is option is use
16310 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64  d to enable or d
16320 69 73 61 62 6c 65 20 5b 43 52 45 41 54 45 20 54  isable [CREATE T
16330 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 72  RIGGER | trigger
16340 73 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f  s]..** There sho
16350 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74  uld be two addit
16360 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e  ional arguments.
16370 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
16380 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74  gument is an int
16390 65 67 65 72 20 77 68 69 63 68 20 69 73 20 30 20  eger which is 0 
163a0 74 6f 20 64 69 73 61 62 6c 65 20 74 72 69 67 67  to disable trigg
163b0 65 72 73 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65  ers,.** positive
163c0 20 74 6f 20 65 6e 61 62 6c 65 20 74 72 69 67 67   to enable trigg
163d0 65 72 73 20 6f 72 20 6e 65 67 61 74 69 76 65 20  ers or negative 
163e0 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65 74  to leave the set
163f0 74 69 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a  ting unchanged..
16400 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  ** The second pa
16410 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69  rameter is a poi
16420 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67  nter to an integ
16430 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a  er into which.**
16440 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72   is written 0 or
16450 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77   1 to indicate w
16460 68 65 74 68 65 72 20 74 72 69 67 67 65 72 73 20  hether triggers 
16470 61 72 65 20 64 69 73 61 62 6c 65 64 20 6f 72 20  are disabled or 
16480 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f  enabled.** follo
16490 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20  wing this call. 
164a0 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
164b0 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e  meter may be a N
164c0 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a  ULL pointer, in.
164d0 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 68  ** which case th
164e0 65 20 74 72 69 67 67 65 72 20 73 65 74 74 69 6e  e trigger settin
164f0 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65  g is not reporte
16500 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a  d back. </dd>.**
16510 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65  .** </dl>.*/.#de
16520 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f  fine SQLITE_DBCO
16530 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20  NFIG_LOOKASIDE  
16540 20 20 20 20 20 31 30 30 31 20 20 2f 2a 20 76 6f       1001  /* vo
16550 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23  id* int int */.#
16560 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42  define SQLITE_DB
16570 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b  CONFIG_ENABLE_FK
16580 45 59 20 20 20 20 20 31 30 30 32 20 20 2f 2a 20  EY     1002  /* 
16590 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66  int int* */.#def
165a0 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ine SQLITE_DBCON
165b0 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47  FIG_ENABLE_TRIGG
165c0 45 52 20 20 31 30 30 33 20 20 2f 2a 20 69 6e 74  ER  1003  /* int
165d0 20 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a   int* */.../*.**
165e0 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c   CAPI3REF: Enabl
165f0 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74  e Or Disable Ext
16600 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64  ended Result Cod
16610 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  es.**.** ^The sq
16620 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72  lite3_extended_r
16630 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f  esult_codes() ro
16640 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72  utine enables or
16650 20 64 69 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a   disables the.**
16660 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
16670 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75 72 65  t codes] feature
16680 20 6f 66 20 53 51 4c 69 74 65 2e 20 5e 54 68 65   of SQLite. ^The
16690 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
166a0 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65 20 64 69  .** codes are di
166b0 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  sabled by defaul
166c0 74 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c  t for historical
166d0 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a   compatibility..
166e0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
166f0 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64  t sqlite3_extend
16700 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28  ed_result_codes(
16710 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 6e  sqlite3*, int on
16720 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  off);../*.** CAP
16730 49 33 52 45 46 3a 20 4c 61 73 74 20 49 6e 73 65  I3REF: Last Inse
16740 72 74 20 52 6f 77 69 64 0a 2a 2a 0a 2a 2a 20 5e  rt Rowid.**.** ^
16750 45 61 63 68 20 65 6e 74 72 79 20 69 6e 20 6d 6f  Each entry in mo
16760 73 74 20 53 51 4c 69 74 65 20 74 61 62 6c 65 73  st SQLite tables
16770 20 28 65 78 63 65 70 74 20 66 6f 72 20 5b 57 49   (except for [WI
16780 54 48 4f 55 54 20 52 4f 57 49 44 5d 20 74 61 62  THOUT ROWID] tab
16790 6c 65 73 29 0a 2a 2a 20 68 61 73 20 61 20 75 6e  les).** has a un
167a0 69 71 75 65 20 36 34 2d 62 69 74 20 73 69 67 6e  ique 64-bit sign
167b0 65 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65  ed.** integer ke
167c0 79 20 63 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f  y called the [RO
167d0 57 49 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20  WID | "rowid"]. 
167e0 5e 54 68 65 20 72 6f 77 69 64 20 69 73 20 61 6c  ^The rowid is al
167f0 77 61 79 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a  ways available.*
16800 2a 20 61 73 20 61 6e 20 75 6e 64 65 63 6c 61 72  * as an undeclar
16810 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20  ed column named 
16820 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f  ROWID, OID, or _
16830 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61  ROWID_ as long a
16840 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73  s those.** names
16850 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73   are not also us
16860 65 64 20 62 79 20 65 78 70 6c 69 63 69 74 6c 79  ed by explicitly
16870 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e   declared column
16880 73 2e 20 5e 49 66 0a 2a 2a 20 74 68 65 20 74 61  s. ^If.** the ta
16890 62 6c 65 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e  ble has a column
168a0 20 6f 66 20 74 79 70 65 20 5b 49 4e 54 45 47 45   of type [INTEGE
168b0 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 74  R PRIMARY KEY] t
168c0 68 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a  hen that column.
168d0 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72 20 61 6c  ** is another al
168e0 69 61 73 20 66 6f 72 20 74 68 65 20 72 6f 77 69  ias for the rowi
168f0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
16900 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72  lite3_last_inser
16910 74 5f 72 6f 77 69 64 28 44 29 20 69 6e 74 65 72  t_rowid(D) inter
16920 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
16930 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20   [rowid] of the 
16940 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  .** most recent 
16950 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45  successful [INSE
16960 52 54 5d 20 69 6e 74 6f 20 61 20 72 6f 77 69 64  RT] into a rowid
16970 20 74 61 62 6c 65 20 6f 72 20 5b 76 69 72 74 75   table or [virtu
16980 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 6f 6e 20  al table].** on 
16990 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
169a0 69 6f 6e 20 44 2e 0a 2a 2a 20 5e 49 6e 73 65 72  ion D..** ^Inser
169b0 74 73 20 69 6e 74 6f 20 5b 57 49 54 48 4f 55 54  ts into [WITHOUT
169c0 20 52 4f 57 49 44 5d 20 74 61 62 6c 65 73 20 61   ROWID] tables a
169d0 72 65 20 6e 6f 74 20 72 65 63 6f 72 64 65 64 2e  re not recorded.
169e0 0a 2a 2a 20 5e 49 66 20 6e 6f 20 73 75 63 63 65  .** ^If no succe
169f0 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 73 20  ssful [INSERT]s 
16a00 69 6e 74 6f 20 72 6f 77 69 64 20 74 61 62 6c 65  into rowid table
16a10 73 0a 2a 2a 20 68 61 76 65 20 65 76 65 72 20 6f  s.** have ever o
16a20 63 63 75 72 72 65 64 20 6f 6e 20 74 68 65 20 64  ccurred on the d
16a30 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
16a40 6f 6e 20 44 2c 20 0a 2a 2a 20 74 68 65 6e 20 73  on D, .** then s
16a50 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
16a60 72 74 5f 72 6f 77 69 64 28 44 29 20 72 65 74 75  rt_rowid(D) retu
16a70 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20  rns zero..**.** 
16a80 5e 28 49 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d  ^(If an [INSERT]
16a90 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61   occurs within a
16aa0 20 74 72 69 67 67 65 72 20 6f 72 20 77 69 74 68   trigger or with
16ab0 69 6e 20 61 20 5b 76 69 72 74 75 61 6c 20 74 61  in a [virtual ta
16ac0 62 6c 65 5d 0a 2a 2a 20 6d 65 74 68 6f 64 2c 20  ble].** method, 
16ad0 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e  then this routin
16ae0 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 74 68  e will return th
16af0 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65  e [rowid] of the
16b00 20 69 6e 73 65 72 74 65 64 0a 2a 2a 20 72 6f 77   inserted.** row
16b10 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20   as long as the 
16b20 74 72 69 67 67 65 72 20 6f 72 20 76 69 72 74 75  trigger or virtu
16b30 61 6c 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20  al table method 
16b40 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42  is running..** B
16b50 75 74 20 6f 6e 63 65 20 74 68 65 20 74 72 69 67  ut once the trig
16b60 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c 20 74  ger or virtual t
16b70 61 62 6c 65 20 6d 65 74 68 6f 64 20 65 6e 64 73  able method ends
16b80 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  , the value retu
16b90 72 6e 65 64 20 0a 2a 2a 20 62 79 20 74 68 69 73  rned .** by this
16ba0 20 72 6f 75 74 69 6e 65 20 72 65 76 65 72 74 73   routine reverts
16bb0 20 74 6f 20 77 68 61 74 20 69 74 20 77 61 73 20   to what it was 
16bc0 62 65 66 6f 72 65 20 74 68 65 20 74 72 69 67 67  before the trigg
16bd0 65 72 20 6f 72 20 76 69 72 74 75 61 6c 0a 2a 2a  er or virtual.**
16be0 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 62 65   table method be
16bf0 67 61 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e  gan.)^.**.** ^An
16c00 20 5b 49 4e 53 45 52 54 5d 20 74 68 61 74 20 66   [INSERT] that f
16c10 61 69 6c 73 20 64 75 65 20 74 6f 20 61 20 63 6f  ails due to a co
16c20 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69  nstraint violati
16c30 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73  on is not a.** s
16c40 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52  uccessful [INSER
16c50 54 5d 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20  T] and does not 
16c60 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65  change the value
16c70 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69   returned by thi
16c80 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20 5e  s.** routine.  ^
16c90 54 68 75 73 20 49 4e 53 45 52 54 20 4f 52 20 46  Thus INSERT OR F
16ca0 41 49 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20 49  AIL, INSERT OR I
16cb0 47 4e 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f 52  GNORE, INSERT OR
16cc0 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e   ROLLBACK,.** an
16cd0 64 20 49 4e 53 45 52 54 20 4f 52 20 41 42 4f 52  d INSERT OR ABOR
16ce0 54 20 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65  T make no change
16cf0 73 20 74 6f 20 74 68 65 20 72 65 74 75 72 6e 20  s to the return 
16d00 76 61 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a  value of this.**
16d10 20 72 6f 75 74 69 6e 65 20 77 68 65 6e 20 74 68   routine when th
16d20 65 69 72 20 69 6e 73 65 72 74 69 6f 6e 20 66 61  eir insertion fa
16d30 69 6c 73 2e 20 20 5e 28 57 68 65 6e 20 49 4e 53  ils.  ^(When INS
16d40 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 0a 2a  ERT OR REPLACE.*
16d50 2a 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 20 63  * encounters a c
16d60 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74  onstraint violat
16d70 69 6f 6e 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74  ion, it does not
16d80 20 66 61 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49   fail.  The.** I
16d90 4e 53 45 52 54 20 63 6f 6e 74 69 6e 75 65 73 20  NSERT continues 
16da0 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66  to completion af
16db0 74 65 72 20 64 65 6c 65 74 69 6e 67 20 72 6f 77  ter deleting row
16dc0 73 20 74 68 61 74 20 63 61 75 73 65 64 0a 2a 2a  s that caused.**
16dd0 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 20   the constraint 
16de0 70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52  problem so INSER
16df0 54 20 4f 52 20 52 45 50 4c 41 43 45 20 77 69 6c  T OR REPLACE wil
16e00 6c 20 61 6c 77 61 79 73 20 63 68 61 6e 67 65 0a  l always change.
16e10 2a 2a 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  ** the return va
16e20 6c 75 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65  lue of this inte
16e30 72 66 61 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  rface.)^.**.** ^
16e40 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65 73  For the purposes
16e50 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65   of this routine
16e60 2c 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 69 73  , an [INSERT] is
16e70 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a   considered to.*
16e80 2a 20 62 65 20 73 75 63 63 65 73 73 66 75 6c 20  * be successful 
16e90 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 73 75  even if it is su
16ea0 62 73 65 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65  bsequently rolle
16eb0 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68  d back..**.** Th
16ec0 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61  is function is a
16ed0 63 63 65 73 73 69 62 6c 65 20 74 6f 20 53 51 4c  ccessible to SQL
16ee0 20 73 74 61 74 65 6d 65 6e 74 73 20 76 69 61 20   statements via 
16ef0 74 68 65 0a 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73  the.** [last_ins
16f00 65 72 74 5f 72 6f 77 69 64 28 29 20 53 51 4c 20  ert_rowid() SQL 
16f10 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a  function]..**.**
16f20 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74   If a separate t
16f30 68 72 65 61 64 20 70 65 72 66 6f 72 6d 73 20 61  hread performs a
16f40 20 6e 65 77 20 5b 49 4e 53 45 52 54 5d 20 6f 6e   new [INSERT] on
16f50 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 64 61 74   the same.** dat
16f60 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
16f70 20 77 68 69 6c 65 20 74 68 65 20 5b 73 71 6c 69   while the [sqli
16f80 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
16f90 72 6f 77 69 64 28 29 5d 0a 2a 2a 20 66 75 6e 63  rowid()].** func
16fa0 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20  tion is running 
16fb0 61 6e 64 20 74 68 75 73 20 63 68 61 6e 67 65 73  and thus changes
16fc0 20 74 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74   the last insert
16fd0 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68 65   [rowid],.** the
16fe0 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  n the value retu
16ff0 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
17000 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
17010 69 64 28 29 5d 20 69 73 0a 2a 2a 20 75 6e 70 72  id()] is.** unpr
17020 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6d 69  edictable and mi
17030 67 68 74 20 6e 6f 74 20 65 71 75 61 6c 20 65 69  ght not equal ei
17040 74 68 65 72 20 74 68 65 20 6f 6c 64 20 6f 72 20  ther the old or 
17050 74 68 65 20 6e 65 77 0a 2a 2a 20 6c 61 73 74 20  the new.** last 
17060 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2e 0a  insert [rowid]..
17070 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71  */.SQLITE_API sq
17080 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
17090 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
170a0 72 6f 77 69 64 28 73 71 6c 69 74 65 33 2a 29 3b  rowid(sqlite3*);
170b0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
170c0 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62  : Count The Numb
170d0 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66  er Of Rows Modif
170e0 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  ied.**.** ^This 
170f0 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
17100 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64   the number of d
17110 61 74 61 62 61 73 65 20 72 6f 77 73 20 74 68 61  atabase rows tha
17120 74 20 77 65 72 65 20 63 68 61 6e 67 65 64 0a 2a  t were changed.*
17130 2a 20 6f 72 20 69 6e 73 65 72 74 65 64 20 6f 72  * or inserted or
17140 20 64 65 6c 65 74 65 64 20 62 79 20 74 68 65 20   deleted by the 
17150 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f  most recently co
17160 6d 70 6c 65 74 65 64 20 53 51 4c 20 73 74 61 74  mpleted SQL stat
17170 65 6d 65 6e 74 0a 2a 2a 20 6f 6e 20 74 68 65 20  ement.** on the 
17180 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
17190 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20  tion] specified 
171a0 62 79 20 74 68 65 20 66 69 72 73 74 20 70 61 72  by the first par
171b0 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 28 4f 6e 6c  ameter..** ^(Onl
171c0 79 20 63 68 61 6e 67 65 73 20 74 68 61 74 20 61  y changes that a
171d0 72 65 20 64 69 72 65 63 74 6c 79 20 73 70 65 63  re directly spec
171e0 69 66 69 65 64 20 62 79 20 74 68 65 20 5b 49 4e  ified by the [IN
171f0 53 45 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d 2c  SERT], [UPDATE],
17200 0a 2a 2a 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20  .** or [DELETE] 
17210 73 74 61 74 65 6d 65 6e 74 20 61 72 65 20 63 6f  statement are co
17220 75 6e 74 65 64 2e 20 20 41 75 78 69 6c 69 61 72  unted.  Auxiliar
17230 79 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64  y changes caused
17240 20 62 79 0a 2a 2a 20 74 72 69 67 67 65 72 73 20   by.** triggers 
17250 6f 72 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20  or [foreign key 
17260 61 63 74 69 6f 6e 73 5d 20 61 72 65 20 6e 6f 74  actions] are not
17270 20 63 6f 75 6e 74 65 64 2e 29 5e 20 55 73 65 20   counted.)^ Use 
17280 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
17290 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d  total_changes()]
172a0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 66 69 6e   function to fin
172b0 64 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62  d the total numb
172c0 65 72 20 6f 66 20 63 68 61 6e 67 65 73 0a 2a 2a  er of changes.**
172d0 20 69 6e 63 6c 75 64 69 6e 67 20 63 68 61 6e 67   including chang
172e0 65 73 20 63 61 75 73 65 64 20 62 79 20 74 72 69  es caused by tri
172f0 67 67 65 72 73 20 61 6e 64 20 66 6f 72 65 69 67  ggers and foreig
17300 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 2e 0a 2a  n key actions..*
17310 2a 0a 2a 2a 20 5e 43 68 61 6e 67 65 73 20 74 6f  *.** ^Changes to
17320 20 61 20 76 69 65 77 20 74 68 61 74 20 61 72 65   a view that are
17330 20 73 69 6d 75 6c 61 74 65 64 20 62 79 20 61 6e   simulated by an
17340 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69   [INSTEAD OF tri
17350 67 67 65 72 5d 0a 2a 2a 20 61 72 65 20 6e 6f 74  gger].** are not
17360 20 63 6f 75 6e 74 65 64 2e 20 20 4f 6e 6c 79 20   counted.  Only 
17370 72 65 61 6c 20 74 61 62 6c 65 20 63 68 61 6e 67  real table chang
17380 65 73 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 0a  es are counted..
17390 2a 2a 0a 2a 2a 20 5e 28 41 20 22 72 6f 77 20 63  **.** ^(A "row c
173a0 68 61 6e 67 65 22 20 69 73 20 61 20 63 68 61 6e  hange" is a chan
173b0 67 65 20 74 6f 20 61 20 73 69 6e 67 6c 65 20 72  ge to a single r
173c0 6f 77 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 74  ow of a single t
173d0 61 62 6c 65 0a 2a 2a 20 63 61 75 73 65 64 20 62  able.** caused b
173e0 79 20 61 6e 20 49 4e 53 45 52 54 2c 20 44 45 4c  y an INSERT, DEL
173f0 45 54 45 2c 20 6f 72 20 55 50 44 41 54 45 20 73  ETE, or UPDATE s
17400 74 61 74 65 6d 65 6e 74 2e 20 20 52 6f 77 73 20  tatement.  Rows 
17410 74 68 61 74 0a 2a 2a 20 61 72 65 20 63 68 61 6e  that.** are chan
17420 67 65 64 20 61 73 20 73 69 64 65 20 65 66 66 65  ged as side effe
17430 63 74 73 20 6f 66 20 5b 52 45 50 4c 41 43 45 5d  cts of [REPLACE]
17440 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f   constraint reso
17450 6c 75 74 69 6f 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62  lution,.** rollb
17460 61 63 6b 2c 20 41 42 4f 52 54 20 70 72 6f 63 65  ack, ABORT proce
17470 73 73 69 6e 67 2c 20 5b 44 52 4f 50 20 54 41 42  ssing, [DROP TAB
17480 4c 45 5d 2c 20 6f 72 20 62 79 20 61 6e 79 20 6f  LE], or by any o
17490 74 68 65 72 0a 2a 2a 20 6d 65 63 68 61 6e 69 73  ther.** mechanis
174a0 6d 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20  ms do not count 
174b0 61 73 20 64 69 72 65 63 74 20 72 6f 77 20 63 68  as direct row ch
174c0 61 6e 67 65 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41  anges.)^.**.** A
174d0 20 22 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78   "trigger contex
174e0 74 22 20 69 73 20 61 20 73 63 6f 70 65 20 6f 66  t" is a scope of
174f0 20 65 78 65 63 75 74 69 6f 6e 20 74 68 61 74 20   execution that 
17500 62 65 67 69 6e 73 20 61 6e 64 0a 2a 2a 20 65 6e  begins and.** en
17510 64 73 20 77 69 74 68 20 74 68 65 20 73 63 72 69  ds with the scri
17520 70 74 20 6f 66 20 61 20 5b 43 52 45 41 54 45 20  pt of a [CREATE 
17530 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65  TRIGGER | trigge
17540 72 5d 2e 20 0a 2a 2a 20 4d 6f 73 74 20 53 51 4c  r]. .** Most SQL
17550 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 0a   statements are.
17560 2a 2a 20 65 76 61 6c 75 61 74 65 64 20 6f 75 74  ** evaluated out
17570 73 69 64 65 20 6f 66 20 61 6e 79 20 74 72 69 67  side of any trig
17580 67 65 72 2e 20 20 54 68 69 73 20 69 73 20 74 68  ger.  This is th
17590 65 20 22 74 6f 70 20 6c 65 76 65 6c 22 0a 2a 2a  e "top level".**
175a0 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74   trigger context
175b0 2e 20 20 49 66 20 61 20 74 72 69 67 67 65 72 20  .  If a trigger 
175c0 66 69 72 65 73 20 66 72 6f 6d 20 74 68 65 20 74  fires from the t
175d0 6f 70 20 6c 65 76 65 6c 2c 20 61 0a 2a 2a 20 6e  op level, a.** n
175e0 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65  ew trigger conte
175f0 78 74 20 69 73 20 65 6e 74 65 72 65 64 20 66 6f  xt is entered fo
17600 72 20 74 68 65 20 64 75 72 61 74 69 6f 6e 20 6f  r the duration o
17610 66 20 74 68 61 74 20 6f 6e 65 0a 2a 2a 20 74 72  f that one.** tr
17620 69 67 67 65 72 2e 20 20 53 75 62 74 72 69 67 67  igger.  Subtrigg
17630 65 72 73 20 63 72 65 61 74 65 20 73 75 62 63 6f  ers create subco
17640 6e 74 65 78 74 73 20 66 6f 72 20 74 68 65 69 72  ntexts for their
17650 20 64 75 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   duration..**.**
17660 20 5e 43 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74   ^Calling [sqlit
17670 65 33 5f 65 78 65 63 28 29 5d 20 6f 72 20 5b 73  e3_exec()] or [s
17680 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72  qlite3_step()] r
17690 65 63 75 72 73 69 76 65 6c 79 20 64 6f 65 73 0a  ecursively does.
176a0 2a 2a 20 6e 6f 74 20 63 72 65 61 74 65 20 61 20  ** not create a 
176b0 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74  new trigger cont
176c0 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  ext..**.** ^This
176d0 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
176e0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
176f0 64 69 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67  direct row chang
17700 65 73 20 69 6e 20 74 68 65 0a 2a 2a 20 6d 6f 73  es in the.** mos
17710 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c  t recent INSERT,
17720 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45   UPDATE, or DELE
17730 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74  TE statement wit
17740 68 69 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20  hin the same.** 
17750 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e  trigger context.
17760 0a 2a 2a 0a 2a 2a 20 5e 54 68 75 73 2c 20 77 68  .**.** ^Thus, wh
17770 65 6e 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74  en called from t
17780 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20 74 68  he top level, th
17790 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  is function retu
177a0 72 6e 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65  rns the.** numbe
177b0 72 20 6f 66 20 63 68 61 6e 67 65 73 20 69 6e 20  r of changes in 
177c0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
177d0 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20  INSERT, UPDATE, 
177e0 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61  or DELETE.** tha
177f0 74 20 61 6c 73 6f 20 6f 63 63 75 72 72 65 64 20  t also occurred 
17800 61 74 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c  at the top level
17810 2e 20 20 5e 28 57 69 74 68 69 6e 20 74 68 65 20  .  ^(Within the 
17820 62 6f 64 79 20 6f 66 20 61 20 74 72 69 67 67 65  body of a trigge
17830 72 2c 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65  r,.** the sqlite
17840 33 5f 63 68 61 6e 67 65 73 28 29 20 69 6e 74 65  3_changes() inte
17850 72 66 61 63 65 20 63 61 6e 20 62 65 20 63 61 6c  rface can be cal
17860 6c 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20  led to find the 
17870 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61  number of.** cha
17880 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74  nges in the most
17890 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65   recently comple
178a0 74 65 64 20 49 4e 53 45 52 54 2c 20 55 50 44 41  ted INSERT, UPDA
178b0 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a  TE, or DELETE.**
178c0 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69   statement withi
178d0 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20 74 68  n the body of th
178e0 65 20 73 61 6d 65 20 74 72 69 67 67 65 72 2e 0a  e same trigger..
178f0 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20  ** However, the 
17900 6e 75 6d 62 65 72 20 72 65 74 75 72 6e 65 64 20  number returned 
17910 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65  does not include
17920 20 63 68 61 6e 67 65 73 0a 2a 2a 20 63 61 75 73   changes.** caus
17930 65 64 20 62 79 20 73 75 62 74 72 69 67 67 65 72  ed by subtrigger
17940 73 20 73 69 6e 63 65 20 74 68 6f 73 65 20 68 61  s since those ha
17950 76 65 20 74 68 65 69 72 20 6f 77 6e 20 63 6f 6e  ve their own con
17960 74 65 78 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65  text.)^.**.** Se
17970 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69  e also the [sqli
17980 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
17990 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20  s()] interface, 
179a0 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68  the.** [count_ch
179b0 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61  anges pragma], a
179c0 6e 64 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28  nd the [changes(
179d0 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e  ) SQL function].
179e0 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61  .**.** If a sepa
179f0 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65  rate thread make
17a00 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65  s changes on the
17a10 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
17a20 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69  onnection.** whi
17a30 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e  le [sqlite3_chan
17a40 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e  ges()] is runnin
17a50 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65  g then the value
17a60 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20   returned.** is 
17a70 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e  unpredictable an
17a80 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c  d not meaningful
17a90 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
17aa0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e  int sqlite3_chan
17ab0 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  ges(sqlite3*);..
17ac0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
17ad0 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20  Total Number Of 
17ae0 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a  Rows Modified.**
17af0 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69  .** ^This functi
17b00 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  on returns the n
17b10 75 6d 62 65 72 20 6f 66 20 72 6f 77 20 63 68 61  umber of row cha
17b20 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20 5b  nges caused by [
17b30 49 4e 53 45 52 54 5d 2c 0a 2a 2a 20 5b 55 50 44  INSERT],.** [UPD
17b40 41 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d  ATE] or [DELETE]
17b50 20 73 74 61 74 65 6d 65 6e 74 73 20 73 69 6e 63   statements sinc
17b60 65 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  e the [database 
17b70 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 61 73 20  connection] was 
17b80 6f 70 65 6e 65 64 2e 0a 2a 2a 20 5e 28 54 68 65  opened..** ^(The
17b90 20 63 6f 75 6e 74 20 72 65 74 75 72 6e 65 64 20   count returned 
17ba0 62 79 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  by sqlite3_total
17bb0 5f 63 68 61 6e 67 65 73 28 29 20 69 6e 63 6c 75  _changes() inclu
17bc0 64 65 73 20 61 6c 6c 20 63 68 61 6e 67 65 73 0a  des all changes.
17bd0 2a 2a 20 66 72 6f 6d 20 61 6c 6c 20 5b 43 52 45  ** from all [CRE
17be0 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72  ATE TRIGGER | tr
17bf0 69 67 67 65 72 5d 20 63 6f 6e 74 65 78 74 73 20  igger] contexts 
17c00 61 6e 64 20 63 68 61 6e 67 65 73 20 6d 61 64 65  and changes made
17c10 20 62 79 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20   by.** [foreign 
17c20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 2e 20 48 6f  key actions]. Ho
17c30 77 65 76 65 72 2c 0a 2a 2a 20 74 68 65 20 63 6f  wever,.** the co
17c40 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63  unt does not inc
17c50 6c 75 64 65 20 63 68 61 6e 67 65 73 20 75 73 65  lude changes use
17c60 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b  d to implement [
17c70 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61  REPLACE] constra
17c80 69 6e 74 73 2c 0a 2a 2a 20 64 6f 20 72 6f 6c 6c  ints,.** do roll
17c90 62 61 63 6b 73 20 6f 72 20 41 42 4f 52 54 20 70  backs or ABORT p
17ca0 72 6f 63 65 73 73 69 6e 67 2c 20 6f 72 20 5b 44  rocessing, or [D
17cb0 52 4f 50 20 54 41 42 4c 45 5d 20 70 72 6f 63 65  ROP TABLE] proce
17cc0 73 73 69 6e 67 2e 20 20 54 68 65 0a 2a 2a 20 63  ssing.  The.** c
17cd0 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e  ount does not in
17ce0 63 6c 75 64 65 20 72 6f 77 73 20 6f 66 20 76 69  clude rows of vi
17cf0 65 77 73 20 74 68 61 74 20 66 69 72 65 20 61 6e  ews that fire an
17d00 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69   [INSTEAD OF tri
17d10 67 67 65 72 5d 2c 0a 2a 2a 20 74 68 6f 75 67 68  gger],.** though
17d20 20 69 66 20 74 68 65 20 49 4e 53 54 45 41 44 20   if the INSTEAD 
17d30 4f 46 20 74 72 69 67 67 65 72 20 6d 61 6b 65 73  OF trigger makes
17d40 20 63 68 61 6e 67 65 73 20 6f 66 20 69 74 73 20   changes of its 
17d50 6f 77 6e 2c 20 74 68 6f 73 65 20 63 68 61 6e 67  own, those chang
17d60 65 73 20 0a 2a 2a 20 61 72 65 20 63 6f 75 6e 74  es .** are count
17d70 65 64 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 73 71  ed.)^.** ^The sq
17d80 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
17d90 67 65 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 63  ges() function c
17da0 6f 75 6e 74 73 20 74 68 65 20 63 68 61 6e 67 65  ounts the change
17db0 73 20 61 73 20 73 6f 6f 6e 20 61 73 0a 2a 2a 20  s as soon as.** 
17dc0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 68  the statement th
17dd0 61 74 20 6d 61 6b 65 73 20 74 68 65 6d 20 69 73  at makes them is
17de0 20 63 6f 6d 70 6c 65 74 65 64 20 28 77 68 65 6e   completed (when
17df0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68   the statement h
17e00 61 6e 64 6c 65 0a 2a 2a 20 69 73 20 70 61 73 73  andle.** is pass
17e10 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  ed to [sqlite3_r
17e20 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69  eset()] or [sqli
17e30 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 29  te3_finalize()])
17e40 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
17e50 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68   the [sqlite3_ch
17e60 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61  anges()] interfa
17e70 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e  ce, the.** [coun
17e80 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61  t_changes pragma
17e90 5d 2c 20 61 6e 64 20 74 68 65 20 5b 74 6f 74 61  ], and the [tota
17ea0 6c 5f 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20  l_changes() SQL 
17eb0 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a  function]..**.**
17ec0 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74   If a separate t
17ed0 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e  hread makes chan
17ee0 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  ges on the same 
17ef0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
17f00 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71  ion.** while [sq
17f10 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
17f20 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e  ges()] is runnin
17f30 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65  g then the value
17f40 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 73 20  .** returned is 
17f50 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e  unpredictable an
17f60 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c  d not meaningful
17f70 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
17f80 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 6f 74 61  int sqlite3_tota
17f90 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65  l_changes(sqlite
17fa0 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
17fb0 33 52 45 46 3a 20 49 6e 74 65 72 72 75 70 74 20  3REF: Interrupt 
17fc0 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 51  A Long-Running Q
17fd0 75 65 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  uery.**.** ^This
17fe0 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73   function causes
17ff0 20 61 6e 79 20 70 65 6e 64 69 6e 67 20 64 61 74   any pending dat
18000 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 20  abase operation 
18010 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20  to abort and.** 
18020 72 65 74 75 72 6e 20 61 74 20 69 74 73 20 65 61  return at its ea
18030 72 6c 69 65 73 74 20 6f 70 70 6f 72 74 75 6e 69  rliest opportuni
18040 74 79 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65  ty. This routine
18050 20 69 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a   is typically.**
18060 20 63 61 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f   called in respo
18070 6e 73 65 20 74 6f 20 61 20 75 73 65 72 20 61 63  nse to a user ac
18080 74 69 6f 6e 20 73 75 63 68 20 61 73 20 70 72 65  tion such as pre
18090 73 73 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a  ssing "Cancel".*
180a0 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77 68 65 72  * or Ctrl-C wher
180b0 65 20 74 68 65 20 75 73 65 72 20 77 61 6e 74 73  e the user wants
180c0 20 61 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70   a long query op
180d0 65 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a  eration to halt.
180e0 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a  ** immediately..
180f0 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 73 61 66  **.** ^It is saf
18100 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72  e to call this r
18110 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61 20 74 68  outine from a th
18120 72 65 61 64 20 64 69 66 66 65 72 65 6e 74 20 66  read different f
18130 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65 61  rom the.** threa
18140 64 20 74 68 61 74 20 69 73 20 63 75 72 72 65 6e  d that is curren
18150 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68 65 20  tly running the 
18160 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69  database operati
18170 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20 69  on.  But it.** i
18180 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 63 61  s not safe to ca
18190 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  ll this routine 
181a0 77 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65  with a [database
181b0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61   connection] tha
181c0 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f  t.** is closed o
181d0 72 20 6d 69 67 68 74 20 63 6c 6f 73 65 20 62 65  r might close be
181e0 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 69 6e 74  fore sqlite3_int
181f0 65 72 72 75 70 74 28 29 20 72 65 74 75 72 6e 73  errupt() returns
18200 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 53  ..**.** ^If an S
18210 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20  QL operation is 
18220 76 65 72 79 20 6e 65 61 72 6c 79 20 66 69 6e 69  very nearly fini
18230 73 68 65 64 20 61 74 20 74 68 65 20 74 69 6d 65  shed at the time
18240 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33   when.** sqlite3
18250 5f 69 6e 74 65 72 72 75 70 74 28 29 20 69 73 20  _interrupt() is 
18260 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74 20  called, then it 
18270 6d 69 67 68 74 20 6e 6f 74 20 68 61 76 65 20 61  might not have a
18280 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a 2a 2a  n opportunity.**
18290 20 74 6f 20 62 65 20 69 6e 74 65 72 72 75 70 74   to be interrupt
182a0 65 64 20 61 6e 64 20 6d 69 67 68 74 20 63 6f 6e  ed and might con
182b0 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74  tinue to complet
182c0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53  ion..**.** ^An S
182d0 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61  QL operation tha
182e0 74 20 69 73 20 69 6e 74 65 72 72 75 70 74 65 64  t is interrupted
182f0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
18300 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e  LITE_INTERRUPT].
18310 0a 2a 2a 20 5e 49 66 20 74 68 65 20 69 6e 74 65  .** ^If the inte
18320 72 72 75 70 74 65 64 20 53 51 4c 20 6f 70 65 72  rrupted SQL oper
18330 61 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45  ation is an INSE
18340 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44  RT, UPDATE, or D
18350 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 69 73  ELETE.** that is
18360 20 69 6e 73 69 64 65 20 61 6e 20 65 78 70 6c 69   inside an expli
18370 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c  cit transaction,
18380 20 74 68 65 6e 20 74 68 65 20 65 6e 74 69 72 65   then the entire
18390 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20   transaction.** 
183a0 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62  will be rolled b
183b0 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ack automaticall
183c0 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  y..**.** ^The sq
183d0 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
183e0 44 29 20 63 61 6c 6c 20 69 73 20 69 6e 20 65 66  D) call is in ef
183f0 66 65 63 74 20 75 6e 74 69 6c 20 61 6c 6c 20 63  fect until all c
18400 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67  urrently running
18410 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
18420 74 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20  ts on [database 
18430 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 63 6f  connection] D co
18440 6d 70 6c 65 74 65 2e 20 20 5e 41 6e 79 20 6e 65  mplete.  ^Any ne
18450 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  w SQL statements
18460 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61  .** that are sta
18470 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20 73  rted after the s
18480 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
18490 28 29 20 63 61 6c 6c 20 61 6e 64 20 62 65 66 6f  () call and befo
184a0 72 65 20 74 68 65 20 0a 2a 2a 20 72 75 6e 6e 69  re the .** runni
184b0 6e 67 20 73 74 61 74 65 6d 65 6e 74 73 20 72 65  ng statements re
184c0 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65 20 69  aches zero are i
184d0 6e 74 65 72 72 75 70 74 65 64 20 61 73 20 69 66  nterrupted as if
184e0 20 74 68 65 79 20 68 61 64 20 62 65 65 6e 0a 2a   they had been.*
184f0 2a 20 72 75 6e 6e 69 6e 67 20 70 72 69 6f 72 20  * running prior 
18500 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  to the sqlite3_i
18510 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 2e  nterrupt() call.
18520 20 20 5e 4e 65 77 20 53 51 4c 20 73 74 61 74 65    ^New SQL state
18530 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72  ments.** that ar
18540 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20  e started after 
18550 74 68 65 20 72 75 6e 6e 69 6e 67 20 73 74 61 74  the running stat
18560 65 6d 65 6e 74 20 63 6f 75 6e 74 20 72 65 61 63  ement count reac
18570 68 65 73 20 7a 65 72 6f 20 61 72 65 0a 2a 2a 20  hes zero are.** 
18580 6e 6f 74 20 65 66 66 65 63 74 65 64 20 62 79 20  not effected by 
18590 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  the sqlite3_inte
185a0 72 72 75 70 74 28 29 2e 0a 2a 2a 20 5e 41 20 63  rrupt()..** ^A c
185b0 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69  all to sqlite3_i
185c0 6e 74 65 72 72 75 70 74 28 44 29 20 74 68 61 74  nterrupt(D) that
185d0 20 6f 63 63 75 72 73 20 77 68 65 6e 20 74 68 65   occurs when the
185e0 72 65 20 61 72 65 20 6e 6f 20 72 75 6e 6e 69 6e  re are no runnin
185f0 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  g.** SQL stateme
18600 6e 74 73 20 69 73 20 61 20 6e 6f 2d 6f 70 20 61  nts is a no-op a
18610 6e 64 20 68 61 73 20 6e 6f 20 65 66 66 65 63 74  nd has no effect
18620 20 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   on SQL statemen
18630 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73  ts.** that are s
18640 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65  tarted after the
18650 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
18660 70 74 28 29 20 63 61 6c 6c 20 72 65 74 75 72 6e  pt() call return
18670 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  s..**.** If the 
18680 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
18690 69 6f 6e 20 63 6c 6f 73 65 73 20 77 68 69 6c 65  ion closes while
186a0 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72   [sqlite3_interr
186b0 75 70 74 28 29 5d 0a 2a 2a 20 69 73 20 72 75 6e  upt()].** is run
186c0 6e 69 6e 67 20 74 68 65 6e 20 62 61 64 20 74 68  ning then bad th
186d0 69 6e 67 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79  ings will likely
186e0 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a 53 51 4c 49   happen..*/.SQLI
186f0 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69  TE_API void sqli
18700 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 73 71  te3_interrupt(sq
18710 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
18720 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d  CAPI3REF: Determ
18730 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74  ine If An SQL St
18740 61 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c  atement Is Compl
18750 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ete.**.** These 
18760 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65  routines are use
18770 66 75 6c 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61  ful during comma
18780 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f  nd-line input to
18790 20 64 65 74 65 72 6d 69 6e 65 20 69 66 20 74 68   determine if th
187a0 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 65  e.** currently e
187b0 6e 74 65 72 65 64 20 74 65 78 74 20 73 65 65 6d  ntered text seem
187c0 73 20 74 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70  s to form a comp
187d0 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65  lete SQL stateme
187e0 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69  nt or.** if addi
187f0 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 20  tional input is 
18800 6e 65 65 64 65 64 20 62 65 66 6f 72 65 20 73 65  needed before se
18810 6e 64 69 6e 67 20 74 68 65 20 74 65 78 74 20 69  nding the text i
18820 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f  nto.** SQLite fo
18830 72 20 70 61 72 73 69 6e 67 2e 20 20 5e 54 68 65  r parsing.  ^The
18840 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  se routines retu
18850 72 6e 20 31 20 69 66 20 74 68 65 20 69 6e 70 75  rn 1 if the inpu
18860 74 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65  t string.** appe
18870 61 72 73 20 74 6f 20 62 65 20 61 20 63 6f 6d 70  ars to be a comp
18880 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65  lete SQL stateme
18890 6e 74 2e 20 20 5e 41 20 73 74 61 74 65 6d 65 6e  nt.  ^A statemen
188a0 74 20 69 73 20 6a 75 64 67 65 64 20 74 6f 20 62  t is judged to b
188b0 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66  e.** complete if
188c0 20 69 74 20 65 6e 64 73 20 77 69 74 68 20 61 20   it ends with a 
188d0 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20  semicolon token 
188e0 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 72 65  and is not a pre
188f0 66 69 78 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c  fix of a.** well
18900 2d 66 6f 72 6d 65 64 20 43 52 45 41 54 45 20 54  -formed CREATE T
18910 52 49 47 47 45 52 20 73 74 61 74 65 6d 65 6e 74  RIGGER statement
18920 2e 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20 74  .  ^Semicolons t
18930 68 61 74 20 61 72 65 20 65 6d 62 65 64 64 65 64  hat are embedded
18940 20 77 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e   within.** strin
18950 67 20 6c 69 74 65 72 61 6c 73 20 6f 72 20 71 75  g literals or qu
18960 6f 74 65 64 20 69 64 65 6e 74 69 66 69 65 72 20  oted identifier 
18970 6e 61 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74  names or comment
18980 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64  s are not.** ind
18990 65 70 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20  ependent tokens 
189a0 28 74 68 65 79 20 61 72 65 20 70 61 72 74 20 6f  (they are part o
189b0 66 20 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77  f the token in w
189c0 68 69 63 68 20 74 68 65 79 20 61 72 65 0a 2a 2a  hich they are.**
189d0 20 65 6d 62 65 64 64 65 64 29 20 61 6e 64 20 74   embedded) and t
189e0 68 75 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74  hus do not count
189f0 20 61 73 20 61 20 73 74 61 74 65 6d 65 6e 74 20   as a statement 
18a00 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 57 68  terminator.  ^Wh
18a10 69 74 65 73 70 61 63 65 0a 2a 2a 20 61 6e 64 20  itespace.** and 
18a20 63 6f 6d 6d 65 6e 74 73 20 74 68 61 74 20 66 6f  comments that fo
18a30 6c 6c 6f 77 20 74 68 65 20 66 69 6e 61 6c 20 73  llow the final s
18a40 65 6d 69 63 6f 6c 6f 6e 20 61 72 65 20 69 67 6e  emicolon are ign
18a50 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ored..**.** ^The
18a60 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  se routines retu
18a70 72 6e 20 30 20 69 66 20 74 68 65 20 73 74 61 74  rn 0 if the stat
18a80 65 6d 65 6e 74 20 69 73 20 69 6e 63 6f 6d 70 6c  ement is incompl
18a90 65 74 65 2e 20 20 5e 49 66 20 61 0a 2a 2a 20 6d  ete.  ^If a.** m
18aa0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
18ab0 20 66 61 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c   fails, then SQL
18ac0 49 54 45 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74  ITE_NOMEM is ret
18ad0 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  urned..**.** ^Th
18ae0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 64 6f 20  ese routines do 
18af0 6e 6f 74 20 70 61 72 73 65 20 74 68 65 20 53 51  not parse the SQ
18b00 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 75  L statements thu
18b10 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65  s.** will not de
18b20 74 65 63 74 20 73 79 6e 74 61 63 74 69 63 61 6c  tect syntactical
18b30 6c 79 20 69 6e 63 6f 72 72 65 63 74 20 53 51 4c  ly incorrect SQL
18b40 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c  ..**.** ^(If SQL
18b50 69 74 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e  ite has not been
18b60 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 75 73 69   initialized usi
18b70 6e 67 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74  ng [sqlite3_init
18b80 69 61 6c 69 7a 65 28 29 5d 20 70 72 69 6f 72 20  ialize()] prior 
18b90 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20  .** to invoking 
18ba0 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
18bb0 31 36 28 29 20 74 68 65 6e 20 73 71 6c 69 74 65  16() then sqlite
18bc0 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
18bd0 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 74  s invoked.** aut
18be0 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71  omatically by sq
18bf0 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
18c00 28 29 2e 20 20 49 66 20 74 68 61 74 20 69 6e 69  ().  If that ini
18c10 74 69 61 6c 69 7a 61 74 69 6f 6e 20 66 61 69 6c  tialization fail
18c20 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 72  s,.** then the r
18c30 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d  eturn value from
18c40 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
18c50 65 31 36 28 29 20 77 69 6c 6c 20 62 65 20 6e 6f  e16() will be no
18c60 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67 61 72 64  n-zero.** regard
18c70 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20  less of whether 
18c80 6f 72 20 6e 6f 74 20 74 68 65 20 69 6e 70 75 74  or not the input
18c90 20 53 51 4c 20 69 73 20 63 6f 6d 70 6c 65 74 65   SQL is complete
18ca0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e  .)^.**.** The in
18cb0 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  put to [sqlite3_
18cc0 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6d 75 73 74  complete()] must
18cd0 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   be a zero-termi
18ce0 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73  nated.** UTF-8 s
18cf0 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tring..**.** The
18d00 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74   input to [sqlit
18d10 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d  e3_complete16()]
18d20 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d   must be a zero-
18d30 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54  terminated.** UT
18d40 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e  F-16 string in n
18d50 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
18d60 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
18d70 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  int sqlite3_comp
18d80 6c 65 74 65 28 63 6f 6e 73 74 20 63 68 61 72 20  lete(const char 
18d90 2a 73 71 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50  *sql);.SQLITE_AP
18da0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  I int sqlite3_co
18db0 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73 74 20 76  mplete16(const v
18dc0 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a  oid *sql);../*.*
18dd0 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 67 69  * CAPI3REF: Regi
18de0 73 74 65 72 20 41 20 43 61 6c 6c 62 61 63 6b 20  ster A Callback 
18df0 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49 54 45  To Handle SQLITE
18e00 5f 42 55 53 59 20 45 72 72 6f 72 73 0a 2a 2a 0a  _BUSY Errors.**.
18e10 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65  ** ^This routine
18e20 20 73 65 74 73 20 61 20 63 61 6c 6c 62 61 63 6b   sets a callback
18e30 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 6d   function that m
18e40 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20  ight be invoked 
18e50 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 61  whenever.** an a
18e60 74 74 65 6d 70 74 20 69 73 20 6d 61 64 65 20 74  ttempt is made t
18e70 6f 20 6f 70 65 6e 20 61 20 64 61 74 61 62 61 73  o open a databas
18e80 65 20 74 61 62 6c 65 20 74 68 61 74 20 61 6e 6f  e table that ano
18e90 74 68 65 72 20 74 68 72 65 61 64 0a 2a 2a 20 6f  ther thread.** o
18ea0 72 20 70 72 6f 63 65 73 73 20 68 61 73 20 6c 6f  r process has lo
18eb0 63 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  cked..**.** ^If 
18ec0 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63  the busy callbac
18ed0 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20  k is NULL, then 
18ee0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72  [SQLITE_BUSY] or
18ef0 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42   [SQLITE_IOERR_B
18f00 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 69 73 20 72 65  LOCKED].** is re
18f10 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65  turned immediate
18f20 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65  ly upon encounte
18f30 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20 20  ring the lock.  
18f40 5e 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c  ^If the busy cal
18f50 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20  lback.** is not 
18f60 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 63  NULL, then the c
18f70 61 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 62 65  allback might be
18f80 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 77   invoked with tw
18f90 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a  o arguments..**.
18fa0 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
18fb0 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 62 75  gument to the bu
18fc0 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 61 20  sy handler is a 
18fd0 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64  copy of the void
18fe0 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 0a  * pointer which.
18ff0 2a 2a 20 69 73 20 74 68 65 20 74 68 69 72 64 20  ** is the third 
19000 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
19010 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
19020 28 29 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64  ().  ^The second
19030 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
19040 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
19050 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65   callback is the
19060 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73   number of times
19070 20 74 68 61 74 20 74 68 65 20 62 75 73 79 20 68   that the busy h
19080 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65  andler has.** be
19090 65 6e 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 74  en invoked for t
190a0 68 69 73 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e  his locking even
190b0 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 62  t.  ^If the.** b
190c0 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  usy callback ret
190d0 75 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20  urns 0, then no 
190e0 61 64 64 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d  additional attem
190f0 70 74 73 20 61 72 65 20 6d 61 64 65 20 74 6f 0a  pts are made to.
19100 2a 2a 20 61 63 63 65 73 73 20 74 68 65 20 64 61  ** access the da
19110 74 61 62 61 73 65 20 61 6e 64 20 5b 53 51 4c 49  tabase and [SQLI
19120 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c  TE_BUSY] or [SQL
19130 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45  ITE_IOERR_BLOCKE
19140 44 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  D] is returned..
19150 2a 2a 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62  ** ^If the callb
19160 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d  ack returns non-
19170 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68  zero, then anoth
19180 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73  er attempt.** is
19190 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 74 68   made to open th
191a0 65 20 64 61 74 61 62 61 73 65 20 66 6f 72 20 72  e database for r
191b0 65 61 64 69 6e 67 20 61 6e 64 20 74 68 65 20 63  eading and the c
191c0 79 63 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a  ycle repeats..**
191d0 0a 2a 2a 20 54 68 65 20 70 72 65 73 65 6e 63 65  .** The presence
191e0 20 6f 66 20 61 20 62 75 73 79 20 68 61 6e 64 6c   of a busy handl
191f0 65 72 20 64 6f 65 73 20 6e 6f 74 20 67 75 61 72  er does not guar
19200 61 6e 74 65 65 20 74 68 61 74 20 69 74 20 77 69  antee that it wi
19210 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a  ll be invoked.**
19220 20 77 68 65 6e 20 74 68 65 72 65 20 69 73 20 6c   when there is l
19230 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20  ock contention. 
19240 5e 49 66 20 53 51 4c 69 74 65 20 64 65 74 65 72  ^If SQLite deter
19250 6d 69 6e 65 73 20 74 68 61 74 20 69 6e 76 6f 6b  mines that invok
19260 69 6e 67 20 74 68 65 20 62 75 73 79 0a 2a 2a 20  ing the busy.** 
19270 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72 65  handler could re
19280 73 75 6c 74 20 69 6e 20 61 20 64 65 61 64 6c 6f  sult in a deadlo
19290 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f 20 61  ck, it will go a
192a0 68 65 61 64 20 61 6e 64 20 72 65 74 75 72 6e 20  head and return 
192b0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a  [SQLITE_BUSY].**
192c0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52   or [SQLITE_IOER
192d0 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 6e 73 74 65  R_BLOCKED] inste
192e0 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 74  ad of invoking t
192f0 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e  he busy handler.
19300 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61 20 73  .** Consider a s
19310 63 65 6e 61 72 69 6f 20 77 68 65 72 65 20 6f 6e  cenario where on
19320 65 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c  e process is hol
19330 64 69 6e 67 20 61 20 72 65 61 64 20 6c 6f 63 6b  ding a read lock
19340 20 74 68 61 74 0a 2a 2a 20 69 74 20 69 73 20 74   that.** it is t
19350 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65  rying to promote
19360 20 74 6f 20 61 20 72 65 73 65 72 76 65 64 20 6c   to a reserved l
19370 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63  ock and.** a sec
19380 6f 6e 64 20 70 72 6f 63 65 73 73 20 69 73 20 68  ond process is h
19390 6f 6c 64 69 6e 67 20 61 20 72 65 73 65 72 76 65  olding a reserve
193a0 64 20 6c 6f 63 6b 20 74 68 61 74 20 69 74 20 69  d lock that it i
193b0 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70  s trying.** to p
193c0 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78 63  romote to an exc
193d0 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68  lusive lock.  Th
193e0 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20  e first process 
193f0 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a  cannot proceed.*
19400 2a 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20  * because it is 
19410 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 73  blocked by the s
19420 65 63 6f 6e 64 20 61 6e 64 20 74 68 65 20 73 65  econd and the se
19430 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 63 61 6e  cond process can
19440 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62  not.** proceed b
19450 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f  ecause it is blo
19460 63 6b 65 64 20 62 79 20 74 68 65 20 66 69 72 73  cked by the firs
19470 74 2e 20 20 49 66 20 62 6f 74 68 20 70 72 6f 63  t.  If both proc
19480 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20  esses.** invoke 
19490 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
194a0 73 2c 20 6e 65 69 74 68 65 72 20 77 69 6c 6c 20  s, neither will 
194b0 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67 72 65 73  make any progres
194c0 73 2e 20 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a  s.  Therefore,.*
194d0 2a 20 53 51 4c 69 74 65 20 72 65 74 75 72 6e 73  * SQLite returns
194e0 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 66   [SQLITE_BUSY] f
194f0 6f 72 20 74 68 65 20 66 69 72 73 74 20 70 72 6f  or the first pro
19500 63 65 73 73 2c 20 68 6f 70 69 6e 67 20 74 68 61  cess, hoping tha
19510 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69  t this.** will i
19520 6e 64 75 63 65 20 74 68 65 20 66 69 72 73 74 20  nduce the first 
19530 70 72 6f 63 65 73 73 20 74 6f 20 72 65 6c 65 61  process to relea
19540 73 65 20 69 74 73 20 72 65 61 64 20 6c 6f 63 6b  se its read lock
19550 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68   and allow.** th
19560 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73  e second process
19570 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a   to proceed..**.
19580 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20  ** ^The default 
19590 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73  busy callback is
195a0 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   NULL..**.** ^Th
195b0 65 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  e [SQLITE_BUSY] 
195c0 65 72 72 6f 72 20 69 73 20 63 6f 6e 76 65 72 74  error is convert
195d0 65 64 20 74 6f 20 5b 53 51 4c 49 54 45 5f 49 4f  ed to [SQLITE_IO
195e0 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20  ERR_BLOCKED].** 
195f0 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 69  when SQLite is i
19600 6e 20 74 68 65 20 6d 69 64 64 6c 65 20 6f 66 20  n the middle of 
19610 61 20 6c 61 72 67 65 20 74 72 61 6e 73 61 63 74  a large transact
19620 69 6f 6e 20 77 68 65 72 65 20 61 6c 6c 20 74 68  ion where all th
19630 65 0a 2a 2a 20 63 68 61 6e 67 65 73 20 77 69 6c  e.** changes wil
19640 6c 20 6e 6f 74 20 66 69 74 20 69 6e 74 6f 20 74  l not fit into t
19650 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 20 63 61 63  he in-memory cac
19660 68 65 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c  he.  SQLite will
19670 0a 2a 2a 20 61 6c 72 65 61 64 79 20 68 6f 6c 64  .** already hold
19680 20 61 20 52 45 53 45 52 56 45 44 20 6c 6f 63 6b   a RESERVED lock
19690 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65   on the database
196a0 20 66 69 6c 65 2c 20 62 75 74 20 69 74 20 6e 65   file, but it ne
196b0 65 64 73 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74  eds.** to promot
196c0 65 20 74 68 69 73 20 6c 6f 63 6b 20 74 6f 20 45  e this lock to E
196d0 58 43 4c 55 53 49 56 45 20 73 6f 20 74 68 61 74  XCLUSIVE so that
196e0 20 69 74 20 63 61 6e 20 73 70 69 6c 6c 20 63 61   it can spill ca
196f0 63 68 65 0a 2a 2a 20 70 61 67 65 73 20 69 6e 74  che.** pages int
19700 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  o the database f
19710 69 6c 65 20 77 69 74 68 6f 75 74 20 68 61 72 6d  ile without harm
19720 20 74 6f 20 63 6f 6e 63 75 72 72 65 6e 74 0a 2a   to concurrent.*
19730 2a 20 72 65 61 64 65 72 73 2e 20 20 5e 49 66 20  * readers.  ^If 
19740 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  it is unable to 
19750 70 72 6f 6d 6f 74 65 20 74 68 65 20 6c 6f 63 6b  promote the lock
19760 2c 20 74 68 65 6e 20 74 68 65 20 69 6e 2d 6d 65  , then the in-me
19770 6d 6f 72 79 0a 2a 2a 20 63 61 63 68 65 20 77 69  mory.** cache wi
19780 6c 6c 20 62 65 20 6c 65 66 74 20 69 6e 20 61 6e  ll be left in an
19790 20 69 6e 63 6f 6e 73 69 73 74 65 6e 74 20 73 74   inconsistent st
197a0 61 74 65 20 61 6e 64 20 73 6f 20 74 68 65 20 65  ate and so the e
197b0 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20 69 73 20  rror.** code is 
197c0 70 72 6f 6d 6f 74 65 64 20 66 72 6f 6d 20 74 68  promoted from th
197d0 65 20 72 65 6c 61 74 69 76 65 6c 79 20 62 65 6e  e relatively ben
197e0 69 67 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  ign [SQLITE_BUSY
197f0 5d 20 74 6f 0a 2a 2a 20 74 68 65 20 6d 6f 72 65  ] to.** the more
19800 20 73 65 76 65 72 65 20 5b 53 51 4c 49 54 45 5f   severe [SQLITE_
19810 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 20  IOERR_BLOCKED]. 
19820 20 5e 54 68 69 73 20 65 72 72 6f 72 20 63 6f 64   ^This error cod
19830 65 20 70 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20 66  e promotion.** f
19840 6f 72 63 65 73 20 61 6e 20 61 75 74 6f 6d 61 74  orces an automat
19850 69 63 20 72 6f 6c 6c 62 61 63 6b 20 6f 66 20 74  ic rollback of t
19860 68 65 20 63 68 61 6e 67 65 73 2e 20 20 53 65 65  he changes.  See
19870 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d   the.** <a href=
19880 22 2f 63 76 73 74 72 61 63 2f 77 69 6b 69 3f 70  "/cvstrac/wiki?p
19890 3d 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f  =CorruptionFollo
198a0 77 69 6e 67 42 75 73 79 45 72 72 6f 72 22 3e 0a  wingBusyError">.
198b0 2a 2a 20 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c  ** CorruptionFol
198c0 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72 3c  lowingBusyError<
198d0 2f 61 3e 20 77 69 6b 69 20 70 61 67 65 20 66 6f  /a> wiki page fo
198e0 72 20 61 20 64 69 73 63 75 73 73 69 6f 6e 20 6f  r a discussion o
198f0 66 20 77 68 79 0a 2a 2a 20 74 68 69 73 20 69 73  f why.** this is
19900 20 69 6d 70 6f 72 74 61 6e 74 2e 0a 2a 2a 0a 2a   important..**.*
19910 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e  * ^(There can on
19920 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62  ly be a single b
19930 75 73 79 20 68 61 6e 64 6c 65 72 20 64 65 66 69  usy handler defi
19940 6e 65 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20  ned for each.** 
19950 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
19960 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20  tion].  Setting 
19970 61 20 6e 65 77 20 62 75 73 79 20 68 61 6e 64 6c  a new busy handl
19980 65 72 20 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a  er clears any.**
19990 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20   previously set 
199a0 68 61 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74  handler.)^  ^Not
199b0 65 20 74 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b  e that calling [
199c0 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d  sqlite3_busy_tim
199d0 65 6f 75 74 28 29 5d 0a 2a 2a 20 77 69 6c 6c 20  eout()].** will 
199e0 61 6c 73 6f 20 73 65 74 20 6f 72 20 63 6c 65 61  also set or clea
199f0 72 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  r the busy handl
19a00 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75  er..**.** The bu
19a10 73 79 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75  sy callback shou
19a20 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61 6e 79 20  ld not take any 
19a30 61 63 74 69 6f 6e 73 20 77 68 69 63 68 20 6d 6f  actions which mo
19a40 64 69 66 79 20 74 68 65 0a 2a 2a 20 64 61 74 61  dify the.** data
19a50 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
19a60 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
19a70 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 20 20   busy handler.  
19a80 41 6e 79 20 73 75 63 68 20 61 63 74 69 6f 6e 73  Any such actions
19a90 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e 20 75 6e  .** result in un
19aa0 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72  defined behavior
19ab0 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75 73 79 20  ..** .** A busy 
19ac0 68 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74  handler must not
19ad0 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62   close the datab
19ae0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
19af0 2a 20 6f 72 20 5b 70 72 65 70 61 72 65 64 20 73  * or [prepared s
19b00 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69  tatement] that i
19b10 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20  nvoked the busy 
19b20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 53 51 4c 49  handler..*/.SQLI
19b30 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
19b40 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  e3_busy_handler(
19b50 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29  sqlite3*, int(*)
19b60 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76 6f 69  (void*,int), voi
19b70 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
19b80 33 52 45 46 3a 20 53 65 74 20 41 20 42 75 73 79  3REF: Set A Busy
19b90 20 54 69 6d 65 6f 75 74 0a 2a 2a 0a 2a 2a 20 5e   Timeout.**.** ^
19ba0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74  This routine set
19bb0 73 20 61 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  s a [sqlite3_bus
19bc0 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75 73 79  y_handler | busy
19bd0 20 68 61 6e 64 6c 65 72 5d 20 74 68 61 74 20 73   handler] that s
19be0 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20 61 20 73  leeps.** for a s
19bf0 70 65 63 69 66 69 65 64 20 61 6d 6f 75 6e 74 20  pecified amount 
19c00 6f 66 20 74 69 6d 65 20 77 68 65 6e 20 61 20 74  of time when a t
19c10 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20  able is locked. 
19c20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 0a 2a 2a   ^The handler.**
19c30 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74   will sleep mult
19c40 69 70 6c 65 20 74 69 6d 65 73 20 75 6e 74 69 6c  iple times until
19c50 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d   at least "ms" m
19c60 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73  illiseconds of s
19c70 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61 76 65 20  leeping.** have 
19c80 61 63 63 75 6d 75 6c 61 74 65 64 2e 20 20 5e 41  accumulated.  ^A
19c90 66 74 65 72 20 61 74 20 6c 65 61 73 74 20 22 6d  fter at least "m
19ca0 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  s" milliseconds 
19cb0 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20  of sleeping,.** 
19cc0 74 68 65 20 68 61 6e 64 6c 65 72 20 72 65 74 75  the handler retu
19cd0 72 6e 73 20 30 20 77 68 69 63 68 20 63 61 75 73  rns 0 which caus
19ce0 65 73 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  es [sqlite3_step
19cf0 28 29 5d 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a  ()] to return.**
19d00 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f   [SQLITE_BUSY] o
19d10 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  r [SQLITE_IOERR_
19d20 42 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20  BLOCKED]..**.** 
19d30 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f  ^Calling this ro
19d40 75 74 69 6e 65 20 77 69 74 68 20 61 6e 20 61 72  utine with an ar
19d50 67 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 61 6e  gument less than
19d60 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72   or equal to zer
19d70 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20 61  o.** turns off a
19d80 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73  ll busy handlers
19d90 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20  ..**.** ^(There 
19da0 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69  can only be a si
19db0 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65  ngle busy handle
19dc0 72 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c  r for a particul
19dd0 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  ar.** [database 
19de0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 79 20  connection] any 
19df0 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74  any given moment
19e00 2e 20 20 49 66 20 61 6e 6f 74 68 65 72 20 62 75  .  If another bu
19e10 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61  sy handler.** wa
19e20 73 20 64 65 66 69 6e 65 64 20 20 28 75 73 69 6e  s defined  (usin
19e30 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  g [sqlite3_busy_
19e40 68 61 6e 64 6c 65 72 28 29 5d 29 20 70 72 69 6f  handler()]) prio
19e50 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20  r to calling.** 
19e60 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 68  this routine, th
19e70 61 74 20 6f 74 68 65 72 20 62 75 73 79 20 68 61  at other busy ha
19e80 6e 64 6c 65 72 20 69 73 20 63 6c 65 61 72 65 64  ndler is cleared
19e90 2e 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  .)^.*/.SQLITE_AP
19ea0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75  I int sqlite3_bu
19eb0 73 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69 74  sy_timeout(sqlit
19ec0 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f  e3*, int ms);../
19ed0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
19ee0 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75 74 69  onvenience Routi
19ef0 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20  nes For Running 
19f00 51 75 65 72 69 65 73 0a 2a 2a 0a 2a 2a 20 54 68  Queries.**.** Th
19f10 69 73 20 69 73 20 61 20 6c 65 67 61 63 79 20 69  is is a legacy i
19f20 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 69 73  nterface that is
19f30 20 70 72 65 73 65 72 76 65 64 20 66 6f 72 20 62   preserved for b
19f40 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
19f50 62 69 6c 69 74 79 2e 0a 2a 2a 20 55 73 65 20 6f  bility..** Use o
19f60 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  f this interface
19f70 20 69 73 20 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e   is not recommen
19f80 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e  ded..**.** Defin
19f90 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75  ition: A <b>resu
19fa0 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20  lt table</b> is 
19fb0 6d 65 6d 6f 72 79 20 64 61 74 61 20 73 74 72 75  memory data stru
19fc0 63 74 75 72 65 20 63 72 65 61 74 65 64 20 62 79  cture created by
19fd0 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
19fe0 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e  _get_table()] in
19ff0 74 65 72 66 61 63 65 2e 20 20 41 20 72 65 73 75  terface.  A resu
1a000 6c 74 20 74 61 62 6c 65 20 72 65 63 6f 72 64 73  lt table records
1a010 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65   the.** complete
1a020 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 20 66   query results f
1a030 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  rom one or more 
1a040 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  queries..**.** T
1a050 68 65 20 74 61 62 6c 65 20 63 6f 6e 63 65 70 74  he table concept
1a060 75 61 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d 62  ually has a numb
1a070 65 72 20 6f 66 20 72 6f 77 73 20 61 6e 64 20 63  er of rows and c
1a080 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20  olumns.  But.** 
1a090 74 68 65 73 65 20 6e 75 6d 62 65 72 73 20 61 72  these numbers ar
1a0a0 65 20 6e 6f 74 20 70 61 72 74 20 6f 66 20 74 68  e not part of th
1a0b0 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69  e result table i
1a0c0 74 73 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a  tself.  These.**
1a0d0 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6f 62 74   numbers are obt
1a0e0 61 69 6e 65 64 20 73 65 70 61 72 61 74 65 6c 79  ained separately
1a0f0 2e 20 20 4c 65 74 20 4e 20 62 65 20 74 68 65 20  .  Let N be the 
1a100 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a  number of rows.*
1a110 2a 20 61 6e 64 20 4d 20 62 65 20 74 68 65 20 6e  * and M be the n
1a120 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
1a130 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74  ..**.** A result
1a140 20 74 61 62 6c 65 20 69 73 20 61 6e 20 61 72 72   table is an arr
1a150 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74  ay of pointers t
1a160 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  o zero-terminate
1a170 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e  d UTF-8 strings.
1a180 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 28 4e  .** There are (N
1a190 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69  +1)*M elements i
1a1a0 6e 20 74 68 65 20 61 72 72 61 79 2e 20 20 54 68  n the array.  Th
1a1b0 65 20 66 69 72 73 74 20 4d 20 70 6f 69 6e 74 65  e first M pointe
1a1c0 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a  rs point.** to z
1a1d0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73  ero-terminated s
1a1e0 74 72 69 6e 67 73 20 74 68 61 74 20 20 63 6f 6e  trings that  con
1a1f0 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f  tain the names o
1a200 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a  f the columns..*
1a210 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20  * The remaining 
1a220 65 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e  entries all poin
1a230 74 20 74 6f 20 71 75 65 72 79 20 72 65 73 75 6c  t to query resul
1a240 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73  ts.  NULL values
1a250 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55   result.** in NU
1a260 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c  LL pointers.  Al
1a270 6c 20 6f 74 68 65 72 20 76 61 6c 75 65 73 20 61  l other values a
1a280 72 65 20 69 6e 20 74 68 65 69 72 20 55 54 46 2d  re in their UTF-
1a290 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  8 zero-terminate
1a2a0 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65 70 72  d.** string repr
1a2b0 65 73 65 6e 74 61 74 69 6f 6e 20 61 73 20 72 65  esentation as re
1a2c0 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
1a2d0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
1a2e0 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c  ]..**.** A resul
1a2f0 74 20 74 61 62 6c 65 20 6d 69 67 68 74 20 63 6f  t table might co
1a300 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20  nsist of one or 
1a310 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  more memory allo
1a320 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69  cations..** It i
1a330 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 70 61  s not safe to pa
1a340 73 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c  ss a result tabl
1a350 65 20 64 69 72 65 63 74 6c 79 20 74 6f 20 5b 73  e directly to [s
1a360 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a  qlite3_free()]..
1a370 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c  ** A result tabl
1a380 65 20 73 68 6f 75 6c 64 20 62 65 20 64 65 61 6c  e should be deal
1a390 6c 6f 63 61 74 65 64 20 75 73 69 6e 67 20 5b 73  located using [s
1a3a0 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c  qlite3_free_tabl
1a3b0 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73  e()]..**.** ^(As
1a3c0 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 74   an example of t
1a3d0 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  he result table 
1a3e0 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73 65 20  format, suppose 
1a3f0 61 20 71 75 65 72 79 20 72 65 73 75 6c 74 0a 2a  a query result.*
1a400 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  * is as follows:
1a410 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
1a420 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20  te><pre>.**     
1a430 20 20 20 4e 61 6d 65 20 20 20 20 20 20 20 20 7c     Name        |
1a440 20 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d   Age.**        -
1a450 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1a460 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20  ------.**       
1a470 20 41 6c 69 63 65 20 20 20 20 20 20 20 7c 20 34   Alice       | 4
1a480 33 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 62 20  3.**        Bob 
1a490 20 20 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20          | 28.** 
1a4a0 20 20 20 20 20 20 20 43 69 6e 64 79 20 20 20 20         Cindy    
1a4b0 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65     | 21.** </pre
1a4c0 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
1a4d0 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74  *.** There are t
1a4e0 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29  wo column (M==2)
1a4f0 20 61 6e 64 20 74 68 72 65 65 20 72 6f 77 73 20   and three rows 
1a500 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20 74 68  (N==3).  Thus th
1a510 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61 62 6c  e.** result tabl
1a520 65 20 68 61 73 20 38 20 65 6e 74 72 69 65 73 2e  e has 8 entries.
1a530 20 20 53 75 70 70 6f 73 65 20 74 68 65 20 72 65    Suppose the re
1a540 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 73 74  sult table is st
1a550 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72  ored.** in an ar
1a560 72 61 79 20 6e 61 6d 65 73 20 61 7a 52 65 73 75  ray names azResu
1a570 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52 65 73 75  lt.  Then azResu
1a580 6c 74 20 68 6f 6c 64 73 20 74 68 69 73 20 63 6f  lt holds this co
1a590 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  ntent:.**.** <bl
1a5a0 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
1a5b0 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
1a5c0 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65  t&#91;0] = "Name
1a5d0 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
1a5e0 65 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22  esult&#91;1] = "
1a5f0 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  Age";.**        
1a600 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 32 5d 20  azResult&#91;2] 
1a610 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20  = "Alice";.**   
1a620 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
1a630 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20  1;3] = "43";.** 
1a640 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
1a650 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a  #91;4] = "Bob";.
1a660 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
1a670 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22 32 38 22  lt&#91;5] = "28"
1a680 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
1a690 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22 43  sult&#91;6] = "C
1a6a0 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20  indy";.**       
1a6b0 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 37 5d   azResult&#91;7]
1a6c0 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72   = "21";.** </pr
1a6d0 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29  e></blockquote>)
1a6e0 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ^.**.** ^The sql
1a6f0 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
1a700 20 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61   function evalua
1a710 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a  tes one or more.
1a720 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70  ** semicolon-sep
1a730 61 72 61 74 65 64 20 53 51 4c 20 73 74 61 74 65  arated SQL state
1a740 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72  ments in the zer
1a750 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
1a760 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20  -8.** string of 
1a770 69 74 73 20 32 6e 64 20 70 61 72 61 6d 65 74 65  its 2nd paramete
1a780 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20  r and returns a 
1a790 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20  result table to 
1a7a0 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67  the.** pointer g
1a7b0 69 76 65 6e 20 69 6e 20 69 74 73 20 33 72 64 20  iven in its 3rd 
1a7c0 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
1a7d0 20 41 66 74 65 72 20 74 68 65 20 61 70 70 6c 69   After the appli
1a7e0 63 61 74 69 6f 6e 20 68 61 73 20 66 69 6e 69 73  cation has finis
1a7f0 68 65 64 20 77 69 74 68 20 74 68 65 20 72 65 73  hed with the res
1a800 75 6c 74 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ult from sqlite3
1a810 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a  _get_table(),.**
1a820 20 69 74 20 6d 75 73 74 20 70 61 73 73 20 74 68   it must pass th
1a830 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 70  e result table p
1a840 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ointer to sqlite
1a850 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 20 69  3_free_table() i
1a860 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65  n order to.** re
1a870 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79  lease the memory
1a880 20 74 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63   that was malloc
1a890 65 64 2e 20 20 42 65 63 61 75 73 65 20 6f 66 20  ed.  Because of 
1a8a0 74 68 65 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b  the way the.** [
1a8b0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1a8c0 5d 20 68 61 70 70 65 6e 73 20 77 69 74 68 69 6e  ] happens within
1a8d0 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
1a8e0 6c 65 28 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e  le(), the callin
1a8f0 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75  g.** function mu
1a900 73 74 20 6e 6f 74 20 74 72 79 20 74 6f 20 63 61  st not try to ca
1a910 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ll [sqlite3_free
1a920 28 29 5d 20 64 69 72 65 63 74 6c 79 2e 20 20 4f  ()] directly.  O
1a930 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  nly.** [sqlite3_
1a940 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 20 69 73  free_table()] is
1a950 20 61 62 6c 65 20 74 6f 20 72 65 6c 65 61 73 65   able to release
1a960 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70   the memory prop
1a970 65 72 6c 79 20 61 6e 64 20 73 61 66 65 6c 79 2e  erly and safely.
1a980 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
1a990 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 69  e3_get_table() i
1a9a0 6e 74 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c  nterface is impl
1a9b0 65 6d 65 6e 74 65 64 20 61 73 20 61 20 77 72 61  emented as a wra
1a9c0 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b  pper around.** [
1a9d0 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2e  sqlite3_exec()].
1a9e0 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65    The sqlite3_ge
1a9f0 74 5f 74 61 62 6c 65 28 29 20 72 6f 75 74 69 6e  t_table() routin
1aa00 65 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20  e does not have 
1aa10 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79  access.** to any
1aa20 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 20 73   internal data s
1aa30 74 72 75 63 74 75 72 65 73 20 6f 66 20 53 51 4c  tructures of SQL
1aa40 69 74 65 2e 20 20 49 74 20 75 73 65 73 20 6f 6e  ite.  It uses on
1aa50 6c 79 20 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a  ly the public.**
1aa60 20 69 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e   interface defin
1aa70 65 64 20 68 65 72 65 2e 20 20 41 73 20 61 20 63  ed here.  As a c
1aa80 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65 72 72 6f  onsequence, erro
1aa90 72 73 20 74 68 61 74 20 6f 63 63 75 72 20 69 6e  rs that occur in
1aaa0 20 74 68 65 0a 2a 2a 20 77 72 61 70 70 65 72 20   the.** wrapper 
1aab0 6c 61 79 65 72 20 6f 75 74 73 69 64 65 20 6f 66  layer outside of
1aac0 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73   the internal [s
1aad0 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 63  qlite3_exec()] c
1aae0 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72  all are not.** r
1aaf0 65 66 6c 65 63 74 65 64 20 69 6e 20 73 75 62 73  eflected in subs
1ab00 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20  equent calls to 
1ab10 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65  [sqlite3_errcode
1ab20 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
1ab30 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f  e3_errmsg()]..*/
1ab40 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
1ab50 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
1ab60 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  e(.  sqlite3 *db
1ab70 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e  ,          /* An
1ab80 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a   open database *
1ab90 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
1aba0 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c  zSql,     /* SQL
1abb0 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64   to be evaluated
1abc0 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61   */.  char ***pa
1abd0 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52  zResult,    /* R
1abe0 65 73 75 6c 74 73 20 6f 66 20 74 68 65 20 71 75  esults of the qu
1abf0 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e  ery */.  int *pn
1ac00 52 6f 77 2c 20 20 20 20 20 20 20 20 20 20 20 2f  Row,           /
1ac10 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75  * Number of resu
1ac20 6c 74 20 72 6f 77 73 20 77 72 69 74 74 65 6e 20  lt rows written 
1ac30 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70  here */.  int *p
1ac40 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20  nColumn,        
1ac50 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73  /* Number of res
1ac60 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74  ult columns writ
1ac70 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63 68  ten here */.  ch
1ac80 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20  ar **pzErrmsg   
1ac90 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67      /* Error msg
1aca0 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f   written here */
1acb0 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  .);.SQLITE_API v
1acc0 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65  oid sqlite3_free
1acd0 5f 74 61 62 6c 65 28 63 68 61 72 20 2a 2a 72 65  _table(char **re
1ace0 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  sult);../*.** CA
1acf0 50 49 33 52 45 46 3a 20 46 6f 72 6d 61 74 74 65  PI3REF: Formatte
1ad00 64 20 53 74 72 69 6e 67 20 50 72 69 6e 74 69 6e  d String Printin
1ad10 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a  g Functions.**.*
1ad20 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
1ad30 20 61 72 65 20 77 6f 72 6b 2d 61 6c 69 6b 65 73   are work-alikes
1ad40 20 6f 66 20 74 68 65 20 22 70 72 69 6e 74 66 28   of the "printf(
1ad50 29 22 20 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e  )" family of fun
1ad60 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74  ctions.** from t
1ad70 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  he standard C li
1ad80 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  brary..**.** ^Th
1ad90 65 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74  e sqlite3_mprint
1ada0 66 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  f() and sqlite3_
1adb0 76 6d 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69  vmprintf() routi
1adc0 6e 65 73 20 77 72 69 74 65 20 74 68 65 69 72 0a  nes write their.
1add0 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f 20  ** results into 
1ade0 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20  memory obtained 
1adf0 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
1ae00 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  lloc()]..** The 
1ae10 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64  strings returned
1ae20 20 62 79 20 74 68 65 73 65 20 74 77 6f 20 72 6f   by these two ro
1ae30 75 74 69 6e 65 73 20 73 68 6f 75 6c 64 20 62 65  utines should be
1ae40 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20 62 79 20  .** released by 
1ae50 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
1ae60 2e 20 20 5e 42 6f 74 68 20 72 6f 75 74 69 6e 65  .  ^Both routine
1ae70 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55  s return a.** NU
1ae80 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 5b 73  LL pointer if [s
1ae90 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
1aea0 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c   is unable to al
1aeb0 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a  locate enough.**
1aec0 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20   memory to hold 
1aed0 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74  the resulting st
1aee0 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  ring..**.** ^(Th
1aef0 65 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  e sqlite3_snprin
1af00 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20  tf() routine is 
1af10 73 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70 72  similar to "snpr
1af20 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20  intf()" from.** 
1af30 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c  the standard C l
1af40 69 62 72 61 72 79 2e 20 20 54 68 65 20 72 65 73  ibrary.  The res
1af50 75 6c 74 20 69 73 20 77 72 69 74 74 65 6e 20 69  ult is written i
1af60 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66 65  nto the.** buffe
1af70 72 20 73 75 70 70 6c 69 65 64 20 61 73 20 74 68  r supplied as th
1af80 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
1af90 65 72 20 77 68 6f 73 65 20 73 69 7a 65 20 69 73  er whose size is
1afa0 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65   given by.** the
1afb0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
1afc0 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20  . Note that the 
1afd0 6f 72 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20  order of the.** 
1afe0 66 69 72 73 74 20 74 77 6f 20 70 61 72 61 6d 65  first two parame
1aff0 74 65 72 73 20 69 73 20 72 65 76 65 72 73 65 64  ters is reversed
1b000 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29   from snprintf()
1b010 2e 29 5e 20 20 54 68 69 73 20 69 73 20 61 6e 0a  .)^  This is an.
1b020 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c 20 61 63  ** historical ac
1b030 63 69 64 65 6e 74 20 74 68 61 74 20 63 61 6e 6e  cident that cann
1b040 6f 74 20 62 65 20 66 69 78 65 64 20 77 69 74 68  ot be fixed with
1b050 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20  out breaking.** 
1b060 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
1b070 69 62 69 6c 69 74 79 2e 20 20 5e 28 4e 6f 74 65  ibility.  ^(Note
1b080 20 61 6c 73 6f 20 74 68 61 74 20 73 71 6c 69 74   also that sqlit
1b090 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a  e3_snprintf().**
1b0a0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
1b0b0 65 72 20 74 6f 20 69 74 73 20 62 75 66 66 65 72  er to its buffer
1b0c0 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20   instead of the 
1b0d0 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61  number of.** cha
1b0e0 72 61 63 74 65 72 73 20 61 63 74 75 61 6c 6c 79  racters actually
1b0f0 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68   written into th
1b100 65 20 62 75 66 66 65 72 2e 29 5e 20 20 57 65 20  e buffer.)^  We 
1b110 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74 68  admit that.** th
1b120 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72  e number of char
1b130 61 63 74 65 72 73 20 77 72 69 74 74 65 6e 20 77  acters written w
1b140 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72 65 20 75  ould be a more u
1b150 73 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20  seful return.** 
1b160 76 61 6c 75 65 20 62 75 74 20 77 65 20 63 61 6e  value but we can
1b170 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 69  not change the i
1b180 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
1b190 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
1b1a0 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f  f().** now witho
1b1b0 75 74 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70  ut breaking comp
1b1c0 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a  atibility..**.**
1b1d0 20 5e 41 73 20 6c 6f 6e 67 20 61 73 20 74 68 65   ^As long as the
1b1e0 20 62 75 66 66 65 72 20 73 69 7a 65 20 69 73 20   buffer size is 
1b1f0 67 72 65 61 74 65 72 20 74 68 61 6e 20 7a 65 72  greater than zer
1b200 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  o, sqlite3_snpri
1b210 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74  ntf().** guarant
1b220 65 65 73 20 74 68 61 74 20 74 68 65 20 62 75 66  ees that the buf
1b230 66 65 72 20 69 73 20 61 6c 77 61 79 73 20 7a 65  fer is always ze
1b240 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20  ro-terminated.  
1b250 5e 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61  ^The first.** pa
1b260 72 61 6d 65 74 65 72 20 22 6e 22 20 69 73 20 74  rameter "n" is t
1b270 68 65 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66  he total size of
1b280 20 74 68 65 20 62 75 66 66 65 72 2c 20 69 6e 63   the buffer, inc
1b290 6c 75 64 69 6e 67 20 73 70 61 63 65 20 66 6f 72  luding space for
1b2a0 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74 65 72  .** the zero ter
1b2b0 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68 65  minator.  So the
1b2c0 20 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e 67 20   longest string 
1b2d0 74 68 61 74 20 63 61 6e 20 62 65 20 63 6f 6d 70  that can be comp
1b2e0 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65  letely.** writte
1b2f0 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68  n will be n-1 ch
1b300 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  aracters..**.** 
1b310 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 73 6e  ^The sqlite3_vsn
1b320 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65  printf() routine
1b330 20 69 73 20 61 20 76 61 72 61 72 67 73 20 76 65   is a varargs ve
1b340 72 73 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33  rsion of sqlite3
1b350 5f 73 6e 70 72 69 6e 74 66 28 29 2e 0a 2a 2a 0a  _snprintf()..**.
1b360 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
1b370 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 20  s all implement 
1b380 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c 20  some additional 
1b390 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f 70  formatting.** op
1b3a0 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 75  tions that are u
1b3b0 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e 73 74 72  seful for constr
1b3c0 75 63 74 69 6e 67 20 53 51 4c 20 73 74 61 74 65  ucting SQL state
1b3d0 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66  ments..** All of
1b3e0 20 74 68 65 20 75 73 75 61 6c 20 70 72 69 6e 74   the usual print
1b3f0 66 28 29 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f  f() formatting o
1b400 70 74 69 6f 6e 73 20 61 70 70 6c 79 2e 20 20 49  ptions apply.  I
1b410 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74 68 65 72  n addition, ther
1b420 65 0a 2a 2a 20 69 73 20 61 72 65 20 22 25 71 22  e.** is are "%q"
1b430 2c 20 22 25 51 22 2c 20 61 6e 64 20 22 25 7a 22  , "%Q", and "%z"
1b440 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20   options..**.** 
1b450 5e 28 54 68 65 20 25 71 20 6f 70 74 69 6f 6e 20  ^(The %q option 
1b460 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e  works like %s in
1b470 20 74 68 61 74 20 69 74 20 73 75 62 73 74 69 74   that it substit
1b480 75 74 65 73 20 61 20 6e 75 6c 2d 74 65 72 6d 69  utes a nul-termi
1b490 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20  nated.** string 
1b4a0 66 72 6f 6d 20 74 68 65 20 61 72 67 75 6d 65 6e  from the argumen
1b4b0 74 20 6c 69 73 74 2e 20 20 42 75 74 20 25 71 20  t list.  But %q 
1b4c0 61 6c 73 6f 20 64 6f 75 62 6c 65 73 20 65 76 65  also doubles eve
1b4d0 72 79 20 27 5c 27 27 20 63 68 61 72 61 63 74 65  ry '\'' characte
1b4e0 72 2e 0a 2a 2a 20 25 71 20 69 73 20 64 65 73 69  r..** %q is desi
1b4f0 67 6e 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73  gned for use ins
1b500 69 64 65 20 61 20 73 74 72 69 6e 67 20 6c 69 74  ide a string lit
1b510 65 72 61 6c 2e 29 5e 20 20 42 79 20 64 6f 75 62  eral.)^  By doub
1b520 6c 69 6e 67 20 65 61 63 68 20 27 5c 27 27 0a 2a  ling each '\''.*
1b530 2a 20 63 68 61 72 61 63 74 65 72 20 69 74 20 65  * character it e
1b540 73 63 61 70 65 73 20 74 68 61 74 20 63 68 61 72  scapes that char
1b550 61 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73  acter and allows
1b560 20 69 74 20 74 6f 20 62 65 20 69 6e 73 65 72 74   it to be insert
1b570 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73  ed into.** the s
1b580 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72  tring..**.** For
1b590 20 65 78 61 6d 70 6c 65 2c 20 61 73 73 75 6d 65   example, assume
1b5a0 20 74 68 65 20 73 74 72 69 6e 67 20 76 61 72 69   the string vari
1b5b0 61 62 6c 65 20 7a 54 65 78 74 20 63 6f 6e 74 61  able zText conta
1b5c0 69 6e 73 20 74 65 78 74 20 61 73 20 66 6f 6c 6c  ins text as foll
1b5d0 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ows:.**.** <bloc
1b5e0 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
1b5f0 20 63 68 61 72 20 2a 7a 54 65 78 74 20 3d 20 22   char *zText = "
1b600 49 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79  It's a happy day
1b610 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  !";.** </pre></b
1b620 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
1b630 20 4f 6e 65 20 63 61 6e 20 75 73 65 20 74 68 69   One can use thi
1b640 73 20 74 65 78 74 20 69 6e 20 61 6e 20 53 51 4c  s text in an SQL
1b650 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20 66 6f   statement as fo
1b660 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  llows:.**.** <bl
1b670 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
1b680 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20  *  char *zSQL = 
1b690 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
1b6a0 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62  "INSERT INTO tab
1b6b0 6c 65 20 56 41 4c 55 45 53 28 27 25 71 27 29 22  le VALUES('%q')"
1b6c0 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71  , zText);.**  sq
1b6d0 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a  lite3_exec(db, z
1b6e0 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a  SQL, 0, 0, 0);.*
1b6f0 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  *  sqlite3_free(
1b700 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  zSQL);.** </pre>
1b710 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
1b720 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65 20  .** Because the 
1b730 25 71 20 66 6f 72 6d 61 74 20 73 74 72 69 6e 67  %q format string
1b740 20 69 73 20 75 73 65 64 2c 20 74 68 65 20 27 5c   is used, the '\
1b750 27 27 20 63 68 61 72 61 63 74 65 72 20 69 6e 20  '' character in 
1b760 7a 54 65 78 74 0a 2a 2a 20 69 73 20 65 73 63 61  zText.** is esca
1b770 70 65 64 20 61 6e 64 20 74 68 65 20 53 51 4c 20  ped and the SQL 
1b780 67 65 6e 65 72 61 74 65 64 20 69 73 20 61 73 20  generated is as 
1b790 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c  follows:.**.** <
1b7a0 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
1b7b0 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f  .**  INSERT INTO
1b7c0 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27   table1 VALUES('
1b7d0 49 74 27 27 73 20 61 20 68 61 70 70 79 20 64 61  It''s a happy da
1b7e0 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  y!').** </pre></
1b7f0 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
1b800 2a 20 54 68 69 73 20 69 73 20 63 6f 72 72 65 63  * This is correc
1b810 74 2e 20 20 48 61 64 20 77 65 20 75 73 65 64 20  t.  Had we used 
1b820 25 73 20 69 6e 73 74 65 61 64 20 6f 66 20 25 71  %s instead of %q
1b830 2c 20 74 68 65 20 67 65 6e 65 72 61 74 65 64 20  , the generated 
1b840 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76  SQL.** would hav
1b850 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68  e looked like th
1b860 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  is:.**.** <block
1b870 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
1b880 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c  INSERT INTO tabl
1b890 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 73 20  e1 VALUES('It's 
1b8a0 61 20 68 61 70 70 79 20 64 61 79 21 27 29 3b 0a  a happy day!');.
1b8b0 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
1b8c0 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  quote>.**.** Thi
1b8d0 73 20 73 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65  s second example
1b8e0 20 69 73 20 61 6e 20 53 51 4c 20 73 79 6e 74 61   is an SQL synta
1b8f0 78 20 65 72 72 6f 72 2e 20 20 41 73 20 61 20 67  x error.  As a g
1b900 65 6e 65 72 61 6c 20 72 75 6c 65 20 79 6f 75 20  eneral rule you 
1b910 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61 79 73  should.** always
1b920 20 75 73 65 20 25 71 20 69 6e 73 74 65 61 64 20   use %q instead 
1b930 6f 66 20 25 73 20 77 68 65 6e 20 69 6e 73 65 72  of %s when inser
1b940 74 69 6e 67 20 74 65 78 74 20 69 6e 74 6f 20 61  ting text into a
1b950 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e   string literal.
1b960 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 51 20  .**.** ^(The %Q 
1b970 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b  option works lik
1b980 65 20 25 71 20 65 78 63 65 70 74 20 69 74 20 61  e %q except it a
1b990 6c 73 6f 20 61 64 64 73 20 73 69 6e 67 6c 65 20  lso adds single 
1b9a0 71 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a  quotes around.**
1b9b0 20 74 68 65 20 6f 75 74 73 69 64 65 20 6f 66 20   the outside of 
1b9c0 74 68 65 20 74 6f 74 61 6c 20 73 74 72 69 6e 67  the total string
1b9d0 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c  .  Additionally,
1b9e0 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
1b9f0 72 20 69 6e 20 74 68 65 0a 2a 2a 20 61 72 67 75  r in the.** argu
1ba00 6d 65 6e 74 20 6c 69 73 74 20 69 73 20 61 20 4e  ment list is a N
1ba10 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25 51 20  ULL pointer, %Q 
1ba20 73 75 62 73 74 69 74 75 74 65 73 20 74 68 65 20  substitutes the 
1ba30 74 65 78 74 20 22 4e 55 4c 4c 22 20 28 77 69 74  text "NULL" (wit
1ba40 68 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 71  hout.** single q
1ba50 75 6f 74 65 73 29 2e 29 5e 20 20 53 6f 2c 20 66  uotes).)^  So, f
1ba60 6f 72 20 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 20  or example, one 
1ba70 63 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a  could say:.**.**
1ba80 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
1ba90 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51  e>.**  char *zSQ
1baa0 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69  L = sqlite3_mpri
1bab0 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f  ntf("INSERT INTO
1bac0 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 25 51   table VALUES(%Q
1bad0 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20  )", zText);.**  
1bae0 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c  sqlite3_exec(db,
1baf0 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b   zSQL, 0, 0, 0);
1bb00 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65  .**  sqlite3_fre
1bb10 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72  e(zSQL);.** </pr
1bb20 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
1bb30 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 61  **.** The code a
1bb40 62 6f 76 65 20 77 69 6c 6c 20 72 65 6e 64 65 72  bove will render
1bb50 20 61 20 63 6f 72 72 65 63 74 20 53 51 4c 20 73   a correct SQL s
1bb60 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20  tatement in the 
1bb70 7a 53 51 4c 0a 2a 2a 20 76 61 72 69 61 62 6c 65  zSQL.** variable
1bb80 20 65 76 65 6e 20 69 66 20 74 68 65 20 7a 54 65   even if the zTe
1bb90 78 74 20 76 61 72 69 61 62 6c 65 20 69 73 20 61  xt variable is a
1bba0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
1bbb0 2a 0a 2a 2a 20 5e 28 54 68 65 20 22 25 7a 22 20  *.** ^(The "%z" 
1bbc0 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f  formatting optio
1bbd0 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 22 25 73  n works like "%s
1bbe0 22 20 62 75 74 20 77 69 74 68 20 74 68 65 0a 2a  " but with the.*
1bbf0 2a 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74 20  * addition that 
1bc00 61 66 74 65 72 20 74 68 65 20 73 74 72 69 6e 67  after the string
1bc10 20 68 61 73 20 62 65 65 6e 20 72 65 61 64 20 61   has been read a
1bc20 6e 64 20 63 6f 70 69 65 64 20 69 6e 74 6f 0a 2a  nd copied into.*
1bc30 2a 20 74 68 65 20 72 65 73 75 6c 74 2c 20 5b 73  * the result, [s
1bc40 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 69  qlite3_free()] i
1bc50 73 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20  s called on the 
1bc60 69 6e 70 75 74 20 73 74 72 69 6e 67 2e 29 5e 0a  input string.)^.
1bc70 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68  */.SQLITE_API ch
1bc80 61 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69  ar *sqlite3_mpri
1bc90 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ntf(const char*,
1bca0 2e 2e 2e 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ...);.SQLITE_API
1bcb0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76   char *sqlite3_v
1bcc0 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68  mprintf(const ch
1bcd0 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 53  ar*, va_list);.S
1bce0 51 4c 49 54 45 5f 41 50 49 20 63 68 61 72 20 2a  QLITE_API char *
1bcf0 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
1bd00 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74  (int,char*,const
1bd10 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 53 51   char*, ...);.SQ
1bd20 4c 49 54 45 5f 41 50 49 20 63 68 61 72 20 2a 73  LITE_API char *s
1bd30 71 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66  qlite3_vsnprintf
1bd40 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74  (int,char*,const
1bd50 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29   char*, va_list)
1bd60 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1bd70 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61  F: Memory Alloca
1bd80 74 69 6f 6e 20 53 75 62 73 79 73 74 65 6d 0a 2a  tion Subsystem.*
1bd90 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20  *.** The SQLite 
1bda0 63 6f 72 65 20 75 73 65 73 20 74 68 65 73 65 20  core uses these 
1bdb0 74 68 72 65 65 20 72 6f 75 74 69 6e 65 73 20 66  three routines f
1bdc0 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77  or all of its ow
1bdd0 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65  n.** internal me
1bde0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
1bdf0 6e 65 65 64 73 2e 20 22 43 6f 72 65 22 20 69 6e  needs. "Core" in
1be00 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 65   the previous se
1be10 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e  ntence.** does n
1be20 6f 74 20 69 6e 63 6c 75 64 65 20 6f 70 65 72 61  ot include opera
1be30 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63  ting-system spec
1be40 69 66 69 63 20 56 46 53 20 69 6d 70 6c 65 6d 65  ific VFS impleme
1be50 6e 74 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a  ntation.  The.**
1be60 20 57 69 6e 64 6f 77 73 20 56 46 53 20 75 73 65   Windows VFS use
1be70 73 20 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28  s native malloc(
1be80 29 20 61 6e 64 20 66 72 65 65 28 29 20 66 6f 72  ) and free() for
1be90 20 73 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73   some operations
1bea0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
1beb0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f  ite3_malloc() ro
1bec0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20  utine returns a 
1bed0 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f  pointer to a blo
1bee0 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20  ck.** of memory 
1bef0 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73  at least N bytes
1bf00 20 69 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65 72   in length, wher
1bf10 65 20 4e 20 69 73 20 74 68 65 20 70 61 72 61 6d  e N is the param
1bf20 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c  eter..** ^If sql
1bf30 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73  ite3_malloc() is
1bf40 20 75 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61 69   unable to obtai
1bf50 6e 20 73 75 66 66 69 63 69 65 6e 74 20 66 72 65  n sufficient fre
1bf60 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20  e.** memory, it 
1bf70 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70  returns a NULL p
1bf80 6f 69 6e 74 65 72 2e 20 20 5e 49 66 20 74 68 65  ointer.  ^If the
1bf90 20 70 61 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a   parameter N to.
1bfa0 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  ** sqlite3_mallo
1bfb0 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e  c() is zero or n
1bfc0 65 67 61 74 69 76 65 20 74 68 65 6e 20 73 71 6c  egative then sql
1bfd0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65  ite3_malloc() re
1bfe0 74 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20  turns.** a NULL 
1bff0 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  pointer..**.** ^
1c000 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f  Calling sqlite3_
1c010 66 72 65 65 28 29 20 77 69 74 68 20 61 20 70 6f  free() with a po
1c020 69 6e 74 65 72 20 70 72 65 76 69 6f 75 73 6c 79  inter previously
1c030 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20   returned.** by 
1c040 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1c050 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   or sqlite3_real
1c060 6c 6f 63 28 29 20 72 65 6c 65 61 73 65 73 20 74  loc() releases t
1c070 68 61 74 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a  hat memory so.**
1c080 20 74 68 61 74 20 69 74 20 6d 69 67 68 74 20 62   that it might b
1c090 65 20 72 65 75 73 65 64 2e 20 20 5e 54 68 65 20  e reused.  ^The 
1c0a0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 72  sqlite3_free() r
1c0b0 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e  outine is.** a n
1c0c0 6f 2d 6f 70 20 69 66 20 69 73 20 63 61 6c 6c 65  o-op if is calle
1c0d0 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f  d with a NULL po
1c0e0 69 6e 74 65 72 2e 20 20 50 61 73 73 69 6e 67 20  inter.  Passing 
1c0f0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  a NULL pointer.*
1c100 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65  * to sqlite3_fre
1c110 65 28 29 20 69 73 20 68 61 72 6d 6c 65 73 73 2e  e() is harmless.
1c120 20 20 41 66 74 65 72 20 62 65 69 6e 67 20 66 72    After being fr
1c130 65 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73  eed, memory.** s
1c140 68 6f 75 6c 64 20 6e 65 69 74 68 65 72 20 62 65  hould neither be
1c150 20 72 65 61 64 20 6e 6f 72 20 77 72 69 74 74 65   read nor writte
1c160 6e 2e 20 20 45 76 65 6e 20 72 65 61 64 69 6e 67  n.  Even reading
1c170 20 70 72 65 76 69 6f 75 73 6c 79 20 66 72 65 65   previously free
1c180 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68  d.** memory migh
1c190 74 20 72 65 73 75 6c 74 20 69 6e 20 61 20 73 65  t result in a se
1c1a0 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74  gmentation fault
1c1b0 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65   or other severe
1c1c0 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72   error..** Memor
1c1d0 79 20 63 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20  y corruption, a 
1c1e0 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75  segmentation fau
1c1f0 6c 74 2c 20 6f 72 20 6f 74 68 65 72 20 73 65 76  lt, or other sev
1c200 65 72 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67  ere error.** mig
1c210 68 74 20 72 65 73 75 6c 74 20 69 66 20 73 71 6c  ht result if sql
1c220 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 63  ite3_free() is c
1c230 61 6c 6c 65 64 20 77 69 74 68 20 61 20 6e 6f 6e  alled with a non
1c240 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68  -NULL pointer th
1c250 61 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62  at.** was not ob
1c260 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69  tained from sqli
1c270 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20  te3_malloc() or 
1c280 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1c290 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73  )..**.** ^(The s
1c2a0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1c2b0 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d   interface attem
1c2c0 70 74 73 20 74 6f 20 72 65 73 69 7a 65 20 61 0a  pts to resize a.
1c2d0 2a 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20  ** prior memory 
1c2e0 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65  allocation to be
1c2f0 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65   at least N byte
1c300 73 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  s, where N is th
1c310 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61  e.** second para
1c320 6d 65 74 65 72 2e 20 20 54 68 65 20 6d 65 6d 6f  meter.  The memo
1c330 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f  ry allocation to
1c340 20 62 65 20 72 65 73 69 7a 65 64 20 69 73 20 74   be resized is t
1c350 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61  he first.** para
1c360 6d 65 74 65 72 2e 29 5e 20 5e 20 49 66 20 74 68  meter.)^ ^ If th
1c370 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
1c380 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61  r to sqlite3_rea
1c390 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 20 4e  lloc().** is a N
1c3a0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e  ULL pointer then
1c3b0 20 69 74 73 20 62 65 68 61 76 69 6f 72 20 69 73   its behavior is
1c3c0 20 69 64 65 6e 74 69 63 61 6c 20 74 6f 20 63 61   identical to ca
1c3d0 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33  lling.** sqlite3
1c3e0 5f 6d 61 6c 6c 6f 63 28 4e 29 20 77 68 65 72 65  _malloc(N) where
1c3f0 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64   N is the second
1c400 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
1c410 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e  lite3_realloc().
1c420 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 65 63 6f  .** ^If the seco
1c430 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  nd parameter to 
1c440 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1c450 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20  ) is zero or.** 
1c460 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 74 68  negative then th
1c470 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 65 78  e behavior is ex
1c480 61 63 74 6c 79 20 74 68 65 20 73 61 6d 65 20 61  actly the same a
1c490 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c  s calling.** sql
1c4a0 69 74 65 33 5f 66 72 65 65 28 50 29 20 77 68 65  ite3_free(P) whe
1c4b0 72 65 20 50 20 69 73 20 74 68 65 20 66 69 72 73  re P is the firs
1c4c0 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  t parameter to s
1c4d0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1c4e0 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65  ..** ^sqlite3_re
1c4f0 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 20  alloc() returns 
1c500 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d  a pointer to a m
1c510 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
1c520 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20  .** of at least 
1c530 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20  N bytes in size 
1c540 6f 72 20 4e 55 4c 4c 20 69 66 20 73 75 66 66 69  or NULL if suffi
1c550 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20  cient memory is 
1c560 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20  unavailable..** 
1c570 5e 49 66 20 4d 20 69 73 20 74 68 65 20 73 69 7a  ^If M is the siz
1c580 65 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61  e of the prior a
1c590 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20  llocation, then 
1c5a0 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a  min(N,M) bytes.*
1c5b0 2a 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61  * of the prior a
1c5c0 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20 63 6f  llocation are co
1c5d0 70 69 65 64 20 69 6e 74 6f 20 74 68 65 20 62 65  pied into the be
1c5e0 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66 65  ginning of buffe
1c5f0 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79  r returned.** by
1c600 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1c610 28 29 20 61 6e 64 20 74 68 65 20 70 72 69 6f 72  () and the prior
1c620 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66   allocation is f
1c630 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c  reed..** ^If sql
1c640 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72  ite3_realloc() r
1c650 65 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 74 68 65  eturns NULL, the
1c660 6e 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f  n the prior allo
1c670 63 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6e 6f 74  cation.** is not
1c680 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54   freed..**.** ^T
1c690 68 65 20 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e  he memory return
1c6a0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61  ed by sqlite3_ma
1c6b0 6c 6c 6f 63 28 29 20 61 6e 64 20 73 71 6c 69 74  lloc() and sqlit
1c6c0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20  e3_realloc().** 
1c6d0 69 73 20 61 6c 77 61 79 73 20 61 6c 69 67 6e 65  is always aligne
1c6e0 64 20 74 6f 20 61 74 20 6c 65 61 73 74 20 61 6e  d to at least an
1c6f0 20 38 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79   8 byte boundary
1c700 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a 20 34 20 62  , or to a.** 4 b
1c710 79 74 65 20 62 6f 75 6e 64 61 72 79 20 69 66 20  yte boundary if 
1c720 74 68 65 20 5b 53 51 4c 49 54 45 5f 34 5f 42 59  the [SQLITE_4_BY
1c730 54 45 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f  TE_ALIGNED_MALLO
1c740 43 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a  C] compile-time.
1c750 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  ** option is use
1c760 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69  d..**.** In SQLi
1c770 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30  te version 3.5.0
1c780 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20 77   and 3.5.1, it w
1c790 61 73 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 64  as possible to d
1c7a0 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51 4c  efine.** the SQL
1c7b0 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f  ITE_OMIT_MEMORY_
1c7c0 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63 68  ALLOCATION which
1c7d0 20 77 6f 75 6c 64 20 63 61 75 73 65 20 74 68 65   would cause the
1c7e0 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70   built-in.** imp
1c7f0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74  lementation of t
1c800 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 6f  hese routines to
1c810 20 62 65 20 6f 6d 69 74 74 65 64 2e 20 20 54 68   be omitted.  Th
1c820 61 74 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a  at capability.**
1c830 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70 72   is no longer pr
1c840 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62 75  ovided.  Only bu
1c850 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c  ilt-in memory al
1c860 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20 62 65 20  locators can be 
1c870 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f  used..**.** Prio
1c880 72 20 74 6f 20 53 51 4c 69 74 65 20 76 65 72 73  r to SQLite vers
1c890 69 6f 6e 20 33 2e 37 2e 31 30 2c 20 74 68 65 20  ion 3.7.10, the 
1c8a0 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65 72  Windows OS inter
1c8b0 66 61 63 65 20 6c 61 79 65 72 20 63 61 6c 6c 65  face layer calle
1c8c0 64 0a 2a 2a 20 74 68 65 20 73 79 73 74 65 6d 20  d.** the system 
1c8d0 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65  malloc() and fre
1c8e0 65 28 29 20 64 69 72 65 63 74 6c 79 20 77 68 65  e() directly whe
1c8f0 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20  n converting.** 
1c900 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 77 65 65  filenames betwee
1c910 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f  n the UTF-8 enco
1c920 64 69 6e 67 20 75 73 65 64 20 62 79 20 53 51 4c  ding used by SQL
1c930 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65  ite.** and whate
1c940 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63  ver filename enc
1c950 6f 64 69 6e 67 20 69 73 20 75 73 65 64 20 62 79  oding is used by
1c960 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20   the particular 
1c970 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61  Windows.** insta
1c980 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79  llation.  Memory
1c990 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f   allocation erro
1c9a0 72 73 20 77 65 72 65 20 64 65 74 65 63 74 65 64  rs were detected
1c9b0 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79 20 77 65  , but.** they we
1c9c0 72 65 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b  re reported back
1c9d0 20 61 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54   as [SQLITE_CANT
1c9e0 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c  OPEN] or.** [SQL
1c9f0 49 54 45 5f 49 4f 45 52 52 5d 20 72 61 74 68 65  ITE_IOERR] rathe
1ca00 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e  r than [SQLITE_N
1ca10 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  OMEM]..**.** The
1ca20 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e   pointer argumen
1ca30 74 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  ts to [sqlite3_f
1ca40 72 65 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ree()] and [sqli
1ca50 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a  te3_realloc()].*
1ca60 2a 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72  * must be either
1ca70 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70 6f   NULL or else po
1ca80 69 6e 74 65 72 73 20 6f 62 74 61 69 6e 65 64 20  inters obtained 
1ca90 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20  from a prior.** 
1caa0 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73  invocation of [s
1cab0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
1cac0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61   or [sqlite3_rea
1cad0 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 68 61 76  lloc()] that hav
1cae0 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62 65 65  e.** not yet bee
1caf0 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a  n released..**.*
1cb00 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
1cb10 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65 61 64 20  n must not read 
1cb20 6f 72 20 77 72 69 74 65 20 61 6e 79 20 70 61 72  or write any par
1cb30 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20  t of.** a block 
1cb40 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 65 72 20  of memory after 
1cb50 69 74 20 68 61 73 20 62 65 65 6e 20 72 65 6c 65  it has been rele
1cb60 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  ased using.** [s
1cb70 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f  qlite3_free()] o
1cb80 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  r [sqlite3_reall
1cb90 6f 63 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45  oc()]..*/.SQLITE
1cba0 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74  _API void *sqlit
1cbb0 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a  e3_malloc(int);.
1cbc0 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
1cbd0 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  *sqlite3_realloc
1cbe0 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 53 51  (void*, int);.SQ
1cbf0 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71  LITE_API void sq
1cc00 6c 69 74 65 33 5f 66 72 65 65 28 76 6f 69 64 2a  lite3_free(void*
1cc10 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1cc20 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63  EF: Memory Alloc
1cc30 61 74 6f 72 20 53 74 61 74 69 73 74 69 63 73 0a  ator Statistics.
1cc40 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f  **.** SQLite pro
1cc50 76 69 64 65 73 20 74 68 65 73 65 20 74 77 6f 20  vides these two 
1cc60 69 6e 74 65 72 66 61 63 65 73 20 66 6f 72 20 72  interfaces for r
1cc70 65 70 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65 20  eporting on the 
1cc80 73 74 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65  status.** of the
1cc90 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
1cca0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72  ()], [sqlite3_fr
1ccb0 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69  ee()], and [sqli
1ccc0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a  te3_realloc()].*
1ccd0 2a 20 72 6f 75 74 69 6e 65 73 2c 20 77 68 69 63  * routines, whic
1cce0 68 20 66 6f 72 6d 20 74 68 65 20 62 75 69 6c 74  h form the built
1ccf0 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  -in memory alloc
1cd00 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e  ation subsystem.
1cd10 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c  .**.** ^The [sql
1cd20 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
1cd30 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75  ()] routine retu
1cd40 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
1cd50 66 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 6d 65  f bytes.** of me
1cd60 6d 6f 72 79 20 63 75 72 72 65 6e 74 6c 79 20 6f  mory currently o
1cd70 75 74 73 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c  utstanding (mall
1cd80 6f 63 65 64 20 62 75 74 20 6e 6f 74 20 66 72 65  oced but not fre
1cd90 65 64 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71  ed)..** ^The [sq
1cda0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
1cdb0 68 77 61 74 65 72 28 29 5d 20 72 6f 75 74 69 6e  hwater()] routin
1cdc0 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6d 61  e returns the ma
1cdd0 78 69 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f  ximum.** value o
1cde0 66 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  f [sqlite3_memor
1cdf0 79 5f 75 73 65 64 28 29 5d 20 73 69 6e 63 65 20  y_used()] since 
1ce00 74 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d  the high-water m
1ce10 61 72 6b 0a 2a 2a 20 77 61 73 20 6c 61 73 74 20  ark.** was last 
1ce20 72 65 73 65 74 2e 20 20 5e 54 68 65 20 76 61 6c  reset.  ^The val
1ce30 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ues returned by 
1ce40 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
1ce50 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b  used()] and.** [
1ce60 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
1ce70 69 67 68 77 61 74 65 72 28 29 5d 20 69 6e 63 6c  ighwater()] incl
1ce80 75 64 65 20 61 6e 79 20 6f 76 65 72 68 65 61 64  ude any overhead
1ce90 0a 2a 2a 20 61 64 64 65 64 20 62 79 20 53 51 4c  .** added by SQL
1cea0 69 74 65 20 69 6e 20 69 74 73 20 69 6d 70 6c 65  ite in its imple
1ceb0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 73 71  mentation of [sq
1cec0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c  lite3_malloc()],
1ced0 0a 2a 2a 20 62 75 74 20 6e 6f 74 20 6f 76 65 72  .** but not over
1cee0 68 65 61 64 20 61 64 64 65 64 20 62 79 20 74 68  head added by th
1cef0 65 20 61 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67  e any underlying
1cf00 20 73 79 73 74 65 6d 20 6c 69 62 72 61 72 79 0a   system library.
1cf10 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74  ** routines that
1cf20 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
1cf30 28 29 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a  ()] may call..**
1cf40 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20  .** ^The memory 
1cf50 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 20  high-water mark 
1cf60 69 73 20 72 65 73 65 74 20 74 6f 20 74 68 65 20  is reset to the 
1cf70 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66  current value of
1cf80 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  .** [sqlite3_mem
1cf90 6f 72 79 5f 75 73 65 64 28 29 5d 20 69 66 20 61  ory_used()] if a
1cfa0 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 70  nd only if the p
1cfb0 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b  arameter to.** [
1cfc0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
1cfd0 69 67 68 77 61 74 65 72 28 29 5d 20 69 73 20 74  ighwater()] is t
1cfe0 72 75 65 2e 20 20 5e 54 68 65 20 76 61 6c 75 65  rue.  ^The value
1cff0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20   returned.** by 
1d000 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
1d010 68 69 67 68 77 61 74 65 72 28 31 29 5d 20 69 73  highwater(1)] is
1d020 20 74 68 65 20 68 69 67 68 2d 77 61 74 65 72 20   the high-water 
1d030 6d 61 72 6b 0a 2a 2a 20 70 72 69 6f 72 20 74 6f  mark.** prior to
1d040 20 74 68 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 53   the reset..*/.S
1d050 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65  QLITE_API sqlite
1d060 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
1d070 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69 64  memory_used(void
1d080 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71  );.SQLITE_API sq
1d090 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
1d0a0 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
1d0b0 61 74 65 72 28 69 6e 74 20 72 65 73 65 74 46 6c  ater(int resetFl
1d0c0 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ag);../*.** CAPI
1d0d0 33 52 45 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e  3REF: Pseudo-Ran
1d0e0 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65 72  dom Number Gener
1d0f0 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  ator.**.** SQLit
1d100 65 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 69 67  e contains a hig
1d110 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64 6f  h-quality pseudo
1d120 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67  -random number g
1d130 65 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 29 20  enerator (PRNG) 
1d140 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63  used to.** selec
1d150 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44 20  t random [ROWID 
1d160 7c 20 52 4f 57 49 44 73 5d 20 77 68 65 6e 20 69  | ROWIDs] when i
1d170 6e 73 65 72 74 69 6e 67 20 6e 65 77 20 72 65 63  nserting new rec
1d180 6f 72 64 73 20 69 6e 74 6f 20 61 20 74 61 62 6c  ords into a tabl
1d190 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64  e that.** alread
1d1a0 79 20 75 73 65 73 20 74 68 65 20 6c 61 72 67 65  y uses the large
1d1b0 73 74 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f 57  st possible [ROW
1d1c0 49 44 5d 2e 20 20 54 68 65 20 50 52 4e 47 20 69  ID].  The PRNG i
1d1d0 73 20 61 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a  s also used for.
1d1e0 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d 69 6e 20  ** the build-in 
1d1f0 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e  random() and ran
1d200 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66 75  domblob() SQL fu
1d210 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69 73 20 69  nctions.  This i
1d220 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a  nterface allows.
1d230 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** applications 
1d240 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 73 61  to access the sa
1d250 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f 74 68 65  me PRNG for othe
1d260 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a  r purposes..**.*
1d270 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 74 68 69  * ^A call to thi
1d280 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73  s routine stores
1d290 20 4e 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64   N bytes of rand
1d2a0 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 66 66  omness into buff
1d2b0 65 72 20 50 2e 0a 2a 2a 20 5e 49 66 20 4e 20 69  er P..** ^If N i
1d2c0 73 20 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65 2c  s less than one,
1d2d0 20 74 68 65 6e 20 50 20 63 61 6e 20 62 65 20 61   then P can be a
1d2e0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
1d2f0 2a 0a 2a 2a 20 5e 49 66 20 74 68 69 73 20 72 6f  *.** ^If this ro
1d300 75 74 69 6e 65 20 68 61 73 20 6e 6f 74 20 62 65  utine has not be
1d310 65 6e 20 70 72 65 76 69 6f 75 73 6c 79 20 63 61  en previously ca
1d320 6c 6c 65 64 20 6f 72 20 69 66 20 74 68 65 20 70  lled or if the p
1d330 72 65 76 69 6f 75 73 0a 2a 2a 20 63 61 6c 6c 20  revious.** call 
1d340 68 61 64 20 4e 20 6c 65 73 73 20 74 68 61 6e 20  had N less than 
1d350 6f 6e 65 2c 20 74 68 65 6e 20 74 68 65 20 50 52  one, then the PR
1d360 4e 47 20 69 73 20 73 65 65 64 65 64 20 75 73 69  NG is seeded usi
1d370 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a  ng randomness.**
1d380 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 74   obtained from t
1d390 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d  he xRandomness m
1d3a0 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66  ethod of the def
1d3b0 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
1d3c0 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 49  s] object..** ^I
1d3d0 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 63  f the previous c
1d3e0 61 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74  all to this rout
1d3f0 69 6e 65 20 68 61 64 20 61 6e 20 4e 20 6f 66 20  ine had an N of 
1d400 31 20 6f 72 20 6d 6f 72 65 20 74 68 65 6e 0a 2a  1 or more then.*
1d410 2a 20 74 68 65 20 70 73 65 75 64 6f 2d 72 61 6e  * the pseudo-ran
1d420 64 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e 65 72  domness is gener
1d430 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c  ated.** internal
1d440 6c 79 20 61 6e 64 20 77 69 74 68 6f 75 74 20 72  ly and without r
1d450 65 63 6f 75 72 73 65 20 74 6f 20 74 68 65 20 5b  ecourse to the [
1d460 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 52 61  sqlite3_vfs] xRa
1d470 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68  ndomness.** meth
1d480 6f 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  od..*/.SQLITE_AP
1d490 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  I void sqlite3_r
1d4a0 61 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 20 4e 2c  andomness(int N,
1d4b0 20 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a   void *P);../*.*
1d4c0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70  * CAPI3REF: Comp
1d4d0 69 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f 72 69  ile-Time Authori
1d4e0 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73  zation Callbacks
1d4f0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
1d500 74 69 6e 65 20 72 65 67 69 73 74 65 72 73 20 61  tine registers a
1d510 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  n authorizer cal
1d520 6c 62 61 63 6b 20 77 69 74 68 20 61 20 70 61 72  lback with a par
1d530 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61  ticular.** [data
1d540 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1d550 2c 20 73 75 70 70 6c 69 65 64 20 69 6e 20 74 68  , supplied in th
1d560 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
1d570 2e 0a 2a 2a 20 5e 54 68 65 20 61 75 74 68 6f 72  ..** ^The author
1d580 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
1d590 20 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20   invoked as SQL 
1d5a0 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 62  statements are b
1d5b0 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a  eing compiled.**
1d5c0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   by [sqlite3_pre
1d5d0 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76  pare()] or its v
1d5e0 61 72 69 61 6e 74 73 20 5b 73 71 6c 69 74 65 33  ariants [sqlite3
1d5f0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a  _prepare_v2()],.
1d600 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
1d610 61 72 65 31 36 28 29 5d 20 61 6e 64 20 5b 73 71  are16()] and [sq
1d620 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
1d630 76 32 28 29 5d 2e 20 20 5e 41 74 20 76 61 72 69  v2()].  ^At vari
1d640 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75  ous.** points du
1d650 72 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 61  ring the compila
1d660 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61 73  tion process, as
1d670 20 6c 6f 67 69 63 20 69 73 20 62 65 69 6e 67 20   logic is being 
1d680 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65  created.** to pe
1d690 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 61 63  rform various ac
1d6a0 74 69 6f 6e 73 2c 20 74 68 65 20 61 75 74 68 6f  tions, the autho
1d6b0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
1d6c0 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20  s invoked to.** 
1d6d0 73 65 65 20 69 66 20 74 68 6f 73 65 20 61 63 74  see if those act
1d6e0 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65 64  ions are allowed
1d6f0 2e 20 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a  .  ^The authoriz
1d700 65 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75  er callback shou
1d710 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51  ld.** return [SQ
1d720 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f  LITE_OK] to allo
1d730 77 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53  w the action, [S
1d740 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f  QLITE_IGNORE] to
1d750 20 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a   disallow the.**
1d760 20 73 70 65 63 69 66 69 63 20 61 63 74 69 6f 6e   specific action
1d770 20 62 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 53   but allow the S
1d780 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20  QL statement to 
1d790 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a  continue to be.*
1d7a0 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b  * compiled, or [
1d7b0 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20  SQLITE_DENY] to 
1d7c0 63 61 75 73 65 20 74 68 65 20 65 6e 74 69 72 65  cause the entire
1d7d0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
1d7e0 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64  o be.** rejected
1d7f0 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20   with an error. 
1d800 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72 69   ^If the authori
1d810 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  zer callback ret
1d820 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75  urns.** any valu
1d830 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  e other than [SQ
1d840 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53  LITE_IGNORE], [S
1d850 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53  QLITE_OK], or [S
1d860 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74  QLITE_DENY].** t
1d870 68 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33  hen the [sqlite3
1d880 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
1d890 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c  r equivalent cal
1d8a0 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64  l that triggered
1d8b0 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a  .** the authoriz
1d8c0 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74  er will fail wit
1d8d0 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61  h an error messa
1d8e0 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74  ge..**.** When t
1d8f0 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
1d900 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c  rns [SQLITE_OK],
1d910 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20   that means the 
1d920 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71  operation.** req
1d930 75 65 73 74 65 64 20 69 73 20 6f 6b 2e 20 20 5e  uested is ok.  ^
1d940 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63  When the callbac
1d950 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  k returns [SQLIT
1d960 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20  E_DENY], the.** 
1d970 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1d980 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61  _v2()] or equiva
1d990 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74  lent call that t
1d9a0 72 69 67 67 65 72 65 64 20 74 68 65 0a 2a 2a 20  riggered the.** 
1d9b0 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20  authorizer will 
1d9c0 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72  fail with an err
1d9d0 6f 72 20 6d 65 73 73 61 67 65 20 65 78 70 6c 61  or message expla
1d9e0 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63  ining that.** ac
1d9f0 63 65 73 73 20 69 73 20 64 65 6e 69 65 64 2e 20  cess is denied. 
1da00 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
1da10 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  t parameter to t
1da20 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1da30 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79  llback is a copy
1da40 20 6f 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a   of the third.**
1da50 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
1da60 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  e sqlite3_set_au
1da70 74 68 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72  thorizer() inter
1da80 66 61 63 65 2e 20 5e 54 68 65 20 73 65 63 6f 6e  face. ^The secon
1da90 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74  d parameter.** t
1daa0 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  o the callback i
1dab0 73 20 61 6e 20 69 6e 74 65 67 65 72 20 5b 53 51  s an integer [SQ
1dac0 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69  LITE_COPY | acti
1dad0 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70  on code] that sp
1dae0 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 70  ecifies.** the p
1daf0 61 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e  articular action
1db00 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65   to be authorize
1db10 64 2e 20 5e 54 68 65 20 74 68 69 72 64 20 74 68  d. ^The third th
1db20 72 6f 75 67 68 20 73 69 78 74 68 20 70 61 72 61  rough sixth para
1db30 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65  meters.** to the
1db40 20 63 61 6c 6c 62 61 63 6b 20 61 72 65 20 7a 65   callback are ze
1db50 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74  ro-terminated st
1db60 72 69 6e 67 73 20 74 68 61 74 20 63 6f 6e 74 61  rings that conta
1db70 69 6e 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  in additional.**
1db80 20 64 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74   details about t
1db90 68 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20  he action to be 
1dba0 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a  authorized..**.*
1dbb0 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e  * ^If the action
1dbc0 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45   code is [SQLITE
1dbd0 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68  _READ].** and th
1dbe0 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
1dbf0 6e 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  ns [SQLITE_IGNOR
1dc00 45 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b  E] then the.** [
1dc10 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1dc20 6e 74 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73  nt] statement is
1dc30 20 63 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 20   constructed to 
1dc40 73 75 62 73 74 69 74 75 74 65 0a 2a 2a 20 61 20  substitute.** a 
1dc50 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c  NULL value in pl
1dc60 61 63 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65  ace of the table
1dc70 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75   column that wou
1dc80 6c 64 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20  ld have.** been 
1dc90 72 65 61 64 20 69 66 20 5b 53 51 4c 49 54 45 5f  read if [SQLITE_
1dca0 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 65 74  OK] had been ret
1dcb0 75 72 6e 65 64 2e 20 20 54 68 65 20 5b 53 51 4c  urned.  The [SQL
1dcc0 49 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72  ITE_IGNORE].** r
1dcd0 65 74 75 72 6e 20 63 61 6e 20 62 65 20 75 73 65  eturn can be use
1dce0 64 20 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74  d to deny an unt
1dcf0 72 75 73 74 65 64 20 75 73 65 72 20 61 63 63 65  rusted user acce
1dd00 73 73 20 74 6f 20 69 6e 64 69 76 69 64 75 61 6c  ss to individual
1dd10 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61  .** columns of a
1dd20 20 74 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 74   table..** ^If t
1dd30 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69  he action code i
1dd40 73 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45  s [SQLITE_DELETE
1dd50 5d 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61  ] and the callba
1dd60 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53  ck returns.** [S
1dd70 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68  QLITE_IGNORE] th
1dd80 65 6e 20 74 68 65 20 5b 44 45 4c 45 54 45 5d 20  en the [DELETE] 
1dd90 6f 70 65 72 61 74 69 6f 6e 20 70 72 6f 63 65 65  operation procee
1dda0 64 73 20 62 75 74 20 74 68 65 0a 2a 2a 20 5b 74  ds but the.** [t
1ddb0 72 75 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a 61  runcate optimiza
1ddc0 74 69 6f 6e 5d 20 69 73 20 64 69 73 61 62 6c 65  tion] is disable
1ddd0 64 20 61 6e 64 20 61 6c 6c 20 72 6f 77 73 20 61  d and all rows a
1dde0 72 65 20 64 65 6c 65 74 65 64 20 69 6e 64 69 76  re deleted indiv
1ddf0 69 64 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41  idually..**.** A
1de00 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20  n authorizer is 
1de10 75 73 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74  used when [sqlit
1de20 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65  e3_prepare | pre
1de30 70 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73  paring].** SQL s
1de40 74 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61  tatements from a
1de50 6e 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72  n untrusted sour
1de60 63 65 2c 20 74 6f 20 65 6e 73 75 72 65 20 74 68  ce, to ensure th
1de70 61 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  at the SQL state
1de80 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20  ments.** do not 
1de90 74 72 79 20 74 6f 20 61 63 63 65 73 73 20 64 61  try to access da
1dea0 74 61 20 74 68 65 79 20 61 72 65 20 6e 6f 74 20  ta they are not 
1deb0 61 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c 20  allowed to see, 
1dec0 6f 72 20 74 68 61 74 20 74 68 65 79 20 64 6f 20  or that they do 
1ded0 6e 6f 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65 78  not.** try to ex
1dee0 65 63 75 74 65 20 6d 61 6c 69 63 69 6f 75 73 20  ecute malicious 
1def0 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20  statements that 
1df00 64 61 6d 61 67 65 20 74 68 65 20 64 61 74 61 62  damage the datab
1df10 61 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61  ase.  For.** exa
1df20 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61  mple, an applica
1df30 74 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61  tion may allow a
1df40 20 75 73 65 72 20 74 6f 20 65 6e 74 65 72 20 61   user to enter a
1df50 72 62 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20  rbitrary.** SQL 
1df60 71 75 65 72 69 65 73 20 66 6f 72 20 65 76 61 6c  queries for eval
1df70 75 61 74 69 6f 6e 20 62 79 20 61 20 64 61 74 61  uation by a data
1df80 62 61 73 65 2e 20 20 42 75 74 20 74 68 65 20 61  base.  But the a
1df90 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a  pplication does.
1dfa0 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20  ** not want the 
1dfb0 75 73 65 72 20 74 6f 20 62 65 20 61 62 6c 65 20  user to be able 
1dfc0 74 6f 20 6d 61 6b 65 20 61 72 62 69 74 72 61 72  to make arbitrar
1dfd0 79 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65  y changes to the
1dfe0 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 41  .** database.  A
1dff0 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 75  n authorizer cou
1e000 6c 64 20 74 68 65 6e 20 62 65 20 70 75 74 20 69  ld then be put i
1e010 6e 20 70 6c 61 63 65 20 77 68 69 6c 65 20 74 68  n place while th
1e020 65 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72 65  e.** user-entere
1e030 64 20 53 51 4c 20 69 73 20 62 65 69 6e 67 20 5b  d SQL is being [
1e040 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20  sqlite3_prepare 
1e050 7c 20 70 72 65 70 61 72 65 64 5d 20 74 68 61 74  | prepared] that
1e060 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65 76  .** disallows ev
1e070 65 72 79 74 68 69 6e 67 20 65 78 63 65 70 74 20  erything except 
1e080 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
1e090 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69  nts..**.** Appli
1e0a0 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6e 65 65  cations that nee
1e0b0 64 20 74 6f 20 70 72 6f 63 65 73 73 20 53 51 4c  d to process SQL
1e0c0 20 66 72 6f 6d 20 75 6e 74 72 75 73 74 65 64 20   from untrusted 
1e0d0 73 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74  sources.** might
1e0e0 20 61 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c   also consider l
1e0f0 6f 77 65 72 69 6e 67 20 72 65 73 6f 75 72 63 65  owering resource
1e100 20 6c 69 6d 69 74 73 20 75 73 69 6e 67 20 5b 73   limits using [s
1e110 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a  qlite3_limit()].
1e120 2a 2a 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20  ** and limiting 
1e130 64 61 74 61 62 61 73 65 20 73 69 7a 65 20 75 73  database size us
1e140 69 6e 67 20 74 68 65 20 5b 6d 61 78 5f 70 61 67  ing the [max_pag
1e150 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41  e_count] [PRAGMA
1e160 5d 0a 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e  ].** in addition
1e170 20 74 6f 20 75 73 69 6e 67 20 61 6e 20 61 75 74   to using an aut
1e180 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  horizer..**.** ^
1e190 28 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 61  (Only a single a
1e1a0 75 74 68 6f 72 69 7a 65 72 20 63 61 6e 20 62 65  uthorizer can be
1e1b0 20 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20 64   in place on a d
1e1c0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1e1d0 6f 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e  on.** at a time.
1e1e0 20 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 73    Each call to s
1e1f0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
1e200 72 69 7a 65 72 20 6f 76 65 72 72 69 64 65 73 20  rizer overrides 
1e210 74 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20  the.** previous 
1e220 63 61 6c 6c 2e 29 5e 20 20 5e 44 69 73 61 62 6c  call.)^  ^Disabl
1e230 65 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  e the authorizer
1e240 20 62 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61   by installing a
1e250 20 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a   NULL callback..
1e260 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65  ** The authorize
1e270 72 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79  r is disabled by
1e280 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20   default..**.** 
1e290 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  The authorizer c
1e2a0 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74  allback must not
1e2b0 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61   do anything tha
1e2c0 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a  t will modify.**
1e2d0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
1e2e0 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e  nnection that in
1e2f0 76 6f 6b 65 64 20 74 68 65 20 61 75 74 68 6f 72  voked the author
1e300 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a  izer callback..*
1e310 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c  * Note that [sql
1e320 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1e330 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
1e340 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64  step()] both mod
1e350 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74  ify their.** dat
1e360 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1e370 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e  s for the meanin
1e380 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e  g of "modify" in
1e390 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e   this paragraph.
1e3a0 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 5b 73 71  .**.** ^When [sq
1e3b0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1e3c0 28 29 5d 20 69 73 20 75 73 65 64 20 74 6f 20 70  ()] is used to p
1e3d0 72 65 70 61 72 65 20 61 20 73 74 61 74 65 6d 65  repare a stateme
1e3e0 6e 74 2c 20 74 68 65 0a 2a 2a 20 73 74 61 74 65  nt, the.** state
1e3f0 6d 65 6e 74 20 6d 69 67 68 74 20 62 65 20 72 65  ment might be re
1e400 2d 70 72 65 70 61 72 65 64 20 64 75 72 69 6e 67  -prepared during
1e410 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1e420 5d 20 64 75 65 20 74 6f 20 61 20 0a 2a 2a 20 73  ] due to a .** s
1e430 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 20 20 48  chema change.  H
1e440 65 6e 63 65 2c 20 74 68 65 20 61 70 70 6c 69 63  ence, the applic
1e450 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 65 6e 73  ation should ens
1e460 75 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  ure that the.** 
1e470 63 6f 72 72 65 63 74 20 61 75 74 68 6f 72 69 7a  correct authoriz
1e480 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 6d 61  er callback rema
1e490 69 6e 73 20 69 6e 20 70 6c 61 63 65 20 64 75 72  ins in place dur
1e4a0 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ing the [sqlite3
1e4b0 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _step()]..**.** 
1e4c0 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 61  ^Note that the a
1e4d0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1e4e0 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e  ck is invoked on
1e4f0 6c 79 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71  ly during.** [sq
1e500 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
1e510 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73   or its variants
1e520 2e 20 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e  .  Authorization
1e530 20 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f   is not.** perfo
1e540 72 6d 65 64 20 64 75 72 69 6e 67 20 73 74 61 74  rmed during stat
1e550 65 6d 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e  ement evaluation
1e560 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   in [sqlite3_ste
1e570 70 28 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20  p()], unless.** 
1e580 61 73 20 73 74 61 74 65 64 20 69 6e 20 74 68 65  as stated in the
1e590 20 70 72 65 76 69 6f 75 73 20 70 61 72 61 67 72   previous paragr
1e5a0 61 70 68 2c 20 73 71 6c 69 74 65 33 5f 73 74 65  aph, sqlite3_ste
1e5b0 70 28 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73  p() invokes.** s
1e5c0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1e5d0 32 28 29 20 74 6f 20 72 65 70 72 65 70 61 72 65  2() to reprepare
1e5e0 20 61 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74   a statement aft
1e5f0 65 72 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e  er a schema chan
1e600 67 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ge..*/.SQLITE_AP
1e610 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 65  I int sqlite3_se
1e620 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a 20 20  t_authorizer(.  
1e630 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20  sqlite3*,.  int 
1e640 28 2a 78 41 75 74 68 29 28 76 6f 69 64 2a 2c 69  (*xAuth)(void*,i
1e650 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63  nt,const char*,c
1e660 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74  onst char*,const
1e670 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61   char*,const cha
1e680 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73  r*),.  void *pUs
1e690 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  erData.);../*.**
1e6a0 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f   CAPI3REF: Autho
1e6b0 72 69 7a 65 72 20 52 65 74 75 72 6e 20 43 6f 64  rizer Return Cod
1e6c0 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71  es.**.** The [sq
1e6d0 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
1e6e0 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65  izer | authorize
1e6f0 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  r callback funct
1e700 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74  ion] must.** ret
1e710 75 72 6e 20 65 69 74 68 65 72 20 5b 53 51 4c 49  urn either [SQLI
1e720 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66  TE_OK] or one of
1e730 20 74 68 65 73 65 20 74 77 6f 20 63 6f 6e 73 74   these two const
1e740 61 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a  ants in order.**
1e750 20 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69 74   to signal SQLit
1e760 65 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  e whether or not
1e770 20 74 68 65 20 61 63 74 69 6f 6e 20 69 73 20 70   the action is p
1e780 65 72 6d 69 74 74 65 64 2e 20 20 53 65 65 20 74  ermitted.  See t
1e790 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  he.** [sqlite3_s
1e7a0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20  et_authorizer | 
1e7b0 61 75 74 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d  authorizer docum
1e7c0 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64  entation] for ad
1e7d0 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f  ditional.** info
1e7e0 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e  rmation..**.** N
1e7f0 6f 74 65 20 74 68 61 74 20 53 51 4c 49 54 45 5f  ote that SQLITE_
1e800 49 47 4e 4f 52 45 20 69 73 20 61 6c 73 6f 20 75  IGNORE is also u
1e810 73 65 64 20 61 73 20 61 20 5b 53 51 4c 49 54 45  sed as a [SQLITE
1e820 5f 52 4f 4c 4c 42 41 43 4b 20 7c 20 72 65 74 75  _ROLLBACK | retu
1e830 72 6e 20 63 6f 64 65 5d 0a 2a 2a 20 66 72 6f 6d  rn code].** from
1e840 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 74   the [sqlite3_vt
1e850 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29  ab_on_conflict()
1e860 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a  ] interface..*/.
1e870 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1e880 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41 62 6f  ENY   1   /* Abo
1e890 72 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  rt the SQL state
1e8a0 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65 72 72  ment with an err
1e8b0 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  or */.#define SQ
1e8c0 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20 20 20  LITE_IGNORE 2   
1e8d0 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61  /* Don't allow a
1e8e0 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e 27 74  ccess, but don't
1e8f0 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65 72 72   generate an err
1e900 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  or */../*.** CAP
1e910 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65  I3REF: Authorize
1e920 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a  r Action Codes.*
1e930 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  *.** The [sqlite
1e940 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
1e950 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  ()] interface re
1e960 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61  gisters a callba
1e970 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74  ck function.** t
1e980 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 74  hat is invoked t
1e990 6f 20 61 75 74 68 6f 72 69 7a 65 20 63 65 72 74  o authorize cert
1e9a0 61 69 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ain SQL statemen
1e9b0 74 20 61 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a  t actions.  The.
1e9c0 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  ** second parame
1e9d0 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  ter to the callb
1e9e0 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ack is an intege
1e9f0 72 20 63 6f 64 65 20 74 68 61 74 20 73 70 65 63  r code that spec
1ea00 69 66 69 65 73 0a 2a 2a 20 77 68 61 74 20 61 63  ifies.** what ac
1ea10 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 61 75  tion is being au
1ea20 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 73 65  thorized.  These
1ea30 20 61 72 65 20 74 68 65 20 69 6e 74 65 67 65 72   are the integer
1ea40 20 61 63 74 69 6f 6e 20 63 6f 64 65 73 20 74 68   action codes th
1ea50 61 74 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72  at.** the author
1ea60 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61  izer callback ma
1ea70 79 20 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a  y be passed..**.
1ea80 2a 2a 20 54 68 65 73 65 20 61 63 74 69 6f 6e 20  ** These action 
1ea90 63 6f 64 65 20 76 61 6c 75 65 73 20 73 69 67 6e  code values sign
1eaa0 69 66 79 20 77 68 61 74 20 6b 69 6e 64 20 6f 66  ify what kind of
1eab0 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 74 6f   operation is to
1eac0 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65   be.** authorize
1ead0 64 2e 20 20 54 68 65 20 33 72 64 20 61 6e 64 20  d.  The 3rd and 
1eae0 34 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74  4th parameters t
1eaf0 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74  o the authorizat
1eb00 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  ion.** callback 
1eb10 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65  function will be
1eb20 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e   parameters or N
1eb30 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ULL depending on
1eb40 20 77 68 69 63 68 20 6f 66 20 74 68 65 73 65 0a   which of these.
1eb50 2a 2a 20 63 6f 64 65 73 20 69 73 20 75 73 65 64  ** codes is used
1eb60 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70   as the second p
1eb70 61 72 61 6d 65 74 65 72 2e 20 20 5e 28 54 68 65  arameter.  ^(The
1eb80 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   5th parameter t
1eb90 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69  o the.** authori
1eba0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
1ebb0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
1ebc0 64 61 74 61 62 61 73 65 20 28 22 6d 61 69 6e 22  database ("main"
1ebd0 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63  , "temp",.** etc
1ebe0 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65  .) if applicable
1ebf0 2e 29 5e 20 20 5e 54 68 65 20 36 74 68 20 70 61  .)^  ^The 6th pa
1ec00 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61  rameter to the a
1ec10 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1ec20 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d  ck.** is the nam
1ec30 65 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d  e of the inner-m
1ec40 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72 20 76  ost trigger or v
1ec50 69 65 77 20 74 68 61 74 20 69 73 20 72 65 73 70  iew that is resp
1ec60 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74  onsible for.** t
1ec70 68 65 20 61 63 63 65 73 73 20 61 74 74 65 6d 70  he access attemp
1ec80 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69  t or NULL if thi
1ec90 73 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74  s access attempt
1eca0 20 69 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f   is directly fro
1ecb0 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53  m.** top-level S
1ecc0 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a  QL code..*/./***
1ecd0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1ece0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1ecf0 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a  ******** 3rd ***
1ed00 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a  ********* 4th **
1ed10 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69  *********/.#defi
1ed20 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
1ed30 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20  _INDEX          
1ed40 31 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  1   /* Index Nam
1ed50 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  e      Table Nam
1ed60 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
1ed70 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
1ed80 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32  TABLE          2
1ed90 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
1eda0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1edb0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1edc0 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
1edd0 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 33 20  EMP_INDEX     3 
1ede0 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
1edf0 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20       Table Name 
1ee00 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1ee10 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45  SQLITE_CREATE_TE
1ee20 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 34 20 20  MP_TABLE     4  
1ee30 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
1ee40 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1ee50 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1ee60 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d  QLITE_CREATE_TEM
1ee70 50 5f 54 52 49 47 47 45 52 20 20 20 35 20 20 20  P_TRIGGER   5   
1ee80 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20  /* Trigger Name 
1ee90 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
1eea0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1eeb0 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
1eec0 5f 56 49 45 57 20 20 20 20 20 20 36 20 20 20 2f  _VIEW      6   /
1eed0 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20  * View Name     
1eee0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1eef0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1ef00 49 54 45 5f 43 52 45 41 54 45 5f 54 52 49 47 47  ITE_CREATE_TRIGG
1ef10 45 52 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a  ER        7   /*
1ef20 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20   Trigger Name   
1ef30 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1ef40 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1ef50 54 45 5f 43 52 45 41 54 45 5f 56 49 45 57 20 20  TE_CREATE_VIEW  
1ef60 20 20 20 20 20 20 20 20 20 38 20 20 20 2f 2a 20           8   /* 
1ef70 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20  View Name       
1ef80 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1ef90 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1efa0 45 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20  E_DELETE        
1efb0 20 20 20 20 20 20 20 20 39 20 20 20 2f 2a 20 54          9   /* T
1efc0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
1efd0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1efe0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1eff0 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20 20 20 20  _DROP_INDEX     
1f000 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 49 6e        10   /* In
1f010 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61  dex Name      Ta
1f020 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
1f030 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1f040 44 52 4f 50 5f 54 41 42 4c 45 20 20 20 20 20 20  DROP_TABLE      
1f050 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 61 62       11   /* Tab
1f060 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
1f070 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1f080 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1f090 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20  ROP_TEMP_INDEX  
1f0a0 20 20 20 20 31 32 20 20 20 2f 2a 20 49 6e 64 65      12   /* Inde
1f0b0 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
1f0c0 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
1f0d0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
1f0e0 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20  OP_TEMP_TABLE   
1f0f0 20 20 20 31 33 20 20 20 2f 2a 20 54 61 62 6c 65     13   /* Table
1f100 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
1f110 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1f120 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
1f130 50 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20  P_TEMP_TRIGGER  
1f140 20 20 31 34 20 20 20 2f 2a 20 54 72 69 67 67 65    14   /* Trigge
1f150 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20  r Name    Table 
1f160 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
1f170 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
1f180 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20  _TEMP_VIEW      
1f190 20 31 35 20 20 20 2f 2a 20 56 69 65 77 20 4e 61   15   /* View Na
1f1a0 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  me       NULL   
1f1b0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1f1c0 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
1f1d0 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20 20  TRIGGER         
1f1e0 31 36 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20  16   /* Trigger 
1f1f0 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
1f200 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
1f210 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56  ne SQLITE_DROP_V
1f220 49 45 57 20 20 20 20 20 20 20 20 20 20 20 20 31  IEW            1
1f230 37 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  7   /* View Name
1f240 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
1f250 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1f260 65 20 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 20  e SQLITE_INSERT 
1f270 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 38                18
1f280 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
1f290 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1f2a0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1f2b0 20 53 51 4c 49 54 45 5f 50 52 41 47 4d 41 20 20   SQLITE_PRAGMA  
1f2c0 20 20 20 20 20 20 20 20 20 20 20 20 20 31 39 20               19 
1f2d0 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65    /* Pragma Name
1f2e0 20 20 20 20 20 31 73 74 20 61 72 67 20 6f 72 20       1st arg or 
1f2f0 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20  NULL */.#define 
1f300 53 51 4c 49 54 45 5f 52 45 41 44 20 20 20 20 20  SQLITE_READ     
1f310 20 20 20 20 20 20 20 20 20 20 20 20 32 30 20 20              20  
1f320 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
1f330 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20      Column Name 
1f340 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1f350 51 4c 49 54 45 5f 53 45 4c 45 43 54 20 20 20 20  QLITE_SELECT    
1f360 20 20 20 20 20 20 20 20 20 20 20 32 31 20 20 20             21   
1f370 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20  /* NULL         
1f380 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1f390 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1f3a0 4c 49 54 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e  LITE_TRANSACTION
1f3b0 20 20 20 20 20 20 20 20 20 20 32 32 20 20 20 2f            22   /
1f3c0 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20  * Operation     
1f3d0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1f3e0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1f3f0 49 54 45 5f 55 50 44 41 54 45 20 20 20 20 20 20  ITE_UPDATE      
1f400 20 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a           23   /*
1f410 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1f420 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20   Column Name    
1f430 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1f440 54 45 5f 41 54 54 41 43 48 20 20 20 20 20 20 20  TE_ATTACH       
1f450 20 20 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20          24   /* 
1f460 46 69 6c 65 6e 61 6d 65 20 20 20 20 20 20 20 20  Filename        
1f470 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1f480 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1f490 45 5f 44 45 54 41 43 48 20 20 20 20 20 20 20 20  E_DETACH        
1f4a0 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 44         25   /* D
1f4b0 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 4e  atabase Name   N
1f4c0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1f4d0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1f4e0 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20 20 20 20  _ALTER_TABLE    
1f4f0 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 44 61        26   /* Da
1f500 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 54 61  tabase Name   Ta
1f510 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
1f520 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1f530 52 45 49 4e 44 45 58 20 20 20 20 20 20 20 20 20  REINDEX         
1f540 20 20 20 20 20 32 37 20 20 20 2f 2a 20 49 6e 64       27   /* Ind
1f550 65 78 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  ex Name      NUL
1f560 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1f570 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
1f580 4e 41 4c 59 5a 45 20 20 20 20 20 20 20 20 20 20  NALYZE          
1f590 20 20 20 20 32 38 20 20 20 2f 2a 20 54 61 62 6c      28   /* Tabl
1f5a0 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
1f5b0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1f5c0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
1f5d0 45 41 54 45 5f 56 54 41 42 4c 45 20 20 20 20 20  EATE_VTABLE     
1f5e0 20 20 20 32 39 20 20 20 2f 2a 20 54 61 62 6c 65     29   /* Table
1f5f0 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c   Name      Modul
1f600 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64  e Name     */.#d
1f610 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
1f620 50 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20  P_VTABLE        
1f630 20 20 33 30 20 20 20 2f 2a 20 54 61 62 6c 65 20    30   /* Table 
1f640 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65  Name      Module
1f650 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65   Name     */.#de
1f660 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e 43  fine SQLITE_FUNC
1f670 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 20 20  TION            
1f680 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20   31   /* NULL   
1f690 20 20 20 20 20 20 20 20 20 46 75 6e 63 74 69 6f           Functio
1f6a0 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66  n Name   */.#def
1f6b0 69 6e 65 20 53 51 4c 49 54 45 5f 53 41 56 45 50  ine SQLITE_SAVEP
1f6c0 4f 49 4e 54 20 20 20 20 20 20 20 20 20 20 20 20  OINT            
1f6d0 33 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f  32   /* Operatio
1f6e0 6e 20 20 20 20 20 20 20 53 61 76 65 70 6f 69 6e  n       Savepoin
1f6f0 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69  t Name  */.#defi
1f700 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50 59 20 20  ne SQLITE_COPY  
1f710 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1f720 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72  0   /* No longer
1f730 20 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20   used */../*.** 
1f740 43 41 50 49 33 52 45 46 3a 20 54 72 61 63 69 6e  CAPI3REF: Tracin
1f750 67 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20  g And Profiling 
1f760 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  Functions.**.** 
1f770 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
1f780 65 67 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b  egister callback
1f790 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20   functions that 
1f7a0 63 61 6e 20 62 65 20 75 73 65 64 20 66 6f 72 0a  can be used for.
1f7b0 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e 64 20 70  ** tracing and p
1f7c0 72 6f 66 69 6c 69 6e 67 20 74 68 65 20 65 78 65  rofiling the exe
1f7d0 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74  cution of SQL st
1f7e0 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  atements..**.** 
1f7f0 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75  ^The callback fu
1f800 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65  nction registere
1f810 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 72 61  d by sqlite3_tra
1f820 63 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20  ce() is invoked 
1f830 61 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74 69  at.** various ti
1f840 6d 65 73 20 77 68 65 6e 20 61 6e 20 53 51 4c 20  mes when an SQL 
1f850 73 74 61 74 65 6d 65 6e 74 20 69 73 20 62 65 69  statement is bei
1f860 6e 67 20 72 75 6e 20 62 79 20 5b 73 71 6c 69 74  ng run by [sqlit
1f870 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e  e3_step()]..** ^
1f880 54 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63  The sqlite3_trac
1f890 65 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  e() callback is 
1f8a0 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 20 55  invoked with a U
1f8b0 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f  TF-8 rendering o
1f8c0 66 20 74 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61  f the.** SQL sta
1f8d0 74 65 6d 65 6e 74 20 74 65 78 74 20 61 73 20 74  tement text as t
1f8e0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72  he statement fir
1f8f0 73 74 20 62 65 67 69 6e 73 20 65 78 65 63 75 74  st begins execut
1f900 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69  ing..** ^(Additi
1f910 6f 6e 61 6c 20 73 71 6c 69 74 65 33 5f 74 72 61  onal sqlite3_tra
1f920 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d  ce() callbacks m
1f930 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73  ight occur.** as
1f940 20 65 61 63 68 20 74 72 69 67 67 65 72 65 64 20   each triggered 
1f950 73 75 62 70 72 6f 67 72 61 6d 20 69 73 20 65 6e  subprogram is en
1f960 74 65 72 65 64 2e 20 20 54 68 65 20 63 61 6c 6c  tered.  The call
1f970 62 61 63 6b 73 20 66 6f 72 20 74 72 69 67 67 65  backs for trigge
1f980 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20  rs.** contain a 
1f990 55 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e  UTF-8 SQL commen
1f9a0 74 20 74 68 61 74 20 69 64 65 6e 74 69 66 69 65  t that identifie
1f9b0 73 20 74 68 65 20 74 72 69 67 67 65 72 2e 29 5e  s the trigger.)^
1f9c0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  .**.** The [SQLI
1f9d0 54 45 5f 54 52 41 43 45 5f 53 49 5a 45 5f 4c 49  TE_TRACE_SIZE_LI
1f9e0 4d 49 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  MIT] compile-tim
1f9f0 65 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20  e option can be 
1fa00 75 73 65 64 20 74 6f 20 6c 69 6d 69 74 0a 2a 2a  used to limit.**
1fa10 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 5b   the length of [
1fa20 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 5d  bound parameter]
1fa30 20 65 78 70 61 6e 73 69 6f 6e 20 69 6e 20 74 68   expansion in th
1fa40 65 20 6f 75 74 70 75 74 20 6f 66 20 73 71 6c 69  e output of sqli
1fa50 74 65 33 5f 74 72 61 63 65 28 29 2e 0a 2a 2a 0a  te3_trace()..**.
1fa60 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b  ** ^The callback
1fa70 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74   function regist
1fa80 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  ered by sqlite3_
1fa90 70 72 6f 66 69 6c 65 28 29 20 69 73 20 69 6e 76  profile() is inv
1faa0 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63 68 20  oked.** as each 
1fab0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69  SQL statement fi
1fac0 6e 69 73 68 65 73 2e 20 20 5e 54 68 65 20 70 72  nishes.  ^The pr
1fad0 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63  ofile callback c
1fae0 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f  ontains.** the o
1faf0 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e  riginal statemen
1fb00 74 20 74 65 78 74 20 61 6e 64 20 61 6e 20 65 73  t text and an es
1fb10 74 69 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63  timate of wall-c
1fb20 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20  lock time.** of 
1fb30 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20 73 74  how long that st
1fb40 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20  atement took to 
1fb50 72 75 6e 2e 20 20 5e 54 68 65 20 70 72 6f 66 69  run.  ^The profi
1fb60 6c 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74  le callback.** t
1fb70 69 6d 65 20 69 73 20 69 6e 20 75 6e 69 74 73 20  ime is in units 
1fb80 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c 20  of nanoseconds, 
1fb90 68 6f 77 65 76 65 72 20 74 68 65 20 63 75 72 72  however the curr
1fba0 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ent implementati
1fbb0 6f 6e 0a 2a 2a 20 69 73 20 6f 6e 6c 79 20 63 61  on.** is only ca
1fbc0 70 61 62 6c 65 20 6f 66 20 6d 69 6c 6c 69 73 65  pable of millise
1fbd0 63 6f 6e 64 20 72 65 73 6f 6c 75 74 69 6f 6e 20  cond resolution 
1fbe0 73 6f 20 74 68 65 20 73 69 78 20 6c 65 61 73 74  so the six least
1fbf0 20 73 69 67 6e 69 66 69 63 61 6e 74 0a 2a 2a 20   significant.** 
1fc00 64 69 67 69 74 73 20 69 6e 20 74 68 65 20 74 69  digits in the ti
1fc10 6d 65 20 61 72 65 20 6d 65 61 6e 69 6e 67 6c 65  me are meaningle
1fc20 73 73 2e 20 20 46 75 74 75 72 65 20 76 65 72 73  ss.  Future vers
1fc30 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a  ions of SQLite.*
1fc40 2a 20 6d 69 67 68 74 20 70 72 6f 76 69 64 65 20  * might provide 
1fc50 67 72 65 61 74 65 72 20 72 65 73 6f 6c 75 74 69  greater resoluti
1fc60 6f 6e 20 6f 6e 20 74 68 65 20 70 72 6f 66 69 6c  on on the profil
1fc70 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 20 54 68  er callback.  Th
1fc80 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 6f  e.** sqlite3_pro
1fc90 66 69 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20  file() function 
1fca0 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 65 78  is considered ex
1fcb0 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69  perimental and i
1fcc0 73 0a 2a 2a 20 73 75 62 6a 65 63 74 20 74 6f 20  s.** subject to 
1fcd0 63 68 61 6e 67 65 20 69 6e 20 66 75 74 75 72 65  change in future
1fce0 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
1fcf0 69 74 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ite..*/.SQLITE_A
1fd00 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  PI void *sqlite3
1fd10 5f 74 72 61 63 65 28 73 71 6c 69 74 65 33 2a 2c  _trace(sqlite3*,
1fd20 20 76 6f 69 64 28 2a 78 54 72 61 63 65 29 28 76   void(*xTrace)(v
1fd30 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  oid*,const char*
1fd40 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54  ), void*);.SQLIT
1fd50 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 45 58 50  E_API SQLITE_EXP
1fd60 45 52 49 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a  ERIMENTAL void *
1fd70 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28  sqlite3_profile(
1fd80 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69  sqlite3*,.   voi
1fd90 64 28 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f 69  d(*xProfile)(voi
1fda0 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73  d*,const char*,s
1fdb0 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 2c 20  qlite3_uint64), 
1fdc0 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
1fdd0 41 50 49 33 52 45 46 3a 20 51 75 65 72 79 20 50  API3REF: Query P
1fde0 72 6f 67 72 65 73 73 20 43 61 6c 6c 62 61 63 6b  rogress Callback
1fdf0 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
1fe00 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61  ite3_progress_ha
1fe10 6e 64 6c 65 72 28 44 2c 4e 2c 58 2c 50 29 20 69  ndler(D,N,X,P) i
1fe20 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20  nterface causes 
1fe30 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  the callback.** 
1fe40 66 75 6e 63 74 69 6f 6e 20 58 20 74 6f 20 62 65  function X to be
1fe50 20 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69   invoked periodi
1fe60 63 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e  cally during lon
1fe70 67 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20  g running calls 
1fe80 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  to.** [sqlite3_e
1fe90 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  xec()], [sqlite3
1fea0 5f 73 74 65 70 28 29 5d 20 61 6e 64 20 5b 73 71  _step()] and [sq
1feb0 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
1fec0 29 5d 20 66 6f 72 0a 2a 2a 20 64 61 74 61 62 61  )] for.** databa
1fed0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e  se connection D.
1fee0 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 65    An example use
1fef0 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74   for this.** int
1ff00 65 72 66 61 63 65 20 69 73 20 74 6f 20 6b 65 65  erface is to kee
1ff10 70 20 61 20 47 55 49 20 75 70 64 61 74 65 64 20  p a GUI updated 
1ff20 64 75 72 69 6e 67 20 61 20 6c 61 72 67 65 20 71  during a large q
1ff30 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  uery..**.** ^The
1ff40 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20   parameter P is 
1ff50 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 61  passed through a
1ff60 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d  s the only param
1ff70 65 74 65 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20  eter to the .** 
1ff80 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
1ff90 6e 20 58 2e 20 20 5e 54 68 65 20 70 61 72 61 6d  n X.  ^The param
1ffa0 65 74 65 72 20 4e 20 69 73 20 74 68 65 20 61 70  eter N is the ap
1ffb0 70 72 6f 78 69 6d 61 74 65 20 6e 75 6d 62 65 72  proximate number
1ffc0 20 6f 66 20 0a 2a 2a 20 5b 76 69 72 74 75 61 6c   of .** [virtual
1ffd0 20 6d 61 63 68 69 6e 65 20 69 6e 73 74 72 75 63   machine instruc
1ffe0 74 69 6f 6e 73 5d 20 74 68 61 74 20 61 72 65 20  tions] that are 
1fff0 65 76 61 6c 75 61 74 65 64 20 62 65 74 77 65 65  evaluated betwee
20000 6e 20 73 75 63 63 65 73 73 69 76 65 0a 2a 2a 20  n successive.** 
20010 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74  invocations of t
20020 68 65 20 63 61 6c 6c 62 61 63 6b 20 58 2e 20 20  he callback X.  
20030 5e 49 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68  ^If N is less th
20040 61 6e 20 6f 6e 65 20 74 68 65 6e 20 74 68 65 20  an one then the 
20050 70 72 6f 67 72 65 73 73 0a 2a 2a 20 68 61 6e 64  progress.** hand
20060 6c 65 72 20 69 73 20 64 69 73 61 62 6c 65 64 2e  ler is disabled.
20070 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61 20 73  .**.** ^Only a s
20080 69 6e 67 6c 65 20 70 72 6f 67 72 65 73 73 20 68  ingle progress h
20090 61 6e 64 6c 65 72 20 6d 61 79 20 62 65 20 64 65  andler may be de
200a0 66 69 6e 65 64 20 61 74 20 6f 6e 65 20 74 69 6d  fined at one tim
200b0 65 20 70 65 72 0a 2a 2a 20 5b 64 61 74 61 62 61  e per.** [databa
200c0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 3b 20  se connection]; 
200d0 73 65 74 74 69 6e 67 20 61 20 6e 65 77 20 70 72  setting a new pr
200e0 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63  ogress handler c
200f0 61 6e 63 65 6c 73 20 74 68 65 0a 2a 2a 20 6f 6c  ancels the.** ol
20100 64 20 6f 6e 65 2e 20 20 5e 53 65 74 74 69 6e 67  d one.  ^Setting
20110 20 70 61 72 61 6d 65 74 65 72 20 58 20 74 6f 20   parameter X to 
20120 4e 55 4c 4c 20 64 69 73 61 62 6c 65 73 20 74 68  NULL disables th
20130 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  e progress handl
20140 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 70 72 6f 67  er..** ^The prog
20150 72 65 73 73 20 68 61 6e 64 6c 65 72 20 69 73 20  ress handler is 
20160 61 6c 73 6f 20 64 69 73 61 62 6c 65 64 20 62 79  also disabled by
20170 20 73 65 74 74 69 6e 67 20 4e 20 74 6f 20 61 20   setting N to a 
20180 76 61 6c 75 65 20 6c 65 73 73 0a 2a 2a 20 74 68  value less.** th
20190 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  an 1..**.** ^If 
201a0 74 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c  the progress cal
201b0 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f  lback returns no
201c0 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65 72  n-zero, the oper
201d0 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65  ation is.** inte
201e0 72 72 75 70 74 65 64 2e 20 20 54 68 69 73 20 66  rrupted.  This f
201f0 65 61 74 75 72 65 20 63 61 6e 20 62 65 20 75 73  eature can be us
20200 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  ed to implement 
20210 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62 75  a.** "Cancel" bu
20220 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70 72  tton on a GUI pr
20230 6f 67 72 65 73 73 20 64 69 61 6c 6f 67 20 62 6f  ogress dialog bo
20240 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f  x..**.** The pro
20250 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61  gress handler ca
20260 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20  llback must not 
20270 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74  do anything that
20280 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20   will modify.** 
20290 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
202a0 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76  nection that inv
202b0 6f 6b 65 64 20 74 68 65 20 70 72 6f 67 72 65 73  oked the progres
202c0 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f  s handler..** No
202d0 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33  te that [sqlite3
202e0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
202f0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  nd [sqlite3_step
20300 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20  ()] both modify 
20310 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73  their.** databas
20320 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f  e connections fo
20330 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66  r the meaning of
20340 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69   "modify" in thi
20350 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a  s paragraph..**.
20360 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  */.SQLITE_API vo
20370 69 64 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72  id sqlite3_progr
20380 65 73 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69  ess_handler(sqli
20390 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a  te3*, int, int(*
203a0 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29  )(void*), void*)
203b0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
203c0 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77  F: Opening A New
203d0 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63   Database Connec
203e0 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  tion.**.** ^Thes
203f0 65 20 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20  e routines open 
20400 61 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 61  an SQLite databa
20410 73 65 20 66 69 6c 65 20 61 73 20 73 70 65 63 69  se file as speci
20420 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20  fied by the .** 
20430 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
20440 74 2e 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65  t. ^The filename
20450 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e 74   argument is int
20460 65 72 70 72 65 74 65 64 20 61 73 20 55 54 46 2d  erpreted as UTF-
20470 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  8 for.** sqlite3
20480 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69  _open() and sqli
20490 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61 6e  te3_open_v2() an
204a0 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 74  d as UTF-16 in t
204b0 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 0a 2a  he native byte.*
204c0 2a 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69  * order for sqli
204d0 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20 5e 28  te3_open16(). ^(
204e0 41 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  A [database conn
204f0 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69  ection] handle i
20500 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74  s usually.** ret
20510 75 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c 20  urned in *ppDb, 
20520 65 76 65 6e 20 69 66 20 61 6e 20 65 72 72 6f 72  even if an error
20530 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20 6f 6e   occurs.  The on
20540 6c 79 20 65 78 63 65 70 74 69 6f 6e 20 69 73 20  ly exception is 
20550 74 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74  that.** if SQLit
20560 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61  e is unable to a
20570 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74  llocate memory t
20580 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69  o hold the [sqli
20590 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20  te3] object,.** 
205a0 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77  a NULL will be w
205b0 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44  ritten into *ppD
205c0 62 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 70  b instead of a p
205d0 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ointer to the [s
205e0 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63  qlite3].** objec
205f0 74 2e 29 5e 20 5e 28 49 66 20 74 68 65 20 64 61  t.)^ ^(If the da
20600 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
20610 20 28 61 6e 64 2f 6f 72 20 63 72 65 61 74 65 64   (and/or created
20620 29 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2c 20  ) successfully, 
20630 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  then.** [SQLITE_
20640 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  OK] is returned.
20650 20 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20 5b    Otherwise an [
20660 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72  error code] is r
20670 65 74 75 72 6e 65 64 2e 29 5e 20 5e 54 68 65 0a  eturned.)^ ^The.
20680 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  ** [sqlite3_errm
20690 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  sg()] or [sqlite
206a0 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 72 6f  3_errmsg16()] ro
206b0 75 74 69 6e 65 73 20 63 61 6e 20 62 65 20 75 73  utines can be us
206c0 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20  ed to obtain.** 
206d0 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75  an English langu
206e0 61 67 65 20 64 65 73 63 72 69 70 74 69 6f 6e 20  age description 
206f0 6f 66 20 74 68 65 20 65 72 72 6f 72 20 66 6f 6c  of the error fol
20700 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 75 72 65  lowing a failure
20710 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68   of any.** of th
20720 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  e sqlite3_open()
20730 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a   routines..**.**
20740 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e   ^The default en
20750 63 6f 64 69 6e 67 20 66 6f 72 20 74 68 65 20 64  coding for the d
20760 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20  atabase will be 
20770 55 54 46 2d 38 20 69 66 0a 2a 2a 20 73 71 6c 69  UTF-8 if.** sqli
20780 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71  te3_open() or sq
20790 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
207a0 69 73 20 63 61 6c 6c 65 64 20 61 6e 64 0a 2a 2a  is called and.**
207b0 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e   UTF-16 in the n
207c0 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
207d0 20 69 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   if sqlite3_open
207e0 31 36 28 29 20 69 73 20 75 73 65 64 2e 0a 2a 2a  16() is used..**
207f0 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f 72 20 6e  .** Whether or n
20800 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75  ot an error occu
20810 72 73 20 77 68 65 6e 20 69 74 20 69 73 20 6f 70  rs when it is op
20820 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 65 73 0a  ened, resources.
20830 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ** associated wi
20840 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  th the [database
20850 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e   connection] han
20860 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 72 65  dle should be re
20870 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20 70 61 73  leased by.** pas
20880 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69  sing it to [sqli
20890 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65  te3_close()] whe
208a0 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65  n it is no longe
208b0 72 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a  r required..**.*
208c0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 70  * The sqlite3_op
208d0 65 6e 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63  en_v2() interfac
208e0 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c  e works like sql
208f0 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65  ite3_open().** e
20900 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61 63  xcept that it ac
20910 63 65 70 74 73 20 74 77 6f 20 61 64 64 69 74 69  cepts two additi
20920 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73 20  onal parameters 
20930 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 63  for additional c
20940 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74  ontrol.** over t
20950 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20  he new database 
20960 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28 54  connection.  ^(T
20970 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74  he flags paramet
20980 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  er to.** sqlite3
20990 5f 6f 70 65 6e 5f 76 32 28 29 20 63 61 6e 20 74  _open_v2() can t
209a0 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68  ake one of.** th
209b0 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65  e following thre
209c0 65 20 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e  e values, option
209d0 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69  ally combined wi
209e0 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49  th the .** [SQLI
209f0 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d  TE_OPEN_NOMUTEX]
20a00 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46  , [SQLITE_OPEN_F
20a10 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49  ULLMUTEX], [SQLI
20a20 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
20a30 43 48 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  CHE],.** [SQLITE
20a40 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43  _OPEN_PRIVATECAC
20a50 48 45 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53 51 4c  HE], and/or [SQL
20a60 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c  ITE_OPEN_URI] fl
20a70 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c  ags:)^.**.** <dl
20a80 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49  >.** ^(<dt>[SQLI
20a90 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
20aa0 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  ]</dt>.** <dd>Th
20ab0 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
20ac0 65 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c  ened in read-onl
20ad0 79 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20  y mode.  If the 
20ae0 64 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f  database does no
20af0 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65 78 69  t.** already exi
20b00 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20  st, an error is 
20b10 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e  returned.</dd>)^
20b20 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51  .**.** ^(<dt>[SQ
20b30 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
20b40 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ITE]</dt>.** <dd
20b50 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73  >The database is
20b60 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64   opened for read
20b70 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20  ing and writing 
20b80 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20  if possible, or 
20b90 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20  reading.** only 
20ba0 69 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 77  if the file is w
20bb0 72 69 74 65 20 70 72 6f 74 65 63 74 65 64 20 62  rite protected b
20bc0 79 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  y the operating 
20bd0 73 79 73 74 65 6d 2e 20 20 49 6e 20 65 69 74 68  system.  In eith
20be0 65 72 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 64  er.** case the d
20bf0 61 74 61 62 61 73 65 20 6d 75 73 74 20 61 6c 72  atabase must alr
20c00 65 61 64 79 20 65 78 69 73 74 2c 20 6f 74 68 65  eady exist, othe
20c10 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20 69  rwise an error i
20c20 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e  s returned.</dd>
20c30 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b  )^.**.** ^(<dt>[
20c40 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
20c50 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45  WRITE] | [SQLITE
20c60 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64  _OPEN_CREATE]</d
20c70 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61  t>.** <dd>The da
20c80 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
20c90 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64   for reading and
20ca0 20 77 72 69 74 69 6e 67 2c 20 61 6e 64 20 69 73   writing, and is
20cb0 20 63 72 65 61 74 65 64 20 69 66 0a 2a 2a 20 69   created if.** i
20cc0 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61  t does not alrea
20cd0 64 79 20 65 78 69 73 74 2e 20 54 68 69 73 20 69  dy exist. This i
20ce0 73 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 74  s the behavior t
20cf0 68 61 74 20 69 73 20 61 6c 77 61 79 73 20 75 73  hat is always us
20d00 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  ed for.** sqlite
20d10 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c  3_open() and sql
20d20 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f  ite3_open16().</
20d30 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  dd>)^.** </dl>.*
20d40 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20  *.** If the 3rd 
20d50 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
20d60 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
20d70 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65  s not one of the
20d80 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73  .** combinations
20d90 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f 70 74   shown above opt
20da0 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64  ionally combined
20db0 20 77 69 74 68 20 6f 74 68 65 72 0a 2a 2a 20 5b   with other.** [
20dc0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
20dd0 4f 4e 4c 59 20 7c 20 53 51 4c 49 54 45 5f 4f 50  ONLY | SQLITE_OP
20de0 45 4e 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20 74 68  EN_* bits].** th
20df0 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
20e00 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
20e10 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c  .** ^If the [SQL
20e20 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58  ITE_OPEN_NOMUTEX
20e30 5d 20 66 6c 61 67 20 69 73 20 73 65 74 2c 20 74  ] flag is set, t
20e40 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
20e50 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f   connection.** o
20e60 70 65 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c 74  pens in the mult
20e70 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 64  i-thread [thread
20e80 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e  ing mode] as lon
20e90 67 20 61 73 20 74 68 65 20 73 69 6e 67 6c 65 2d  g as the single-
20ea0 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68  thread.** mode h
20eb0 61 73 20 6e 6f 74 20 62 65 65 6e 20 73 65 74 20  as not been set 
20ec0 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  at compile-time 
20ed0 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 20 20  or start-time.  
20ee0 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ^If the.** [SQLI
20ef0 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45  TE_OPEN_FULLMUTE
20f00 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20 74  X] flag is set t
20f10 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
20f20 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e   connection open
20f30 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65 72 69  s.** in the seri
20f40 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e  alized [threadin
20f50 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73  g mode] unless s
20f60 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 77 61 73  ingle-thread was
20f70 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73  .** previously s
20f80 65 6c 65 63 74 65 64 20 61 74 20 63 6f 6d 70 69  elected at compi
20f90 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74  le-time or start
20fa0 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b  -time..** ^The [
20fb0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52  SQLITE_OPEN_SHAR
20fc0 45 44 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61  EDCACHE] flag ca
20fd0 75 73 65 73 20 74 68 65 20 64 61 74 61 62 61 73  uses the databas
20fe0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20  e connection to 
20ff0 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c 65 20 74  be.** eligible t
21000 6f 20 75 73 65 20 5b 73 68 61 72 65 64 20 63 61  o use [shared ca
21010 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65 67 61 72  che mode], regar
21020 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72  dless of whether
21030 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 0a 2a   or not shared.*
21040 2a 20 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c  * cache is enabl
21050 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
21060 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f  3_enable_shared_
21070 63 61 63 68 65 28 29 5d 2e 20 20 5e 54 68 65 0a  cache()].  ^The.
21080 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
21090 50 52 49 56 41 54 45 43 41 43 48 45 5d 20 66 6c  PRIVATECACHE] fl
210a0 61 67 20 63 61 75 73 65 73 20 74 68 65 20 64 61  ag causes the da
210b0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
210c0 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72 74  n to not.** part
210d0 69 63 69 70 61 74 65 20 69 6e 20 5b 73 68 61 72  icipate in [shar
210e0 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 20 65  ed cache mode] e
210f0 76 65 6e 20 69 66 20 69 74 20 69 73 20 65 6e 61  ven if it is ena
21100 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  bled..**.** ^The
21110 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
21120 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  r to sqlite3_ope
21130 6e 5f 76 32 28 29 20 69 73 20 74 68 65 20 6e 61  n_v2() is the na
21140 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  me of the.** [sq
21150 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
21160 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 74  t that defines t
21170 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  he operating sys
21180 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68  tem interface th
21190 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 61  at.** the new da
211a0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
211b0 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 5e  n should use.  ^
211c0 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  If the fourth pa
211d0 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61 20  rameter is.** a 
211e0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65  NULL pointer the
211f0 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73  n the default [s
21200 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
21210 63 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a  ct is used..**.*
21220 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61  * ^If the filena
21230 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22  me is ":memory:"
21240 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65  , then a private
21250 2c 20 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d  , temporary in-m
21260 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 0a 2a  emory database.*
21270 2a 20 69 73 20 63 72 65 61 74 65 64 20 66 6f 72  * is created for
21280 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e   the connection.
21290 20 20 5e 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72    ^This in-memor
212a0 79 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20  y database will 
212b0 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74  vanish when.** t
212c0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
212d0 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64  ection is closed
212e0 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f  .  Future versio
212f0 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67  ns of SQLite mig
21300 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f  ht.** make use o
21310 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 70 65  f additional spe
21320 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74  cial filenames t
21330 68 61 74 20 62 65 67 69 6e 20 77 69 74 68 20 74  hat begin with t
21340 68 65 20 22 3a 22 20 63 68 61 72 61 63 74 65 72  he ":" character
21350 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65 63 6f 6d  ..** It is recom
21360 6d 65 6e 64 65 64 20 74 68 61 74 20 77 68 65 6e  mended that when
21370 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65   a database file
21380 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79 20 64 6f  name actually do
21390 65 73 20 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a  es begin with.**
213a0 20 61 20 22 3a 22 20 63 68 61 72 61 63 74 65 72   a ":" character
213b0 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 72 65 66   you should pref
213c0 69 78 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  ix the filename 
213d0 77 69 74 68 20 61 20 70 61 74 68 6e 61 6d 65 20  with a pathname 
213e0 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20  such as.** "./" 
213f0 74 6f 20 61 76 6f 69 64 20 61 6d 62 69 67 75 69  to avoid ambigui
21400 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ty..**.** ^If th
21410 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e  e filename is an
21420 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74   empty string, t
21430 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74  hen a private, t
21440 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64  emporary.** on-d
21450 69 73 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c  isk database wil
21460 6c 20 62 65 20 63 72 65 61 74 65 64 2e 20 20 5e  l be created.  ^
21470 54 68 69 73 20 70 72 69 76 61 74 65 20 64 61 74  This private dat
21480 61 62 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a  abase will be.**
21490 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64   automatically d
214a0 65 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61  eleted as soon a
214b0 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  s the database c
214c0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f  onnection is clo
214d0 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49  sed..**.** [[URI
214e0 20 66 69 6c 65 6e 61 6d 65 73 20 69 6e 20 73 71   filenames in sq
214f0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 5d 20 3c  lite3_open()]] <
21500 68 33 3e 55 52 49 20 46 69 6c 65 6e 61 6d 65 73  h3>URI Filenames
21510 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  </h3>.**.** ^If 
21520 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 5d 20 69  [URI filename] i
21530 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73  nterpretation is
21540 20 65 6e 61 62 6c 65 64 2c 20 61 6e 64 20 74 68   enabled, and th
21550 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  e filename argum
21560 65 6e 74 0a 2a 2a 20 62 65 67 69 6e 73 20 77 69  ent.** begins wi
21570 74 68 20 22 66 69 6c 65 3a 22 2c 20 74 68 65 6e  th "file:", then
21580 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73   the filename is
21590 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
215a0 61 20 55 52 49 2e 20 5e 55 52 49 0a 2a 2a 20 66  a URI. ^URI.** f
215b0 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65  ilename interpre
215c0 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65  tation is enable
215d0 64 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45  d if the [SQLITE
215e0 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20  _OPEN_URI] flag 
215f0 69 73 0a 2a 2a 20 73 65 74 20 69 6e 20 74 68 65  is.** set in the
21600 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
21610 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
21620 5f 76 32 28 29 2c 20 6f 72 20 69 66 20 69 74 20  _v2(), or if it 
21630 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65 6e 61 62  has.** been enab
21640 6c 65 64 20 67 6c 6f 62 61 6c 6c 79 20 75 73 69  led globally usi
21650 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43  ng the [SQLITE_C
21660 4f 4e 46 49 47 5f 55 52 49 5d 20 6f 70 74 69 6f  ONFIG_URI] optio
21670 6e 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 73  n with the.** [s
21680 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
21690 20 6d 65 74 68 6f 64 20 6f 72 20 62 79 20 74 68   method or by th
216a0 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52  e [SQLITE_USE_UR
216b0 49 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  I] compile-time 
216c0 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 41 73 20 6f 66  option..** As of
216d0 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
216e0 33 2e 37 2e 37 2c 20 55 52 49 20 66 69 6c 65 6e  3.7.7, URI filen
216f0 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74 69  ame interpretati
21700 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 66 66  on is turned off
21710 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c 74 2c 20  .** by default, 
21720 62 75 74 20 66 75 74 75 72 65 20 72 65 6c 65 61  but future relea
21730 73 65 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69  ses of SQLite mi
21740 67 68 74 20 65 6e 61 62 6c 65 20 55 52 49 20 66  ght enable URI f
21750 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74 65 72  ilename.** inter
21760 70 72 65 74 61 74 69 6f 6e 20 62 79 20 64 65 66  pretation by def
21770 61 75 6c 74 2e 20 20 53 65 65 20 22 5b 55 52 49  ault.  See "[URI
21780 20 66 69 6c 65 6e 61 6d 65 73 5d 22 20 66 6f 72   filenames]" for
21790 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69   additional.** i
217a0 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
217b0 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20  * URI filenames 
217c0 61 72 65 20 70 61 72 73 65 64 20 61 63 63 6f 72  are parsed accor
217d0 64 69 6e 67 20 74 6f 20 52 46 43 20 33 39 38 36  ding to RFC 3986
217e0 2e 20 5e 49 66 20 74 68 65 20 55 52 49 20 63 6f  . ^If the URI co
217f0 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a 20 61 75 74  ntains an.** aut
21800 68 6f 72 69 74 79 2c 20 74 68 65 6e 20 69 74 20  hority, then it 
21810 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61  must be either a
21820 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f  n empty string o
21830 72 20 74 68 65 20 73 74 72 69 6e 67 20 0a 2a 2a  r the string .**
21840 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2e 20 5e 49   "localhost". ^I
21850 66 20 74 68 65 20 61 75 74 68 6f 72 69 74 79 20  f the authority 
21860 69 73 20 6e 6f 74 20 61 6e 20 65 6d 70 74 79 20  is not an empty 
21870 73 74 72 69 6e 67 20 6f 72 20 22 6c 6f 63 61 6c  string or "local
21880 68 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a 20 65 72  host", an .** er
21890 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 20  ror is returned 
218a0 74 6f 20 74 68 65 20 63 61 6c 6c 65 72 2e 20 5e  to the caller. ^
218b0 54 68 65 20 66 72 61 67 6d 65 6e 74 20 63 6f 6d  The fragment com
218c0 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 2c  ponent of a URI,
218d0 20 69 66 20 0a 2a 2a 20 70 72 65 73 65 6e 74 2c   if .** present,
218e0 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a   is ignored..**.
218f0 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20  ** ^SQLite uses 
21900 74 68 65 20 70 61 74 68 20 63 6f 6d 70 6f 6e 65  the path compone
21910 6e 74 20 6f 66 20 74 68 65 20 55 52 49 20 61 73  nt of the URI as
21920 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
21930 20 64 69 73 6b 20 66 69 6c 65 0a 2a 2a 20 77 68   disk file.** wh
21940 69 63 68 20 63 6f 6e 74 61 69 6e 73 20 74 68 65  ich contains the
21950 20 64 61 74 61 62 61 73 65 2e 20 5e 49 66 20 74   database. ^If t
21960 68 65 20 70 61 74 68 20 62 65 67 69 6e 73 20 77  he path begins w
21970 69 74 68 20 61 20 27 2f 27 20 63 68 61 72 61 63  ith a '/' charac
21980 74 65 72 2c 20 0a 2a 2a 20 74 68 65 6e 20 69 74  ter, .** then it
21990 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20   is interpreted 
219a0 61 73 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70  as an absolute p
219b0 61 74 68 2e 20 5e 49 66 20 74 68 65 20 70 61 74  ath. ^If the pat
219c0 68 20 64 6f 65 73 20 6e 6f 74 20 62 65 67 69 6e  h does not begin
219d0 20 0a 2a 2a 20 77 69 74 68 20 61 20 27 2f 27 20   .** with a '/' 
219e0 28 6d 65 61 6e 69 6e 67 20 74 68 61 74 20 74 68  (meaning that th
219f0 65 20 61 75 74 68 6f 72 69 74 79 20 73 65 63 74  e authority sect
21a00 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 20 66  ion is omitted f
21a10 72 6f 6d 20 74 68 65 20 55 52 49 29 0a 2a 2a 20  rom the URI).** 
21a20 74 68 65 6e 20 74 68 65 20 70 61 74 68 20 69 73  then the path is
21a30 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
21a40 61 20 72 65 6c 61 74 69 76 65 20 70 61 74 68 2e  a relative path.
21a50 20 0a 2a 2a 20 5e 4f 6e 20 77 69 6e 64 6f 77 73   .** ^On windows
21a60 2c 20 74 68 65 20 66 69 72 73 74 20 63 6f 6d 70  , the first comp
21a70 6f 6e 65 6e 74 20 6f 66 20 61 6e 20 61 62 73 6f  onent of an abso
21a80 6c 75 74 65 20 70 61 74 68 20 0a 2a 2a 20 69 73  lute path .** is
21a90 20 61 20 64 72 69 76 65 20 73 70 65 63 69 66 69   a drive specifi
21aa0 63 61 74 69 6f 6e 20 28 65 2e 67 2e 20 22 43 3a  cation (e.g. "C:
21ab0 22 29 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72 65  ")..**.** [[core
21ac0 20 55 52 49 20 71 75 65 72 79 20 70 61 72 61 6d   URI query param
21ad0 65 74 65 72 73 5d 5d 0a 2a 2a 20 54 68 65 20 71  eters]].** The q
21ae0 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f  uery component o
21af0 66 20 61 20 55 52 49 20 6d 61 79 20 63 6f 6e 74  f a URI may cont
21b00 61 69 6e 20 70 61 72 61 6d 65 74 65 72 73 20 74  ain parameters t
21b10 68 61 74 20 61 72 65 20 69 6e 74 65 72 70 72 65  hat are interpre
21b20 74 65 64 0a 2a 2a 20 65 69 74 68 65 72 20 62 79  ted.** either by
21b30 20 53 51 4c 69 74 65 20 69 74 73 65 6c 66 2c 20   SQLite itself, 
21b40 6f 72 20 62 79 20 61 20 5b 56 46 53 20 7c 20 63  or by a [VFS | c
21b50 75 73 74 6f 6d 20 56 46 53 20 69 6d 70 6c 65 6d  ustom VFS implem
21b60 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 53 51  entation]..** SQ
21b70 4c 69 74 65 20 69 6e 74 65 72 70 72 65 74 73 20  Lite interprets 
21b80 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68  the following th
21b90 72 65 65 20 71 75 65 72 79 20 70 61 72 61 6d 65  ree query parame
21ba0 74 65 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ters:.**.** <ul>
21bb0 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 76 66  .**   <li> <b>vf
21bc0 73 3c 2f 62 3e 3a 20 5e 54 68 65 20 22 76 66 73  s</b>: ^The "vfs
21bd0 22 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  " parameter may 
21be0 62 65 20 75 73 65 64 20 74 6f 20 73 70 65 63 69  be used to speci
21bf0 66 79 20 74 68 65 20 6e 61 6d 65 20 6f 66 0a 2a  fy the name of.*
21c00 2a 20 20 20 20 20 61 20 56 46 53 20 6f 62 6a 65  *     a VFS obje
21c10 63 74 20 74 68 61 74 20 70 72 6f 76 69 64 65 73  ct that provides
21c20 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73   the operating s
21c30 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20  ystem interface 
21c40 74 68 61 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 20  that should.**  
21c50 20 20 20 62 65 20 75 73 65 64 20 74 6f 20 61 63     be used to ac
21c60 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73  cess the databas
21c70 65 20 66 69 6c 65 20 6f 6e 20 64 69 73 6b 2e 20  e file on disk. 
21c80 5e 49 66 20 74 68 69 73 20 6f 70 74 69 6f 6e 20  ^If this option 
21c90 69 73 20 73 65 74 20 74 6f 0a 2a 2a 20 20 20 20  is set to.**    
21ca0 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
21cb0 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 53   the default VFS
21cc0 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e   object is used.
21cd0 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e 20   ^Specifying an 
21ce0 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20 20 20 20 56  unknown.**     V
21cf0 46 53 20 69 73 20 61 6e 20 65 72 72 6f 72 2e 20  FS is an error. 
21d00 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ^If sqlite3_open
21d10 5f 76 32 28 29 20 69 73 20 75 73 65 64 20 61 6e  _v2() is used an
21d20 64 20 74 68 65 20 76 66 73 20 6f 70 74 69 6f 6e  d the vfs option
21d30 20 69 73 0a 2a 2a 20 20 20 20 20 70 72 65 73 65   is.**     prese
21d40 6e 74 2c 20 74 68 65 6e 20 74 68 65 20 56 46 53  nt, then the VFS
21d50 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68   specified by th
21d60 65 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 70  e option takes p
21d70 72 65 63 65 64 65 6e 63 65 20 6f 76 65 72 0a 2a  recedence over.*
21d80 2a 20 20 20 20 20 74 68 65 20 76 61 6c 75 65 20  *     the value 
21d90 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66 6f  passed as the fo
21da0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
21db0 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
21dc0 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69  2()..**.**   <li
21dd0 3e 20 3c 62 3e 6d 6f 64 65 3c 2f 62 3e 3a 20 5e  > <b>mode</b>: ^
21de0 28 54 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65  (The mode parame
21df0 74 65 72 20 6d 61 79 20 62 65 20 73 65 74 20 74  ter may be set t
21e00 6f 20 65 69 74 68 65 72 20 22 72 6f 22 2c 20 22  o either "ro", "
21e10 72 77 22 2c 0a 2a 2a 20 20 20 20 20 22 72 77 63  rw",.**     "rwc
21e20 22 2c 20 6f 72 20 22 6d 65 6d 6f 72 79 22 2e 20  ", or "memory". 
21e30 41 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 73 65  Attempting to se
21e40 74 20 69 74 20 74 6f 20 61 6e 79 20 6f 74 68 65  t it to any othe
21e50 72 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 20 20  r value is.**   
21e60 20 20 61 6e 20 65 72 72 6f 72 29 5e 2e 20 0a 2a    an error)^. .*
21e70 2a 20 20 20 20 20 5e 49 66 20 22 72 6f 22 20 69  *     ^If "ro" i
21e80 73 20 73 70 65 63 69 66 69 65 64 2c 20 74 68 65  s specified, the
21e90 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  n the database i
21ea0 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61  s opened for rea
21eb0 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 20 20 20 61  d-only .**     a
21ec0 63 63 65 73 73 2c 20 6a 75 73 74 20 61 73 20 69  ccess, just as i
21ed0 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  f the [SQLITE_OP
21ee0 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20 66 6c 61  EN_READONLY] fla
21ef0 67 20 68 61 64 20 62 65 65 6e 20 73 65 74 20 69  g had been set i
21f00 6e 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 74 68  n the .**     th
21f10 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ird argument to 
21f20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
21f30 29 2e 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20  ). ^If the mode 
21f40 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f  option is set to
21f50 20 0a 2a 2a 20 20 20 20 20 22 72 77 22 2c 20 74   .**     "rw", t
21f60 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
21f70 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72   is opened for r
21f80 65 61 64 2d 77 72 69 74 65 20 28 62 75 74 20 6e  ead-write (but n
21f90 6f 74 20 63 72 65 61 74 65 29 20 0a 2a 2a 20 20  ot create) .**  
21fa0 20 20 20 61 63 63 65 73 73 2c 20 61 73 20 69 66     access, as if
21fb0 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41   SQLITE_OPEN_REA
21fc0 44 57 52 49 54 45 20 28 62 75 74 20 6e 6f 74 20  DWRITE (but not 
21fd0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
21fe0 54 45 29 20 68 61 64 20 0a 2a 2a 20 20 20 20 20  TE) had .**     
21ff0 62 65 65 6e 20 73 65 74 2e 20 5e 56 61 6c 75 65  been set. ^Value
22000 20 22 72 77 63 22 20 69 73 20 65 71 75 69 76 61   "rwc" is equiva
22010 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20  lent to setting 
22020 62 6f 74 68 20 0a 2a 2a 20 20 20 20 20 53 51 4c  both .**     SQL
22030 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
22040 54 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 4f 50  TE and SQLITE_OP
22050 45 4e 5f 43 52 45 41 54 45 2e 20 20 5e 49 66 20  EN_CREATE.  ^If 
22060 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20  the mode option 
22070 69 73 0a 2a 2a 20 20 20 20 20 73 65 74 20 74 6f  is.**     set to
22080 20 22 6d 65 6d 6f 72 79 22 20 74 68 65 6e 20 61   "memory" then a
22090 20 70 75 72 65 20 5b 69 6e 2d 6d 65 6d 6f 72 79   pure [in-memory
220a0 20 64 61 74 61 62 61 73 65 5d 20 74 68 61 74 20   database] that 
220b0 6e 65 76 65 72 20 72 65 61 64 73 0a 2a 2a 20 20  never reads.**  
220c0 20 20 20 6f 72 20 77 72 69 74 65 73 20 66 72 6f     or writes fro
220d0 6d 20 64 69 73 6b 20 69 73 20 75 73 65 64 2e 20  m disk is used. 
220e0 5e 49 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20  ^It is an error 
220f0 74 6f 20 73 70 65 63 69 66 79 20 61 20 76 61 6c  to specify a val
22100 75 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 74 68  ue for.**     th
22110 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72  e mode parameter
22120 20 74 68 61 74 20 69 73 20 6c 65 73 73 20 72 65   that is less re
22130 73 74 72 69 63 74 69 76 65 20 74 68 61 6e 20 74  strictive than t
22140 68 61 74 20 73 70 65 63 69 66 69 65 64 20 62 79  hat specified by
22150 0a 2a 2a 20 20 20 20 20 74 68 65 20 66 6c 61 67  .**     the flag
22160 73 20 70 61 73 73 65 64 20 69 6e 20 74 68 65 20  s passed in the 
22170 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
22180 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
22190 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c  v2()..**.**   <l
221a0 69 3e 20 3c 62 3e 63 61 63 68 65 3c 2f 62 3e 3a  i> <b>cache</b>:
221b0 20 5e 54 68 65 20 63 61 63 68 65 20 70 61 72 61   ^The cache para
221c0 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73 65 74  meter may be set
221d0 20 74 6f 20 65 69 74 68 65 72 20 22 73 68 61 72   to either "shar
221e0 65 64 22 20 6f 72 0a 2a 2a 20 20 20 20 20 22 70  ed" or.**     "p
221f0 72 69 76 61 74 65 22 2e 20 5e 53 65 74 74 69 6e  rivate". ^Settin
22200 67 20 69 74 20 74 6f 20 22 73 68 61 72 65 64 22  g it to "shared"
22210 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74   is equivalent t
22220 6f 20 73 65 74 74 69 6e 67 20 74 68 65 0a 2a 2a  o setting the.**
22230 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e       SQLITE_OPEN
22240 5f 53 48 41 52 45 44 43 41 43 48 45 20 62 69 74  _SHAREDCACHE bit
22250 20 69 6e 20 74 68 65 20 66 6c 61 67 73 20 61 72   in the flags ar
22260 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 74 6f  gument passed to
22270 0a 2a 2a 20 20 20 20 20 73 71 6c 69 74 65 33 5f  .**     sqlite3_
22280 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 53 65 74 74  open_v2(). ^Sett
22290 69 6e 67 20 74 68 65 20 63 61 63 68 65 20 70 61  ing the cache pa
222a0 72 61 6d 65 74 65 72 20 74 6f 20 22 70 72 69 76  rameter to "priv
222b0 61 74 65 22 20 69 73 20 0a 2a 2a 20 20 20 20 20  ate" is .**     
222c0 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65  equivalent to se
222d0 74 74 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45  tting the SQLITE
222e0 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43  _OPEN_PRIVATECAC
222f0 48 45 20 62 69 74 2e 0a 2a 2a 20 20 20 20 20 5e  HE bit..**     ^
22300 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  If sqlite3_open_
22310 76 32 28 29 20 69 73 20 75 73 65 64 20 61 6e 64  v2() is used and
22320 20 74 68 65 20 22 63 61 63 68 65 22 20 70 61 72   the "cache" par
22330 61 6d 65 74 65 72 20 69 73 20 70 72 65 73 65 6e  ameter is presen
22340 74 20 69 6e 0a 2a 2a 20 20 20 20 20 61 20 55 52  t in.**     a UR
22350 49 20 66 69 6c 65 6e 61 6d 65 2c 20 69 74 73 20  I filename, its 
22360 76 61 6c 75 65 20 6f 76 65 72 72 69 64 65 73 20  value overrides 
22370 61 6e 79 20 62 65 68 61 76 69 6f 72 20 72 65 71  any behavior req
22380 75 65 73 74 65 64 20 62 79 20 73 65 74 74 69 6e  uested by settin
22390 67 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f  g.**     SQLITE_
223a0 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48  OPEN_PRIVATECACH
223b0 45 20 6f 72 20 53 51 4c 49 54 45 5f 4f 50 45 4e  E or SQLITE_OPEN
223c0 5f 53 48 41 52 45 44 43 41 43 48 45 20 66 6c 61  _SHAREDCACHE fla
223d0 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  g..** </ul>.**.*
223e0 2a 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e  * ^Specifying an
223f0 20 75 6e 6b 6e 6f 77 6e 20 70 61 72 61 6d 65 74   unknown paramet
22400 65 72 20 69 6e 20 74 68 65 20 71 75 65 72 79 20  er in the query 
22410 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55  component of a U
22420 52 49 20 69 73 20 6e 6f 74 20 61 6e 0a 2a 2a 20  RI is not an.** 
22430 65 72 72 6f 72 2e 20 20 46 75 74 75 72 65 20 76  error.  Future v
22440 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
22450 65 20 6d 69 67 68 74 20 75 6e 64 65 72 73 74 61  e might understa
22460 6e 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 71 75  nd additional qu
22470 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ery.** parameter
22480 73 2e 20 20 53 65 65 20 22 5b 71 75 65 72 79 20  s.  See "[query 
22490 70 61 72 61 6d 65 74 65 72 73 20 77 69 74 68 20  parameters with 
224a0 73 70 65 63 69 61 6c 20 6d 65 61 6e 69 6e 67 20  special meaning 
224b0 74 6f 20 53 51 4c 69 74 65 5d 22 20 66 6f 72 0a  to SQLite]" for.
224c0 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  ** additional in
224d0 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
224e0 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 20   [[URI filename 
224f0 65 78 61 6d 70 6c 65 73 5d 5d 20 3c 68 33 3e 55  examples]] <h3>U
22500 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d  RI filename exam
22510 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20  ples</h3>.**.** 
22520 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31  <table border="1
22530 22 20 61 6c 69 67 6e 3d 63 65 6e 74 65 72 20 63  " align=center c
22540 65 6c 6c 70 61 64 64 69 6e 67 3d 35 3e 0a 2a 2a  ellpadding=5>.**
22550 20 3c 74 72 3e 3c 74 68 3e 20 55 52 49 20 66 69   <tr><th> URI fi
22560 6c 65 6e 61 6d 65 73 20 3c 74 68 3e 20 52 65 73  lenames <th> Res
22570 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  ults.** <tr><td>
22580 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 20 3c 74   file:data.db <t
22590 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  d> .**          
225a0 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22 64  Open the file "d
225b0 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63  ata.db" in the c
225c0 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79  urrent directory
225d0 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  ..** <tr><td> fi
225e0 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61  le:/home/fred/da
225f0 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a 20 20 20 20  ta.db<br>.**    
22600 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 68 6f        file:///ho
22610 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20  me/fred/data.db 
22620 3c 62 72 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  <br> .**        
22630 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63 61 6c 68 6f    file://localho
22640 73 74 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74  st/home/fred/dat
22650 61 2e 64 62 20 3c 62 72 3e 20 3c 74 64 3e 20 0a  a.db <br> <td> .
22660 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e  **          Open
22670 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
22680 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  le "/home/fred/d
22690 61 74 61 2e 64 62 22 2e 0a 2a 2a 20 3c 74 72 3e  ata.db"..** <tr>
226a0 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f 64 61 72 6b  <td> file://dark
226b0 73 74 61 72 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  star/home/fred/d
226c0 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20  ata.db <td> .** 
226d0 20 20 20 20 20 20 20 20 20 41 6e 20 65 72 72 6f           An erro
226e0 72 2e 20 22 64 61 72 6b 73 74 61 72 22 20 69 73  r. "darkstar" is
226f0 20 6e 6f 74 20 61 20 72 65 63 6f 67 6e 69 7a 65   not a recognize
22700 64 20 61 75 74 68 6f 72 69 74 79 2e 0a 2a 2a 20  d authority..** 
22710 3c 74 72 3e 3c 74 64 20 73 74 79 6c 65 3d 22 77  <tr><td style="w
22720 68 69 74 65 2d 73 70 61 63 65 3a 6e 6f 77 72 61  hite-space:nowra
22730 70 22 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  p"> .**         
22740 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f 63 75   file:///C:/Docu
22750 6d 65 6e 74 73 25 32 30 61 6e 64 25 32 30 53 65  ments%20and%20Se
22760 74 74 69 6e 67 73 2f 66 72 65 64 2f 44 65 73 6b  ttings/fred/Desk
22770 74 6f 70 2f 64 61 74 61 2e 64 62 0a 2a 2a 20 20  top/data.db.**  
22780 20 20 20 3c 74 64 3e 20 57 69 6e 64 6f 77 73 20     <td> Windows 
22790 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74 68 65 20 66  only: Open the f
227a0 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 6f 6e  ile "data.db" on
227b0 20 66 72 65 64 27 73 20 64 65 73 6b 74 6f 70 20   fred's desktop 
227c0 6f 6e 20 64 72 69 76 65 0a 2a 2a 20 20 20 20 20  on drive.**     
227d0 20 20 20 20 20 43 3a 2e 20 4e 6f 74 65 20 74 68       C:. Note th
227e0 61 74 20 74 68 65 20 25 32 30 20 65 73 63 61 70  at the %20 escap
227f0 69 6e 67 20 69 6e 20 74 68 69 73 20 65 78 61 6d  ing in this exam
22800 70 6c 65 20 69 73 20 6e 6f 74 20 73 74 72 69 63  ple is not stric
22810 74 6c 79 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  tly .**         
22820 20 6e 65 63 65 73 73 61 72 79 20 2d 20 73 70 61   necessary - spa
22830 63 65 20 63 68 61 72 61 63 74 65 72 73 20 63 61  ce characters ca
22840 6e 20 62 65 20 75 73 65 64 20 6c 69 74 65 72 61  n be used litera
22850 6c 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  lly.**          
22860 69 6e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73  in URI filenames
22870 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  ..** <tr><td> fi
22880 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d  le:data.db?mode=
22890 72 6f 26 63 61 63 68 65 3d 70 72 69 76 61 74 65  ro&cache=private
228a0 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20   <td> .**       
228b0 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 64 61     Open file "da
228c0 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63 75  ta.db" in the cu
228d0 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79 20  rrent directory 
228e0 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 61 63  for read-only ac
228f0 63 65 73 73 2e 0a 2a 2a 20 20 20 20 20 20 20 20  cess..**        
22900 20 20 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20    Regardless of 
22910 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73  whether or not s
22920 68 61 72 65 64 2d 63 61 63 68 65 20 6d 6f 64 65  hared-cache mode
22930 20 69 73 20 65 6e 61 62 6c 65 64 20 62 79 0a 2a   is enabled by.*
22940 2a 20 20 20 20 20 20 20 20 20 20 64 65 66 61 75  *          defau
22950 6c 74 2c 20 75 73 65 20 61 20 70 72 69 76 61 74  lt, use a privat
22960 65 20 63 61 63 68 65 2e 0a 2a 2a 20 3c 74 72 3e  e cache..** <tr>
22970 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f  <td> file:/home/
22980 66 72 65 64 2f 64 61 74 61 2e 64 62 3f 76 66 73  fred/data.db?vfs
22990 3d 75 6e 69 78 2d 6e 6f 6c 6f 63 6b 20 3c 74 64  =unix-nolock <td
229a0 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70  >.**          Op
229b0 65 6e 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66  en file "/home/f
229c0 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 20 55 73  red/data.db". Us
229d0 65 20 74 68 65 20 73 70 65 63 69 61 6c 20 56 46  e the special VF
229e0 53 20 22 75 6e 69 78 2d 6e 6f 6c 6f 63 6b 22 2e  S "unix-nolock".
229f0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c  .** <tr><td> fil
22a00 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72  e:data.db?mode=r
22a10 65 61 64 6f 6e 6c 79 20 3c 74 64 3e 20 0a 2a 2a  eadonly <td> .**
22a20 20 20 20 20 20 20 20 20 20 20 41 6e 20 65 72 72            An err
22a30 6f 72 2e 20 22 72 65 61 64 6f 6e 6c 79 22 20 69  or. "readonly" i
22a40 73 20 6e 6f 74 20 61 20 76 61 6c 69 64 20 6f 70  s not a valid op
22a50 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 22 6d 6f  tion for the "mo
22a60 64 65 22 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  de" parameter..*
22a70 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a  * </table>.**.**
22a80 20 5e 55 52 49 20 68 65 78 61 64 65 63 69 6d 61   ^URI hexadecima
22a90 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e 63  l escape sequenc
22aa0 65 73 20 28 25 48 48 29 20 61 72 65 20 73 75 70  es (%HH) are sup
22ab0 70 6f 72 74 65 64 20 77 69 74 68 69 6e 20 74 68  ported within th
22ac0 65 20 70 61 74 68 20 61 6e 64 0a 2a 2a 20 71 75  e path and.** qu
22ad0 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f  ery components o
22ae0 66 20 61 20 55 52 49 2e 20 41 20 68 65 78 61 64  f a URI. A hexad
22af0 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65  ecimal escape se
22b00 71 75 65 6e 63 65 20 63 6f 6e 73 69 73 74 73 20  quence consists 
22b10 6f 66 20 61 0a 2a 2a 20 70 65 72 63 65 6e 74 20  of a.** percent 
22b20 73 69 67 6e 20 2d 20 22 25 22 20 2d 20 66 6f 6c  sign - "%" - fol
22b30 6c 6f 77 65 64 20 62 79 20 65 78 61 63 74 6c 79  lowed by exactly
22b40 20 74 77 6f 20 68 65 78 61 64 65 63 69 6d 61 6c   two hexadecimal
22b50 20 64 69 67 69 74 73 20 0a 2a 2a 20 73 70 65 63   digits .** spec
22b60 69 66 79 69 6e 67 20 61 6e 20 6f 63 74 65 74 20  ifying an octet 
22b70 76 61 6c 75 65 2e 20 5e 42 65 66 6f 72 65 20 74  value. ^Before t
22b80 68 65 20 70 61 74 68 20 6f 72 20 71 75 65 72 79  he path or query
22b90 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61   components of a
22ba0 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65  .** URI filename
22bb0 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64   are interpreted
22bc0 2c 20 74 68 65 79 20 61 72 65 20 65 6e 63 6f 64  , they are encod
22bd0 65 64 20 75 73 69 6e 67 20 55 54 46 2d 38 20 61  ed using UTF-8 a
22be0 6e 64 20 61 6c 6c 20 0a 2a 2a 20 68 65 78 61 64  nd all .** hexad
22bf0 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65  ecimal escape se
22c00 71 75 65 6e 63 65 73 20 72 65 70 6c 61 63 65 64  quences replaced
22c10 20 62 79 20 61 20 73 69 6e 67 6c 65 20 62 79 74   by a single byt
22c20 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  e containing the
22c30 0a 2a 2a 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  .** correspondin
22c40 67 20 6f 63 74 65 74 2e 20 49 66 20 74 68 69 73  g octet. If this
22c50 20 70 72 6f 63 65 73 73 20 67 65 6e 65 72 61 74   process generat
22c60 65 73 20 61 6e 20 69 6e 76 61 6c 69 64 20 55 54  es an invalid UT
22c70 46 2d 38 20 65 6e 63 6f 64 69 6e 67 2c 0a 2a 2a  F-8 encoding,.**
22c80 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
22c90 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
22ca0 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e  * <b>Note to Win
22cb0 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20  dows users:</b> 
22cc0 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 20 75 73   The encoding us
22cd0 65 64 20 66 6f 72 20 74 68 65 20 66 69 6c 65 6e  ed for the filen
22ce0 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  ame argument.** 
22cf0 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  of sqlite3_open(
22d00 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70  ) and sqlite3_op
22d10 65 6e 5f 76 32 28 29 20 6d 75 73 74 20 62 65 20  en_v2() must be 
22d20 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65  UTF-8, not whate
22d30 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20  ver.** codepage 
22d40 69 73 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66  is currently def
22d50 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73  ined.  Filenames
22d60 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65   containing inte
22d70 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61  rnational.** cha
22d80 72 61 63 74 65 72 73 20 6d 75 73 74 20 62 65 20  racters must be 
22d90 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 55 54 46  converted to UTF
22da0 2d 38 20 70 72 69 6f 72 20 74 6f 20 70 61 73 73  -8 prior to pass
22db0 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a  ing them into.**
22dc0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
22dd0 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
22de0 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e  v2()..**.** <b>N
22df0 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 52  ote to Windows R
22e00 75 6e 74 69 6d 65 20 75 73 65 72 73 3a 3c 2f 62  untime users:</b
22e10 3e 20 20 54 68 65 20 74 65 6d 70 6f 72 61 72 79  >  The temporary
22e20 20 64 69 72 65 63 74 6f 72 79 20 6d 75 73 74 20   directory must 
22e30 62 65 20 73 65 74 0a 2a 2a 20 70 72 69 6f 72 20  be set.** prior 
22e40 74 6f 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74  to calling sqlit
22e50 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c  e3_open() or sql
22e60 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20  ite3_open_v2(). 
22e70 20 4f 74 68 65 72 77 69 73 65 2c 20 76 61 72 69   Otherwise, vari
22e80 6f 75 73 0a 2a 2a 20 66 65 61 74 75 72 65 73 20  ous.** features 
22e90 74 68 61 74 20 72 65 71 75 69 72 65 20 74 68 65  that require the
22ea0 20 75 73 65 20 6f 66 20 74 65 6d 70 6f 72 61 72   use of temporar
22eb0 79 20 66 69 6c 65 73 20 6d 61 79 20 66 61 69 6c  y files may fail
22ec0 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
22ed0 3a 20 5b 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f  : [sqlite3_temp_
22ee0 64 69 72 65 63 74 6f 72 79 5d 0a 2a 2f 0a 53 51  directory].*/.SQ
22ef0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
22f00 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e  ite3_open(.  con
22f10 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d  st char *filenam
22f20 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  e,   /* Database
22f30 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38   filename (UTF-8
22f40 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a  ) */.  sqlite3 *
22f50 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f  *ppDb          /
22f60 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62  * OUT: SQLite db
22f70 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 53 51   handle */.);.SQ
22f80 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
22f90 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63  ite3_open16(.  c
22fa0 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e  onst void *filen
22fb0 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61  ame,   /* Databa
22fc0 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46  se filename (UTF
22fd0 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65  -16) */.  sqlite
22fe0 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20  3 **ppDb        
22ff0 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65    /* OUT: SQLite
23000 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b   db handle */.);
23010 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
23020 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
23030 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66  .  const char *f
23040 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61  ilename,   /* Da
23050 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
23060 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c  (UTF-8) */.  sql
23070 69 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 20 20  ite3 **ppDb,    
23080 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c       /* OUT: SQL
23090 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f  ite db handle */
230a0 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 20 20  .  int flags,   
230b0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 6c             /* Fl
230c0 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ags */.  const c
230d0 68 61 72 20 2a 7a 56 66 73 20 20 20 20 20 20 20  har *zVfs       
230e0 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53 20   /* Name of VFS 
230f0 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f  module to use */
23100 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
23110 52 45 46 3a 20 4f 62 74 61 69 6e 20 56 61 6c 75  REF: Obtain Valu
23120 65 73 20 46 6f 72 20 55 52 49 20 50 61 72 61 6d  es For URI Param
23130 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  eters.**.** Thes
23140 65 20 61 72 65 20 75 74 69 6c 69 74 79 20 72 6f  e are utility ro
23150 75 74 69 6e 65 73 2c 20 75 73 65 66 75 6c 20 74  utines, useful t
23160 6f 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  o VFS implementa
23170 74 69 6f 6e 73 2c 20 74 68 61 74 20 63 68 65 63  tions, that chec
23180 6b 0a 2a 2a 20 74 6f 20 73 65 65 20 69 66 20 61  k.** to see if a
23190 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77   database file w
231a0 61 73 20 61 20 55 52 49 20 74 68 61 74 20 63 6f  as a URI that co
231b0 6e 74 61 69 6e 65 64 20 61 20 73 70 65 63 69 66  ntained a specif
231c0 69 63 20 71 75 65 72 79 20 0a 2a 2a 20 70 61 72  ic query .** par
231d0 61 6d 65 74 65 72 2c 20 61 6e 64 20 69 66 20 73  ameter, and if s
231e0 6f 20 6f 62 74 61 69 6e 73 20 74 68 65 20 76 61  o obtains the va
231f0 6c 75 65 20 6f 66 20 74 68 61 74 20 71 75 65 72  lue of that quer
23200 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  y parameter..**.
23210 2a 2a 20 49 66 20 46 20 69 73 20 74 68 65 20 64  ** If F is the d
23220 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
23230 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64 20   pointer passed 
23240 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29  into the xOpen()
23250 20 6d 65 74 68 6f 64 20 6f 66 20 0a 2a 2a 20 61   method of .** a
23260 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
23270 69 6f 6e 20 77 68 65 6e 20 74 68 65 20 66 6c 61  ion when the fla
23280 67 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  gs parameter to 
23290 78 4f 70 65 6e 28 29 20 68 61 73 20 6f 6e 65 20  xOpen() has one 
232a0 6f 72 20 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20 74  or .** more of t
232b0 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
232c0 55 52 49 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  URI] or [SQLITE_
232d0 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 20 62 69  OPEN_MAIN_DB] bi
232e0 74 73 20 73 65 74 20 61 6e 64 0a 2a 2a 20 50 20  ts set and.** P 
232f0 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
23300 68 65 20 71 75 65 72 79 20 70 61 72 61 6d 65 74  he query paramet
23310 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69  er, then.** sqli
23320 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65  te3_uri_paramete
23330 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20 74  r(F,P) returns t
23340 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  he value of the 
23350 50 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69  P.** parameter i
23360 66 20 69 74 20 65 78 69 73 74 73 20 6f 72 20 61  f it exists or a
23370 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66   NULL pointer if
23380 20 50 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 65   P does not appe
23390 61 72 20 61 73 20 61 20 0a 2a 2a 20 71 75 65 72  ar as a .** quer
233a0 79 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46  y parameter on F
233b0 2e 20 20 49 66 20 50 20 69 73 20 61 20 71 75 65  .  If P is a que
233c0 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  ry parameter of 
233d0 46 0a 2a 2a 20 68 61 73 20 6e 6f 20 65 78 70 6c  F.** has no expl
233e0 69 63 69 74 20 76 61 6c 75 65 2c 20 74 68 65 6e  icit value, then
233f0 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72   sqlite3_uri_par
23400 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75  ameter(F,P) retu
23410 72 6e 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72  rns.** a pointer
23420 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74 72   to an empty str
23430 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ing..**.** The s
23440 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65  qlite3_uri_boole
23450 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e  an(F,P,B) routin
23460 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 50  e assumes that P
23470 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 0a 2a 2a   is a boolean.**
23480 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72   parameter and r
23490 65 74 75 72 6e 73 20 74 72 75 65 20 28 31 29 20  eturns true (1) 
234a0 6f 72 20 66 61 6c 73 65 20 28 30 29 20 61 63 63  or false (0) acc
234b0 6f 72 64 69 6e 67 20 74 6f 20 74 68 65 20 76 61  ording to the va
234c0 6c 75 65 0a 2a 2a 20 6f 66 20 50 2e 20 20 54 68  lue.** of P.  Th
234d0 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f  e sqlite3_uri_bo
234e0 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75  olean(F,P,B) rou
234f0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 72 75  tine returns tru
23500 65 20 28 31 29 20 69 66 20 74 68 65 0a 2a 2a 20  e (1) if the.** 
23510 76 61 6c 75 65 20 6f 66 20 71 75 65 72 79 20 70  value of query p
23520 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f 6e  arameter P is on
23530 65 20 6f 66 20 22 79 65 73 22 2c 20 22 74 72 75  e of "yes", "tru
23540 65 22 2c 20 6f 72 20 22 6f 6e 22 20 69 6e 20 61  e", or "on" in a
23550 6e 79 0a 2a 2a 20 63 61 73 65 20 6f 72 20 69 66  ny.** case or if
23560 20 74 68 65 20 76 61 6c 75 65 20 62 65 67 69 6e   the value begin
23570 73 20 77 69 74 68 20 61 20 6e 6f 6e 2d 7a 65 72  s with a non-zer
23580 6f 20 6e 75 6d 62 65 72 2e 20 20 54 68 65 20 0a  o number.  The .
23590 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  ** sqlite3_uri_b
235a0 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f  oolean(F,P,B) ro
235b0 75 74 69 6e 65 73 20 72 65 74 75 72 6e 73 20 66  utines returns f
235c0 61 6c 73 65 20 28 30 29 20 69 66 20 74 68 65 20  alse (0) if the 
235d0 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 71 75 65 72  value of.** quer
235e0 79 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 73  y parameter P is
235f0 20 6f 6e 65 20 6f 66 20 22 6e 6f 22 2c 20 22 66   one of "no", "f
23600 61 6c 73 65 22 2c 20 6f 72 20 22 6f 66 66 22 20  alse", or "off" 
23610 69 6e 20 61 6e 79 20 63 61 73 65 20 6f 72 0a 2a  in any case or.*
23620 2a 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 62  * if the value b
23630 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e 75 6d  egins with a num
23640 65 72 69 63 20 7a 65 72 6f 2e 20 20 49 66 20 50  eric zero.  If P
23650 20 69 73 20 6e 6f 74 20 61 20 71 75 65 72 79 0a   is not a query.
23660 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20  ** parameter on 
23670 46 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c 75  F or if the valu
23680 65 20 6f 66 20 50 20 69 73 20 64 6f 65 73 20 6e  e of P is does n
23690 6f 74 20 6d 61 74 63 68 20 61 6e 79 20 6f 66 20  ot match any of 
236a0 74 68 65 0a 2a 2a 20 61 62 6f 76 65 2c 20 74 68  the.** above, th
236b0 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  en sqlite3_uri_b
236c0 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 65  oolean(F,P,B) re
236d0 74 75 72 6e 73 20 28 42 21 3d 30 29 2e 0a 2a 2a  turns (B!=0)..**
236e0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
236f0 75 72 69 5f 69 6e 74 36 34 28 46 2c 50 2c 44 29  uri_int64(F,P,D)
23700 20 72 6f 75 74 69 6e 65 20 63 6f 6e 76 65 72 74   routine convert
23710 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50  s the value of P
23720 20 69 6e 74 6f 20 61 0a 2a 2a 20 36 34 2d 62 69   into a.** 64-bi
23730 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
23740 20 61 6e 64 20 72 65 74 75 72 6e 73 20 74 68 61   and returns tha
23750 74 20 69 6e 74 65 67 65 72 2c 20 6f 72 20 44 20  t integer, or D 
23760 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a  if P does not.**
23770 20 65 78 69 73 74 2e 20 20 49 66 20 74 68 65 20   exist.  If the 
23780 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20 73 6f  value of P is so
23790 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68  mething other th
237a0 61 6e 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74  an an integer, t
237b0 68 65 6e 0a 2a 2a 20 7a 65 72 6f 20 69 73 20 72  hen.** zero is r
237c0 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a 20  eturned..** .** 
237d0 49 66 20 46 20 69 73 20 61 20 4e 55 4c 4c 20 70  If F is a NULL p
237e0 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 73 71 6c  ointer, then sql
237f0 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74  ite3_uri_paramet
23800 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20  er(F,P) returns 
23810 4e 55 4c 4c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69  NULL and.** sqli
23820 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28  te3_uri_boolean(
23830 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20 42  F,P,B) returns B
23840 2e 20 20 49 66 20 46 20 69 73 20 6e 6f 74 20 61  .  If F is not a
23850 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e   NULL pointer an
23860 64 0a 2a 2a 20 69 73 20 6e 6f 74 20 61 20 64 61  d.** is not a da
23870 74 61 62 61 73 65 20 66 69 6c 65 20 70 61 74 68  tabase file path
23880 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 74 68 61  name pointer tha
23890 74 20 53 51 4c 69 74 65 20 70 61 73 73 65 64 20  t SQLite passed 
238a0 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 0a 2a  into the xOpen.*
238b0 2a 20 56 46 53 20 6d 65 74 68 6f 64 2c 20 74 68  * VFS method, th
238c0 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
238d0 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  of this routine 
238e0 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64  is undefined and
238f0 20 70 72 6f 62 61 62 6c 79 0a 2a 2a 20 75 6e 64   probably.** und
23900 65 73 69 72 61 62 6c 65 2e 0a 2a 2f 0a 53 51 4c  esirable..*/.SQL
23910 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68  ITE_API const ch
23920 61 72 20 2a 73 71 6c 69 74 65 33 5f 75 72 69 5f  ar *sqlite3_uri_
23930 70 61 72 61 6d 65 74 65 72 28 63 6f 6e 73 74 20  parameter(const 
23940 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 2c  char *zFilename,
23950 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61   const char *zPa
23960 72 61 6d 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ram);.SQLITE_API
23970 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 75 72 69   int sqlite3_uri
23980 5f 62 6f 6f 6c 65 61 6e 28 63 6f 6e 73 74 20 63  _boolean(const c
23990 68 61 72 20 2a 7a 46 69 6c 65 2c 20 63 6f 6e 73  har *zFile, cons
239a0 74 20 63 68 61 72 20 2a 7a 50 61 72 61 6d 2c 20  t char *zParam, 
239b0 69 6e 74 20 62 44 65 66 61 75 6c 74 29 3b 0a 53  int bDefault);.S
239c0 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65  QLITE_API sqlite
239d0 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
239e0 75 72 69 5f 69 6e 74 36 34 28 63 6f 6e 73 74 20  uri_int64(const 
239f0 63 68 61 72 2a 2c 20 63 6f 6e 73 74 20 63 68 61  char*, const cha
23a00 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  r*, sqlite3_int6
23a10 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  4);.../*.** CAPI
23a20 33 52 45 46 3a 20 45 72 72 6f 72 20 43 6f 64 65  3REF: Error Code
23a30 73 20 41 6e 64 20 4d 65 73 73 61 67 65 73 0a 2a  s And Messages.*
23a40 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
23a50 33 5f 65 72 72 63 6f 64 65 28 29 20 69 6e 74 65  3_errcode() inte
23a60 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
23a70 65 20 6e 75 6d 65 72 69 63 20 5b 72 65 73 75 6c  e numeric [resul
23a80 74 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65  t code] or.** [e
23a90 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
23aa0 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f 73  ode] for the mos
23ab0 74 20 72 65 63 65 6e 74 20 66 61 69 6c 65 64 20  t recent failed 
23ac0 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61  sqlite3_* API ca
23ad0 6c 6c 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64  ll.** associated
23ae0 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 61 73   with a [databas
23af0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 49  e connection]. I
23b00 66 20 61 20 70 72 69 6f 72 20 41 50 49 20 63 61  f a prior API ca
23b10 6c 6c 20 66 61 69 6c 65 64 0a 2a 2a 20 62 75 74  ll failed.** but
23b20 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
23b30 20 41 50 49 20 63 61 6c 6c 20 73 75 63 63 65 65   API call succee
23b40 64 65 64 2c 20 74 68 65 20 72 65 74 75 72 6e 20  ded, the return 
23b50 76 61 6c 75 65 20 66 72 6f 6d 0a 2a 2a 20 73 71  value from.** sq
23b60 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20  lite3_errcode() 
23b70 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 5e  is undefined.  ^
23b80 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65  The sqlite3_exte
23b90 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a  nded_errcode().*
23ba0 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74  * interface is t
23bb0 68 65 20 73 61 6d 65 20 65 78 63 65 70 74 20 74  he same except t
23bc0 68 61 74 20 69 74 20 61 6c 77 61 79 73 20 72 65  hat it always re
23bd0 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65  turns the .** [e
23be0 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
23bf0 6f 64 65 5d 20 65 76 65 6e 20 77 68 65 6e 20 65  ode] even when e
23c00 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
23c10 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64 69 73 61  odes are.** disa
23c20 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  bled..**.** ^The
23c30 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28   sqlite3_errmsg(
23c40 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 72  ) and sqlite3_er
23c50 72 6d 73 67 31 36 28 29 20 72 65 74 75 72 6e 20  rmsg16() return 
23c60 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65  English-language
23c70 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20 64 65  .** text that de
23c80 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f  scribes the erro
23c90 72 2c 20 61 73 20 65 69 74 68 65 72 20 55 54 46  r, as either UTF
23ca0 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72 65 73  -8 or UTF-16 res
23cb0 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28  pectively..** ^(
23cc0 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74  Memory to hold t
23cd0 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
23ce0 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67   string is manag
23cf0 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a  ed internally..*
23d00 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
23d10 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  n does not need 
23d20 74 6f 20 77 6f 72 72 79 20 61 62 6f 75 74 20 66  to worry about f
23d30 72 65 65 69 6e 67 20 74 68 65 20 72 65 73 75 6c  reeing the resul
23d40 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74  t..** However, t
23d50 68 65 20 65 72 72 6f 72 20 73 74 72 69 6e 67 20  he error string 
23d60 6d 69 67 68 74 20 62 65 20 6f 76 65 72 77 72 69  might be overwri
23d70 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61  tten or dealloca
23d80 74 65 64 20 62 79 0a 2a 2a 20 73 75 62 73 65 71  ted by.** subseq
23d90 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74  uent calls to ot
23da0 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72  her SQLite inter
23db0 66 61 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e 29  face functions.)
23dc0 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ^.**.** ^The sql
23dd0 69 74 65 33 5f 65 72 72 73 74 72 28 29 20 69 6e  ite3_errstr() in
23de0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
23df0 74 68 65 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67  the English-lang
23e00 75 61 67 65 20 74 65 78 74 0a 2a 2a 20 74 68 61  uage text.** tha
23e10 74 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20  t describes the 
23e20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 2c 20 61  [result code], a
23e30 73 20 55 54 46 2d 38 2e 0a 2a 2a 20 5e 28 4d 65  s UTF-8..** ^(Me
23e40 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65  mory to hold the
23e50 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73   error message s
23e60 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64  tring is managed
23e70 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 61   internally.** a
23e80 6e 64 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 66  nd must not be f
23e90 72 65 65 64 20 62 79 20 74 68 65 20 61 70 70 6c  reed by the appl
23ea0 69 63 61 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a 2a 2a  ication)^..**.**
23eb0 20 57 68 65 6e 20 74 68 65 20 73 65 72 69 61 6c   When the serial
23ec0 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20  ized [threading 
23ed0 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75 73 65 2c  mode] is in use,
23ee0 20 69 74 20 6d 69 67 68 74 20 62 65 20 74 68 65   it might be the
23ef0 0a 2a 2a 20 63 61 73 65 20 74 68 61 74 20 61 20  .** case that a 
23f00 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63 63  second error occ
23f10 75 72 73 20 6f 6e 20 61 20 73 65 70 61 72 61 74  urs on a separat
23f20 65 20 74 68 72 65 61 64 20 69 6e 20 62 65 74 77  e thread in betw
23f30 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65 20  een.** the time 
23f40 6f 66 20 74 68 65 20 66 69 72 73 74 20 65 72 72  of the first err
23f50 6f 72 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 20  or and the call 
23f60 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 61  to these interfa
23f70 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 61  ces..** When tha
23f80 74 20 68 61 70 70 65 6e 73 2c 20 74 68 65 20 73  t happens, the s
23f90 65 63 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c 6c  econd error will
23fa0 20 62 65 20 72 65 70 6f 72 74 65 64 20 73 69 6e   be reported sin
23fb0 63 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74 65  ce these.** inte
23fc0 72 66 61 63 65 73 20 61 6c 77 61 79 73 20 72 65  rfaces always re
23fd0 70 6f 72 74 20 74 68 65 20 6d 6f 73 74 20 72 65  port the most re
23fe0 63 65 6e 74 20 72 65 73 75 6c 74 2e 20 20 54 6f  cent result.  To
23ff0 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c 20   avoid.** this, 
24000 65 61 63 68 20 74 68 72 65 61 64 20 63 61 6e 20  each thread can 
24010 6f 62 74 61 69 6e 20 65 78 63 6c 75 73 69 76 65  obtain exclusive
24020 20 75 73 65 20 6f 66 20 74 68 65 20 5b 64 61 74   use of the [dat
24030 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
24040 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69  ] D.** by invoki
24050 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  ng [sqlite3_mute
24060 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74 65  x_enter]([sqlite
24070 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20  3_db_mutex](D)) 
24080 62 65 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e 67  before beginning
24090 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20 61 6e 64  .** to use D and
240a0 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74   invoking [sqlit
240b0 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d 28  e3_mutex_leave](
240c0 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65  [sqlite3_db_mute
240d0 78 5d 28 44 29 29 20 61 66 74 65 72 0a 2a 2a 20  x](D)) after.** 
240e0 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68 65  all calls to the
240f0 20 69 6e 74 65 72 66 61 63 65 73 20 6c 69 73 74   interfaces list
24100 65 64 20 68 65 72 65 20 61 72 65 20 63 6f 6d 70  ed here are comp
24110 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  leted..**.** If 
24120 61 6e 20 69 6e 74 65 72 66 61 63 65 20 66 61 69  an interface fai
24130 6c 73 20 77 69 74 68 20 53 51 4c 49 54 45 5f 4d  ls with SQLITE_M
24140 49 53 55 53 45 2c 20 74 68 61 74 20 6d 65 61 6e  ISUSE, that mean
24150 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a  s the interface.
24160 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64 20 69  ** was invoked i
24170 6e 63 6f 72 72 65 63 74 6c 79 20 62 79 20 74 68  ncorrectly by th
24180 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20  e application.  
24190 49 6e 20 74 68 61 74 20 63 61 73 65 2c 20 74 68  In that case, th
241a0 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20  e.** error code 
241b0 61 6e 64 20 6d 65 73 73 61 67 65 20 6d 61 79 20  and message may 
241c0 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65 20 73 65  or may not be se
241d0 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  t..*/.SQLITE_API
241e0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 72 72   int sqlite3_err
241f0 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62  code(sqlite3 *db
24200 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
24210 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64  t sqlite3_extend
24220 65 64 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74  ed_errcode(sqlit
24230 65 33 20 2a 64 62 29 3b 0a 53 51 4c 49 54 45 5f  e3 *db);.SQLITE_
24240 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  API const char *
24250 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 73  sqlite3_errmsg(s
24260 71 6c 69 74 65 33 2a 29 3b 0a 53 51 4c 49 54 45  qlite3*);.SQLITE
24270 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20  _API const void 
24280 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31  *sqlite3_errmsg1
24290 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 53 51 4c  6(sqlite3*);.SQL
242a0 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68  ITE_API const ch
242b0 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 73  ar *sqlite3_errs
242c0 74 72 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  tr(int);../*.** 
242d0 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 53 74  CAPI3REF: SQL St
242e0 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a  atement Object.*
242f0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 65  * KEYWORDS: {pre
24300 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 7d  pared statement}
24310 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   {prepared state
24320 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20  ments}.**.** An 
24330 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
24340 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e   object represen
24350 74 73 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20  ts a single SQL 
24360 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54 68  statement..** Th
24370 69 73 20 6f 62 6a 65 63 74 20 69 73 20 76 61 72  is object is var
24380 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20 61 73 20  iously known as 
24390 61 20 22 70 72 65 70 61 72 65 64 20 73 74 61 74  a "prepared stat
243a0 65 6d 65 6e 74 22 20 6f 72 20 61 0a 2a 2a 20 22  ement" or a.** "
243b0 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74 61  compiled SQL sta
243c0 74 65 6d 65 6e 74 22 20 6f 72 20 73 69 6d 70 6c  tement" or simpl
243d0 79 20 61 73 20 61 20 22 73 74 61 74 65 6d 65 6e  y as a "statemen
243e0 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69  t"..**.** The li
243f0 66 65 20 6f 66 20 61 20 73 74 61 74 65 6d 65 6e  fe of a statemen
24400 74 20 6f 62 6a 65 63 74 20 67 6f 65 73 20 73 6f  t object goes so
24410 6d 65 74 68 69 6e 67 20 6c 69 6b 65 20 74 68 69  mething like thi
24420 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a  s:.**.** <ol>.**
24430 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 68 65   <li> Create the
24440 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73   object using [s
24450 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
24460 32 28 29 5d 20 6f 72 20 61 20 72 65 6c 61 74 65  2()] or a relate
24470 64 0a 2a 2a 20 20 20 20 20 20 66 75 6e 63 74 69  d.**      functi
24480 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64  on..** <li> Bind
24490 20 76 61 6c 75 65 73 20 74 6f 20 5b 68 6f 73 74   values to [host
244a0 20 70 61 72 61 6d 65 74 65 72 73 5d 20 75 73 69   parameters] usi
244b0 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  ng the sqlite3_b
244c0 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20 20  ind_*().**      
244d0 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 3c  interfaces..** <
244e0 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 51 4c 20  li> Run the SQL 
244f0 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  by calling [sqli
24500 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20  te3_step()] one 
24510 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a  or more times..*
24520 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 74 68 65  * <li> Reset the
24530 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67   statement using
24540 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
24550 29 5d 20 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a  )] then go back.
24560 2a 2a 20 20 20 20 20 20 74 6f 20 73 74 65 70 20  **      to step 
24570 32 2e 20 20 44 6f 20 74 68 69 73 20 7a 65 72 6f  2.  Do this zero
24580 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a   or more times..
24590 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20  ** <li> Destroy 
245a0 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67  the object using
245b0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
245c0 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a  ze()]..** </ol>.
245d0 2a 2a 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 64  **.** Refer to d
245e0 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e 20  ocumentation on 
245f0 69 6e 64 69 76 69 64 75 61 6c 20 6d 65 74 68 6f  individual metho
24600 64 73 20 61 62 6f 76 65 20 66 6f 72 20 61 64 64  ds above for add
24610 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72  itional.** infor
24620 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64  mation..*/.typed
24630 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
24640 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 33 5f 73  3_stmt sqlite3_s
24650 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  tmt;../*.** CAPI
24660 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65 20 4c  3REF: Run-time L
24670 69 6d 69 74 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  imits.**.** ^(Th
24680 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c  is interface all
24690 6f 77 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20  ows the size of 
246a0 76 61 72 69 6f 75 73 20 63 6f 6e 73 74 72 75 63  various construc
246b0 74 73 20 74 6f 20 62 65 20 6c 69 6d 69 74 65 64  ts to be limited
246c0 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 74  .** on a connect
246d0 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74 69 6f  ion by connectio
246e0 6e 20 62 61 73 69 73 2e 20 20 54 68 65 20 66 69  n basis.  The fi
246f0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
24700 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73   the.** [databas
24710 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 68  e connection] wh
24720 6f 73 65 20 6c 69 6d 69 74 20 69 73 20 74 6f 20  ose limit is to 
24730 62 65 20 73 65 74 20 6f 72 20 71 75 65 72 69 65  be set or querie
24740 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e  d.  The.** secon
24750 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6f  d parameter is o
24760 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d 69 74  ne of the [limit
24770 20 63 61 74 65 67 6f 72 69 65 73 5d 20 74 68 61   categories] tha
24780 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20 63 6c  t define a.** cl
24790 61 73 73 20 6f 66 20 63 6f 6e 73 74 72 75 63 74  ass of construct
247a0 73 20 74 6f 20 62 65 20 73 69 7a 65 20 6c 69 6d  s to be size lim
247b0 69 74 65 64 2e 20 20 54 68 65 20 74 68 69 72 64  ited.  The third
247c0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
247d0 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74 20 66  e.** new limit f
247e0 6f 72 20 74 68 61 74 20 63 6f 6e 73 74 72 75 63  or that construc
247f0 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  t.)^.**.** ^If t
24800 68 65 20 6e 65 77 20 6c 69 6d 69 74 20 69 73 20  he new limit is 
24810 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 65  a negative numbe
24820 72 2c 20 74 68 65 20 6c 69 6d 69 74 20 69 73 20  r, the limit is 
24830 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 5e 28  unchanged..** ^(
24840 46 6f 72 20 65 61 63 68 20 6c 69 6d 69 74 20 63  For each limit c
24850 61 74 65 67 6f 72 79 20 53 51 4c 49 54 45 5f 4c  ategory SQLITE_L
24860 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e  IMIT_<i>NAME</i>
24870 20 74 68 65 72 65 20 69 73 20 61 20 0a 2a 2a 20   there is a .** 
24880 5b 6c 69 6d 69 74 73 20 7c 20 68 61 72 64 20 75  [limits | hard u
24890 70 70 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73  pper bound].** s
248a0 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69  et at compile-ti
248b0 6d 65 20 62 79 20 61 20 43 20 70 72 65 70 72 6f  me by a C prepro
248c0 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 63 61 6c  cessor macro cal
248d0 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c  led.** [limits |
248e0 20 53 51 4c 49 54 45 5f 4d 41 58 5f 3c 69 3e 4e   SQLITE_MAX_<i>N
248f0 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28 54 68  AME</i>]..** (Th
24900 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69 6e 20 74  e "_LIMIT_" in t
24910 68 65 20 6e 61 6d 65 20 69 73 20 63 68 61 6e 67  he name is chang
24920 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29 29  ed to "_MAX_".))
24930 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70 74 73 20 74  ^.** ^Attempts t
24940 6f 20 69 6e 63 72 65 61 73 65 20 61 20 6c 69 6d  o increase a lim
24950 69 74 20 61 62 6f 76 65 20 69 74 73 20 68 61 72  it above its har
24960 64 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61 72  d upper bound ar
24970 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 74 72  e.** silently tr
24980 75 6e 63 61 74 65 64 20 74 6f 20 74 68 65 20 68  uncated to the h
24990 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 2e  ard upper bound.
249a0 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61 72 64 6c 65  .**.** ^Regardle
249b0 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ss of whether or
249c0 20 6e 6f 74 20 74 68 65 20 6c 69 6d 69 74 20 77   not the limit w
249d0 61 73 20 63 68 61 6e 67 65 64 2c 20 74 68 65 20  as changed, the 
249e0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d  .** [sqlite3_lim
249f0 69 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  it()] interface 
24a00 72 65 74 75 72 6e 73 20 74 68 65 20 70 72 69 6f  returns the prio
24a10 72 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 6c  r value of the l
24a20 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65 6e 63 65 2c  imit..** ^Hence,
24a30 20 74 6f 20 66 69 6e 64 20 74 68 65 20 63 75 72   to find the cur
24a40 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 20 61 20  rent value of a 
24a50 6c 69 6d 69 74 20 77 69 74 68 6f 75 74 20 63 68  limit without ch
24a60 61 6e 67 69 6e 67 20 69 74 2c 0a 2a 2a 20 73 69  anging it,.** si
24a70 6d 70 6c 79 20 69 6e 76 6f 6b 65 20 74 68 69 73  mply invoke this
24a80 20 69 6e 74 65 72 66 61 63 65 20 77 69 74 68 20   interface with 
24a90 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
24aa0 74 65 72 20 73 65 74 20 74 6f 20 2d 31 2e 0a 2a  ter set to -1..*
24ab0 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d 65 20 6c 69  *.** Run-time li
24ac0 6d 69 74 73 20 61 72 65 20 69 6e 74 65 6e 64 65  mits are intende
24ad0 64 20 66 6f 72 20 75 73 65 20 69 6e 20 61 70 70  d for use in app
24ae0 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6d  lications that m
24af0 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 20 74 68  anage.** both th
24b00 65 69 72 20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c  eir own internal
24b10 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 61 6c   database and al
24b20 73 6f 20 64 61 74 61 62 61 73 65 73 20 74 68 61  so databases tha
24b30 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 64  t are controlled
24b40 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73 74 65 64  .** by untrusted
24b50 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65   external source
24b60 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 61  s.  An example a
24b70 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68 74  pplication might
24b80 20 62 65 20 61 0a 2a 2a 20 77 65 62 20 62 72 6f   be a.** web bro
24b90 77 73 65 72 20 74 68 61 74 20 68 61 73 20 69 74  wser that has it
24ba0 73 20 6f 77 6e 20 64 61 74 61 62 61 73 65 73 20  s own databases 
24bb0 66 6f 72 20 73 74 6f 72 69 6e 67 20 68 69 73 74  for storing hist
24bc0 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65 70 61 72  ory and.** separ
24bd0 61 74 65 20 64 61 74 61 62 61 73 65 73 20 63 6f  ate databases co
24be0 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a 61 76 61  ntrolled by Java
24bf0 53 63 72 69 70 74 20 61 70 70 6c 69 63 61 74 69  Script applicati
24c00 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a  ons downloaded.*
24c10 2a 20 6f 66 66 20 74 68 65 20 49 6e 74 65 72 6e  * off the Intern
24c20 65 74 2e 20 20 54 68 65 20 69 6e 74 65 72 6e 61  et.  The interna
24c30 6c 20 64 61 74 61 62 61 73 65 73 20 63 61 6e 20  l databases can 
24c40 62 65 20 67 69 76 65 6e 20 74 68 65 0a 2a 2a 20  be given the.** 
24c50 6c 61 72 67 65 2c 20 64 65 66 61 75 6c 74 20 6c  large, default l
24c60 69 6d 69 74 73 2e 20 20 44 61 74 61 62 61 73 65  imits.  Database
24c70 73 20 6d 61 6e 61 67 65 64 20 62 79 20 65 78 74  s managed by ext
24c80 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 20 63 61  ernal sources ca
24c90 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e 20 6d 75  n.** be given mu
24ca0 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69 6d 69 74  ch smaller limit
24cb0 73 20 64 65 73 69 67 6e 65 64 20 74 6f 20 70 72  s designed to pr
24cc0 65 76 65 6e 74 20 61 20 64 65 6e 69 61 6c 20 6f  event a denial o
24cd0 66 20 73 65 72 76 69 63 65 0a 2a 2a 20 61 74 74  f service.** att
24ce0 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70 65 72 73  ack.  Developers
24cf0 20 6d 69 67 68 74 20 61 6c 73 6f 20 77 61 6e 74   might also want
24d00 20 74 6f 20 75 73 65 20 74 68 65 20 5b 73 71 6c   to use the [sql
24d10 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
24d20 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66  zer()].** interf
24d30 61 63 65 20 74 6f 20 66 75 72 74 68 65 72 20 63  ace to further c
24d40 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73 74 65 64  ontrol untrusted
24d50 20 53 51 4c 2e 20 20 54 68 65 20 73 69 7a 65 20   SQL.  The size 
24d60 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  of the database.
24d70 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 61 6e  ** created by an
24d80 20 75 6e 74 72 75 73 74 65 64 20 73 63 72 69 70   untrusted scrip
24d90 74 20 63 61 6e 20 62 65 20 63 6f 6e 74 61 69 6e  t can be contain
24da0 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  ed using the.** 
24db0 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d  [max_page_count]
24dc0 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a   [PRAGMA]..**.**
24dd0 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65 20 6c 69   New run-time li
24de0 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 20 6d  mit categories m
24df0 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
24e00 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a  uture releases..
24e10 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
24e20 74 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28  t sqlite3_limit(
24e30 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69 64  sqlite3*, int id
24e40 2c 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a  , int newVal);..
24e50 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
24e60 52 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43  Run-Time Limit C
24e70 61 74 65 67 6f 72 69 65 73 0a 2a 2a 20 4b 45 59  ategories.** KEY
24e80 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61  WORDS: {limit ca
24e90 74 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74 20  tegory} {*limit 
24ea0 63 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a  categories}.**.*
24eb0 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
24ec0 73 20 64 65 66 69 6e 65 20 76 61 72 69 6f 75 73  s define various
24ed0 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6c 69 6d   performance lim
24ee0 69 74 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20  its.** that can 
24ef0 62 65 20 6c 6f 77 65 72 65 64 20 61 74 20 72 75  be lowered at ru
24f00 6e 2d 74 69 6d 65 20 75 73 69 6e 67 20 5b 73 71  n-time using [sq
24f10 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a  lite3_limit()]..
24f20 2a 2a 20 54 68 65 20 73 79 6e 6f 70 73 69 73 20  ** The synopsis 
24f30 6f 66 20 74 68 65 20 6d 65 61 6e 69 6e 67 73 20  of the meanings 
24f40 6f 66 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c  of the various l
24f50 69 6d 69 74 73 20 69 73 20 73 68 6f 77 6e 20 62  imits is shown b
24f60 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69 74 69 6f  elow..** Additio
24f70 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  nal information 
24f80 69 73 20 61 76 61 69 6c 61 62 6c 65 20 61 74 20  is available at 
24f90 5b 6c 69 6d 69 74 73 20 7c 20 4c 69 6d 69 74 73  [limits | Limits
24fa0 20 69 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a   in SQLite]..**.
24fb0 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c  ** <dl>.** [[SQL
24fc0 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48  ITE_LIMIT_LENGTH
24fd0 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
24fe0 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 74  LIMIT_LENGTH</dt
24ff0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
25000 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e 79  imum size of any
25010 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20   string or BLOB 
25020 6f 72 20 74 61 62 6c 65 20 72 6f 77 2c 20 69 6e  or table row, in
25030 20 62 79 74 65 73 2e 3c 64 64 3e 29 5e 0a 2a 2a   bytes.<dd>)^.**
25040 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
25050 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 5d 5d 20  IT_SQL_LENGTH]] 
25060 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
25070 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64  IT_SQL_LENGTH</d
25080 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
25090 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
250a0 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
250b0 2c 20 69 6e 20 62 79 74 65 73 2e 3c 2f 64 64 3e  , in bytes.</dd>
250c0 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
250d0 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 5d 5d  E_LIMIT_COLUMN]]
250e0 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
250f0 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a  MIT_COLUMN</dt>.
25100 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
25110 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  um number of col
25120 75 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c 65 20  umns in a table 
25130 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e  definition or in
25140 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73   the.** result s
25150 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d  et of a [SELECT]
25160 20 6f 72 20 74 68 65 20 6d 61 78 69 6d 75 6d 20   or the maximum 
25170 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
25180 73 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a  s in an index.**
25190 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45 52 20   or in an ORDER 
251a0 42 59 20 6f 72 20 47 52 4f 55 50 20 42 59 20 63  BY or GROUP BY c
251b0 6c 61 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  lause.</dd>)^.**
251c0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
251d0 49 54 5f 45 58 50 52 5f 44 45 50 54 48 5d 5d 20  IT_EXPR_DEPTH]] 
251e0 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
251f0 49 54 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f 64  IT_EXPR_DEPTH</d
25200 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
25210 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 74  ximum depth of t
25220 68 65 20 70 61 72 73 65 20 74 72 65 65 20 6f 6e  he parse tree on
25230 20 61 6e 79 20 65 78 70 72 65 73 73 69 6f 6e 2e   any expression.
25240 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
25250 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d  SQLITE_LIMIT_COM
25260 50 4f 55 4e 44 5f 53 45 4c 45 43 54 5d 5d 20 5e  POUND_SELECT]] ^
25270 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
25280 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43  T_COMPOUND_SELEC
25290 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  T</dt>.** <dd>Th
252a0 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
252b0 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 61 20 63   of terms in a c
252c0 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54 20 73  ompound SELECT s
252d0 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e  tatement.</dd>)^
252e0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
252f0 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 5d 5d 20  LIMIT_VDBE_OP]] 
25300 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
25310 49 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a  IT_VDBE_OP</dt>.
25320 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
25330 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e 73  um number of ins
25340 74 72 75 63 74 69 6f 6e 73 20 69 6e 20 61 20 76  tructions in a v
25350 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 70  irtual machine p
25360 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 64 20 74  rogram.** used t
25370 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 6e 20 53  o implement an S
25380 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 54  QL statement.  T
25390 68 69 73 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74  his limit is not
253a0 20 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 65 6e   currently.** en
253b0 66 6f 72 63 65 64 2c 20 74 68 6f 75 67 68 20 74  forced, though t
253c0 68 61 74 20 6d 69 67 68 74 20 62 65 20 61 64 64  hat might be add
253d0 65 64 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72  ed in some futur
253e0 65 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20  e release of.** 
253f0 53 51 4c 69 74 65 2e 3c 2f 64 64 3e 29 5e 0a 2a  SQLite.</dd>)^.*
25400 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
25410 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47  MIT_FUNCTION_ARG
25420 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
25430 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41  LIMIT_FUNCTION_A
25440 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  RG</dt>.** <dd>T
25450 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
25460 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 6f  r of arguments o
25470 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64  n a function.</d
25480 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
25490 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48  ITE_LIMIT_ATTACH
254a0 45 44 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  ED]] ^(<dt>SQLIT
254b0 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44  E_LIMIT_ATTACHED
254c0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
254d0 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
254e0 6f 66 20 5b 41 54 54 41 43 48 20 7c 20 61 74 74  of [ATTACH | att
254f0 61 63 68 65 64 20 64 61 74 61 62 61 73 65 73 5d  ached databases]
25500 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  .)^</dd>.**.** [
25510 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49  [SQLITE_LIMIT_LI
25520 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54  KE_PATTERN_LENGT
25530 48 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c  H]].** ^(<dt>SQL
25540 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50  ITE_LIMIT_LIKE_P
25550 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64  ATTERN_LENGTH</d
25560 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
25570 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
25580 74 68 65 20 70 61 74 74 65 72 6e 20 61 72 67 75  the pattern argu
25590 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 4c 49 4b  ment to the [LIK
255a0 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20  E] or.** [GLOB] 
255b0 6f 70 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e 29  operators.</dd>)
255c0 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
255d0 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f  _LIMIT_VARIABLE_
255e0 4e 55 4d 42 45 52 5d 5d 0a 2a 2a 20 5e 28 3c 64  NUMBER]].** ^(<d
255f0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  t>SQLITE_LIMIT_V
25600 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f  ARIABLE_NUMBER</
25610 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
25620 61 78 69 6d 75 6d 20 69 6e 64 65 78 20 6e 75 6d  aximum index num
25630 62 65 72 20 6f 66 20 61 6e 79 20 5b 70 61 72 61  ber of any [para
25640 6d 65 74 65 72 5d 20 69 6e 20 61 6e 20 53 51 4c  meter] in an SQL
25650 20 73 74 61 74 65 6d 65 6e 74 2e 29 5e 0a 2a 2a   statement.)^.**
25660 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
25670 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48  IT_TRIGGER_DEPTH
25680 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
25690 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45  LIMIT_TRIGGER_DE
256a0 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  PTH</dt>.** <dd>
256b0 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74  The maximum dept
256c0 68 20 6f 66 20 72 65 63 75 72 73 69 6f 6e 20 66  h of recursion f
256d0 6f 72 20 74 72 69 67 67 65 72 73 2e 3c 2f 64 64  or triggers.</dd
256e0 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a  >)^.** </dl>.*/.
256f0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
25700 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20 20 20 20  IMIT_LENGTH     
25710 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
25720 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
25730 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48  LIMIT_SQL_LENGTH
25740 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
25750 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
25760 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20 20  _LIMIT_COLUMN   
25770 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
25780 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
25790 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50  E_LIMIT_EXPR_DEP
257a0 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TH              
257b0 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    3.#define SQLI
257c0 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e  TE_LIMIT_COMPOUN
257d0 44 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20  D_SELECT        
257e0 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c     4.#define SQL
257f0 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f  ITE_LIMIT_VDBE_O
25800 50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  P               
25810 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51      5.#define SQ
25820 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54  LITE_LIMIT_FUNCT
25830 49 4f 4e 5f 41 52 47 20 20 20 20 20 20 20 20 20  ION_ARG         
25840 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53       6.#define S
25850 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41  QLITE_LIMIT_ATTA
25860 43 48 45 44 20 20 20 20 20 20 20 20 20 20 20 20  CHED            
25870 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20        7.#define 
25880 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b  SQLITE_LIMIT_LIK
25890 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48  E_PATTERN_LENGTH
258a0 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65         8.#define
258b0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41   SQLITE_LIMIT_VA
258c0 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20 20 20  RIABLE_NUMBER   
258d0 20 20 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e          9.#defin
258e0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54  e SQLITE_LIMIT_T
258f0 52 49 47 47 45 52 5f 44 45 50 54 48 20 20 20 20  RIGGER_DEPTH    
25900 20 20 20 20 20 20 20 20 31 30 0a 0a 2f 2a 0a 2a          10../*.*
25910 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70  * CAPI3REF: Comp
25920 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53 74 61  iling An SQL Sta
25930 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45 59 57 4f 52  tement.** KEYWOR
25940 44 53 3a 20 7b 53 51 4c 20 73 74 61 74 65 6d 65  DS: {SQL stateme
25950 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a 0a  nt compiler}.**.
25960 2a 2a 20 54 6f 20 65 78 65 63 75 74 65 20 61 6e  ** To execute an
25970 20 53 51 4c 20 71 75 65 72 79 2c 20 69 74 20 6d   SQL query, it m
25980 75 73 74 20 66 69 72 73 74 20 62 65 20 63 6f 6d  ust first be com
25990 70 69 6c 65 64 20 69 6e 74 6f 20 61 20 62 79 74  piled into a byt
259a0 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 61  e-code.** progra
259b0 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74  m using one of t
259c0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  hese routines..*
259d0 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  *.** The first a
259e0 72 67 75 6d 65 6e 74 2c 20 22 64 62 22 2c 20 69  rgument, "db", i
259f0 73 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  s a [database co
25a00 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74 61 69 6e  nnection] obtain
25a10 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 70 72 69  ed from a.** pri
25a20 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20 63 61  or successful ca
25a30 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f  ll to [sqlite3_o
25a40 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  pen()], [sqlite3
25a50 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6f 72 0a 2a  _open_v2()] or.*
25a60 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  * [sqlite3_open1
25a70 36 28 29 5d 2e 20 20 54 68 65 20 64 61 74 61 62  6()].  The datab
25a80 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d  ase connection m
25a90 75 73 74 20 6e 6f 74 20 68 61 76 65 20 62 65 65  ust not have bee
25aa0 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  n closed..**.** 
25ab0 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
25ac0 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20 69 73 20  ent, "zSql", is 
25ad0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  the statement to
25ae0 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20 65 6e   be compiled, en
25af0 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69 74 68  coded.** as eith
25b00 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d  er UTF-8 or UTF-
25b10 31 36 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  16.  The sqlite3
25b20 5f 70 72 65 70 61 72 65 28 29 20 61 6e 64 20 73  _prepare() and s
25b30 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
25b40 32 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  2().** interface
25b50 73 20 75 73 65 20 55 54 46 2d 38 2c 20 61 6e 64  s use UTF-8, and
25b60 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
25b70 31 36 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  16() and sqlite3
25b80 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 0a  _prepare16_v2().
25b90 2a 2a 20 75 73 65 20 55 54 46 2d 31 36 2e 0a 2a  ** use UTF-16..*
25ba0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 42 79  *.** ^If the nBy
25bb0 74 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6c  te argument is l
25bc0 65 73 73 20 74 68 61 6e 20 7a 65 72 6f 2c 20 74  ess than zero, t
25bd0 68 65 6e 20 7a 53 71 6c 20 69 73 20 72 65 61 64  hen zSql is read
25be0 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69   up to the.** fi
25bf0 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  rst zero termina
25c00 74 6f 72 2e 20 5e 49 66 20 6e 42 79 74 65 20 69  tor. ^If nByte i
25c10 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20  s non-negative, 
25c20 74 68 65 6e 20 69 74 20 69 73 20 74 68 65 20 6d  then it is the m
25c30 61 78 69 6d 75 6d 0a 2a 2a 20 6e 75 6d 62 65 72  aximum.** number
25c40 20 6f 66 20 20 62 79 74 65 73 20 72 65 61 64 20   of  bytes read 
25c50 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e 57 68 65  from zSql.  ^Whe
25c60 6e 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e  n nByte is non-n
25c70 65 67 61 74 69 76 65 2c 20 74 68 65 0a 2a 2a 20  egative, the.** 
25c80 7a 53 71 6c 20 73 74 72 69 6e 67 20 65 6e 64 73  zSql string ends
25c90 20 61 74 20 65 69 74 68 65 72 20 74 68 65 20 66   at either the f
25ca0 69 72 73 74 20 27 5c 30 30 30 27 20 6f 72 20 27  irst '\000' or '
25cb0 5c 75 30 30 30 30 27 20 63 68 61 72 61 63 74 65  \u0000' characte
25cc0 72 20 6f 72 0a 2a 2a 20 74 68 65 20 6e 42 79 74  r or.** the nByt
25cd0 65 2d 74 68 20 62 79 74 65 2c 20 77 68 69 63 68  e-th byte, which
25ce0 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72 73 74  ever comes first
25cf0 2e 20 49 66 20 74 68 65 20 63 61 6c 6c 65 72 20  . If the caller 
25d00 6b 6e 6f 77 73 0a 2a 2a 20 74 68 61 74 20 74 68  knows.** that th
25d10 65 20 73 75 70 70 6c 69 65 64 20 73 74 72 69 6e  e supplied strin
25d20 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e 61  g is nul-termina
25d30 74 65 64 2c 20 74 68 65 6e 20 74 68 65 72 65 20  ted, then there 
25d40 69 73 20 61 20 73 6d 61 6c 6c 0a 2a 2a 20 70 65  is a small.** pe
25d50 72 66 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e 74  rformance advant
25d60 61 67 65 20 74 6f 20 62 65 20 67 61 69 6e 65 64  age to be gained
25d70 20 62 79 20 70 61 73 73 69 6e 67 20 61 6e 20 6e   by passing an n
25d80 42 79 74 65 20 70 61 72 61 6d 65 74 65 72 20 74  Byte parameter t
25d90 68 61 74 0a 2a 2a 20 69 73 20 65 71 75 61 6c 20  hat.** is equal 
25da0 74 6f 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  to the number of
25db0 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 69 6e   bytes in the in
25dc0 70 75 74 20 73 74 72 69 6e 67 20 3c 69 3e 69 6e  put string <i>in
25dd0 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74  cluding</i>.** t
25de0 68 65 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 6f  he nul-terminato
25df0 72 20 62 79 74 65 73 20 61 73 20 74 68 69 73 20  r bytes as this 
25e00 73 61 76 65 73 20 53 51 4c 69 74 65 20 66 72 6f  saves SQLite fro
25e10 6d 20 68 61 76 69 6e 67 20 74 6f 0a 2a 2a 20 6d  m having to.** m
25e20 61 6b 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68  ake a copy of th
25e30 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 2e 0a  e input string..
25e40 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a 54 61 69 6c  **.** ^If pzTail
25e50 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65   is not NULL the
25e60 6e 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61 64  n *pzTail is mad
25e70 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68  e to point to th
25e80 65 20 66 69 72 73 74 20 62 79 74 65 0a 2a 2a 20  e first byte.** 
25e90 70 61 73 74 20 74 68 65 20 65 6e 64 20 6f 66 20  past the end of 
25ea0 74 68 65 20 66 69 72 73 74 20 53 51 4c 20 73 74  the first SQL st
25eb0 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e  atement in zSql.
25ec0 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73    These routines
25ed0 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65   only.** compile
25ee0 20 74 68 65 20 66 69 72 73 74 20 73 74 61 74 65   the first state
25ef0 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f  ment in zSql, so
25f00 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65 66 74   *pzTail is left
25f10 20 70 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20   pointing to.** 
25f20 77 68 61 74 20 72 65 6d 61 69 6e 73 20 75 6e 63  what remains unc
25f30 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  ompiled..**.** ^
25f40 2a 70 70 53 74 6d 74 20 69 73 20 6c 65 66 74 20  *ppStmt is left 
25f50 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f  pointing to a co
25f60 6d 70 69 6c 65 64 20 5b 70 72 65 70 61 72 65 64  mpiled [prepared
25f70 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
25f80 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75   can be.** execu
25f90 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ted using [sqlit
25fa0 65 33 5f 73 74 65 70 28 29 5d 2e 20 20 5e 49 66  e3_step()].  ^If
25fb0 20 74 68 65 72 65 20 69 73 20 61 6e 20 65 72 72   there is an err
25fc0 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69 73 20 73  or, *ppStmt is s
25fd0 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20  et.** to NULL.  
25fe0 5e 49 66 20 74 68 65 20 69 6e 70 75 74 20 74 65  ^If the input te
25ff0 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53  xt contains no S
26000 51 4c 20 28 69 66 20 74 68 65 20 69 6e 70 75 74  QL (if the input
26010 20 69 73 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20   is an empty.** 
26020 73 74 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d  string or a comm
26030 65 6e 74 29 20 74 68 65 6e 20 2a 70 70 53 74 6d  ent) then *ppStm
26040 74 20 69 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c  t is set to NULL
26050 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 69 6e 67  ..** The calling
26060 20 70 72 6f 63 65 64 75 72 65 20 69 73 20 72 65   procedure is re
26070 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64 65  sponsible for de
26080 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6d 70 69  leting the compi
26090 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  led.** SQL state
260a0 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  ment using [sqli
260b0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
260c0 61 66 74 65 72 20 69 74 20 68 61 73 20 66 69 6e  after it has fin
260d0 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 0a 2a  ished with it..*
260e0 2a 20 70 70 53 74 6d 74 20 6d 61 79 20 6e 6f 74  * ppStmt may not
260f0 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   be NULL..**.** 
26100 5e 4f 6e 20 73 75 63 63 65 73 73 2c 20 74 68 65  ^On success, the
26110 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
26120 28 29 20 66 61 6d 69 6c 79 20 6f 66 20 72 6f 75  () family of rou
26130 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51  tines return [SQ
26140 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68  LITE_OK];.** oth
26150 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72  erwise an [error
26160 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e   code] is return
26170 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ed..**.** The sq
26180 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
26190 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70  () and sqlite3_p
261a0 72 65 70 61 72 65 31 36 5f 76 32 28 29 20 69 6e  repare16_v2() in
261b0 74 65 72 66 61 63 65 73 20 61 72 65 0a 2a 2a 20  terfaces are.** 
261c0 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20  recommended for 
261d0 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d 73  all new programs
261e0 2e 20 54 68 65 20 74 77 6f 20 6f 6c 64 65 72 20  . The two older 
261f0 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 72  interfaces are r
26200 65 74 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62  etained.** for b
26210 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
26220 62 69 6c 69 74 79 2c 20 62 75 74 20 74 68 65 69  bility, but thei
26230 72 20 75 73 65 20 69 73 20 64 69 73 63 6f 75 72  r use is discour
26240 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65  aged..** ^In the
26250 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 73   "v2" interfaces
26260 2c 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73  , the prepared s
26270 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74  tatement.** that
26280 20 69 73 20 72 65 74 75 72 6e 65 64 20 28 74 68   is returned (th
26290 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d  e [sqlite3_stmt]
262a0 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e   object) contain
262b0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a  s a copy of the.
262c0 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20  ** original SQL 
262d0 74 65 78 74 2e 20 54 68 69 73 20 63 61 75 73 65  text. This cause
262e0 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  s the [sqlite3_s
262f0 74 65 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65  tep()] interface
26300 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20 64 69   to.** behave di
26310 66 66 65 72 65 6e 74 6c 79 20 69 6e 20 74 68 72  fferently in thr
26320 65 65 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ee ways:.**.** <
26330 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e  ol>.** <li>.** ^
26340 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  If the database 
26350 73 63 68 65 6d 61 20 63 68 61 6e 67 65 73 2c 20  schema changes, 
26360 69 6e 73 74 65 61 64 20 6f 66 20 72 65 74 75 72  instead of retur
26370 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43 48  ning [SQLITE_SCH
26380 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c  EMA] as it.** al
26390 77 61 79 73 20 75 73 65 64 20 74 6f 20 64 6f 2c  ways used to do,
263a0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
263b0 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63  ] will automatic
263c0 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20 74  ally recompile t
263d0 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d  he SQL.** statem
263e0 65 6e 74 20 61 6e 64 20 74 72 79 20 74 6f 20 72  ent and try to r
263f0 75 6e 20 69 74 20 61 67 61 69 6e 2e 20 41 73 20  un it again. As 
26400 6d 61 6e 79 20 61 73 20 5b 53 51 4c 49 54 45 5f  many as [SQLITE_
26410 4d 41 58 5f 53 43 48 45 4d 41 5f 52 45 54 52 59  MAX_SCHEMA_RETRY
26420 5d 0a 2a 2a 20 72 65 74 72 69 65 73 20 77 69 6c  ].** retries wil
26430 6c 20 6f 63 63 75 72 20 62 65 66 6f 72 65 20 73  l occur before s
26440 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 67 69  qlite3_step() gi
26450 76 65 73 20 75 70 20 61 6e 64 20 72 65 74 75 72  ves up and retur
26460 6e 73 20 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a 20  ns an error..** 
26470 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  </li>.**.** <li>
26480 0a 2a 2a 20 5e 57 68 65 6e 20 61 6e 20 65 72 72  .** ^When an err
26490 6f 72 20 6f 63 63 75 72 73 2c 20 5b 73 71 6c 69  or occurs, [sqli
264a0 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c  te3_step()] will
264b0 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74   return one of t
264c0 68 65 20 64 65 74 61 69 6c 65 64 0a 2a 2a 20 5b  he detailed.** [
264d0 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 6f 72 20  error codes] or 
264e0 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20  [extended error 
264f0 63 6f 64 65 73 5d 2e 20 20 5e 54 68 65 20 6c 65  codes].  ^The le
26500 67 61 63 79 20 62 65 68 61 76 69 6f 72 20 77 61  gacy behavior wa
26510 73 20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 74  s that.** [sqlit
26520 65 33 5f 73 74 65 70 28 29 5d 20 77 6f 75 6c 64  e3_step()] would
26530 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61 20 67   only return a g
26540 65 6e 65 72 69 63 20 5b 53 51 4c 49 54 45 5f 45  eneric [SQLITE_E
26550 52 52 4f 52 5d 20 72 65 73 75 6c 74 20 63 6f 64  RROR] result cod
26560 65 0a 2a 2a 20 61 6e 64 20 74 68 65 20 61 70 70  e.** and the app
26570 6c 69 63 61 74 69 6f 6e 20 77 6f 75 6c 64 20 68  lication would h
26580 61 76 65 20 74 6f 20 6d 61 6b 65 20 61 20 73 65  ave to make a se
26590 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71  cond call to [sq
265a0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 0a 2a  lite3_reset()].*
265b0 2a 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69  * in order to fi
265c0 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e  nd the underlyin
265d0 67 20 63 61 75 73 65 20 6f 66 20 74 68 65 20 70  g cause of the p
265e0 72 6f 62 6c 65 6d 2e 20 57 69 74 68 20 74 68 65  roblem. With the
265f0 20 22 76 32 22 20 70 72 65 70 61 72 65 0a 2a 2a   "v2" prepare.**
26600 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65   interfaces, the
26610 20 75 6e 64 65 72 6c 79 69 6e 67 20 72 65 61 73   underlying reas
26620 6f 6e 20 66 6f 72 20 74 68 65 20 65 72 72 6f 72  on for the error
26630 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d   is returned imm
26640 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c  ediately..** </l
26650 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a  i>.**.** <li>.**
26660 20 5e 49 66 20 74 68 65 20 73 70 65 63 69 66 69   ^If the specifi
26670 63 20 76 61 6c 75 65 20 62 6f 75 6e 64 20 74 6f  c value bound to
26680 20 5b 70 61 72 61 6d 65 74 65 72 20 7c 20 68 6f   [parameter | ho
26690 73 74 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e  st parameter] in
266a0 20 74 68 65 20 0a 2a 2a 20 57 48 45 52 45 20 63   the .** WHERE c
266b0 6c 61 75 73 65 20 6d 69 67 68 74 20 69 6e 66 6c  lause might infl
266c0 75 65 6e 63 65 20 74 68 65 20 63 68 6f 69 63 65  uence the choice
266d0 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20 66   of query plan f
266e0 6f 72 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 0a  or a statement,.
266f0 2a 2a 20 74 68 65 6e 20 74 68 65 20 73 74 61 74  ** then the stat
26700 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 61 75  ement will be au
26710 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f  tomatically reco
26720 6d 70 69 6c 65 64 2c 20 61 73 20 69 66 20 74 68  mpiled, as if th
26730 65 72 65 20 68 61 64 20 62 65 65 6e 20 0a 2a 2a  ere had been .**
26740 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65   a schema change
26750 2c 20 6f 6e 20 74 68 65 20 66 69 72 73 74 20 20  , on the first  
26760 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
26770 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20   call following 
26780 61 6e 79 20 63 68 61 6e 67 65 0a 2a 2a 20 74 6f  any change.** to
26790 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   the [sqlite3_bi
267a0 6e 64 5f 74 65 78 74 20 7c 20 62 69 6e 64 69 6e  nd_text | bindin
267b0 67 73 5d 20 6f 66 20 74 68 61 74 20 5b 70 61 72  gs] of that [par
267c0 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a 20 5e 54 68  ameter]. .** ^Th
267d0 65 20 73 70 65 63 69 66 69 63 20 76 61 6c 75 65  e specific value
267e0 20 6f 66 20 57 48 45 52 45 2d 63 6c 61 75 73 65   of WHERE-clause
267f0 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 6d 69 67   [parameter] mig
26800 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65  ht influence the
26810 20 0a 2a 2a 20 63 68 6f 69 63 65 20 6f 66 20 71   .** choice of q
26820 75 65 72 79 20 70 6c 61 6e 20 69 66 20 74 68 65  uery plan if the
26830 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
26840 65 20 6c 65 66 74 2d 68 61 6e 64 20 73 69 64 65  e left-hand side
26850 20 6f 66 20 61 20 5b 4c 49 4b 45 5d 0a 2a 2a 20   of a [LIKE].** 
26860 6f 72 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74  or [GLOB] operat
26870 6f 72 20 6f 72 20 69 66 20 74 68 65 20 70 61 72  or or if the par
26880 61 6d 65 74 65 72 20 69 73 20 63 6f 6d 70 61 72  ameter is compar
26890 65 64 20 74 6f 20 61 6e 20 69 6e 64 65 78 65 64  ed to an indexed
268a0 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e 64 20 74   column.** and t
268b0 68 65 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  he [SQLITE_ENABL
268c0 45 5f 53 54 41 54 33 5d 20 63 6f 6d 70 69 6c 65  E_STAT3] compile
268d0 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20  -time option is 
268e0 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 3c 2f 6c 69  enabled..** </li
268f0 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 53 51  >.** </ol>.*/.SQ
26900 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
26910 69 74 65 33 5f 70 72 65 70 61 72 65 28 0a 20 20  ite3_prepare(.  
26920 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
26930 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
26940 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ase handle */.  
26950 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c  const char *zSql
26960 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73  ,       /* SQL s
26970 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20  tatement, UTF-8 
26980 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74  encoded */.  int
26990 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20   nByte,         
269a0 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
269b0 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69  length of zSql i
269c0 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71  n bytes. */.  sq
269d0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53  lite3_stmt **ppS
269e0 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74  tmt,  /* OUT: St
269f0 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a  atement handle *
26a00 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
26a10 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f  *pzTail     /* O
26a20 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75  UT: Pointer to u
26a30 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66  nused portion of
26a40 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49   zSql */.);.SQLI
26a50 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
26a60 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 0a 20  e3_prepare_v2(. 
26a70 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
26a80 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
26a90 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  base handle */. 
26aa0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71   const char *zSq
26ab0 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  l,       /* SQL 
26ac0 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38  statement, UTF-8
26ad0 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
26ae0 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
26af0 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
26b00 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
26b10 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73  in bytes. */.  s
26b20 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
26b30 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
26b40 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
26b50 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
26b60 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
26b70 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
26b80 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
26b90 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c  f zSql */.);.SQL
26ba0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
26bb0 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 0a 20  te3_prepare16(. 
26bc0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
26bd0 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
26be0 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  base handle */. 
26bf0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71   const void *zSq
26c00 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  l,       /* SQL 
26c10 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31  statement, UTF-1
26c20 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  6 encoded */.  i
26c30 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
26c40 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
26c50 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
26c60 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
26c70 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
26c80 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
26c90 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
26ca0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
26cb0 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
26cc0 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
26cd0 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
26ce0 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51  of zSql */.);.SQ
26cf0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
26d00 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
26d10 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  2(.  sqlite3 *db
26d20 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
26d30 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
26d40 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
26d50 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
26d60 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
26d70 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f  TF-16 encoded */
26d80 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
26d90 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
26da0 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
26db0 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
26dc0 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
26dd0 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
26de0 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
26df0 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
26e00 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20  void **pzTail   
26e10 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
26e20 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
26e30 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
26e40 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
26e50 46 3a 20 52 65 74 72 69 65 76 69 6e 67 20 53 74  F: Retrieving St
26e60 61 74 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a 0a 2a  atement SQL.**.*
26e70 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63  * ^This interfac
26e80 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  e can be used to
26e90 20 72 65 74 72 69 65 76 65 20 61 20 73 61 76 65   retrieve a save
26ea0 64 20 63 6f 70 79 20 6f 66 20 74 68 65 20 6f 72  d copy of the or
26eb0 69 67 69 6e 61 6c 0a 2a 2a 20 53 51 4c 20 74 65  iginal.** SQL te
26ec0 78 74 20 75 73 65 64 20 74 6f 20 63 72 65 61 74  xt used to creat
26ed0 65 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  e a [prepared st
26ee0 61 74 65 6d 65 6e 74 5d 20 69 66 20 74 68 61 74  atement] if that
26ef0 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 0a 2a   statement was.*
26f00 2a 20 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67  * compiled using
26f10 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33   either [sqlite3
26f20 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
26f30 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
26f40 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 53  re16_v2()]..*/.S
26f50 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
26f60 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 71  char *sqlite3_sq
26f70 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  l(sqlite3_stmt *
26f80 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
26f90 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69  API3REF: Determi
26fa0 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61  ne If An SQL Sta
26fb0 74 65 6d 65 6e 74 20 57 72 69 74 65 73 20 54 68  tement Writes Th
26fc0 65 20 44 61 74 61 62 61 73 65 0a 2a 2a 0a 2a 2a  e Database.**.**
26fd0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74   ^The sqlite3_st
26fe0 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 58 29 20 69  mt_readonly(X) i
26ff0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
27000 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29   true (non-zero)
27010 20 69 66 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20   if.** and only 
27020 69 66 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  if the [prepared
27030 20 73 74 61 74 65 6d 65 6e 74 5d 20 58 20 6d 61   statement] X ma
27040 6b 65 73 20 6e 6f 20 64 69 72 65 63 74 20 63 68  kes no direct ch
27050 61 6e 67 65 73 20 74 6f 0a 2a 2a 20 74 68 65 20  anges to.** the 
27060 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 64  content of the d
27070 61 74 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a  atabase file..**
27080 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 61  .** Note that [a
27090 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
270a0 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
270b0 5d 20 6f 72 0a 2a 2a 20 5b 76 69 72 74 75 61 6c  ] or.** [virtual
270c0 20 74 61 62 6c 65 73 5d 20 6d 69 67 68 74 20 63   tables] might c
270d0 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61  hange the databa
270e0 73 65 20 69 6e 64 69 72 65 63 74 6c 79 20 61 73  se indirectly as
270f0 20 61 20 73 69 64 65 20 65 66 66 65 63 74 2e 20   a side effect. 
27100 20 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70   .** ^(For examp
27110 6c 65 2c 20 69 66 20 61 6e 20 61 70 70 6c 69 63  le, if an applic
27120 61 74 69 6f 6e 20 64 65 66 69 6e 65 73 20 61 20  ation defines a 
27130 66 75 6e 63 74 69 6f 6e 20 22 65 76 61 6c 28 29  function "eval()
27140 22 20 74 68 61 74 20 0a 2a 2a 20 63 61 6c 6c 73  " that .** calls
27150 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
27160 5d 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 6c 6c  ], then the foll
27170 6f 77 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d  owing SQL statem
27180 65 6e 74 20 77 6f 75 6c 64 0a 2a 2a 20 63 68 61  ent would.** cha
27190 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65  nge the database
271a0 20 66 69 6c 65 20 74 68 72 6f 75 67 68 20 73 69   file through si
271b0 64 65 2d 65 66 66 65 63 74 73 3a 0a 2a 2a 0a 2a  de-effects:.**.*
271c0 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
271d0 72 65 3e 0a 2a 2a 20 20 20 20 53 45 4c 45 43 54  re>.**    SELECT
271e0 20 65 76 61 6c 28 27 44 45 4c 45 54 45 20 46 52   eval('DELETE FR
271f0 4f 4d 20 74 31 27 29 20 46 52 4f 4d 20 74 32 3b  OM t1') FROM t2;
27200 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
27210 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 75  kquote>.**.** Bu
27220 74 20 62 65 63 61 75 73 65 20 74 68 65 20 5b 53  t because the [S
27230 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
27240 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65   does not change
27250 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
27260 6c 65 0a 2a 2a 20 64 69 72 65 63 74 6c 79 2c 20  le.** directly, 
27270 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61  sqlite3_stmt_rea
27280 64 6f 6e 6c 79 28 29 20 77 6f 75 6c 64 20 73 74  donly() would st
27290 69 6c 6c 20 72 65 74 75 72 6e 20 74 72 75 65 2e  ill return true.
272a0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72 61 6e 73 61  )^.**.** ^Transa
272b0 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 20 73 74  ction control st
272c0 61 74 65 6d 65 6e 74 73 20 73 75 63 68 20 61 73  atements such as
272d0 20 5b 42 45 47 49 4e 5d 2c 20 5b 43 4f 4d 4d 49   [BEGIN], [COMMI
272e0 54 5d 2c 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2c 0a  T], [ROLLBACK],.
272f0 2a 2a 20 5b 53 41 56 45 50 4f 49 4e 54 5d 2c 20  ** [SAVEPOINT], 
27300 61 6e 64 20 5b 52 45 4c 45 41 53 45 5d 20 63 61  and [RELEASE] ca
27310 75 73 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  use sqlite3_stmt
27320 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72  _readonly() to r
27330 65 74 75 72 6e 20 74 72 75 65 2c 0a 2a 2a 20 73  eturn true,.** s
27340 69 6e 63 65 20 74 68 65 20 73 74 61 74 65 6d 65  ince the stateme
27350 6e 74 73 20 74 68 65 6d 73 65 6c 76 65 73 20 64  nts themselves d
27360 6f 20 6e 6f 74 20 61 63 74 75 61 6c 6c 79 20 6d  o not actually m
27370 6f 64 69 66 79 20 74 68 65 20 64 61 74 61 62 61  odify the databa
27380 73 65 20 62 75 74 0a 2a 2a 20 72 61 74 68 65 72  se but.** rather
27390 20 74 68 65 79 20 63 6f 6e 74 72 6f 6c 20 74 68   they control th
273a0 65 20 74 69 6d 69 6e 67 20 6f 66 20 77 68 65 6e  e timing of when
273b0 20 6f 74 68 65 72 20 73 74 61 74 65 6d 65 6e 74   other statement
273c0 73 20 6d 6f 64 69 66 79 20 74 68 65 20 0a 2a 2a  s modify the .**
273d0 20 64 61 74 61 62 61 73 65 2e 20 20 5e 54 68 65   database.  ^The
273e0 20 5b 41 54 54 41 43 48 5d 20 61 6e 64 20 5b 44   [ATTACH] and [D
273f0 45 54 41 43 48 5d 20 73 74 61 74 65 6d 65 6e 74  ETACH] statement
27400 73 20 61 6c 73 6f 20 63 61 75 73 65 0a 2a 2a 20  s also cause.** 
27410 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61  sqlite3_stmt_rea
27420 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 72  donly() to retur
27430 6e 20 74 72 75 65 20 73 69 6e 63 65 2c 20 77 68  n true since, wh
27440 69 6c 65 20 74 68 6f 73 65 20 73 74 61 74 65 6d  ile those statem
27450 65 6e 74 73 0a 2a 2a 20 63 68 61 6e 67 65 20 74  ents.** change t
27460 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  he configuration
27470 20 6f 66 20 61 20 64 61 74 61 62 61 73 65 20 63   of a database c
27480 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74 68 65 79 20  onnection, they 
27490 64 6f 20 6e 6f 74 20 6d 61 6b 65 20 0a 2a 2a 20  do not make .** 
274a0 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 63  changes to the c
274b0 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 64 61  ontent of the da
274c0 74 61 62 61 73 65 20 66 69 6c 65 73 20 6f 6e 20  tabase files on 
274d0 64 69 73 6b 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  disk..*/.SQLITE_
274e0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
274f0 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 73 71  stmt_readonly(sq
27500 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
27510 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
27520 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49  REF: Determine I
27530 66 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  f A Prepared Sta
27540 74 65 6d 65 6e 74 20 48 61 73 20 42 65 65 6e 20  tement Has Been 
27550 52 65 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  Reset.**.** ^The
27560 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75   sqlite3_stmt_bu
27570 73 79 28 53 29 20 69 6e 74 65 72 66 61 63 65 20  sy(S) interface 
27580 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f  returns true (no
27590 6e 2d 7a 65 72 6f 29 20 69 66 20 74 68 65 0a 2a  n-zero) if the.*
275a0 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
275b0 65 6d 65 6e 74 5d 20 53 20 68 61 73 20 62 65 65  ement] S has bee
275c0 6e 20 73 74 65 70 70 65 64 20 61 74 20 6c 65 61  n stepped at lea
275d0 73 74 20 6f 6e 63 65 20 75 73 69 6e 67 20 0a 2a  st once using .*
275e0 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  * [sqlite3_step(
275f0 53 29 5d 20 62 75 74 20 68 61 73 20 6e 6f 74 20  S)] but has not 
27600 72 75 6e 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f  run to completio
27610 6e 20 61 6e 64 2f 6f 72 20 68 61 73 20 6e 6f 74  n and/or has not
27620 20 0a 2a 2a 20 62 65 65 6e 20 72 65 73 65 74 20   .** been reset 
27630 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  using [sqlite3_r
27640 65 73 65 74 28 53 29 5d 2e 20 20 5e 54 68 65 20  eset(S)].  ^The 
27650 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73  sqlite3_stmt_bus
27660 79 28 53 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  y(S).** interfac
27670 65 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20  e returns false 
27680 69 66 20 53 20 69 73 20 61 20 4e 55 4c 4c 20 70  if S is a NULL p
27690 6f 69 6e 74 65 72 2e 20 20 49 66 20 53 20 69 73  ointer.  If S is
276a0 20 6e 6f 74 20 61 20 0a 2a 2a 20 4e 55 4c 4c 20   not a .** NULL 
276b0 70 6f 69 6e 74 65 72 20 61 6e 64 20 69 73 20 6e  pointer and is n
276c0 6f 74 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ot a pointer to 
276d0 61 20 76 61 6c 69 64 20 5b 70 72 65 70 61 72 65  a valid [prepare
276e0 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20  d statement].** 
276f0 6f 62 6a 65 63 74 2c 20 74 68 65 6e 20 74 68 65  object, then the
27700 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64   behavior is und
27710 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61  efined and proba
27720 62 6c 79 20 75 6e 64 65 73 69 72 61 62 6c 65 2e  bly undesirable.
27730 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65  .**.** This inte
27740 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65  rface can be use
27750 64 20 69 6e 20 63 6f 6d 62 69 6e 61 74 69 6f 6e  d in combination
27760 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73   [sqlite3_next_s
27770 74 6d 74 28 29 5d 0a 2a 2a 20 74 6f 20 6c 6f 63  tmt()].** to loc
27780 61 74 65 20 61 6c 6c 20 70 72 65 70 61 72 65 64  ate all prepared
27790 20 73 74 61 74 65 6d 65 6e 74 73 20 61 73 73 6f   statements asso
277a0 63 69 61 74 65 64 20 77 69 74 68 20 61 20 64 61  ciated with a da
277b0 74 61 62 61 73 65 20 0a 2a 2a 20 63 6f 6e 6e 65  tabase .** conne
277c0 63 74 69 6f 6e 20 74 68 61 74 20 61 72 65 20 69  ction that are i
277d0 6e 20 6e 65 65 64 20 6f 66 20 62 65 69 6e 67 20  n need of being 
277e0 72 65 73 65 74 2e 20 20 54 68 69 73 20 63 61 6e  reset.  This can
277f0 20 62 65 20 75 73 65 64 2c 0a 2a 2a 20 66 6f 72   be used,.** for
27800 20 65 78 61 6d 70 6c 65 2c 20 69 6e 20 64 69 61   example, in dia
27810 67 6e 6f 73 74 69 63 20 72 6f 75 74 69 6e 65 73  gnostic routines
27820 20 74 6f 20 73 65 61 72 63 68 20 66 6f 72 20 70   to search for p
27830 72 65 70 61 72 65 64 20 0a 2a 2a 20 73 74 61 74  repared .** stat
27840 65 6d 65 6e 74 73 20 74 68 61 74 20 61 72 65 20  ements that are 
27850 68 6f 6c 64 69 6e 67 20 61 20 74 72 61 6e 73 61  holding a transa
27860 63 74 69 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 53  ction open..*/.S
27870 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
27880 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28  lite3_stmt_busy(
27890 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
278a0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
278b0 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70   Dynamically Typ
278c0 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74 0a  ed Value Object.
278d0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72  ** KEYWORDS: {pr
278e0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
278f0 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65 63  value} {unprotec
27900 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
27910 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  e}.**.** SQLite 
27920 75 73 65 73 20 74 68 65 20 73 71 6c 69 74 65 33  uses the sqlite3
27930 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74 6f  _value object to
27940 20 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20 76   represent all v
27950 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 63 61  alues.** that ca
27960 6e 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20 61  n be stored in a
27970 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 2e   database table.
27980 20 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e   SQLite uses dyn
27990 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20 66  amic typing.** f
279a0 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20 69 74  or the values it
279b0 20 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c 75 65   stores.  ^Value
279c0 73 20 73 74 6f 72 65 64 20 69 6e 20 73 71 6c 69  s stored in sqli
279d0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
279e0 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74 65  s.** can be inte
279f0 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70  gers, floating p
27a00 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74 72  oint values, str
27a10 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20  ings, BLOBs, or 
27a20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73  NULL..**.** An s
27a30 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
27a40 65 63 74 20 6d 61 79 20 62 65 20 65 69 74 68 65  ect may be eithe
27a50 72 20 22 70 72 6f 74 65 63 74 65 64 22 20 6f 72  r "protected" or
27a60 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a   "unprotected"..
27a70 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 61 63  ** Some interfac
27a80 65 73 20 72 65 71 75 69 72 65 20 61 20 70 72 6f  es require a pro
27a90 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
27aa0 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 6e 74  alue.  Other int
27ab0 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20  erfaces.** will 
27ac0 61 63 63 65 70 74 20 65 69 74 68 65 72 20 61 20  accept either a 
27ad0 70 72 6f 74 65 63 74 65 64 20 6f 72 20 61 6e 20  protected or an 
27ae0 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
27af0 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76  te3_value..** Ev
27b00 65 72 79 20 69 6e 74 65 72 66 61 63 65 20 74 68  ery interface th
27b10 61 74 20 61 63 63 65 70 74 73 20 73 71 6c 69 74  at accepts sqlit
27b20 65 33 5f 76 61 6c 75 65 20 61 72 67 75 6d 65 6e  e3_value argumen
27b30 74 73 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  ts specifies.** 
27b40 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 69  whether or not i
27b50 74 20 72 65 71 75 69 72 65 73 20 61 20 70 72 6f  t requires a pro
27b60 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
27b70 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  alue..**.** The 
27b80 74 65 72 6d 73 20 22 70 72 6f 74 65 63 74 65 64  terms "protected
27b90 22 20 61 6e 64 20 22 75 6e 70 72 6f 74 65 63 74  " and "unprotect
27ba0 65 64 22 20 72 65 66 65 72 20 74 6f 20 77 68 65  ed" refer to whe
27bb0 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61  ther or not.** a
27bc0 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 2e 20   mutex is held. 
27bd0 20 41 6e 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74   An internal mut
27be0 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61  ex is held for a
27bf0 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71   protected.** sq
27c00 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
27c10 63 74 20 62 75 74 20 6e 6f 20 6d 75 74 65 78 20  ct but no mutex 
27c20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 6e 20 75  is held for an u
27c30 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71  nprotected.** sq
27c40 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
27c50 63 74 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69  ct.  If SQLite i
27c60 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65  s compiled to be
27c70 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 64   single-threaded
27c80 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c 49 54  .** (with [SQLIT
27c90 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
27ca0 61 6e 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65  and with [sqlite
27cb0 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d 20  3_threadsafe()] 
27cc0 72 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20  returning 0).** 
27cd0 6f 72 20 69 66 20 53 51 4c 69 74 65 20 69 73 20  or if SQLite is 
27ce0 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72 65  run in one of re
27cf0 64 75 63 65 64 20 6d 75 74 65 78 20 6d 6f 64 65  duced mutex mode
27d00 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f  s .** [SQLITE_CO
27d10 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
27d20 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f  D] or [SQLITE_CO
27d30 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44  NFIG_MULTITHREAD
27d40 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72 65 20  ].** then there 
27d50 69 73 20 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f  is no distinctio
27d60 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63  n between protec
27d70 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63  ted and unprotec
27d80 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  ted.** sqlite3_v
27d90 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 61 6e 64  alue objects and
27da0 20 74 68 65 79 20 63 61 6e 20 62 65 20 75 73 65   they can be use
27db0 64 20 69 6e 74 65 72 63 68 61 6e 67 65 61 62 6c  d interchangeabl
27dc0 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20  y.  However,.** 
27dd0 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65  for maximum code
27de0 20 70 6f 72 74 61 62 69 6c 69 74 79 20 69 74 20   portability it 
27df0 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74  is recommended t
27e00 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  hat applications
27e10 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74  .** still make t
27e20 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62  he distinction b
27e30 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64  etween protected
27e40 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64   and unprotected
27e50 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
27e60 65 20 6f 62 6a 65 63 74 73 20 65 76 65 6e 20 77  e objects even w
27e70 68 65 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c 79  hen not strictly
27e80 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a   required..**.**
27e90 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61   ^The sqlite3_va
27ea0 6c 75 65 20 6f 62 6a 65 63 74 73 20 74 68 61 74  lue objects that
27eb0 20 61 72 65 20 70 61 73 73 65 64 20 61 73 20 70   are passed as p
27ec0 61 72 61 6d 65 74 65 72 73 20 69 6e 74 6f 20 74  arameters into t
27ed0 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  he.** implementa
27ee0 74 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63 61  tion of [applica
27ef0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
27f00 20 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65 20   functions] are 
27f10 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 5e 54  protected..** ^T
27f20 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
27f30 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64   object returned
27f40 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   by.** [sqlite3_
27f50 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20  column_value()] 
27f60 69 73 20 75 6e 70 72 6f 74 65 63 74 65 64 2e 0a  is unprotected..
27f70 2a 2a 20 55 6e 70 72 6f 74 65 63 74 65 64 20 73  ** Unprotected s
27f80 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
27f90 65 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65  ects may only be
27fa0 20 75 73 65 64 20 77 69 74 68 0a 2a 2a 20 5b 73   used with.** [s
27fb0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
27fc0 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  lue()] and [sqli
27fd0 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29  te3_bind_value()
27fe0 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74  ]..** The [sqlit
27ff0 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c 20  e3_value_blob | 
28000 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79  sqlite3_value_ty
28010 70 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66 0a  pe()] family of.
28020 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 72 65  ** interfaces re
28030 71 75 69 72 65 20 70 72 6f 74 65 63 74 65 64 20  quire protected 
28040 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
28050 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 65  jects..*/.typede
28060 66 20 73 74 72 75 63 74 20 4d 65 6d 20 73 71 6c  f struct Mem sql
28070 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a  ite3_value;../*.
28080 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c  ** CAPI3REF: SQL
28090 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78   Function Contex
280a0 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54  t Object.**.** T
280b0 68 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 77 68  he context in wh
280c0 69 63 68 20 61 6e 20 53 51 4c 20 66 75 6e 63 74  ich an SQL funct
280d0 69 6f 6e 20 65 78 65 63 75 74 65 73 20 69 73 20  ion executes is 
280e0 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20  stored in an.** 
280f0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20  sqlite3_context 
28100 6f 62 6a 65 63 74 2e 20 20 5e 41 20 70 6f 69 6e  object.  ^A poin
28110 74 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 74 65  ter to an sqlite
28120 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74  3_context object
28130 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 66 69  .** is always fi
28140 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
28150 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   [application-de
28160 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
28170 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 70  ons]..** The app
28180 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
28190 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d   SQL function im
281a0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c  plementation wil
281b0 6c 20 70 61 73 73 20 74 68 69 73 0a 2a 2a 20 70  l pass this.** p
281c0 6f 69 6e 74 65 72 20 74 68 72 6f 75 67 68 20 69  ointer through i
281d0 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  nto calls to [sq
281e0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
281f0 20 7c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c   | sqlite3_resul
28200 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  t()],.** [sqlite
28210 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
28220 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  ext()], [sqlite3
28230 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a 2a  _user_data()],.*
28240 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  * [sqlite3_conte
28250 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d 2c  xt_db_handle()],
28260 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75   [sqlite3_get_au
28270 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64  xdata()],.** and
28280 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  /or [sqlite3_set
28290 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a  _auxdata()]..*/.
282a0 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
282b0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 73  qlite3_context s
282c0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a  qlite3_context;.
282d0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
282e0 20 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73 20   Binding Values 
282f0 54 6f 20 50 72 65 70 61 72 65 64 20 53 74 61 74  To Prepared Stat
28300 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f 52  ements.** KEYWOR
28310 44 53 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d 65  DS: {host parame
28320 74 65 72 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d  ter} {host param
28330 65 74 65 72 73 7d 20 7b 68 6f 73 74 20 70 61 72  eters} {host par
28340 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20  ameter name}.** 
28350 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 70  KEYWORDS: {SQL p
28360 61 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20 70  arameter} {SQL p
28370 61 72 61 6d 65 74 65 72 73 7d 20 7b 70 61 72 61  arameters} {para
28380 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a 2a  meter binding}.*
28390 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 65 20 53 51  *.** ^(In the SQ
283a0 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74  L statement text
283b0 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74   input to [sqlit
283c0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
283d0 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74   and its variant
283e0 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d  s,.** literals m
283f0 61 79 20 62 65 20 72 65 70 6c 61 63 65 64 20 62  ay be replaced b
28400 79 20 61 20 5b 70 61 72 61 6d 65 74 65 72 5d 20  y a [parameter] 
28410 74 68 61 74 20 6d 61 74 63 68 65 73 20 6f 6e 65  that matches one
28420 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a   of following.**
28430 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a   templates:.**.*
28440 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20  * <ul>.** <li>  
28450 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a  ?.** <li>  ?NNN.
28460 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a  ** <li>  :VVV.**
28470 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c   <li>  @VVV.** <
28480 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75  li>  $VVV.** </u
28490 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20  l>.**.** In the 
284a0 74 65 6d 70 6c 61 74 65 73 20 61 62 6f 76 65 2c  templates above,
284b0 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e 74 73 20   NNN represents 
284c0 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65 72  an integer liter
284d0 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20 72  al,.** and VVV r
284e0 65 70 72 65 73 65 6e 74 73 20 61 6e 20 61 6c 70  epresents an alp
284f0 68 61 6e 75 6d 65 72 69 63 20 69 64 65 6e 74 69  hanumeric identi
28500 66 69 65 72 2e 29 5e 20 20 5e 54 68 65 20 76 61  fier.)^  ^The va
28510 6c 75 65 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a  lues of these.**
28520 20 70 61 72 61 6d 65 74 65 72 73 20 28 61 6c 73   parameters (als
28530 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 20 70  o called "host p
28540 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 22 20  arameter names" 
28550 6f 72 20 22 53 51 4c 20 70 61 72 61 6d 65 74 65  or "SQL paramete
28560 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73  rs").** can be s
28570 65 74 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c  et using the sql
28580 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
28590 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20 68  utines defined h
285a0 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ere..**.** ^The 
285b0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
285c0 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  o the sqlite3_bi
285d0 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20  nd_*() routines 
285e0 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70  is always.** a p
285f0 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ointer to the [s
28600 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a  qlite3_stmt] obj
28610 65 63 74 20 72 65 74 75 72 6e 65 64 20 66 72 6f  ect returned fro
28620 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  m.** [sqlite3_pr
28630 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 69  epare_v2()] or i
28640 74 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a  ts variants..**.
28650 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61  ** ^The second a
28660 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69  rgument is the i
28670 6e 64 65 78 20 6f 66 20 74 68 65 20 53 51 4c 20  ndex of the SQL 
28680 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20  parameter to be 
28690 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66  set..** ^The lef
286a0 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 6d 65  tmost SQL parame
286b0 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78  ter has an index
286c0 20 6f 66 20 31 2e 20 20 5e 57 68 65 6e 20 74 68   of 1.  ^When th
286d0 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20  e same named.** 
286e0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73  SQL parameter is
286f0 20 75 73 65 64 20 6d 6f 72 65 20 74 68 61 6e 20   used more than 
28700 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64  once, second and
28710 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f   subsequent.** o
28720 63 63 75 72 72 65 6e 63 65 73 20 68 61 76 65 20  ccurrences have 
28730 74 68 65 20 73 61 6d 65 20 69 6e 64 65 78 20 61  the same index a
28740 73 20 74 68 65 20 66 69 72 73 74 20 6f 63 63 75  s the first occu
28750 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65 20  rrence..** ^The 
28760 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 64 20  index for named 
28770 70 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20 62  parameters can b
28780 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e  e looked up usin
28790 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  g the.** [sqlite
287a0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
287b0 5f 69 6e 64 65 78 28 29 5d 20 41 50 49 20 69 66  _index()] API if
287c0 20 64 65 73 69 72 65 64 2e 20 20 5e 54 68 65 20   desired.  ^The 
287d0 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e  index.** for "?N
287e0 4e 4e 22 20 70 61 72 61 6d 65 74 65 72 73 20 69  NN" parameters i
287f0 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 4e  s the value of N
28800 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20  NN..** ^The NNN 
28810 76 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62 65  value must be be
28820 74 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65 20  tween 1 and the 
28830 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29  [sqlite3_limit()
28840 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 5b  ].** parameter [
28850 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52  SQLITE_LIMIT_VAR
28860 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64  IABLE_NUMBER] (d
28870 65 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 39  efault value: 99
28880 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74  9)..**.** ^The t
28890 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
288a0 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 62 69   the value to bi
288b0 6e 64 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65  nd to the parame
288c0 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ter..** ^If the 
288d0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
288e0 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  to sqlite3_bind_
288f0 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65  text() or sqlite
28900 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 0a  3_bind_text16().
28910 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69  ** or sqlite3_bi
28920 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20 61 20 4e  nd_blob() is a N
28930 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e  ULL pointer then
28940 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
28950 6d 65 74 65 72 0a 2a 2a 20 69 73 20 69 67 6e 6f  meter.** is igno
28960 72 65 64 20 61 6e 64 20 74 68 65 20 65 6e 64 20  red and the end 
28970 72 65 73 75 6c 74 20 69 73 20 74 68 65 20 73 61  result is the sa
28980 6d 65 20 61 73 20 73 71 6c 69 74 65 33 5f 62 69  me as sqlite3_bi
28990 6e 64 5f 6e 75 6c 6c 28 29 2e 0a 2a 2a 0a 2a 2a  nd_null()..**.**
289a0 20 5e 28 49 6e 20 74 68 6f 73 65 20 72 6f 75 74   ^(In those rout
289b0 69 6e 65 73 20 74 68 61 74 20 68 61 76 65 20 61  ines that have a
289c0 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
289d0 2c 20 69 74 73 20 76 61 6c 75 65 20 69 73 20 74  , its value is t
289e0 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
289f0 62 79 74 65 73 20 69 6e 20 74 68 65 20 70 61 72  bytes in the par
28a00 61 6d 65 74 65 72 2e 20 20 54 6f 20 62 65 20 63  ameter.  To be c
28a10 6c 65 61 72 3a 20 74 68 65 20 76 61 6c 75 65 20  lear: the value 
28a20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  is the.** number
28a30 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e   of <u>bytes</u>
28a40 20 69 6e 20 74 68 65 20 76 61 6c 75 65 2c 20 6e   in the value, n
28a50 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ot the number of
28a60 20 63 68 61 72 61 63 74 65 72 73 2e 29 5e 0a 2a   characters.)^.*
28a70 2a 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68  * ^If the fourth
28a80 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
28a90 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
28aa0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e  ) or sqlite3_bin
28ab0 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 69 73  d_text16().** is
28ac0 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20   negative, then 
28ad0 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68  the length of th
28ae0 65 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74  e string is.** t
28af0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
28b00 65 73 20 75 70 20 74 6f 20 74 68 65 20 66 69 72  es up to the fir
28b10 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  st zero terminat
28b20 6f 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 6f  or..** If the fo
28b30 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
28b40 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62  o sqlite3_bind_b
28b50 6c 6f 62 28 29 20 69 73 20 6e 65 67 61 74 69 76  lob() is negativ
28b60 65 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 62  e, then.** the b
28b70 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66  ehavior is undef
28b80 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 61 20 6e 6f  ined..** If a no
28b90 6e 2d 6e 65 67 61 74 69 76 65 20 66 6f 75 72 74  n-negative fourt
28ba0 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70  h parameter is p
28bb0 72 6f 76 69 64 65 64 20 74 6f 20 73 71 6c 69 74  rovided to sqlit
28bc0 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 0a 2a  e3_bind_text().*
28bd0 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e  * or sqlite3_bin
28be0 64 5f 74 65 78 74 31 36 28 29 20 74 68 65 6e 20  d_text16() then 
28bf0 74 68 61 74 20 70 61 72 61 6d 65 74 65 72 20 6d  that parameter m
28c00 75 73 74 20 62 65 20 74 68 65 20 62 79 74 65 20  ust be the byte 
28c10 6f 66 66 73 65 74 0a 2a 2a 20 77 68 65 72 65 20  offset.** where 
28c20 74 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74  the NUL terminat
28c30 6f 72 20 77 6f 75 6c 64 20 6f 63 63 75 72 20 61  or would occur a
28c40 73 73 75 6d 69 6e 67 20 74 68 65 20 73 74 72 69  ssuming the stri
28c50 6e 67 20 77 65 72 65 20 4e 55 4c 0a 2a 2a 20 74  ng were NUL.** t
28c60 65 72 6d 69 6e 61 74 65 64 2e 20 20 49 66 20 61  erminated.  If a
28c70 6e 79 20 4e 55 4c 20 63 68 61 72 61 63 74 65 72  ny NUL character
28c80 73 20 6f 63 63 75 72 20 61 74 20 62 79 74 65 20  s occur at byte 
28c90 6f 66 66 73 65 74 73 20 6c 65 73 73 20 74 68 61  offsets less tha
28ca0 6e 20 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20  n .** the value 
28cb0 6f 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  of the fourth pa
28cc0 72 61 6d 65 74 65 72 20 74 68 65 6e 20 74 68 65  rameter then the
28cd0 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e   resulting strin
28ce0 67 20 76 61 6c 75 65 20 77 69 6c 6c 0a 2a 2a 20  g value will.** 
28cf0 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64 65 64  contain embedded
28d00 20 4e 55 4c 73 2e 20 20 54 68 65 20 72 65 73 75   NULs.  The resu
28d10 6c 74 20 6f 66 20 65 78 70 72 65 73 73 69 6f 6e  lt of expression
28d20 73 20 69 6e 76 6f 6c 76 69 6e 67 20 73 74 72 69  s involving stri
28d30 6e 67 73 0a 2a 2a 20 77 69 74 68 20 65 6d 62 65  ngs.** with embe
28d40 64 64 65 64 20 4e 55 4c 73 20 69 73 20 75 6e 64  dded NULs is und
28d50 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  efined..**.** ^T
28d60 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e  he fifth argumen
28d70 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  t to sqlite3_bin
28d80 64 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65  d_blob(), sqlite
28d90 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c 20 61  3_bind_text(), a
28da0 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69  nd.** sqlite3_bi
28db0 6e 64 5f 74 65 78 74 31 36 28 29 20 69 73 20 61  nd_text16() is a
28dc0 20 64 65 73 74 72 75 63 74 6f 72 20 75 73 65 64   destructor used
28dd0 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74   to dispose of t
28de0 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74  he BLOB or.** st
28df0 72 69 6e 67 20 61 66 74 65 72 20 53 51 4c 69 74  ring after SQLit
28e00 65 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77  e has finished w
28e10 69 74 68 20 69 74 2e 20 20 5e 54 68 65 20 64 65  ith it.  ^The de
28e20 73 74 72 75 63 74 6f 72 20 69 73 20 63 61 6c 6c  structor is call
28e30 65 64 0a 2a 2a 20 74 6f 20 64 69 73 70 6f 73 65  ed.** to dispose
28e40 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 20   of the BLOB or 
28e50 73 74 72 69 6e 67 20 65 76 65 6e 20 69 66 20 74  string even if t
28e60 68 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  he call to sqlit
28e70 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 0a  e3_bind_blob(),.
28e80 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  ** sqlite3_bind_
28e90 74 65 78 74 28 29 2c 20 6f 72 20 73 71 6c 69 74  text(), or sqlit
28ea0 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29  e3_bind_text16()
28eb0 20 66 61 69 6c 73 2e 20 20 0a 2a 2a 20 5e 49 66   fails.  .** ^If
28ec0 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d   the fifth argum
28ed0 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73 70  ent is.** the sp
28ee0 65 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c  ecial value [SQL
28ef0 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 65  ITE_STATIC], the
28f00 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73  n SQLite assumes
28f10 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66   that the.** inf
28f20 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20 73  ormation is in s
28f30 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64  tatic, unmanaged
28f40 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20   space and does 
28f50 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 66  not need to be f
28f60 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  reed..** ^If the
28f70 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20   fifth argument 
28f80 68 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b 53  has the value [S
28f90 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d  QLITE_TRANSIENT]
28fa0 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65  , then.** SQLite
28fb0 20 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 70   makes its own p
28fc0 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74  rivate copy of t
28fd0 68 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61 74  he data immediat
28fe0 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74  ely, before.** t
28ff0 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
29000 2a 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  *() routine retu
29010 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  rns..**.** ^The 
29020 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72  sqlite3_bind_zer
29030 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 20  oblob() routine 
29040 62 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 20  binds a BLOB of 
29050 6c 65 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a  length N that.**
29060 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20   is filled with 
29070 7a 65 72 6f 65 73 2e 20 20 5e 41 20 7a 65 72 6f  zeroes.  ^A zero
29080 62 6c 6f 62 20 75 73 65 73 20 61 20 66 69 78 65  blob uses a fixe
29090 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f  d amount of memo
290a0 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69  ry.** (just an i
290b0 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 20 69  nteger to hold i
290c0 74 73 20 73 69 7a 65 29 20 77 68 69 6c 65 20 69  ts size) while i
290d0 74 20 69 73 20 62 65 69 6e 67 20 70 72 6f 63 65  t is being proce
290e0 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f  ssed..** Zeroblo
290f0 62 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20  bs are intended 
29100 74 6f 20 73 65 72 76 65 20 61 73 20 70 6c 61 63  to serve as plac
29110 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f  eholders for BLO
29120 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74  Bs whose.** cont
29130 65 6e 74 20 69 73 20 6c 61 74 65 72 20 77 72 69  ent is later wri
29140 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  tten using.** [s
29150 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e  qlite3_blob_open
29160 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42   | incremental B
29170 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65  LOB I/O] routine
29180 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 69 76  s..** ^A negativ
29190 65 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20  e value for the 
291a0 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73  zeroblob results
291b0 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74   in a zero-lengt
291c0 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49  h BLOB..**.** ^I
291d0 66 20 61 6e 79 20 6f 66 20 74 68 65 20 73 71 6c  f any of the sql
291e0 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
291f0 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65  utines are calle
29200 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f  d with a NULL po
29210 69 6e 74 65 72 0a 2a 2a 20 66 6f 72 20 74 68 65  inter.** for the
29220 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
29230 6d 65 6e 74 5d 20 6f 72 20 77 69 74 68 20 61 20  ment] or with a 
29240 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
29250 6e 74 20 66 6f 72 20 77 68 69 63 68 0a 2a 2a 20  nt for which.** 
29260 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
29270 20 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 64   has been called
29280 20 6d 6f 72 65 20 72 65 63 65 6e 74 6c 79 20 74   more recently t
29290 68 61 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  han [sqlite3_res
292a0 65 74 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74  et()],.** then t
292b0 68 65 20 63 61 6c 6c 20 77 69 6c 6c 20 72 65 74  he call will ret
292c0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  urn [SQLITE_MISU
292d0 53 45 5d 2e 20 20 49 66 20 61 6e 79 20 73 71 6c  SE].  If any sql
292e0 69 74 65 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20  ite3_bind_().** 
292f0 72 6f 75 74 69 6e 65 20 69 73 20 70 61 73 73 65  routine is passe
29300 64 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  d a [prepared st
29310 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61  atement] that ha
29320 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64  s been finalized
29330 2c 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20  , the.** result 
29340 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64  is undefined and
29350 20 70 72 6f 62 61 62 6c 79 20 68 61 72 6d 66 75   probably harmfu
29360 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e  l..**.** ^Bindin
29370 67 73 20 61 72 65 20 6e 6f 74 20 63 6c 65 61 72  gs are not clear
29380 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74  ed by the [sqlit
29390 65 33 5f 72 65 73 65 74 28 29 5d 20 72 6f 75 74  e3_reset()] rout
293a0 69 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64  ine..** ^Unbound
293b0 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20   parameters are 
293c0 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 4e  interpreted as N
293d0 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ULL..**.** ^The 
293e0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20 72  sqlite3_bind_* r
293f0 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b  outines return [
29400 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75  SQLITE_OK] on su
29410 63 63 65 73 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b  ccess or an.** [
29420 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61  error code] if a
29430 6e 79 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f  nything goes wro
29440 6e 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f  ng..** ^[SQLITE_
29450 52 41 4e 47 45 5d 20 69 73 20 72 65 74 75 72 6e  RANGE] is return
29460 65 64 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  ed if the parame
29470 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20  ter.** index is 
29480 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 5e  out of range.  ^
29490 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69  [SQLITE_NOMEM] i
294a0 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6d 61  s returned if ma
294b0 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a  lloc() fails..**
294c0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
294d0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
294e0 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a  meter_count()],.
294f0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
29500 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
29510 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  )], and [sqlite3
29520 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
29530 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c  index()]..*/.SQL
29540 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
29550 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71  te3_bind_blob(sq
29560 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
29570 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
29580 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f  nt n, void(*)(vo
29590 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50  id*));.SQLITE_AP
295a0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  I int sqlite3_bi
295b0 6e 64 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65  nd_double(sqlite
295c0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f  3_stmt*, int, do
295d0 75 62 6c 65 29 3b 0a 53 51 4c 49 54 45 5f 41 50  uble);.SQLITE_AP
295e0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  I int sqlite3_bi
295f0 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73  nd_int(sqlite3_s
29600 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b  tmt*, int, int);
29610 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
29620 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74  sqlite3_bind_int
29630 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  64(sqlite3_stmt*
29640 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69  , int, sqlite3_i
29650 6e 74 36 34 29 3b 0a 53 51 4c 49 54 45 5f 41 50  nt64);.SQLITE_AP
29660 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  I int sqlite3_bi
29670 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f  nd_null(sqlite3_
29680 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c  stmt*, int);.SQL
29690 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
296a0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 71  te3_bind_text(sq
296b0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
296c0 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69  , const char*, i
296d0 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f  nt n, void(*)(vo
296e0 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50  id*));.SQLITE_AP
296f0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  I int sqlite3_bi
29700 6e 64 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65  nd_text16(sqlite
29710 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
29720 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20  nst void*, int, 
29730 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
29740 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
29750 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c  sqlite3_bind_val
29760 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ue(sqlite3_stmt*
29770 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c  , int, const sql
29780 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51  ite3_value*);.SQ
29790 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
297a0 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c  ite3_bind_zerobl
297b0 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ob(sqlite3_stmt*
297c0 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a  , int, int n);..
297d0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
297e0 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c 20 50 61  Number Of SQL Pa
297f0 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 5e  rameters.**.** ^
29800 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e  This routine can
29810 20 62 65 20 75 73 65 64 20 74 6f 20 66 69 6e 64   be used to find
29820 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b   the number of [
29830 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 5d 0a  SQL parameters].
29840 2a 2a 20 69 6e 20 61 20 5b 70 72 65 70 61 72 65  ** in a [prepare
29850 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53  d statement].  S
29860 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 61 72  QL parameters ar
29870 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a  e tokens of the.
29880 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e  ** form "?", "?N
29890 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22 24 41  NN", ":AAA", "$A
298a0 41 41 22 2c 20 6f 72 20 22 40 41 41 41 22 20 74  AA", or "@AAA" t
298b0 68 61 74 20 73 65 72 76 65 20 61 73 0a 2a 2a 20  hat serve as.** 
298c0 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72  placeholders for
298d0 20 76 61 6c 75 65 73 20 74 68 61 74 20 61 72 65   values that are
298e0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
298f0 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20  lob | bound].** 
29900 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  to the parameter
29910 73 20 61 74 20 61 20 6c 61 74 65 72 20 74 69 6d  s at a later tim
29920 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20  e..**.** ^(This 
29930 72 6f 75 74 69 6e 65 20 61 63 74 75 61 6c 6c 79  routine actually
29940 20 72 65 74 75 72 6e 73 20 74 68 65 20 69 6e 64   returns the ind
29950 65 78 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73  ex of the larges
29960 74 20 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a  t (rightmost).**
29970 20 70 61 72 61 6d 65 74 65 72 2e 20 46 6f 72 20   parameter. For 
29980 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65 70 74  all forms except
29990 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c   ?NNN, this will
299a0 20 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20 74   correspond to t
299b0 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
299c0 75 6e 69 71 75 65 20 70 61 72 61 6d 65 74 65 72  unique parameter
299d0 73 2e 20 20 49 66 20 70 61 72 61 6d 65 74 65 72  s.  If parameter
299e0 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 66 6f  s of the ?NNN fo
299f0 72 6d 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20  rm are used,.** 
29a00 74 68 65 72 65 20 6d 61 79 20 62 65 20 67 61 70  there may be gap
29a10 73 20 69 6e 20 74 68 65 20 6c 69 73 74 2e 29 5e  s in the list.)^
29a20 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
29a30 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
29a40 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64  lob|sqlite3_bind
29a50 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
29a60 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
29a70 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  name()], and.** 
29a80 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
29a90 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
29aa0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
29ab0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
29ac0 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74  _parameter_count
29ad0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
29ae0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
29af0 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73 74  : Name Of A Host
29b00 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a 0a 2a 2a   Parameter.**.**
29b10 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69   ^The sqlite3_bi
29b20 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
29b30 65 28 50 2c 4e 29 20 69 6e 74 65 72 66 61 63 65  e(P,N) interface
29b40 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20   returns.** the 
29b50 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e 2d 74 68  name of the N-th
29b60 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d   [SQL parameter]
29b70 20 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65   in the [prepare
29b80 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a  d statement] P..
29b90 2a 2a 20 5e 28 53 51 4c 20 70 61 72 61 6d 65 74  ** ^(SQL paramet
29ba0 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20  ers of the form 
29bb0 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22  "?NNN" or ":AAA"
29bc0 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24   or "@AAA" or "$
29bd0 41 41 41 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e  AAA".** have a n
29be0 61 6d 65 20 77 68 69 63 68 20 69 73 20 74 68 65  ame which is the
29bf0 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f   string "?NNN" o
29c00 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41  r ":AAA" or "@AA
29c10 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20  A" or "$AAA".** 
29c20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a  respectively..**
29c30 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
29c40 20 74 68 65 20 69 6e 69 74 69 61 6c 20 22 3a 22   the initial ":"
29c50 20 6f 72 20 22 24 22 20 6f 72 20 22 40 22 20 6f   or "$" or "@" o
29c60 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c  r "?".** is incl
29c70 75 64 65 64 20 61 73 20 70 61 72 74 20 6f 66 20  uded as part of 
29c80 74 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e  the name.)^.** ^
29c90 50 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68  Parameters of th
29ca0 65 20 66 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f  e form "?" witho
29cb0 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69  ut a following i
29cc0 6e 74 65 67 65 72 20 68 61 76 65 20 6e 6f 20 6e  nteger have no n
29cd0 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20 72  ame.** and are r
29ce0 65 66 65 72 72 65 64 20 74 6f 20 61 73 20 22 6e  eferred to as "n
29cf0 61 6d 65 6c 65 73 73 22 20 6f 72 20 22 61 6e 6f  ameless" or "ano
29d00 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65 74 65 72  nymous parameter
29d10 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  s"..**.** ^The f
29d20 69 72 73 74 20 68 6f 73 74 20 70 61 72 61 6d 65  irst host parame
29d30 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78  ter has an index
29d40 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a   of 1, not 0..**
29d50 0a 2a 2a 20 5e 49 66 20 74 68 65 20 76 61 6c 75  .** ^If the valu
29d60 65 20 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61  e N is out of ra
29d70 6e 67 65 20 6f 72 20 69 66 20 74 68 65 20 4e 2d  nge or if the N-
29d80 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a  th parameter is.
29d90 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65  ** nameless, the
29da0 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e  n NULL is return
29db0 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e  ed.  ^The return
29dc0 65 64 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20  ed string is.** 
29dd0 61 6c 77 61 79 73 20 69 6e 20 55 54 46 2d 38 20  always in UTF-8 
29de0 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20 69 66  encoding even if
29df0 20 74 68 65 20 6e 61 6d 65 64 20 70 61 72 61 6d   the named param
29e00 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67  eter was.** orig
29e10 69 6e 61 6c 6c 79 20 73 70 65 63 69 66 69 65 64  inally specified
29e20 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 5b 73   as UTF-16 in [s
29e30 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
29e40 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
29e50 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
29e60 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  )]..**.** See al
29e70 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  so: [sqlite3_bin
29e80 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62  d_blob|sqlite3_b
29e90 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ind()],.** [sqli
29ea0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
29eb0 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64  er_count()], and
29ec0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
29ed0 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
29ee0 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  x()]..*/.SQLITE_
29ef0 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  API const char *
29f00 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
29f10 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69  ameter_name(sqli
29f20 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b  te3_stmt*, int);
29f30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
29f40 3a 20 49 6e 64 65 78 20 4f 66 20 41 20 50 61 72  : Index Of A Par
29f50 61 6d 65 74 65 72 20 57 69 74 68 20 41 20 47 69  ameter With A Gi
29f60 76 65 6e 20 4e 61 6d 65 0a 2a 2a 0a 2a 2a 20 5e  ven Name.**.** ^
29f70 52 65 74 75 72 6e 20 74 68 65 20 69 6e 64 65 78  Return the index
29f80 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 61 6d   of an SQL param
29f90 65 74 65 72 20 67 69 76 65 6e 20 69 74 73 20 6e  eter given its n
29fa0 61 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 69 6e  ame.  ^The.** in
29fb0 64 65 78 20 76 61 6c 75 65 20 72 65 74 75 72 6e  dex value return
29fc0 65 64 20 69 73 20 73 75 69 74 61 62 6c 65 20 66  ed is suitable f
29fd0 6f 72 20 75 73 65 20 61 73 20 74 68 65 20 73 65  or use as the se
29fe0 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65  cond.** paramete
29ff0 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69  r to [sqlite3_bi
2a000 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f  nd_blob|sqlite3_
2a010 62 69 6e 64 28 29 5d 2e 20 20 5e 41 20 7a 65 72  bind()].  ^A zer
2a020 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64  o.** is returned
2a030 20 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20   if no matching 
2a040 70 61 72 61 6d 65 74 65 72 20 69 73 20 66 6f 75  parameter is fou
2a050 6e 64 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65  nd.  ^The parame
2a060 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74  ter.** name must
2a070 20 62 65 20 67 69 76 65 6e 20 69 6e 20 55 54 46   be given in UTF
2a080 2d 38 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f  -8 even if the o
2a090 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e  riginal statemen
2a0a0 74 0a 2a 2a 20 77 61 73 20 70 72 65 70 61 72 65  t.** was prepare
2a0b0 64 20 66 72 6f 6d 20 55 54 46 2d 31 36 20 74 65  d from UTF-16 te
2a0c0 78 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  xt using [sqlite
2a0d0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
2a0e0 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  ]..**.** See als
2a0f0 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  o: [sqlite3_bind
2a100 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69  _blob|sqlite3_bi
2a110 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  nd()],.** [sqlit
2a120 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2a130 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a  r_count()], and.
2a140 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
2a150 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
2a160 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ()]..*/.SQLITE_A
2a170 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  PI int sqlite3_b
2a180 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
2a190 64 65 78 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  dex(sqlite3_stmt
2a1a0 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
2a1b0 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Name);../*.** CA
2a1c0 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 6c  PI3REF: Reset Al
2a1d0 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20  l Bindings On A 
2a1e0 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
2a1f0 6e 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61  nt.**.** ^Contra
2a200 72 79 20 74 6f 20 74 68 65 20 69 6e 74 75 69 74  ry to the intuit
2a210 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71  ion of many, [sq
2a220 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 64  lite3_reset()] d
2a230 6f 65 73 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a  oes not reset.**
2a240 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   the [sqlite3_bi
2a250 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e  nd_blob | bindin
2a260 67 73 5d 20 6f 6e 20 61 20 5b 70 72 65 70 61 72  gs] on a [prepar
2a270 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
2a280 2a 20 5e 55 73 65 20 74 68 69 73 20 72 6f 75 74  * ^Use this rout
2a290 69 6e 65 20 74 6f 20 72 65 73 65 74 20 61 6c 6c  ine to reset all
2a2a0 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73   host parameters
2a2b0 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 53 51 4c   to NULL..*/.SQL
2a2c0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
2a2d0 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e  te3_clear_bindin
2a2e0 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  gs(sqlite3_stmt*
2a2f0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2a300 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f  EF: Number Of Co
2a310 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65 73 75 6c  lumns In A Resul
2a320 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74  t Set.**.** ^Ret
2a330 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  urn the number o
2a340 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65  f columns in the
2a350 20 72 65 73 75 6c 74 20 73 65 74 20 72 65 74 75   result set retu
2a360 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b  rned by the.** [
2a370 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2a380 6e 74 5d 2e 20 5e 54 68 69 73 20 72 6f 75 74 69  nt]. ^This routi
2a390 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69 66 20  ne returns 0 if 
2a3a0 70 53 74 6d 74 20 69 73 20 61 6e 20 53 51 4c 0a  pStmt is an SQL.
2a3b0 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61  ** statement tha
2a3c0 74 20 64 6f 65 73 20 6e 6f 74 20 72 65 74 75 72  t does not retur
2a3d0 6e 20 64 61 74 61 20 28 66 6f 72 20 65 78 61 6d  n data (for exam
2a3e0 70 6c 65 20 61 6e 20 5b 55 50 44 41 54 45 5d 29  ple an [UPDATE])
2a3f0 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
2a400 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  : [sqlite3_data_
2a410 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 53 51 4c 49  count()].*/.SQLI
2a420 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
2a430 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28  e3_column_count(
2a440 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
2a450 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
2a460 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61  I3REF: Column Na
2a470 6d 65 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20  mes In A Result 
2a480 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  Set.**.** ^These
2a490 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
2a4a0 20 74 68 65 20 6e 61 6d 65 20 61 73 73 69 67 6e   the name assign
2a4b0 65 64 20 74 6f 20 61 20 70 61 72 74 69 63 75 6c  ed to a particul
2a4c0 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20  ar column.** in 
2a4d0 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f  the result set o
2a4e0 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  f a [SELECT] sta
2a4f0 74 65 6d 65 6e 74 2e 20 20 5e 54 68 65 20 73 71  tement.  ^The sq
2a500 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
2a510 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  e().** interface
2a520 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
2a530 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72  er to a zero-ter
2a540 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74  minated UTF-8 st
2a550 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69  ring.** and sqli
2a560 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31  te3_column_name1
2a570 36 28 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f  6() returns a po
2a580 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d  inter to a zero-
2a590 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54  terminated.** UT
2a5a0 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54  F-16 string.  ^T
2a5b0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
2a5c0 65 72 20 69 73 20 74 68 65 20 5b 70 72 65 70 61  er is the [prepa
2a5d0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a  red statement].*
2a5e0 2a 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74  * that implement
2a5f0 73 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73  s the [SELECT] s
2a600 74 61 74 65 6d 65 6e 74 2e 20 5e 54 68 65 20 73  tatement. ^The s
2a610 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
2a620 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e  is the.** column
2a630 20 6e 75 6d 62 65 72 2e 20 20 5e 54 68 65 20 6c   number.  ^The l
2a640 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69  eftmost column i
2a650 73 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a  s number 0..**.*
2a660 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20  * ^The returned 
2a670 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 69  string pointer i
2a680 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 65 69  s valid until ei
2a690 74 68 65 72 20 74 68 65 20 5b 70 72 65 70 61 72  ther the [prepar
2a6a0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a  ed statement].**
2a6b0 20 69 73 20 64 65 73 74 72 6f 79 65 64 20 62 79   is destroyed by
2a6c0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
2a6d0 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74  ze()] or until t
2a6e0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
2a6f0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a  automatically.**
2a700 20 72 65 70 72 65 70 61 72 65 64 20 62 79 20 74   reprepared by t
2a710 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f  he first call to
2a720 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2a730 5d 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c  ] for a particul
2a740 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74  ar run.** or unt
2a750 69 6c 20 74 68 65 20 6e 65 78 74 20 63 61 6c 6c  il the next call
2a760 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   to.** sqlite3_c
2a770 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72 20  olumn_name() or 
2a780 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
2a790 61 6d 65 31 36 28 29 20 6f 6e 20 74 68 65 20 73  ame16() on the s
2a7a0 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a  ame column..**.*
2a7b0 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61  * ^If sqlite3_ma
2a7c0 6c 6c 6f 63 28 29 20 66 61 69 6c 73 20 64 75 72  lloc() fails dur
2a7d0 69 6e 67 20 74 68 65 20 70 72 6f 63 65 73 73 69  ing the processi
2a7e0 6e 67 20 6f 66 20 65 69 74 68 65 72 20 72 6f 75  ng of either rou
2a7f0 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61  tine.** (for exa
2a800 6d 70 6c 65 20 64 75 72 69 6e 67 20 61 20 63 6f  mple during a co
2a810 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54  nversion from UT
2a820 46 2d 38 20 74 6f 20 55 54 46 2d 31 36 29 20 74  F-8 to UTF-16) t
2a830 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f  hen a.** NULL po
2a840 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65  inter is returne
2a850 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61  d..**.** ^The na
2a860 6d 65 20 6f 66 20 61 20 72 65 73 75 6c 74 20 63  me of a result c
2a870 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20 76 61 6c  olumn is the val
2a880 75 65 20 6f 66 20 74 68 65 20 22 41 53 22 20 63  ue of the "AS" c
2a890 6c 61 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 61  lause for.** tha
2a8a0 74 20 63 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 65  t column, if the
2a8b0 72 65 20 69 73 20 61 6e 20 41 53 20 63 6c 61 75  re is an AS clau
2a8c0 73 65 2e 20 20 49 66 20 74 68 65 72 65 20 69 73  se.  If there is
2a8d0 20 6e 6f 20 41 53 20 63 6c 61 75 73 65 0a 2a 2a   no AS clause.**
2a8e0 20 74 68 65 6e 20 74 68 65 20 6e 61 6d 65 20 6f   then the name o
2a8f0 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20  f the column is 
2a900 75 6e 73 70 65 63 69 66 69 65 64 20 61 6e 64 20  unspecified and 
2a910 6d 61 79 20 63 68 61 6e 67 65 20 66 72 6f 6d 0a  may change from.
2a920 2a 2a 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 6f  ** one release o
2a930 66 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20  f SQLite to the 
2a940 6e 65 78 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  next..*/.SQLITE_
2a950 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  API const char *
2a960 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
2a970 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
2a980 2a 2c 20 69 6e 74 20 4e 29 3b 0a 53 51 4c 49 54  *, int N);.SQLIT
2a990 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64  E_API const void
2a9a0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2a9b0 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
2a9c0 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a  stmt*, int N);..
2a9d0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2a9e0 53 6f 75 72 63 65 20 4f 66 20 44 61 74 61 20 49  Source Of Data I
2a9f0 6e 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74  n A Query Result
2aa00 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
2aa10 75 74 69 6e 65 73 20 70 72 6f 76 69 64 65 20 61  utines provide a
2aa20 20 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 72 6d   means to determ
2aa30 69 6e 65 20 74 68 65 20 64 61 74 61 62 61 73 65  ine the database
2aa40 2c 20 74 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20  , table, and.** 
2aa50 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61  table column tha
2aa60 74 20 69 73 20 74 68 65 20 6f 72 69 67 69 6e 20  t is the origin 
2aa70 6f 66 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  of a particular 
2aa80 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e  result column in
2aa90 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  .** [SELECT] sta
2aaa0 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20  tement..** ^The 
2aab0 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61  name of the data
2aac0 62 61 73 65 20 6f 72 20 74 61 62 6c 65 20 6f 72  base or table or
2aad0 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72   column can be r
2aae0 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69  eturned as.** ei
2aaf0 74 68 65 72 20 61 20 55 54 46 2d 38 20 6f 72 20  ther a UTF-8 or 
2ab00 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20  UTF-16 string.  
2ab10 5e 54 68 65 20 5f 64 61 74 61 62 61 73 65 5f 20  ^The _database_ 
2ab20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 0a  routines return.
2ab30 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
2ab40 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c 65  name, the _table
2ab50 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  _ routines retur
2ab60 6e 20 74 68 65 20 74 61 62 6c 65 20 6e 61 6d 65  n the table name
2ab70 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69  , and.** the ori
2ab80 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72 65  gin_ routines re
2ab90 74 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20  turn the column 
2aba0 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 72 65  name..** ^The re
2abb0 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73  turned string is
2abc0 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65   valid until the
2abd0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2abe0 6d 65 6e 74 5d 20 69 73 20 64 65 73 74 72 6f 79  ment] is destroy
2abf0 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c  ed.** using [sql
2ac00 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
2ac10 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74   or until the st
2ac20 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d  atement is autom
2ac30 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72  atically.** repr
2ac40 65 70 61 72 65 64 20 62 79 20 74 68 65 20 66 69  epared by the fi
2ac50 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  rst call to [sql
2ac60 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72  ite3_step()] for
2ac70 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 75   a particular ru
2ac80 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68  n.** or until th
2ac90 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69  e same informati
2aca0 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65 64 0a  on is requested.
2acb0 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 64 69  ** again in a di
2acc0 66 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67  fferent encoding
2acd0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d  ..**.** ^The nam
2ace0 65 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20  es returned are 
2acf0 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d  the original un-
2ad00 61 6c 69 61 73 65 64 20 6e 61 6d 65 73 20 6f 66  aliased names of
2ad10 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
2ad20 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c  , table, and col
2ad30 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  umn..**.** ^The 
2ad40 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
2ad50 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63  o these interfac
2ad60 65 73 20 69 73 20 61 20 5b 70 72 65 70 61 72 65  es is a [prepare
2ad70 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a  d statement]..**
2ad80 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e   ^These function
2ad90 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61  s return informa
2ada0 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4e  tion about the N
2adb0 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  th result column
2adc0 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
2add0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2c 20 77  the statement, w
2ade0 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65  here N is the se
2adf0 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72  cond function ar
2ae00 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20  gument..** ^The 
2ae10 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e  left-most column
2ae20 20 69 73 20 63 6f 6c 75 6d 6e 20 30 20 66 6f 72   is column 0 for
2ae30 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e   these routines.
2ae40 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e  .**.** ^If the N
2ae50 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e  th column return
2ae60 65 64 20 62 79 20 74 68 65 20 73 74 61 74 65 6d  ed by the statem
2ae70 65 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65 73  ent is an expres
2ae80 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75  sion or.** subqu
2ae90 65 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 61  ery and is not a
2aea0 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74   column value, t
2aeb0 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 65  hen all of these
2aec0 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72   functions retur
2aed0 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68 65  n.** NULL.  ^The
2aee0 73 65 20 72 6f 75 74 69 6e 65 20 6d 69 67 68 74  se routine might
2aef0 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c   also return NUL
2af00 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c  L if a memory al
2af10 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a  location error.*
2af20 2a 20 6f 63 63 75 72 73 2e 20 20 5e 4f 74 68 65  * occurs.  ^Othe
2af30 72 77 69 73 65 2c 20 74 68 65 79 20 72 65 74 75  rwise, they retu
2af40 72 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  rn the name of t
2af50 68 65 20 61 74 74 61 63 68 65 64 20 64 61 74 61  he attached data
2af60 62 61 73 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20  base, table,.** 
2af70 6f 72 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71  or column that q
2af80 75 65 72 79 20 72 65 73 75 6c 74 20 63 6f 6c 75  uery result colu
2af90 6d 6e 20 77 61 73 20 65 78 74 72 61 63 74 65 64  mn was extracted
2afa0 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73   from..**.** ^As
2afb0 20 77 69 74 68 20 61 6c 6c 20 6f 74 68 65 72 20   with all other 
2afc0 53 51 4c 69 74 65 20 41 50 49 73 2c 20 74 68 6f  SQLite APIs, tho
2afd0 73 65 20 77 68 6f 73 65 20 6e 61 6d 65 73 20 65  se whose names e
2afe0 6e 64 20 77 69 74 68 20 22 31 36 22 20 72 65 74  nd with "16" ret
2aff0 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e  urn.** UTF-16 en
2b000 63 6f 64 65 64 20 73 74 72 69 6e 67 73 20 61 6e  coded strings an
2b010 64 20 74 68 65 20 6f 74 68 65 72 20 66 75 6e 63  d the other func
2b020 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 55 54 46  tions return UTF
2b030 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  -8..**.** ^These
2b040 20 41 50 49 73 20 61 72 65 20 6f 6e 6c 79 20 61   APIs are only a
2b050 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20  vailable if the 
2b060 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70  library was comp
2b070 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a  iled with the.**
2b080 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
2b090 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d  COLUMN_METADATA]
2b0a0 20 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20   C-preprocessor 
2b0b0 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66  symbol..**.** If
2b0c0 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72   two or more thr
2b0d0 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72  eads call one or
2b0e0 20 6d 6f 72 65 20 6f 66 20 74 68 65 73 65 20 72   more of these r
2b0f0 6f 75 74 69 6e 65 73 20 61 67 61 69 6e 73 74 20  outines against 
2b100 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70  the same.** prep
2b110 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61  ared statement a
2b120 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65  nd column at the
2b130 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20   same time then 
2b140 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 0a  the results are.
2b150 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  ** undefined..**
2b160 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f  .** If two or mo
2b170 72 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20  re threads call 
2b180 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b  one or more.** [
2b190 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
2b1a0 61 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63  atabase_name | c
2b1b0 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 20 69  olumn metadata i
2b1c0 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 66 6f  nterfaces].** fo
2b1d0 72 20 74 68 65 20 73 61 6d 65 20 5b 70 72 65 70  r the same [prep
2b1e0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2b1f0 61 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  and result colum
2b200 6e 0a 2a 2a 20 61 74 20 74 68 65 20 73 61 6d 65  n.** at the same
2b210 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72   time then the r
2b220 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66  esults are undef
2b230 69 6e 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  ined..*/.SQLITE_
2b240 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  API const char *
2b250 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
2b260 61 74 61 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c  atabase_name(sql
2b270 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
2b280 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
2b290 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
2b2a0 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f  column_database_
2b2b0 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73  name16(sqlite3_s
2b2c0 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54  tmt*,int);.SQLIT
2b2d0 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72  E_API const char
2b2e0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2b2f0 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69  _table_name(sqli
2b300 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
2b310 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
2b320 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
2b330 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65  olumn_table_name
2b340 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
2b350 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50  ,int);.SQLITE_AP
2b360 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  I const char *sq
2b370 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69  lite3_column_ori
2b380 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  gin_name(sqlite3
2b390 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c  _stmt*,int);.SQL
2b3a0 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f  ITE_API const vo
2b3b0 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
2b3c0 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36  mn_origin_name16
2b3d0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
2b3e0 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
2b3f0 33 52 45 46 3a 20 44 65 63 6c 61 72 65 64 20 44  3REF: Declared D
2b400 61 74 61 74 79 70 65 20 4f 66 20 41 20 51 75 65  atatype Of A Que
2b410 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20  ry Result.**.** 
2b420 5e 28 54 68 65 20 66 69 72 73 74 20 70 61 72 61  ^(The first para
2b430 6d 65 74 65 72 20 69 73 20 61 20 5b 70 72 65 70  meter is a [prep
2b440 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
2b450 0a 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61 74  .** If this stat
2b460 65 6d 65 6e 74 20 69 73 20 61 20 5b 53 45 4c 45  ement is a [SELE
2b470 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 6e  CT] statement an
2b480 64 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  d the Nth column
2b490 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74 75 72   of the.** retur
2b4a0 6e 65 64 20 72 65 73 75 6c 74 20 73 65 74 20 6f  ned result set o
2b4b0 66 20 74 68 61 74 20 5b 53 45 4c 45 43 54 5d 20  f that [SELECT] 
2b4c0 69 73 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d  is a table colum
2b4d0 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70  n (not an.** exp
2b4e0 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75  ression or subqu
2b4f0 65 72 79 29 20 74 68 65 6e 20 74 68 65 20 64 65  ery) then the de
2b500 63 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20 74  clared type of t
2b510 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75  he table.** colu
2b520 6d 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29  mn is returned.)
2b530 5e 20 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63  ^  ^If the Nth c
2b540 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73  olumn of the res
2b550 75 6c 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a  ult set is an.**
2b560 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73   expression or s
2b570 75 62 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20  ubquery, then a 
2b580 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20  NULL pointer is 
2b590 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68  returned..** ^Th
2b5a0 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e  e returned strin
2b5b0 67 20 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d  g is always UTF-
2b5c0 38 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a  8 encoded..**.**
2b5d0 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20   ^(For example, 
2b5e0 67 69 76 65 6e 20 74 68 65 20 64 61 74 61 62 61  given the databa
2b5f0 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a  se schema:.**.**
2b600 20 43 52 45 41 54 45 20 54 41 42 4c 45 20 74 31   CREATE TABLE t1
2b610 28 63 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a  (c1 VARIANT);.**
2b620 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c  .** and the foll
2b630 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20  owing statement 
2b640 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a  to be compiled:.
2b650 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31 20  **.** SELECT c1 
2b660 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b  + 1, c1 FROM t1;
2b670 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74  .**.** this rout
2b680 69 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72 6e  ine would return
2b690 20 74 68 65 20 73 74 72 69 6e 67 20 22 56 41 52   the string "VAR
2b6a0 49 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73 65  IANT" for the se
2b6b0 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63  cond result.** c
2b6c0 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e  olumn (i==1), an
2b6d0 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  d a NULL pointer
2b6e0 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 72   for the first r
2b6f0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d  esult column (i=
2b700 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51  =0).)^.**.** ^SQ
2b710 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69  Lite uses dynami
2b720 63 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e  c run-time typin
2b730 67 2e 20 20 5e 53 6f 20 6a 75 73 74 20 62 65 63  g.  ^So just bec
2b740 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a  ause a column.**
2b750 20 69 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20   is declared to 
2b760 63 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63  contain a partic
2b770 75 6c 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e  ular type does n
2b780 6f 74 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65  ot mean that the
2b790 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20  .** data stored 
2b7a0 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69  in that column i
2b7b0 73 20 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65  s of the declare
2b7c0 64 20 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20  d type.  SQLite 
2b7d0 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74  is.** strongly t
2b7e0 79 70 65 64 2c 20 62 75 74 20 74 68 65 20 74 79  yped, but the ty
2b7f0 70 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20  ping is dynamic 
2b800 6e 6f 74 20 73 74 61 74 69 63 2e 20 20 5e 54 79  not static.  ^Ty
2b810 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61  pe.** is associa
2b820 74 65 64 20 77 69 74 68 20 69 6e 64 69 76 69 64  ted with individ
2b830 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20  ual values, not 
2b840 77 69 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e  with the contain
2b850 65 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68  ers.** used to h
2b860 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73  old those values
2b870 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
2b880 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
2b890 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74  te3_column_declt
2b8a0 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ype(sqlite3_stmt
2b8b0 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41  *,int);.SQLITE_A
2b8c0 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  PI const void *s
2b8d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65  qlite3_column_de
2b8e0 63 6c 74 79 70 65 31 36 28 73 71 6c 69 74 65 33  cltype16(sqlite3
2b8f0 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a  _stmt*,int);../*
2b900 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 76  .** CAPI3REF: Ev
2b910 61 6c 75 61 74 65 20 41 6e 20 53 51 4c 20 53 74  aluate An SQL St
2b920 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 41 66  atement.**.** Af
2b930 74 65 72 20 61 20 5b 70 72 65 70 61 72 65 64 20  ter a [prepared 
2b940 73 74 61 74 65 6d 65 6e 74 5d 20 68 61 73 20 62  statement] has b
2b950 65 65 6e 20 70 72 65 70 61 72 65 64 20 75 73 69  een prepared usi
2b960 6e 67 20 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71  ng either.** [sq
2b970 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2b980 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
2b990 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20  prepare16_v2()] 
2b9a0 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65  or one of the le
2b9b0 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63  gacy.** interfac
2b9c0 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  es [sqlite3_prep
2b9d0 61 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  are()] or [sqlit
2b9e0 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c  e3_prepare16()],
2b9f0 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a   this function.*
2ba00 2a 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64  * must be called
2ba10 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d   one or more tim
2ba20 65 73 20 74 6f 20 65 76 61 6c 75 61 74 65 20 74  es to evaluate t
2ba30 68 65 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a  he statement..**
2ba40 0a 2a 2a 20 54 68 65 20 64 65 74 61 69 6c 73 20  .** The details 
2ba50 6f 66 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  of the behavior 
2ba60 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73  of the sqlite3_s
2ba70 74 65 70 28 29 20 69 6e 74 65 72 66 61 63 65 20  tep() interface 
2ba80 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65  depend.** on whe
2ba90 74 68 65 72 20 74 68 65 20 73 74 61 74 65 6d 65  ther the stateme
2baa0 6e 74 20 77 61 73 20 70 72 65 70 61 72 65 64 20  nt was prepared 
2bab0 75 73 69 6e 67 20 74 68 65 20 6e 65 77 65 72 20  using the newer 
2bac0 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 0a 2a  "v2" interface.*
2bad0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
2bae0 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71  re_v2()] and [sq
2baf0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
2bb00 76 32 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64  v2()] or the old
2bb10 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74  er legacy.** int
2bb20 65 72 66 61 63 65 20 5b 73 71 6c 69 74 65 33 5f  erface [sqlite3_
2bb30 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b  prepare()] and [
2bb40 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2bb50 36 28 29 5d 2e 20 20 54 68 65 20 75 73 65 20 6f  6()].  The use o
2bb60 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32  f the.** new "v2
2bb70 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72  " interface is r
2bb80 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e  ecommended for n
2bb90 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  ew applications 
2bba0 62 75 74 20 74 68 65 20 6c 65 67 61 63 79 0a 2a  but the legacy.*
2bbb0 2a 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c  * interface will
2bbc0 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 20   continue to be 
2bbd0 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a  supported..**.**
2bbe0 20 5e 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20   ^In the legacy 
2bbf0 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 72  interface, the r
2bc00 65 74 75 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c  eturn value will
2bc10 20 62 65 20 65 69 74 68 65 72 20 5b 53 51 4c 49   be either [SQLI
2bc20 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51  TE_BUSY],.** [SQ
2bc30 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c  LITE_DONE], [SQL
2bc40 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54  ITE_ROW], [SQLIT
2bc50 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51  E_ERROR], or [SQ
2bc60 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a  LITE_MISUSE]..**
2bc70 20 5e 57 69 74 68 20 74 68 65 20 22 76 32 22 20   ^With the "v2" 
2bc80 69 6e 74 65 72 66 61 63 65 2c 20 61 6e 79 20 6f  interface, any o
2bc90 66 20 74 68 65 20 6f 74 68 65 72 20 5b 72 65 73  f the other [res
2bca0 75 6c 74 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a  ult codes] or.**
2bcb0 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
2bcc0 74 20 63 6f 64 65 73 5d 20 6d 69 67 68 74 20 62  t codes] might b
2bcd0 65 20 72 65 74 75 72 6e 65 64 20 61 73 20 77 65  e returned as we
2bce0 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49  ll..**.** ^[SQLI
2bcf0 54 45 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20 74  TE_BUSY] means t
2bd00 68 61 74 20 74 68 65 20 64 61 74 61 62 61 73 65  hat the database
2bd10 20 65 6e 67 69 6e 65 20 77 61 73 20 75 6e 61 62   engine was unab
2bd20 6c 65 20 74 6f 20 61 63 71 75 69 72 65 20 74 68  le to acquire th
2bd30 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 6c 6f  e.** database lo
2bd40 63 6b 73 20 69 74 20 6e 65 65 64 73 20 74 6f 20  cks it needs to 
2bd50 64 6f 20 69 74 73 20 6a 6f 62 2e 20 20 5e 49 66  do its job.  ^If
2bd60 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
2bd70 73 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20  s a [COMMIT].** 
2bd80 6f 72 20 6f 63 63 75 72 73 20 6f 75 74 73 69 64  or occurs outsid
2bd90 65 20 6f 66 20 61 6e 20 65 78 70 6c 69 63 69 74  e of an explicit
2bda0 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68   transaction, th
2bdb0 65 6e 20 79 6f 75 20 63 61 6e 20 72 65 74 72 79  en you can retry
2bdc0 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e   the.** statemen
2bdd0 74 2e 20 20 49 66 20 74 68 65 20 73 74 61 74 65  t.  If the state
2bde0 6d 65 6e 74 20 69 73 20 6e 6f 74 20 61 20 5b 43  ment is not a [C
2bdf0 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f 63 63 75 72  OMMIT] and occur
2be00 73 20 77 69 74 68 69 6e 20 61 6e 0a 2a 2a 20 65  s within an.** e
2be10 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74  xplicit transact
2be20 69 6f 6e 20 74 68 65 6e 20 79 6f 75 20 73 68 6f  ion then you sho
2be30 75 6c 64 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65  uld rollback the
2be40 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 66   transaction bef
2be50 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e  ore.** continuin
2be60 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54  g..**.** ^[SQLIT
2be70 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68  E_DONE] means th
2be80 61 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  at the statement
2be90 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 65 78   has finished ex
2bea0 65 63 75 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65  ecuting.** succe
2beb0 73 73 66 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65  ssfully.  sqlite
2bec0 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20  3_step() should 
2bed0 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67  not be called ag
2bee0 61 69 6e 20 6f 6e 20 74 68 69 73 20 76 69 72 74  ain on this virt
2bef0 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77  ual.** machine w
2bf00 69 74 68 6f 75 74 20 66 69 72 73 74 20 63 61 6c  ithout first cal
2bf10 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  ling [sqlite3_re
2bf20 73 65 74 28 29 5d 20 74 6f 20 72 65 73 65 74 20  set()] to reset 
2bf30 74 68 65 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d  the virtual.** m
2bf40 61 63 68 69 6e 65 20 62 61 63 6b 20 74 6f 20 69  achine back to i
2bf50 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65  ts initial state
2bf60 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
2bf70 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 62 65  SQL statement be
2bf80 69 6e 67 20 65 78 65 63 75 74 65 64 20 72 65 74  ing executed ret
2bf90 75 72 6e 73 20 61 6e 79 20 64 61 74 61 2c 20 74  urns any data, t
2bfa0 68 65 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  hen [SQLITE_ROW]
2bfb0 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20  .** is returned 
2bfc0 65 61 63 68 20 74 69 6d 65 20 61 20 6e 65 77 20  each time a new 
2bfd0 72 6f 77 20 6f 66 20 64 61 74 61 20 69 73 20 72  row of data is r
2bfe0 65 61 64 79 20 66 6f 72 20 70 72 6f 63 65 73 73  eady for process
2bff0 69 6e 67 20 62 79 20 74 68 65 0a 2a 2a 20 63 61  ing by the.** ca
2c000 6c 6c 65 72 2e 20 54 68 65 20 76 61 6c 75 65 73  ller. The values
2c010 20 6d 61 79 20 62 65 20 61 63 63 65 73 73 65 64   may be accessed
2c020 20 75 73 69 6e 67 20 74 68 65 20 5b 63 6f 6c 75   using the [colu
2c030 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69  mn access functi
2c040 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33  ons]..** sqlite3
2c050 5f 73 74 65 70 28 29 20 69 73 20 63 61 6c 6c 65  _step() is calle
2c060 64 20 61 67 61 69 6e 20 74 6f 20 72 65 74 72 69  d again to retri
2c070 65 76 65 20 74 68 65 20 6e 65 78 74 20 72 6f 77  eve the next row
2c080 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20   of data..**.** 
2c090 5e 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20  ^[SQLITE_ERROR] 
2c0a0 6d 65 61 6e 73 20 74 68 61 74 20 61 20 72 75 6e  means that a run
2c0b0 2d 74 69 6d 65 20 65 72 72 6f 72 20 28 73 75 63  -time error (suc
2c0c0 68 20 61 73 20 61 20 63 6f 6e 73 74 72 61 69 6e  h as a constrain
2c0d0 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20  t.** violation) 
2c0e0 68 61 73 20 6f 63 63 75 72 72 65 64 2e 20 20 73  has occurred.  s
2c0f0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68  qlite3_step() sh
2c100 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c  ould not be call
2c110 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74  ed again on.** t
2c120 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f  he VM. More info
2c130 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62 65 20 66  rmation may be f
2c140 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67 20  ound by calling 
2c150 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
2c160 29 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65  )]..** ^With the
2c170 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63   legacy interfac
2c180 65 2c 20 61 20 6d 6f 72 65 20 73 70 65 63 69 66  e, a more specif
2c190 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 28 66  ic error code (f
2c1a0 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b  or example,.** [
2c1b0 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
2c1c0 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d  ], [SQLITE_SCHEM
2c1d0 41 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52  A], [SQLITE_CORR
2c1e0 55 50 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72  UPT], and so for
2c1f0 74 68 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62  th).** can be ob
2c200 74 61 69 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e  tained by callin
2c210 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
2c220 28 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70  ()] on the.** [p
2c230 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2c240 74 5d 2e 20 20 5e 49 6e 20 74 68 65 20 22 76 32  t].  ^In the "v2
2c250 22 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20  " interface,.** 
2c260 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69  the more specifi
2c270 63 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20  c error code is 
2c280 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c  returned directl
2c290 79 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65  y by sqlite3_ste
2c2a0 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49  p()..**.** [SQLI
2c2b0 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73  TE_MISUSE] means
2c2c0 20 74 68 61 74 20 74 68 65 20 74 68 69 73 20 72   that the this r
2c2d0 6f 75 74 69 6e 65 20 77 61 73 20 63 61 6c 6c 65  outine was calle
2c2e0 64 20 69 6e 61 70 70 72 6f 70 72 69 61 74 65 6c  d inappropriatel
2c2f0 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73 20 69 74  y..** Perhaps it
2c300 20 77 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61   was called on a
2c310 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2c320 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 0a 2a  ment] that has.*
2c330 2a 20 61 6c 72 65 61 64 79 20 62 65 65 6e 20 5b  * already been [
2c340 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2c350 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72   | finalized] or
2c360 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20 68 61 64   on one that had
2c370 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 72  .** previously r
2c380 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f  eturned [SQLITE_
2c390 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54  ERROR] or [SQLIT
2c3a0 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20  E_DONE].  Or it 
2c3b0 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20  could.** be the 
2c3c0 63 61 73 65 20 74 68 61 74 20 74 68 65 20 73 61  case that the sa
2c3d0 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
2c3e0 65 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20  ection is being 
2c3f0 75 73 65 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a  used by two or.*
2c400 2a 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 61  * more threads a
2c410 74 20 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e  t the same momen
2c420 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a  t in time..**.**
2c430 20 46 6f 72 20 61 6c 6c 20 76 65 72 73 69 6f 6e   For all version
2c440 73 20 6f 66 20 53 51 4c 69 74 65 20 75 70 20 74  s of SQLite up t
2c450 6f 20 61 6e 64 20 69 6e 63 6c 75 64 69 6e 67 20  o and including 
2c460 33 2e 36 2e 32 33 2e 31 2c 20 61 20 63 61 6c 6c  3.6.23.1, a call
2c470 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
2c480 72 65 73 65 74 28 29 5d 20 77 61 73 20 72 65 71  reset()] was req
2c490 75 69 72 65 64 20 61 66 74 65 72 20 73 71 6c 69  uired after sqli
2c4a0 74 65 33 5f 73 74 65 70 28 29 20 72 65 74 75 72  te3_step() retur
2c4b0 6e 65 64 20 61 6e 79 74 68 69 6e 67 0a 2a 2a 20  ned anything.** 
2c4c0 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
2c4d0 54 45 5f 52 4f 57 5d 20 62 65 66 6f 72 65 20 61  TE_ROW] before a
2c4e0 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e  ny subsequent in
2c4f0 76 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73  vocation of.** s
2c500 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20  qlite3_step().  
2c510 46 61 69 6c 75 72 65 20 74 6f 20 72 65 73 65 74  Failure to reset
2c520 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74   the prepared st
2c530 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 0a 2a  atement using .*
2c540 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  * [sqlite3_reset
2c550 28 29 5d 20 77 6f 75 6c 64 20 72 65 73 75 6c 74  ()] would result
2c560 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4d   in an [SQLITE_M
2c570 49 53 55 53 45 5d 20 72 65 74 75 72 6e 20 66 72  ISUSE] return fr
2c580 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74  om.** sqlite3_st
2c590 65 70 28 29 2e 20 20 42 75 74 20 61 66 74 65 72  ep().  But after
2c5a0 20 76 65 72 73 69 6f 6e 20 33 2e 36 2e 32 33 2e   version 3.6.23.
2c5b0 31 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  1, sqlite3_step(
2c5c0 29 20 62 65 67 61 6e 0a 2a 2a 20 63 61 6c 6c 69  ) began.** calli
2c5d0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ng [sqlite3_rese
2c5e0 74 28 29 5d 20 61 75 74 6f 6d 61 74 69 63 61 6c  t()] automatical
2c5f0 6c 79 20 69 6e 20 74 68 69 73 20 63 69 72 63 75  ly in this circu
2c600 6d 73 74 61 6e 63 65 20 72 61 74 68 65 72 0a 2a  mstance rather.*
2c610 2a 20 74 68 61 6e 20 72 65 74 75 72 6e 69 6e 67  * than returning
2c620 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
2c630 2e 20 20 54 68 69 73 20 69 73 20 6e 6f 74 20 63  .  This is not c
2c640 6f 6e 73 69 64 65 72 65 64 20 61 20 63 6f 6d 70  onsidered a comp
2c650 61 74 69 62 69 6c 69 74 79 0a 2a 2a 20 62 72 65  atibility.** bre
2c660 61 6b 20 62 65 63 61 75 73 65 20 61 6e 79 20 61  ak because any a
2c670 70 70 6c 69 63 61 74 69 6f 6e 20 74 68 61 74 20  pplication that 
2c680 65 76 65 72 20 72 65 63 65 69 76 65 73 20 61 6e  ever receives an
2c690 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 65   SQLITE_MISUSE e
2c6a0 72 72 6f 72 0a 2a 2a 20 69 73 20 62 72 6f 6b 65  rror.** is broke
2c6b0 6e 20 62 79 20 64 65 66 69 6e 69 74 69 6f 6e 2e  n by definition.
2c6c0 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d    The [SQLITE_OM
2c6d0 49 54 5f 41 55 54 4f 52 45 53 45 54 5d 20 63 6f  IT_AUTORESET] co
2c6e0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
2c6f0 6e 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64  n.** can be used
2c700 20 74 6f 20 72 65 73 74 6f 72 65 20 74 68 65 20   to restore the 
2c710 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 2e  legacy behavior.
2c720 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20  .**.** <b>Goofy 
2c730 49 6e 74 65 72 66 61 63 65 20 41 6c 65 72 74 3a  Interface Alert:
2c740 3c 2f 62 3e 20 49 6e 20 74 68 65 20 6c 65 67 61  </b> In the lega
2c750 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68  cy interface, th
2c760 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  e sqlite3_step()
2c770 0a 2a 2a 20 41 50 49 20 61 6c 77 61 79 73 20 72  .** API always r
2c780 65 74 75 72 6e 73 20 61 20 67 65 6e 65 72 69 63  eturns a generic
2c790 20 65 72 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51   error code, [SQ
2c7a0 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c  LITE_ERROR], fol
2c7b0 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72  lowing any.** er
2c7c0 72 6f 72 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  ror other than [
2c7d0 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 61 6e 64  SQLITE_BUSY] and
2c7e0 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
2c7f0 2e 20 20 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c  .  You must call
2c800 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
2c810 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  et()] or [sqlite
2c820 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e  3_finalize()] in
2c830 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 6f   order to find o
2c840 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65  ne of the.** spe
2c850 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64  cific [error cod
2c860 65 73 5d 20 74 68 61 74 20 62 65 74 74 65 72 20  es] that better 
2c870 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72  describes the er
2c880 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74  ror..** We admit
2c890 20 74 68 61 74 20 74 68 69 73 20 69 73 20 61 20   that this is a 
2c8a0 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e 20 20 54  goofy design.  T
2c8b0 68 65 20 70 72 6f 62 6c 65 6d 20 68 61 73 20 62  he problem has b
2c8c0 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69 74  een fixed.** wit
2c8d0 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  h the "v2" inter
2c8e0 66 61 63 65 2e 20 20 49 66 20 79 6f 75 20 70 72  face.  If you pr
2c8f0 65 70 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75  epare all of you
2c900 72 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  r SQL statements
2c910 0a 2a 2a 20 75 73 69 6e 67 20 65 69 74 68 65 72  .** using either
2c920 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2c930 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69  e_v2()] or [sqli
2c940 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
2c950 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f  ()] instead.** o
2c960 66 20 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71  f the legacy [sq
2c970 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
2c980 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
2c990 65 70 61 72 65 31 36 28 29 5d 20 69 6e 74 65 72  epare16()] inter
2c9a0 66 61 63 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74  faces,.** then t
2c9b0 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63  he more specific
2c9c0 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 61   [error codes] a
2c9d0 72 65 20 72 65 74 75 72 6e 65 64 20 64 69 72 65  re returned dire
2c9e0 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74  ctly.** by sqlit
2c9f0 65 33 5f 73 74 65 70 28 29 2e 20 20 54 68 65 20  e3_step().  The 
2ca00 75 73 65 20 6f 66 20 74 68 65 20 22 76 32 22 20  use of the "v2" 
2ca10 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63  interface is rec
2ca20 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f 0a 53 51 4c  ommended..*/.SQL
2ca30 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
2ca40 74 65 33 5f 73 74 65 70 28 73 71 6c 69 74 65 33  te3_step(sqlite3
2ca50 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _stmt*);../*.** 
2ca60 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72  CAPI3REF: Number
2ca70 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61   of columns in a
2ca80 20 72 65 73 75 6c 74 20 73 65 74 0a 2a 2a 0a 2a   result set.**.*
2ca90 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64  * ^The sqlite3_d
2caa0 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 69 6e 74  ata_count(P) int
2cab0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
2cac0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
2cad0 75 6d 6e 73 20 69 6e 20 74 68 65 0a 2a 2a 20 63  umns in the.** c
2cae0 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68  urrent row of th
2caf0 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  e result set of 
2cb00 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2cb10 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 49 66 20 70  ent] P..** ^If p
2cb20 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2cb30 74 20 50 20 64 6f 65 73 20 6e 6f 74 20 68 61 76  t P does not hav
2cb40 65 20 72 65 73 75 6c 74 73 20 72 65 61 64 79 20  e results ready 
2cb50 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 28 76 69  to return.** (vi
2cb60 61 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 5b  a calls to the [
2cb70 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69  sqlite3_column_i
2cb80 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c  nt | sqlite3_col
2cb90 75 6d 6e 5f 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69  umn_*()] of.** i
2cba0 6e 74 65 72 66 61 63 65 73 29 20 74 68 65 6e 20  nterfaces) then 
2cbb0 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
2cbc0 6e 74 28 50 29 20 72 65 74 75 72 6e 73 20 30 2e  nt(P) returns 0.
2cbd0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2cbe0 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72  _data_count(P) r
2cbf0 6f 75 74 69 6e 65 20 61 6c 73 6f 20 72 65 74 75  outine also retu
2cc00 72 6e 73 20 30 20 69 66 20 50 20 69 73 20 61 20  rns 0 if P is a 
2cc10 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
2cc20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61   ^The sqlite3_da
2cc30 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74  ta_count(P) rout
2cc40 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69 66  ine returns 0 if
2cc50 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 61   the previous ca
2cc60 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ll to.** [sqlite
2cc70 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75 72  3_step](P) retur
2cc80 6e 65 64 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45  ned [SQLITE_DONE
2cc90 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  ].  ^The sqlite3
2cca0 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 0a 2a  _data_count(P).*
2ccb0 2a 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6e 6f  * will return no
2ccc0 6e 2d 7a 65 72 6f 20 69 66 20 70 72 65 76 69 6f  n-zero if previo
2ccd0 75 73 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  us call to [sqli
2cce0 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74  te3_step](P) ret
2ccf0 75 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45  urned.** [SQLITE
2cd00 5f 52 4f 57 5d 2c 20 65 78 63 65 70 74 20 69 6e  _ROW], except in
2cd10 20 74 68 65 20 63 61 73 65 20 6f 66 20 74 68 65   the case of the
2cd20 20 5b 50 52 41 47 4d 41 20 69 6e 63 72 65 6d 65   [PRAGMA increme
2cd30 6e 74 61 6c 5f 76 61 63 75 75 6d 5d 0a 2a 2a 20  ntal_vacuum].** 
2cd40 77 68 65 72 65 20 69 74 20 61 6c 77 61 79 73 20  where it always 
2cd50 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 73 69 6e  returns zero sin
2cd60 63 65 20 65 61 63 68 20 73 74 65 70 20 6f 66 20  ce each step of 
2cd70 74 68 61 74 20 6d 75 6c 74 69 2d 73 74 65 70 0a  that multi-step.
2cd80 2a 2a 20 70 72 61 67 6d 61 20 72 65 74 75 72 6e  ** pragma return
2cd90 73 20 30 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 64  s 0 columns of d
2cda0 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ata..**.** See a
2cdb0 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  lso: [sqlite3_co
2cdc0 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f  lumn_count()].*/
2cdd0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2cde0 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
2cdf0 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  nt(sqlite3_stmt 
2ce00 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
2ce10 43 41 50 49 33 52 45 46 3a 20 46 75 6e 64 61 6d  CAPI3REF: Fundam
2ce20 65 6e 74 61 6c 20 44 61 74 61 74 79 70 65 73 0a  ental Datatypes.
2ce30 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c  ** KEYWORDS: SQL
2ce40 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 5e  ITE_TEXT.**.** ^
2ce50 28 45 76 65 72 79 20 76 61 6c 75 65 20 69 6e 20  (Every value in 
2ce60 53 51 4c 69 74 65 20 68 61 73 20 6f 6e 65 20 6f  SQLite has one o
2ce70 66 20 66 69 76 65 20 66 75 6e 64 61 6d 65 6e 74  f five fundament
2ce80 61 6c 20 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a  al datatypes:.**
2ce90 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
2cea0 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69   64-bit signed i
2ceb0 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36  nteger.** <li> 6
2cec0 34 2d 62 69 74 20 49 45 45 45 20 66 6c 6f 61 74  4-bit IEEE float
2ced0 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72  ing point number
2cee0 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a  .** <li> string.
2cef0 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20  ** <li> BLOB.** 
2cf00 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75  <li> NULL.** </u
2cf10 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  l>)^.**.** These
2cf20 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 63   constants are c
2cf30 6f 64 65 73 20 66 6f 72 20 65 61 63 68 20 6f 66  odes for each of
2cf40 20 74 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a   those types..**
2cf50 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68  .** Note that th
2cf60 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 63 6f  e SQLITE_TEXT co
2cf70 6e 73 74 61 6e 74 20 77 61 73 20 61 6c 73 6f 20  nstant was also 
2cf80 75 73 65 64 20 69 6e 20 53 51 4c 69 74 65 20 76  used in SQLite v
2cf90 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20  ersion 2.** for 
2cfa0 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66  a completely dif
2cfb0 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20  ferent meaning. 
2cfc0 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 20 6c   Software that l
2cfd0 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 62 6f 74  inks against bot
2cfe0 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73  h.** SQLite vers
2cff0 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69 74 65  ion 2 and SQLite
2d000 20 76 65 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c   version 3 shoul
2d010 64 20 75 73 65 20 53 51 4c 49 54 45 33 5f 54 45  d use SQLITE3_TE
2d020 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54  XT, not.** SQLIT
2d030 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69  E_TEXT..*/.#defi
2d040 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  ne SQLITE_INTEGE
2d050 52 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c  R  1.#define SQL
2d060 49 54 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23  ITE_FLOAT    2.#
2d070 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c  define SQLITE_BL
2d080 4f 42 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65  OB     4.#define
2d090 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20   SQLITE_NULL    
2d0a0 20 35 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45   5.#ifdef SQLITE
2d0b0 5f 54 45 58 54 0a 23 20 75 6e 64 65 66 20 53 51  _TEXT.# undef SQ
2d0c0 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a  LITE_TEXT.#else.
2d0d0 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
2d0e0 54 45 58 54 20 20 20 20 20 33 0a 23 65 6e 64 69  TEXT     3.#endi
2d0f0 66 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  f.#define SQLITE
2d100 33 5f 54 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a  3_TEXT     3../*
2d110 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
2d120 73 75 6c 74 20 56 61 6c 75 65 73 20 46 72 6f 6d  sult Values From
2d130 20 41 20 51 75 65 72 79 0a 2a 2a 20 4b 45 59 57   A Query.** KEYW
2d140 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63  ORDS: {column ac
2d150 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d 0a  cess functions}.
2d160 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
2d170 69 6e 65 73 20 66 6f 72 6d 20 74 68 65 20 22 72  ines form the "r
2d180 65 73 75 6c 74 20 73 65 74 22 20 69 6e 74 65 72  esult set" inter
2d190 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  face..**.** ^The
2d1a0 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  se routines retu
2d1b0 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  rn information a
2d1c0 62 6f 75 74 20 61 20 73 69 6e 67 6c 65 20 63 6f  bout a single co
2d1d0 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63 75 72 72  lumn of the curr
2d1e0 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f  ent.** result ro
2d1f0 77 20 6f 66 20 61 20 71 75 65 72 79 2e 20 20 5e  w of a query.  ^
2d200 49 6e 20 65 76 65 72 79 20 63 61 73 65 20 74 68  In every case th
2d210 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
2d220 20 69 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a   is a pointer.**
2d230 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65   to the [prepare
2d240 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
2d250 74 20 69 73 20 62 65 69 6e 67 20 65 76 61 6c 75  t is being evalu
2d260 61 74 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74  ated (the [sqlit
2d270 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61  e3_stmt*].** tha
2d280 74 20 77 61 73 20 72 65 74 75 72 6e 65 64 20 66  t was returned f
2d290 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  rom [sqlite3_pre
2d2a0 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e  pare_v2()] or on
2d2b0 65 20 6f 66 20 69 74 73 20 76 61 72 69 61 6e 74  e of its variant
2d2c0 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73 65  s).** and the se
2d2d0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73  cond argument is
2d2e0 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68   the index of th
2d2f0 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69  e column for whi
2d300 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a  ch information.*
2d310 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75  * should be retu
2d320 72 6e 65 64 2e 20 5e 54 68 65 20 6c 65 66 74 6d  rned. ^The leftm
2d330 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  ost column of th
2d340 65 20 72 65 73 75 6c 74 20 73 65 74 20 68 61 73  e result set has
2d350 20 74 68 65 20 69 6e 64 65 78 20 30 2e 0a 2a 2a   the index 0..**
2d360 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20   ^The number of 
2d370 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72  columns in the r
2d380 65 73 75 6c 74 20 63 61 6e 20 62 65 20 64 65 74  esult can be det
2d390 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a  ermined using.**
2d3a0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2d3b0 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a  _count()]..**.**
2d3c0 20 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74   If the SQL stat
2d3d0 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63  ement does not c
2d3e0 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74  urrently point t
2d3f0 6f 20 61 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f  o a valid row, o
2d400 72 20 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75  r if the.** colu
2d410 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20  mn index is out 
2d420 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 20 72 65  of range, the re
2d430 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65  sult is undefine
2d440 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  d..** These rout
2d450 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65  ines may only be
2d460 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65   called when the
2d470 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c   most recent cal
2d480 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  l to.** [sqlite3
2d490 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74  _step()] has ret
2d4a0 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f  urned [SQLITE_RO
2d4b0 57 5d 20 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a  W] and neither.*
2d4c0 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  * [sqlite3_reset
2d4d0 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33  ()] nor [sqlite3
2d4e0 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76  _finalize()] hav
2d4f0 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 73 75  e been called su
2d500 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49  bsequently..** I
2d510 66 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72  f any of these r
2d520 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c  outines are call
2d530 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65  ed after [sqlite
2d540 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a  3_reset()] or.**
2d550 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
2d560 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 5b  ze()] or after [
2d570 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2d580 68 61 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  has returned.** 
2d590 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20  something other 
2d5a0 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57  than [SQLITE_ROW
2d5b0 5d 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  ], the results a
2d5c0 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  re undefined..**
2d5d0 20 49 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   If [sqlite3_ste
2d5e0 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  p()] or [sqlite3
2d5f0 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71  _reset()] or [sq
2d600 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
2d610 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64 20  ].** are called 
2d620 66 72 6f 6d 20 61 20 64 69 66 66 65 72 65 6e 74  from a different
2d630 20 74 68 72 65 61 64 20 77 68 69 6c 65 20 61 6e   thread while an
2d640 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  y of these routi
2d650 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69  nes.** are pendi
2d660 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73  ng, then the res
2d670 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
2d680 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
2d690 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
2d6a0 70 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  pe() routine ret
2d6b0 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  urns the.** [SQL
2d6c0 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61  ITE_INTEGER | da
2d6d0 74 61 74 79 70 65 20 63 6f 64 65 5d 20 66 6f 72  tatype code] for
2d6e0 20 74 68 65 20 69 6e 69 74 69 61 6c 20 64 61 74   the initial dat
2d6f0 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65  a type.** of the
2d700 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20   result column. 
2d710 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 76   ^The returned v
2d720 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b  alue is one of [
2d730 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c  SQLITE_INTEGER],
2d740 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41  .** [SQLITE_FLOA
2d750 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 54  T], [SQLITE_TEXT
2d760 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d  ], [SQLITE_BLOB]
2d770 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c  , or [SQLITE_NUL
2d780 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75 65 0a 2a  L].  The value.*
2d790 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  * returned by sq
2d7a0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
2d7b0 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e  e() is only mean
2d7c0 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20 74 79 70  ingful if no typ
2d7d0 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73  e.** conversions
2d7e0 20 68 61 76 65 20 6f 63 63 75 72 72 65 64 20 61   have occurred a
2d7f0 73 20 64 65 73 63 72 69 62 65 64 20 62 65 6c 6f  s described belo
2d800 77 2e 20 20 41 66 74 65 72 20 61 20 74 79 70 65  w.  After a type
2d810 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20   conversion,.** 
2d820 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
2d830 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
2d840 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 75  lumn_type() is u
2d850 6e 64 65 66 69 6e 65 64 2e 20 20 46 75 74 75 72  ndefined.  Futur
2d860 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66  e.** versions of
2d870 20 53 51 4c 69 74 65 20 6d 61 79 20 63 68 61 6e   SQLite may chan
2d880 67 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  ge the behavior 
2d890 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  of sqlite3_colum
2d8a0 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c  n_type().** foll
2d8b0 6f 77 69 6e 67 20 61 20 74 79 70 65 20 63 6f 6e  owing a type con
2d8c0 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  version..**.** ^
2d8d0 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
2d8e0 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38   a BLOB or UTF-8
2d8f0 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65   string then the
2d900 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2d910 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69  bytes().** routi
2d920 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ne returns the n
2d930 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
2d940 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73  n that BLOB or s
2d950 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68  tring..** ^If th
2d960 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 54  e result is a UT
2d970 46 2d 31 36 20 73 74 72 69 6e 67 2c 20 74 68 65  F-16 string, the
2d980 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
2d990 5f 62 79 74 65 73 28 29 20 63 6f 6e 76 65 72 74  _bytes() convert
2d9a0 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20  s.** the string 
2d9b0 74 6f 20 55 54 46 2d 38 20 61 6e 64 20 74 68 65  to UTF-8 and the
2d9c0 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
2d9d0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a  mber of bytes..*
2d9e0 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
2d9f0 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61   is a numeric va
2da00 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33  lue then sqlite3
2da10 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
2da20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  uses.** [sqlite3
2da30 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20  _snprintf()] to 
2da40 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c  convert that val
2da50 75 65 20 74 6f 20 61 20 55 54 46 2d 38 20 73 74  ue to a UTF-8 st
2da60 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73  ring and returns
2da70 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
2da80 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20  f bytes in that 
2da90 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74  string..** ^If t
2daa0 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c  he result is NUL
2dab0 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  L, then sqlite3_
2dac0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 72  column_bytes() r
2dad0 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a  eturns zero..**.
2dae0 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
2daf0 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55  t is a BLOB or U
2db00 54 46 2d 31 36 20 73 74 72 69 6e 67 20 74 68 65  TF-16 string the
2db10 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  n the sqlite3_co
2db20 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 0a 2a  lumn_bytes16().*
2db30 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  * routine return
2db40 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
2db50 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c  bytes in that BL
2db60 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a  OB or string..**
2db70 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
2db80 69 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e  is a UTF-8 strin
2db90 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  g, then sqlite3_
2dba0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
2dbb0 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65   converts.** the
2dbc0 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 31   string to UTF-1
2dbd0 36 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72  6 and then retur
2dbe0 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
2dbf0 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74   bytes..** ^If t
2dc00 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e  he result is a n
2dc10 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 65  umeric value the
2dc20 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
2dc30 5f 62 79 74 65 73 31 36 28 29 20 75 73 65 73 0a  _bytes16() uses.
2dc40 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72  ** [sqlite3_snpr
2dc50 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65  intf()] to conve
2dc60 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f  rt that value to
2dc70 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67   a UTF-16 string
2dc80 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20   and returns.** 
2dc90 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
2dca0 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 69  tes in that stri
2dcb0 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  ng..** ^If the r
2dcc0 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74  esult is NULL, t
2dcd0 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
2dce0 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 72 65 74  mn_bytes16() ret
2dcf0 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a  urns zero..**.**
2dd00 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65 74   ^The values ret
2dd10 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
2dd20 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
2dd30 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74  ] and .** [sqlit
2dd40 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
2dd50 36 28 29 5d 20 64 6f 20 6e 6f 74 20 69 6e 63 6c  6()] do not incl
2dd60 75 64 65 20 74 68 65 20 7a 65 72 6f 20 74 65 72  ude the zero ter
2dd70 6d 69 6e 61 74 6f 72 73 20 61 74 20 74 68 65 20  minators at the 
2dd80 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74  end.** of the st
2dd90 72 69 6e 67 2e 20 20 5e 46 6f 72 20 63 6c 61 72  ring.  ^For clar
2dda0 69 74 79 3a 20 74 68 65 20 76 61 6c 75 65 73 20  ity: the values 
2ddb0 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b  returned by.** [
2ddc0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2ddd0 79 74 65 73 28 29 5d 20 61 6e 64 20 5b 73 71 6c  ytes()] and [sql
2dde0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2ddf0 73 31 36 28 29 5d 20 61 72 65 20 74 68 65 20 6e  s16()] are the n
2de00 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65  umber of.** byte
2de10 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 2c  s in the string,
2de20 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20   not the number 
2de30 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a  of characters..*
2de40 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67 73 20 72 65  *.** ^Strings re
2de50 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
2de60 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
2de70 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
2de80 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20  mn_text16(),.** 
2de90 65 76 65 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  even empty strin
2dea0 67 73 2c 20 61 72 65 20 61 6c 77 61 79 73 20 7a  gs, are always z
2deb0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20  ero-terminated. 
2dec0 20 5e 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20   ^The return.** 
2ded0 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74  value from sqlit
2dee0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
2def0 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67   for a zero-leng
2df00 74 68 20 42 4c 4f 42 20 69 73 20 61 20 4e 55 4c  th BLOB is a NUL
2df10 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  L pointer..**.**
2df20 20 5e 54 68 65 20 6f 62 6a 65 63 74 20 72 65 74   ^The object ret
2df30 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
2df40 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29  3_column_value()
2df50 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72  ] is an.** [unpr
2df60 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2df70 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20  value] object.  
2df80 41 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73  An unprotected s
2df90 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
2dfa0 65 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20  ect.** may only 
2dfb0 62 65 20 75 73 65 64 20 77 69 74 68 20 5b 73 71  be used with [sq
2dfc0 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65  lite3_bind_value
2dfd0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
2dfe0 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d  _result_value()]
2dff0 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e 70  ..** If the [unp
2e000 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2e010 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72  _value] object r
2e020 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73  eturned by.** [s
2e030 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
2e040 6c 75 65 28 29 5d 20 69 73 20 75 73 65 64 20 69  lue()] is used i
2e050 6e 20 61 6e 79 20 6f 74 68 65 72 20 77 61 79 2c  n any other way,
2e060 20 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73   including calls
2e070 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73 20  .** to routines 
2e080 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 76 61  like [sqlite3_va
2e090 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 6c  lue_int()], [sql
2e0a0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28  ite3_value_text(
2e0b0 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74  )],.** or [sqlit
2e0c0 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29  e3_value_bytes()
2e0d0 5d 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  ], then the beha
2e0e0 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
2e0f0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  d..**.** These r
2e100 6f 75 74 69 6e 65 73 20 61 74 74 65 6d 70 74 20  outines attempt 
2e110 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76  to convert the v
2e120 61 6c 75 65 20 77 68 65 72 65 20 61 70 70 72 6f  alue where appro
2e130 70 72 69 61 74 65 2e 20 20 5e 46 6f 72 0a 2a 2a  priate.  ^For.**
2e140 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 68 65   example, if the
2e150 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73   internal repres
2e160 65 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41  entation is FLOA
2e170 54 20 61 6e 64 20 61 20 74 65 78 74 20 72 65 73  T and a text res
2e180 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75 65 73  ult.** is reques
2e190 74 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e  ted, [sqlite3_sn
2e1a0 70 72 69 6e 74 66 28 29 5d 20 69 73 20 75 73 65  printf()] is use
2e1b0 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20  d internally to 
2e1c0 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63  perform the.** c
2e1d0 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61  onversion automa
2e1e0 74 69 63 61 6c 6c 79 2e 20 20 5e 28 54 68 65 20  tically.  ^(The 
2e1f0 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20  following table 
2e200 64 65 74 61 69 6c 73 20 74 68 65 20 63 6f 6e 76  details the conv
2e210 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20  ersions.** that 
2e220 61 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a  are applied:.**.
2e230 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  ** <blockquote>.
2e240 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72  ** <table border
2e250 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68  ="1">.** <tr><th
2e260 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79  > Internal<br>Ty
2e270 70 65 20 3c 74 68 3e 20 52 65 71 75 65 73 74 65  pe <th> Requeste
2e280 64 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20  d<br>Type <th>  
2e290 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a  Conversion.**.**
2e2a0 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20   <tr><td>  NULL 
2e2b0 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20     <td> INTEGER 
2e2c0 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73    <td> Result is
2e2d0 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20   0.** <tr><td>  
2e2e0 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c  NULL    <td>  FL
2e2f0 4f 41 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75  OAT    <td> Resu
2e300 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72  lt is 0.0.** <tr
2e310 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
2e320 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
2e330 64 3e 20 52 65 73 75 6c 74 20 69 73 20 61 20 4e  d> Result is a N
2e340 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c  ULL pointer.** <
2e350 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20  tr><td>  NULL   
2e360 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20   <td>   BLOB    
2e370 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 61  <td> Result is a
2e380 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
2e390 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45   <tr><td> INTEGE
2e3a0 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  R  <td>  FLOAT  
2e3b0 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66    <td> Convert f
2e3c0 72 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f 20 66  rom integer to f
2e3d0 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  loat.** <tr><td>
2e3e0 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20   INTEGER  <td>  
2e3f0 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53   TEXT    <td> AS
2e400 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66  CII rendering of
2e410 20 74 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20   the integer.** 
2e420 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52  <tr><td> INTEGER
2e430 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
2e440 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 49 4e   <td> Same as IN
2e450 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c  TEGER->TEXT.** <
2e460 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  tr><td>  FLOAT  
2e470 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20   <td> INTEGER   
2e480 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49  <td> [CAST] to I
2e490 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74  NTEGER.** <tr><t
2e4a0 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e  d>  FLOAT   <td>
2e4b0 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20     TEXT    <td> 
2e4c0 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20  ASCII rendering 
2e4d0 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20  of the float.** 
2e4e0 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20  <tr><td>  FLOAT 
2e4f0 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
2e500 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20   <td> [CAST] to 
2e510 42 4c 4f 42 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  BLOB.** <tr><td>
2e520 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 49    TEXT    <td> I
2e530 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43  NTEGER   <td> [C
2e540 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a  AST] to INTEGER.
2e550 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58  ** <tr><td>  TEX
2e560 54 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54  T    <td>  FLOAT
2e570 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20      <td> [CAST] 
2e580 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c  to REAL.** <tr><
2e590 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64  td>  TEXT    <td
2e5a0 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  >   BLOB    <td>
2e5b0 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74   No change.** <t
2e5c0 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20  r><td>  BLOB    
2e5d0 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c  <td> INTEGER   <
2e5e0 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e  td> [CAST] to IN
2e5f0 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64  TEGER.** <tr><td
2e600 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20  >  BLOB    <td> 
2e610 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 5b   FLOAT    <td> [
2e620 43 41 53 54 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a  CAST] to REAL.**
2e630 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20   <tr><td>  BLOB 
2e640 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20     <td>   TEXT  
2e650 20 20 3c 74 64 3e 20 41 64 64 20 61 20 7a 65 72    <td> Add a zer
2e660 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 66 20  o terminator if 
2e670 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c  needed.** </tabl
2e680 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f  e>.** </blockquo
2e690 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  te>)^.**.** The 
2e6a0 74 61 62 6c 65 20 61 62 6f 76 65 20 6d 61 6b 65  table above make
2e6b0 73 20 72 65 66 65 72 65 6e 63 65 20 74 6f 20 73  s reference to s
2e6c0 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72  tandard C librar
2e6d0 79 20 66 75 6e 63 74 69 6f 6e 73 20 61 74 6f 69  y functions atoi
2e6e0 28 29 0a 2a 2a 20 61 6e 64 20 61 74 6f 66 28 29  ().** and atof()
2e6f0 2e 20 20 53 51 4c 69 74 65 20 64 6f 65 73 20 6e  .  SQLite does n
2e700 6f 74 20 72 65 61 6c 6c 79 20 75 73 65 20 74 68  ot really use th
2e710 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20  ese functions.  
2e720 49 74 20 68 61 73 20 69 74 73 0a 2a 2a 20 6f 77  It has its.** ow
2e730 6e 20 65 71 75 69 76 61 6c 65 6e 74 20 69 6e 74  n equivalent int
2e740 65 72 6e 61 6c 20 72 6f 75 74 69 6e 65 73 2e 20  ernal routines. 
2e750 20 54 68 65 20 61 74 6f 69 28 29 20 61 6e 64 20   The atoi() and 
2e760 61 74 6f 66 28 29 20 6e 61 6d 65 73 20 61 72 65  atof() names are
2e770 0a 2a 2a 20 75 73 65 64 20 69 6e 20 74 68 65 20  .** used in the 
2e780 74 61 62 6c 65 20 66 6f 72 20 62 72 65 76 69 74  table for brevit
2e790 79 20 61 6e 64 20 62 65 63 61 75 73 65 20 74 68  y and because th
2e7a0 65 79 20 61 72 65 20 66 61 6d 69 6c 69 61 72 20  ey are familiar 
2e7b0 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20 70 72 6f  to most.** C pro
2e7c0 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  grammers..**.** 
2e7d0 4e 6f 74 65 20 74 68 61 74 20 77 68 65 6e 20 74  Note that when t
2e7e0 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20  ype conversions 
2e7f0 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65 72 73 20  occur, pointers 
2e800 72 65 74 75 72 6e 65 64 20 62 79 20 70 72 69 6f  returned by prio
2e810 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71  r.** calls to sq
2e820 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
2e830 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c  b(), sqlite3_col
2e840 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f  umn_text(), and/
2e850 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  or.** sqlite3_co
2e860 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d 61  lumn_text16() ma
2e870 79 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64  y be invalidated
2e880 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65 72  ..** Type conver
2e890 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65  sions and pointe
2e8a0 72 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20  r invalidations 
2e8b0 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69  might occur.** i
2e8c0 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  n the following 
2e8d0 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  cases:.**.** <ul
2e8e0 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e  >.** <li> The in
2e8f0 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73  itial content is
2e900 20 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69   a BLOB and sqli
2e910 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
2e920 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c  ) or.**      sql
2e930 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2e940 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20  16() is called. 
2e950 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   A zero-terminat
2e960 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20  or might.**     
2e970 20 6e 65 65 64 20 74 6f 20 62 65 20 61 64 64 65   need to be adde
2e980 64 20 74 6f 20 74 68 65 20 73 74 72 69 6e 67 2e  d to the string.
2e990 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68  </li>.** <li> Th
2e9a0 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e  e initial conten
2e9b0 74 20 69 73 20 55 54 46 2d 38 20 74 65 78 74 20  t is UTF-8 text 
2e9c0 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
2e9d0 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 6f 72 0a  mn_bytes16() or.
2e9e0 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f  **      sqlite3_
2e9f0 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
2ea00 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20  is called.  The 
2ea10 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20  content must be 
2ea20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20  converted.**    
2ea30 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c 69    to UTF-16.</li
2ea40 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e  >.** <li> The in
2ea50 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73  itial content is
2ea60 20 55 54 46 2d 31 36 20 74 65 78 74 20 61 6e 64   UTF-16 text and
2ea70 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2ea80 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20  bytes() or.**   
2ea90 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d     sqlite3_colum
2eaa0 6e 5f 74 65 78 74 28 29 20 69 73 20 63 61 6c 6c  n_text() is call
2eab0 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74  ed.  The content
2eac0 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74   must be convert
2ead0 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54  ed.**      to UT
2eae0 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75  F-8.</li>.** </u
2eaf0 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65 72  l>.**.** ^Conver
2eb00 73 69 6f 6e 73 20 62 65 74 77 65 65 6e 20 55 54  sions between UT
2eb10 46 2d 31 36 62 65 20 61 6e 64 20 55 54 46 2d 31  F-16be and UTF-1
2eb20 36 6c 65 20 61 72 65 20 61 6c 77 61 79 73 20 64  6le are always d
2eb30 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 61 6e 64  one in place and
2eb40 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c   do.** not inval
2eb50 69 64 61 74 65 20 61 20 70 72 69 6f 72 20 70 6f  idate a prior po
2eb60 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 20 6f 66  inter, though of
2eb70 20 63 6f 75 72 73 65 20 74 68 65 20 63 6f 6e 74   course the cont
2eb80 65 6e 74 20 6f 66 20 74 68 65 20 62 75 66 66 65  ent of the buffe
2eb90 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 70 72  r.** that the pr
2eba0 69 6f 72 20 70 6f 69 6e 74 65 72 20 72 65 66 65  ior pointer refe
2ebb0 72 65 6e 63 65 73 20 77 69 6c 6c 20 68 61 76 65  rences will have
2ebc0 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20   been modified. 
2ebd0 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20   Other kinds.** 
2ebe0 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72  of conversion ar
2ebf0 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20  e done in place 
2ec00 77 68 65 6e 20 69 74 20 69 73 20 70 6f 73 73 69  when it is possi
2ec10 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d  ble, but sometim
2ec20 65 73 20 74 68 65 79 0a 2a 2a 20 61 72 65 20 6e  es they.** are n
2ec30 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 6e 64 20  ot possible and 
2ec40 69 6e 20 74 68 6f 73 65 20 63 61 73 65 73 20 70  in those cases p
2ec50 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 20 61 72  rior pointers ar
2ec60 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a  e invalidated..*
2ec70 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65 73 74 20  *.** The safest 
2ec80 61 6e 64 20 65 61 73 69 65 73 74 20 74 6f 20 72  and easiest to r
2ec90 65 6d 65 6d 62 65 72 20 70 6f 6c 69 63 79 20 69  emember policy i
2eca0 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73  s to invoke thes
2ecb0 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e  e routines.** in
2ecc0 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c   one of the foll
2ecd0 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a  owing ways:.**.*
2ece0 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73  * <ul>.**  <li>s
2ecf0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2ed00 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79  xt() followed by
2ed10 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2ed20 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20  bytes()</li>.** 
2ed30 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c   <li>sqlite3_col
2ed40 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f  umn_blob() follo
2ed50 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  wed by sqlite3_c
2ed60 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c  olumn_bytes()</l
2ed70 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74  i>.**  <li>sqlit
2ed80 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
2ed90 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73  () followed by s
2eda0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2edb0 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20  tes16()</li>.** 
2edc0 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f  </ul>.**.** In o
2edd0 74 68 65 72 20 77 6f 72 64 73 2c 20 79 6f 75 20  ther words, you 
2ede0 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69  should call sqli
2edf0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
2ee00 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  ),.** sqlite3_co
2ee10 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20  lumn_blob(), or 
2ee20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2ee30 65 78 74 31 36 28 29 20 66 69 72 73 74 20 74 6f  ext16() first to
2ee40 20 66 6f 72 63 65 20 74 68 65 20 72 65 73 75 6c   force the resul
2ee50 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64 65  t.** into the de
2ee60 73 69 72 65 64 20 66 6f 72 6d 61 74 2c 20 74 68  sired format, th
2ee70 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  en invoke sqlite
2ee80 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
2ee90 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   or.** sqlite3_c
2eea0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
2eeb0 74 6f 20 66 69 6e 64 20 74 68 65 20 73 69 7a 65  to find the size
2eec0 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 2e 20   of the result. 
2eed0 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c   Do not mix call
2eee0 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f  s.** to sqlite3_
2eef0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72  column_text() or
2ef00 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2ef10 62 6c 6f 62 28 29 20 77 69 74 68 20 63 61 6c 6c  blob() with call
2ef20 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  s to.** sqlite3_
2ef30 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
2ef40 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78  , and do not mix
2ef50 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
2ef60 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
2ef70 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73 20  ).** with calls 
2ef80 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  to sqlite3_colum
2ef90 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a  n_bytes()..**.**
2efa0 20 5e 54 68 65 20 70 6f 69 6e 74 65 72 73 20 72   ^The pointers r
2efb0 65 74 75 72 6e 65 64 20 61 72 65 20 76 61 6c 69  eturned are vali
2efc0 64 20 75 6e 74 69 6c 20 61 20 74 79 70 65 20 63  d until a type c
2efd0 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73  onversion occurs
2efe0 20 61 73 0a 2a 2a 20 64 65 73 63 72 69 62 65 64   as.** described
2eff0 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c   above, or until
2f000 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2f010 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
2f020 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  set()] or.** [sq
2f030 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
2f040 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 5e 54  ] is called.  ^T
2f050 68 65 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 20  he memory space 
2f060 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 73 74 72  used to hold str
2f070 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42  ings.** and BLOB
2f080 73 20 69 73 20 66 72 65 65 64 20 61 75 74 6f 6d  s is freed autom
2f090 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c 62  atically.  Do <b
2f0a0 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73 73 20 74 68  >not</b> pass th
2f0b0 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72  e pointers retur
2f0c0 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  ned.** from [sql
2f0d0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
2f0e0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f  ()], [sqlite3_co
2f0f0 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74  lumn_text()], et
2f100 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69  c. into.** [sqli
2f110 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a  te3_free()]..**.
2f120 2a 2a 20 5e 28 49 66 20 61 20 6d 65 6d 6f 72 79  ** ^(If a memory
2f130 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f   allocation erro
2f140 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20  r occurs during 
2f150 74 68 65 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f  the evaluation o
2f160 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73  f any.** of thes
2f170 65 20 72 6f 75 74 69 6e 65 73 2c 20 61 20 64 65  e routines, a de
2f180 66 61 75 6c 74 20 76 61 6c 75 65 20 69 73 20 72  fault value is r
2f190 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 64 65  eturned.  The de
2f1a0 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69  fault value.** i
2f1b0 73 20 65 69 74 68 65 72 20 74 68 65 20 69 6e 74  s either the int
2f1c0 65 67 65 72 20 30 2c 20 74 68 65 20 66 6c 6f 61  eger 0, the floa
2f1d0 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65  ting point numbe
2f1e0 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c  r 0.0, or a NULL
2f1f0 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53 75  .** pointer.  Su
2f200 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74  bsequent calls t
2f210 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  o [sqlite3_errco
2f220 64 65 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  de()] will retur
2f230 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d  n.** [SQLITE_NOM
2f240 45 4d 5d 2e 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45  EM].)^.*/.SQLITE
2f250 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20  _API const void 
2f260 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
2f270 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d  blob(sqlite3_stm
2f280 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53  t*, int iCol);.S
2f290 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
2f2a0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2f2b0 65 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  es(sqlite3_stmt*
2f2c0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c  , int iCol);.SQL
2f2d0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
2f2e0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2f2f0 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
2f300 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c  , int iCol);.SQL
2f310 49 54 45 5f 41 50 49 20 64 6f 75 62 6c 65 20 73  ITE_API double s
2f320 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f  qlite3_column_do
2f330 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  uble(sqlite3_stm
2f340 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53  t*, int iCol);.S
2f350 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
2f360 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74  lite3_column_int
2f370 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2f380 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54  int iCol);.SQLIT
2f390 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e  E_API sqlite3_in
2f3a0 74 36 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  t64 sqlite3_colu
2f3b0 6d 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33  mn_int64(sqlite3
2f3c0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
2f3d0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
2f3e0 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61  nst unsigned cha
2f3f0 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
2f400 6e 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73  n_text(sqlite3_s
2f410 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
2f420 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
2f430 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
2f440 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 73 71  column_text16(sq
2f450 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2f460 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41   iCol);.SQLITE_A
2f470 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  PI int sqlite3_c
2f480 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74  olumn_type(sqlit
2f490 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
2f4a0 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  ol);.SQLITE_API 
2f4b0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 73  sqlite3_value *s
2f4c0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
2f4d0 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lue(sqlite3_stmt
2f4e0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f  *, int iCol);../
2f4f0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
2f500 65 73 74 72 6f 79 20 41 20 50 72 65 70 61 72 65  estroy A Prepare
2f510 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65  d Statement Obje
2f520 63 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ct.**.** ^The sq
2f530 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
2f540 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c   function is cal
2f550 6c 65 64 20 74 6f 20 64 65 6c 65 74 65 20 61 20  led to delete a 
2f560 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2f570 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ent]..** ^If the
2f580 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61   most recent eva
2f590 6c 75 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73  luation of the s
2f5a0 74 61 74 65 6d 65 6e 74 20 65 6e 63 6f 75 6e 74  tatement encount
2f5b0 65 72 65 64 20 6e 6f 20 65 72 72 6f 72 73 0a 2a  ered no errors.*
2f5c0 2a 20 6f 72 20 69 66 20 74 68 65 20 73 74 61 74  * or if the stat
2f5d0 65 6d 65 6e 74 20 69 73 20 6e 65 76 65 72 20 62  ement is never b
2f5e0 65 65 6e 20 65 76 61 6c 75 61 74 65 64 2c 20 74  een evaluated, t
2f5f0 68 65 6e 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  hen sqlite3_fina
2f600 6c 69 7a 65 28 29 20 72 65 74 75 72 6e 73 0a 2a  lize() returns.*
2f610 2a 20 53 51 4c 49 54 45 5f 4f 4b 2e 20 20 5e 49  * SQLITE_OK.  ^I
2f620 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
2f630 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20  t evaluation of 
2f640 73 74 61 74 65 6d 65 6e 74 20 53 20 66 61 69 6c  statement S fail
2f650 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69  ed, then.** sqli
2f660 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20  te3_finalize(S) 
2f670 72 65 74 75 72 6e 73 20 74 68 65 20 61 70 70 72  returns the appr
2f680 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63  opriate [error c
2f690 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65  ode] or.** [exte
2f6a0 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d  nded error code]
2f6b0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
2f6c0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29  ite3_finalize(S)
2f6d0 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20   routine can be 
2f6e0 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 20 70 6f  called at any po
2f6f0 69 6e 74 20 64 75 72 69 6e 67 0a 2a 2a 20 74 68  int during.** th
2f700 65 20 6c 69 66 65 20 63 79 63 6c 65 20 6f 66 20  e life cycle of 
2f710 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2f720 65 6e 74 5d 20 53 3a 0a 2a 2a 20 62 65 66 6f 72  ent] S:.** befor
2f730 65 20 73 74 61 74 65 6d 65 6e 74 20 53 20 69 73  e statement S is
2f740 20 65 76 65 72 20 65 76 61 6c 75 61 74 65 64 2c   ever evaluated,
2f750 20 61 66 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72   after.** one or
2f760 20 6d 6f 72 65 20 63 61 6c 6c 73 20 74 6f 20 5b   more calls to [
2f770 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2f780 2c 20 6f 72 20 61 66 74 65 72 20 61 6e 79 20 63  , or after any c
2f790 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74  all.** to [sqlit
2f7a0 65 33 5f 73 74 65 70 28 29 5d 20 72 65 67 61 72  e3_step()] regar
2f7b0 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72  dless of whether
2f7c0 20 6f 72 20 6e 6f 74 20 74 68 65 20 73 74 61 74   or not the stat
2f7d0 65 6d 65 6e 74 20 68 61 73 0a 2a 2a 20 63 6f 6d  ement has.** com
2f7e0 70 6c 65 74 65 64 20 65 78 65 63 75 74 69 6f 6e  pleted execution
2f7f0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b 69 6e  ..**.** ^Invokin
2f800 67 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  g sqlite3_finali
2f810 7a 65 28 29 20 6f 6e 20 61 20 4e 55 4c 4c 20 70  ze() on a NULL p
2f820 6f 69 6e 74 65 72 20 69 73 20 61 20 68 61 72 6d  ointer is a harm
2f830 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a  less no-op..**.*
2f840 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
2f850 6e 20 6d 75 73 74 20 66 69 6e 61 6c 69 7a 65 20  n must finalize 
2f860 65 76 65 72 79 20 5b 70 72 65 70 61 72 65 64 20  every [prepared 
2f870 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 6f 72  statement] in or
2f880 64 65 72 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20  der to avoid.** 
2f890 72 65 73 6f 75 72 63 65 20 6c 65 61 6b 73 2e 20  resource leaks. 
2f8a0 20 49 74 20 69 73 20 61 20 67 72 69 65 76 6f 75   It is a grievou
2f8b0 73 20 65 72 72 6f 72 20 66 6f 72 20 74 68 65 20  s error for the 
2f8c0 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 74  application to t
2f8d0 72 79 20 74 6f 20 75 73 65 0a 2a 2a 20 61 20 70  ry to use.** a p
2f8e0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2f8f0 74 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62  t after it has b
2f900 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 20 20  een finalized.  
2f910 41 6e 79 20 75 73 65 20 6f 66 20 61 20 70 72 65  Any use of a pre
2f920 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65  pared.** stateme
2f930 6e 74 20 61 66 74 65 72 20 69 74 20 68 61 73 20  nt after it has 
2f940 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 20 63  been finalized c
2f950 61 6e 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64  an result in und
2f960 65 66 69 6e 65 64 20 61 6e 64 0a 2a 2a 20 75 6e  efined and.** un
2f970 64 65 73 69 72 61 62 6c 65 20 62 65 68 61 76 69  desirable behavi
2f980 6f 72 20 73 75 63 68 20 61 73 20 73 65 67 66 61  or such as segfa
2f990 75 6c 74 73 20 61 6e 64 20 68 65 61 70 20 63 6f  ults and heap co
2f9a0 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c  rruption..*/.SQL
2f9b0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
2f9c0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c  te3_finalize(sql
2f9d0 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
2f9e0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2f9f0 45 46 3a 20 52 65 73 65 74 20 41 20 50 72 65 70  EF: Reset A Prep
2fa00 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f  ared Statement O
2fa10 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20  bject.**.** The 
2fa20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 20  sqlite3_reset() 
2fa30 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c  function is call
2fa40 65 64 20 74 6f 20 72 65 73 65 74 20 61 20 5b 70  ed to reset a [p
2fa50 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2fa60 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 62 61 63  t].** object bac
2fa70 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c  k to its initial
2fa80 20 73 74 61 74 65 2c 20 72 65 61 64 79 20 74 6f   state, ready to
2fa90 20 62 65 20 72 65 2d 65 78 65 63 75 74 65 64 2e   be re-executed.
2faa0 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c 20 73 74 61  .** ^Any SQL sta
2fab0 74 65 6d 65 6e 74 20 76 61 72 69 61 62 6c 65 73  tement variables
2fac0 20 74 68 61 74 20 68 61 64 20 76 61 6c 75 65 73   that had values
2fad0 20 62 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20 75   bound to them u
2fae0 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c  sing.** the [sql
2faf0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c  ite3_bind_blob |
2fb00 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
2fb10 29 20 41 50 49 5d 20 72 65 74 61 69 6e 20 74 68  ) API] retain th
2fb20 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 55  eir values..** U
2fb30 73 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61  se [sqlite3_clea
2fb40 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d 20 74 6f  r_bindings()] to
2fb50 20 72 65 73 65 74 20 74 68 65 20 62 69 6e 64 69   reset the bindi
2fb60 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ngs..**.** ^The 
2fb70 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
2fb80 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 73  )] interface res
2fb90 65 74 73 20 74 68 65 20 5b 70 72 65 70 61 72 65  ets the [prepare
2fba0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a  d statement] S.*
2fbb0 2a 20 62 61 63 6b 20 74 6f 20 74 68 65 20 62 65  * back to the be
2fbc0 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74 73 20 70  ginning of its p
2fbd0 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49  rogram..**.** ^I
2fbe0 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
2fbf0 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
2fc00 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20  e3_step(S)] for 
2fc10 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
2fc20 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 72 65   statement] S re
2fc30 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52  turned [SQLITE_R
2fc40 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  OW] or [SQLITE_D
2fc50 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20 69 66 20 5b  ONE],.** or if [
2fc60 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
2fc70 20 68 61 73 20 6e 65 76 65 72 20 62 65 66 6f 72   has never befor
2fc80 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e  e been called on
2fc90 20 53 2c 0a 2a 2a 20 74 68 65 6e 20 5b 73 71 6c   S,.** then [sql
2fca0 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72  ite3_reset(S)] r
2fcb0 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
2fcc0 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  K]..**.** ^If th
2fcd0 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61  e most recent ca
2fce0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
2fcf0 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a  tep(S)] for the.
2fd00 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
2fd10 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64 69 63 61  tement] S indica
2fd20 74 65 64 20 61 6e 20 65 72 72 6f 72 2c 20 74 68  ted an error, th
2fd30 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  en.** [sqlite3_r
2fd40 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73  eset(S)] returns
2fd50 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20   an appropriate 
2fd60 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a  [error code]..**
2fd70 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  .** ^The [sqlite
2fd80 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65  3_reset(S)] inte
2fd90 72 66 61 63 65 20 64 6f 65 73 20 6e 6f 74 20 63  rface does not c
2fda0 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 73  hange the values
2fdb0 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b 73 71 6c 69  .** of any [sqli
2fdc0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62 69  te3_bind_blob|bi
2fdd0 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68 65 20 5b  ndings] on the [
2fde0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2fdf0 6e 74 5d 20 53 2e 0a 2a 2f 0a 53 51 4c 49 54 45  nt] S..*/.SQLITE
2fe00 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
2fe10 5f 72 65 73 65 74 28 73 71 6c 69 74 65 33 5f 73  _reset(sqlite3_s
2fe20 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
2fe30 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 72  .** CAPI3REF: Cr
2fe40 65 61 74 65 20 4f 72 20 52 65 64 65 66 69 6e 65  eate Or Redefine
2fe50 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73 0a 2a   SQL Functions.*
2fe60 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e  * KEYWORDS: {fun
2fe70 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72  ction creation r
2fe80 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57  outines}.** KEYW
2fe90 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69  ORDS: {applicati
2fea0 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
2feb0 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57  unction}.** KEYW
2fec0 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69  ORDS: {applicati
2fed0 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
2fee0 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20  unctions}.**.** 
2fef0 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73  ^These functions
2ff00 20 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b   (collectively k
2ff10 6e 6f 77 6e 20 61 73 20 22 66 75 6e 63 74 69 6f  nown as "functio
2ff20 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69  n creation routi
2ff30 6e 65 73 22 29 0a 2a 2a 20 61 72 65 20 75 73 65  nes").** are use
2ff40 64 20 74 6f 20 61 64 64 20 53 51 4c 20 66 75 6e  d to add SQL fun
2ff50 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67  ctions or aggreg
2ff60 61 74 65 73 20 6f 72 20 74 6f 20 72 65 64 65 66  ates or to redef
2ff70 69 6e 65 20 74 68 65 20 62 65 68 61 76 69 6f 72  ine the behavior
2ff80 0a 2a 2a 20 6f 66 20 65 78 69 73 74 69 6e 67 20  .** of existing 
2ff90 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72  SQL functions or
2ffa0 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 54 68   aggregates.  Th
2ffb0 65 20 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63  e only differenc
2ffc0 65 73 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68  es between.** th
2ffd0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
2ffe0 20 74 68 65 20 74 65 78 74 20 65 6e 63 6f 64 69   the text encodi
2fff0 6e 67 20 65 78 70 65 63 74 65 64 20 66 6f 72 0a  ng expected for.
30000 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  ** the second pa
30010 72 61 6d 65 74 65 72 20 28 74 68 65 20 6e 61 6d  rameter (the nam
30020 65 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f  e of the functio
30030 6e 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 29  n being created)
30040 0a 2a 2a 20 61 6e 64 20 74 68 65 20 70 72 65 73  .** and the pres
30050 65 6e 63 65 20 6f 72 20 61 62 73 65 6e 63 65 20  ence or absence 
30060 6f 66 20 61 20 64 65 73 74 72 75 63 74 6f 72 20  of a destructor 
30070 63 61 6c 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a 20  callback for.** 
30080 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
30090 64 61 74 61 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  data pointer..**
300a0 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70  .** ^The first p
300b0 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
300c0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
300d0 74 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20 74  tion] to which t
300e0 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69  he SQL.** functi
300f0 6f 6e 20 69 73 20 74 6f 20 62 65 20 61 64 64 65  on is to be adde
30100 64 2e 20 20 5e 49 66 20 61 6e 20 61 70 70 6c 69  d.  ^If an appli
30110 63 61 74 69 6f 6e 20 75 73 65 73 20 6d 6f 72 65  cation uses more
30120 20 74 68 61 6e 20 6f 6e 65 20 64 61 74 61 62 61   than one databa
30130 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
30140 20 74 68 65 6e 20 61 70 70 6c 69 63 61 74 69 6f   then applicatio
30150 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
30160 6e 63 74 69 6f 6e 73 20 6d 75 73 74 20 62 65 20  nctions must be 
30170 61 64 64 65 64 0a 2a 2a 20 74 6f 20 65 61 63 68  added.** to each
30180 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
30190 74 69 6f 6e 20 73 65 70 61 72 61 74 65 6c 79 2e  tion separately.
301a0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f  .**.** ^The seco
301b0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
301c0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
301d0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  SQL function to 
301e0 62 65 20 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a  be created or.**
301f0 20 72 65 64 65 66 69 6e 65 64 2e 20 20 5e 54 68   redefined.  ^Th
30200 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20  e length of the 
30210 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74 65 64 20  name is limited 
30220 74 6f 20 32 35 35 20 62 79 74 65 73 20 69 6e 20  to 255 bytes in 
30230 61 20 55 54 46 2d 38 0a 2a 2a 20 72 65 70 72 65  a UTF-8.** repre
30240 73 65 6e 74 61 74 69 6f 6e 2c 20 65 78 63 6c 75  sentation, exclu
30250 73 69 76 65 20 6f 66 20 74 68 65 20 7a 65 72 6f  sive of the zero
30260 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e  -terminator.  ^N
30270 6f 74 65 20 74 68 61 74 20 74 68 65 20 6e 61 6d  ote that the nam
30280 65 0a 2a 2a 20 6c 65 6e 67 74 68 20 6c 69 6d 69  e.** length limi
30290 74 20 69 73 20 69 6e 20 55 54 46 2d 38 20 62 79  t is in UTF-8 by
302a0 74 65 73 2c 20 6e 6f 74 20 63 68 61 72 61 63 74  tes, not charact
302b0 65 72 73 20 6e 6f 72 20 55 54 46 2d 31 36 20 62  ers nor UTF-16 b
302c0 79 74 65 73 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20  ytes.  .** ^Any 
302d0 61 74 74 65 6d 70 74 20 74 6f 20 63 72 65 61 74  attempt to creat
302e0 65 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74  e a function wit
302f0 68 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a  h a longer name.
30300 2a 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74 20 69  ** will result i
30310 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  n [SQLITE_MISUSE
30320 5d 20 62 65 69 6e 67 20 72 65 74 75 72 6e 65 64  ] being returned
30330 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69  ..**.** ^The thi
30340 72 64 20 70 61 72 61 6d 65 74 65 72 20 28 6e 41  rd parameter (nA
30350 72 67 29 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75  rg).** is the nu
30360 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74  mber of argument
30370 73 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 66  s that the SQL f
30380 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67  unction or.** ag
30390 67 72 65 67 61 74 65 20 74 61 6b 65 73 2e 20 5e  gregate takes. ^
303a0 49 66 20 74 68 69 73 20 70 61 72 61 6d 65 74 65  If this paramete
303b0 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 74 68  r is -1, then th
303c0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f  e SQL function o
303d0 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 6d  r.** aggregate m
303e0 61 79 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62  ay take any numb
303f0 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20  er of arguments 
30400 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68  between 0 and th
30410 65 20 6c 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62  e limit.** set b
30420 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  y [sqlite3_limit
30430 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ]([SQLITE_LIMIT_
30440 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20  FUNCTION_ARG]). 
30450 20 49 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a   If the third.**
30460 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6c 65   parameter is le
30470 73 73 20 74 68 61 6e 20 2d 31 20 6f 72 20 67 72  ss than -1 or gr
30480 65 61 74 65 72 20 74 68 61 6e 20 31 32 37 20 74  eater than 127 t
30490 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
304a0 20 69 73 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64   is.** undefined
304b0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75  ..**.** ^The fou
304c0 72 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20 65  rth parameter, e
304d0 54 65 78 74 52 65 70 2c 20 73 70 65 63 69 66 69  TextRep, specifi
304e0 65 73 20 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49  es what.** [SQLI
304f0 54 45 5f 55 54 46 38 20 7c 20 74 65 78 74 20 65  TE_UTF8 | text e
30500 6e 63 6f 64 69 6e 67 5d 20 74 68 69 73 20 53 51  ncoding] this SQ
30510 4c 20 66 75 6e 63 74 69 6f 6e 20 70 72 65 66 65  L function prefe
30520 72 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61  rs for.** its pa
30530 72 61 6d 65 74 65 72 73 2e 20 20 45 76 65 72 79  rameters.  Every
30540 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d   SQL function im
30550 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73  plementation mus
30560 74 20 62 65 20 61 62 6c 65 20 74 6f 20 77 6f 72  t be able to wor
30570 6b 0a 2a 2a 20 77 69 74 68 20 55 54 46 2d 38 2c  k.** with UTF-8,
30580 20 55 54 46 2d 31 36 6c 65 2c 20 6f 72 20 55 54   UTF-16le, or UT
30590 46 2d 31 36 62 65 2e 20 20 42 75 74 20 73 6f 6d  F-16be.  But som
305a0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
305b0 73 20 6d 61 79 20 62 65 0a 2a 2a 20 6d 6f 72 65  s may be.** more
305c0 20 65 66 66 69 63 69 65 6e 74 20 77 69 74 68 20   efficient with 
305d0 6f 6e 65 20 65 6e 63 6f 64 69 6e 67 20 74 68 61  one encoding tha
305e0 6e 20 61 6e 6f 74 68 65 72 2e 20 20 5e 41 6e 20  n another.  ^An 
305f0 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 0a  application may.
30600 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  ** invoke sqlite
30610 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
30620 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  n() or sqlite3_c
30630 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
30640 28 29 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 74  () multiple.** t
30650 69 6d 65 73 20 77 69 74 68 20 74 68 65 20 73 61  imes with the sa
30660 6d 65 20 66 75 6e 63 74 69 6f 6e 20 62 75 74 20  me function but 
30670 77 69 74 68 20 64 69 66 66 65 72 65 6e 74 20 76  with different v
30680 61 6c 75 65 73 20 6f 66 20 65 54 65 78 74 52 65  alues of eTextRe
30690 70 2e 0a 2a 2a 20 5e 57 68 65 6e 20 6d 75 6c 74  p..** ^When mult
306a0 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  iple implementat
306b0 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
306c0 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 61 76   function are av
306d0 61 69 6c 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a  ailable, SQLite.
306e0 2a 2a 20 77 69 6c 6c 20 70 69 63 6b 20 74 68 65  ** will pick the
306f0 20 6f 6e 65 20 74 68 61 74 20 69 6e 76 6f 6c 76   one that involv
30700 65 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f  es the least amo
30710 75 6e 74 20 6f 66 20 64 61 74 61 20 63 6f 6e 76  unt of data conv
30720 65 72 73 69 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68  ersion..** If th
30730 65 72 65 20 69 73 20 6f 6e 6c 79 20 61 20 73 69  ere is only a si
30740 6e 67 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ngle implementat
30750 69 6f 6e 20 77 68 69 63 68 20 64 6f 65 73 20 6e  ion which does n
30760 6f 74 20 63 61 72 65 20 77 68 61 74 20 74 65 78  ot care what tex
30770 74 0a 2a 2a 20 65 6e 63 6f 64 69 6e 67 20 69 73  t.** encoding is
30780 20 75 73 65 64 2c 20 74 68 65 6e 20 74 68 65 20   used, then the 
30790 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20  fourth argument 
307a0 73 68 6f 75 6c 64 20 62 65 20 5b 53 51 4c 49 54  should be [SQLIT
307b0 45 5f 41 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28  E_ANY]..**.** ^(
307c0 54 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65  The fifth parame
307d0 74 65 72 20 69 73 20 61 6e 20 61 72 62 69 74 72  ter is an arbitr
307e0 61 72 79 20 70 6f 69 6e 74 65 72 2e 20 20 54 68  ary pointer.  Th
307f0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
30800 20 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74   of the.** funct
30810 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61 63 63  ion can gain acc
30820 65 73 73 20 74 6f 20 74 68 69 73 20 70 6f 69 6e  ess to this poin
30830 74 65 72 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ter using [sqlit
30840 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2e  e3_user_data()].
30850 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69  )^.**.** ^The si
30860 78 74 68 2c 20 73 65 76 65 6e 74 68 20 61 6e 64  xth, seventh and
30870 20 65 69 67 68 74 68 20 70 61 72 61 6d 65 74 65   eighth paramete
30880 72 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 70  rs, xFunc, xStep
30890 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 65   and xFinal, are
308a0 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20  .** pointers to 
308b0 43 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 74  C-language funct
308c0 69 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 6d  ions that implem
308d0 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63  ent the SQL func
308e0 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65  tion or.** aggre
308f0 67 61 74 65 2e 20 5e 41 20 73 63 61 6c 61 72 20  gate. ^A scalar 
30900 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71  SQL function req
30910 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65  uires an impleme
30920 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78  ntation of the x
30930 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  Func.** callback
30940 20 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e   only; NULL poin
30950 74 65 72 73 20 6d 75 73 74 20 62 65 20 70 61 73  ters must be pas
30960 73 65 64 20 61 73 20 74 68 65 20 78 53 74 65 70  sed as the xStep
30970 20 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70   and xFinal.** p
30980 61 72 61 6d 65 74 65 72 73 2e 20 5e 41 6e 20 61  arameters. ^An a
30990 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e  ggregate SQL fun
309a0 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61  ction requires a
309b0 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
309c0 20 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64   of xStep.** and
309d0 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c   xFinal and NULL
309e0 20 70 6f 69 6e 74 65 72 20 6d 75 73 74 20 62 65   pointer must be
309f0 20 70 61 73 73 65 64 20 66 6f 72 20 78 46 75 6e   passed for xFun
30a00 63 2e 20 5e 54 6f 20 64 65 6c 65 74 65 20 61 6e  c. ^To delete an
30a10 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c   existing.** SQL
30a20 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67   function or agg
30a30 72 65 67 61 74 65 2c 20 70 61 73 73 20 4e 55 4c  regate, pass NUL
30a40 4c 20 70 6f 69 6e 74 65 72 73 20 66 6f 72 20 61  L pointers for a
30a50 6c 6c 20 74 68 72 65 65 20 66 75 6e 63 74 69 6f  ll three functio
30a60 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 73 2e 0a  n.** callbacks..
30a70 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20 6e  **.** ^(If the n
30a80 69 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  inth parameter t
30a90 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  o sqlite3_create
30aa0 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 69  _function_v2() i
30ab0 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74  s not NULL,.** t
30ac0 68 65 6e 20 69 74 20 69 73 20 64 65 73 74 72 75  hen it is destru
30ad0 63 74 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70  ctor for the app
30ae0 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f  lication data po
30af0 69 6e 74 65 72 2e 20 0a 2a 2a 20 54 68 65 20 64  inter. .** The d
30b00 65 73 74 72 75 63 74 6f 72 20 69 73 20 69 6e 76  estructor is inv
30b10 6f 6b 65 64 20 77 68 65 6e 20 74 68 65 20 66 75  oked when the fu
30b20 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c 65 74 65  nction is delete
30b30 64 2c 20 65 69 74 68 65 72 20 62 79 20 62 65 69  d, either by bei
30b40 6e 67 0a 2a 2a 20 6f 76 65 72 6c 6f 61 64 65 64  ng.** overloaded
30b50 20 6f 72 20 77 68 65 6e 20 74 68 65 20 64 61 74   or when the dat
30b60 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
30b70 20 63 6c 6f 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54   closes.)^.** ^T
30b80 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73  he destructor is
30b90 20 61 6c 73 6f 20 69 6e 76 6f 6b 65 64 20 69 66   also invoked if
30ba0 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20   the call to.** 
30bb0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
30bc0 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 66 61 69  unction_v2() fai
30bd0 6c 73 2e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65  ls..** ^When the
30be0 20 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c   destructor call
30bf0 62 61 63 6b 20 6f 66 20 74 68 65 20 74 65 6e 74  back of the tent
30c00 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 69  h parameter is i
30c10 6e 76 6f 6b 65 64 2c 20 69 74 0a 2a 2a 20 69 73  nvoked, it.** is
30c20 20 70 61 73 73 65 64 20 61 20 73 69 6e 67 6c 65   passed a single
30c30 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
30c40 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  is a copy of the
30c50 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74   application dat
30c60 61 20 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 77 68  a .** pointer wh
30c70 69 63 68 20 77 61 73 20 74 68 65 20 66 69 66 74  ich was the fift
30c80 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
30c90 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
30ca0 6e 63 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a  nction_v2()..**.
30cb0 2a 2a 20 5e 49 74 20 69 73 20 70 65 72 6d 69 74  ** ^It is permit
30cc0 74 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 20  ted to register 
30cd0 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65  multiple impleme
30ce0 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ntations of the 
30cf0 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  same.** function
30d00 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20  s with the same 
30d10 6e 61 6d 65 20 62 75 74 20 77 69 74 68 20 65 69  name but with ei
30d20 74 68 65 72 20 64 69 66 66 65 72 69 6e 67 20 6e  ther differing n
30d30 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67  umbers of.** arg
30d40 75 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 65 72  uments or differ
30d50 69 6e 67 20 70 72 65 66 65 72 72 65 64 20 74 65  ing preferred te
30d60 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 5e  xt encodings.  ^
30d70 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a  SQLite will use.
30d80 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  ** the implement
30d90 61 74 69 6f 6e 20 74 68 61 74 20 6d 6f 73 74 20  ation that most 
30da0 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 20  closely matches 
30db0 74 68 65 20 77 61 79 20 69 6e 20 77 68 69 63 68  the way in which
30dc0 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63   the.** SQL func
30dd0 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 20 20 5e  tion is used.  ^
30de0 41 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65  A function imple
30df0 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 20 61  mentation with a
30e00 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a 2a   non-negative.**
30e10 20 6e 41 72 67 20 70 61 72 61 6d 65 74 65 72 20   nArg parameter 
30e20 69 73 20 61 20 62 65 74 74 65 72 20 6d 61 74 63  is a better matc
30e30 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f  h than a functio
30e40 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
30e50 20 77 69 74 68 0a 2a 2a 20 61 20 6e 65 67 61 74   with.** a negat
30e60 69 76 65 20 6e 41 72 67 2e 20 20 5e 41 20 66 75  ive nArg.  ^A fu
30e70 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65  nction where the
30e80 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20   preferred text 
30e90 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 63  encoding.** matc
30ea0 68 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65  hes the database
30eb0 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 61 20 62   encoding is a b
30ec0 65 74 74 65 72 0a 2a 2a 20 6d 61 74 63 68 20 74  etter.** match t
30ed0 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77  han a function w
30ee0 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e  here the encodin
30ef0 67 20 69 73 20 64 69 66 66 65 72 65 6e 74 2e 20  g is different. 
30f00 20 0a 2a 2a 20 5e 41 20 66 75 6e 63 74 69 6f 6e   .** ^A function
30f10 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64   where the encod
30f20 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69  ing difference i
30f30 73 20 62 65 74 77 65 65 6e 20 55 54 46 31 36 6c  s between UTF16l
30f40 65 20 61 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a  e and UTF16be.**
30f50 20 69 73 20 61 20 63 6c 6f 73 65 72 20 6d 61 74   is a closer mat
30f60 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69  ch than a functi
30f70 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63  on where the enc
30f80 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65  oding difference
30f90 20 69 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55   is.** between U
30fa0 54 46 38 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a  TF8 and UTF16..*
30fb0 2a 0a 2a 2a 20 5e 42 75 69 6c 74 2d 69 6e 20 66  *.** ^Built-in f
30fc0 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20  unctions may be 
30fd0 6f 76 65 72 6c 6f 61 64 65 64 20 62 79 20 6e 65  overloaded by ne
30fe0 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  w application-de
30ff0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 2e  fined functions.
31000 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c 69  .**.** ^An appli
31010 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
31020 75 6e 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69  unction is permi
31030 74 74 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74 68  tted to call oth
31040 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74  er.** SQLite int
31050 65 72 66 61 63 65 73 2e 20 20 48 6f 77 65 76 65  erfaces.  Howeve
31060 72 2c 20 73 75 63 68 20 63 61 6c 6c 73 20 6d 75  r, such calls mu
31070 73 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20  st not.** close 
31080 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
31090 6e 65 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e 61  nection nor fina
310a0 6c 69 7a 65 20 6f 72 20 72 65 73 65 74 20 74 68  lize or reset th
310b0 65 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74  e prepared.** st
310c0 61 74 65 6d 65 6e 74 20 69 6e 20 77 68 69 63 68  atement in which
310d0 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73   the function is
310e0 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c   running..*/.SQL
310f0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
31100 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
31110 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  ion(.  sqlite3 *
31120 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  db,.  const char
31130 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c   *zFunctionName,
31140 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69  .  int nArg,.  i
31150 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76  nt eTextRep,.  v
31160 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69  oid *pApp,.  voi
31170 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74  d (*xFunc)(sqlit
31180 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
31190 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
311a0 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70  ,.  void (*xStep
311b0 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
311c0 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
311d0 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
311e0 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65  (*xFinal)(sqlite
311f0 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 53  3_context*).);.S
31200 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
31210 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
31220 63 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74  ction16(.  sqlit
31230 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20  e3 *db,.  const 
31240 76 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e  void *zFunctionN
31250 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c  ame,.  int nArg,
31260 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
31270 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20  .  void *pApp,. 
31280 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73   void (*xFunc)(s
31290 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
312a0 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
312b0 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
312c0 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f  Step)(sqlite3_co
312d0 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
312e0 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
312f0 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71  oid (*xFinal)(sq
31300 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a  lite3_context*).
31310 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
31320 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
31330 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 0a 20 20  _function_v2(.  
31340 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63  sqlite3 *db,.  c
31350 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63  onst char *zFunc
31360 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20  tionName,.  int 
31370 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78  nArg,.  int eTex
31380 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41  tRep,.  void *pA
31390 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75  pp,.  void (*xFu
313a0 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  nc)(sqlite3_cont
313b0 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
313c0 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
313d0 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74  d (*xStep)(sqlit
313e0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
313f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
31400 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61  ,.  void (*xFina
31410 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  l)(sqlite3_conte
31420 78 74 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44  xt*),.  void(*xD
31430 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29  estroy)(void*).)
31440 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
31450 46 3a 20 54 65 78 74 20 45 6e 63 6f 64 69 6e 67  F: Text Encoding
31460 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  s.**.** These co
31470 6e 73 74 61 6e 74 20 64 65 66 69 6e 65 20 69 6e  nstant define in
31480 74 65 67 65 72 20 63 6f 64 65 73 20 74 68 61 74  teger codes that
31490 20 72 65 70 72 65 73 65 6e 74 20 74 68 65 20 76   represent the v
314a0 61 72 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65  arious.** text e
314b0 6e 63 6f 64 69 6e 67 73 20 73 75 70 70 6f 72 74  ncodings support
314c0 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f  ed by SQLite..*/
314d0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
314e0 55 54 46 38 20 20 20 20 20 20 20 20 20 20 20 31  UTF8           1
314f0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
31500 55 54 46 31 36 4c 45 20 20 20 20 20 20 20 20 32  UTF16LE        2
31510 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
31520 55 54 46 31 36 42 45 20 20 20 20 20 20 20 20 33  UTF16BE        3
31530 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
31540 55 54 46 31 36 20 20 20 20 20 20 20 20 20 20 34  UTF16          4
31550 20 20 20 20 2f 2a 20 55 73 65 20 6e 61 74 69 76      /* Use nativ
31560 65 20 62 79 74 65 20 6f 72 64 65 72 20 2a 2f 0a  e byte order */.
31570 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
31580 4e 59 20 20 20 20 20 20 20 20 20 20 20 20 35 20  NY            5 
31590 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72     /* sqlite3_cr
315a0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 20 6f 6e  eate_function on
315b0 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
315c0 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e  LITE_UTF16_ALIGN
315d0 45 44 20 20 38 20 20 20 20 2f 2a 20 73 71 6c 69  ED  8    /* sqli
315e0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
315f0 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a  tion only */../*
31600 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
31610 70 72 65 63 61 74 65 64 20 46 75 6e 63 74 69 6f  precated Functio
31620 6e 73 0a 2a 2a 20 44 45 50 52 45 43 41 54 45 44  ns.** DEPRECATED
31630 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e  .**.** These fun
31640 63 74 69 6f 6e 73 20 61 72 65 20 5b 64 65 70 72  ctions are [depr
31650 65 63 61 74 65 64 5d 2e 20 20 49 6e 20 6f 72 64  ecated].  In ord
31660 65 72 20 74 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a  er to maintain.*
31670 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70  * backwards comp
31680 61 74 69 62 69 6c 69 74 79 20 77 69 74 68 20 6f  atibility with o
31690 6c 64 65 72 20 63 6f 64 65 2c 20 74 68 65 73 65  lder code, these
316a0 20 66 75 6e 63 74 69 6f 6e 73 20 63 6f 6e 74 69   functions conti
316b0 6e 75 65 20 0a 2a 2a 20 74 6f 20 62 65 20 73 75  nue .** to be su
316c0 70 70 6f 72 74 65 64 2e 20 20 48 6f 77 65 76 65  pported.  Howeve
316d0 72 2c 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69  r, new applicati
316e0 6f 6e 73 20 73 68 6f 75 6c 64 20 61 76 6f 69 64  ons should avoid
316f0 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20 74  .** the use of t
31700 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20  hese functions. 
31710 20 54 6f 20 68 65 6c 70 20 65 6e 63 6f 75 72 61   To help encoura
31720 67 65 20 70 65 6f 70 6c 65 20 74 6f 20 61 76 6f  ge people to avo
31730 69 64 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65 73  id.** using thes
31740 65 20 66 75 6e 63 74 69 6f 6e 73 2c 20 77 65 20  e functions, we 
31750 61 72 65 20 6e 6f 74 20 67 6f 69 6e 67 20 74 6f  are not going to
31760 20 74 65 6c 6c 20 79 6f 75 20 77 68 61 74 20 74   tell you what t
31770 68 65 79 20 64 6f 2e 0a 2a 2f 0a 23 69 66 6e 64  hey do..*/.#ifnd
31780 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 44  ef SQLITE_OMIT_D
31790 45 50 52 45 43 41 54 45 44 0a 53 51 4c 49 54 45  EPRECATED.SQLITE
317a0 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52  _API SQLITE_DEPR
317b0 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74  ECATED int sqlit
317c0 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 75  e3_aggregate_cou
317d0 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  nt(sqlite3_conte
317e0 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  xt*);.SQLITE_API
317f0 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54   SQLITE_DEPRECAT
31800 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  ED int sqlite3_e
31810 78 70 69 72 65 64 28 73 71 6c 69 74 65 33 5f 73  xpired(sqlite3_s
31820 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  tmt*);.SQLITE_AP
31830 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  I SQLITE_DEPRECA
31840 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TED int sqlite3_
31850 74 72 61 6e 73 66 65 72 5f 62 69 6e 64 69 6e 67  transfer_binding
31860 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  s(sqlite3_stmt*,
31870 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b   sqlite3_stmt*);
31880 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49  .SQLITE_API SQLI
31890 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e  TE_DEPRECATED in
318a0 74 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c  t sqlite3_global
318b0 5f 72 65 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a  _recover(void);.
318c0 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54  SQLITE_API SQLIT
318d0 45 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f 69  E_DEPRECATED voi
318e0 64 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64  d sqlite3_thread
318f0 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a  _cleanup(void);.
31900 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54  SQLITE_API SQLIT
31910 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74  E_DEPRECATED int
31920 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f   sqlite3_memory_
31930 61 6c 61 72 6d 28 76 6f 69 64 28 2a 29 28 76 6f  alarm(void(*)(vo
31940 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36  id*,sqlite3_int6
31950 34 2c 69 6e 74 29 2c 0a 20 20 20 20 20 20 20 20  4,int),.        
31960 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f                vo
31970 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36  id*,sqlite3_int6
31980 34 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a  4);.#endif../*.*
31990 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61  * CAPI3REF: Obta
319a0 69 6e 69 6e 67 20 53 51 4c 20 46 75 6e 63 74 69  ining SQL Functi
319b0 6f 6e 20 50 61 72 61 6d 65 74 65 72 20 56 61 6c  on Parameter Val
319c0 75 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d  ues.**.** The C-
319d0 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d 65  language impleme
319e0 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66  ntation of SQL f
319f0 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67  unctions and agg
31a00 72 65 67 61 74 65 73 20 75 73 65 73 0a 2a 2a 20  regates uses.** 
31a10 74 68 69 73 20 73 65 74 20 6f 66 20 69 6e 74 65  this set of inte
31a20 72 66 61 63 65 20 72 6f 75 74 69 6e 65 73 20 74  rface routines t
31a30 6f 20 61 63 63 65 73 73 20 74 68 65 20 70 61 72  o access the par
31a40 61 6d 65 74 65 72 20 76 61 6c 75 65 73 20 6f 6e  ameter values on
31a50 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  .** the function
31a60 20 6f 72 20 61 67 67 72 65 67 61 74 65 2e 0a 2a   or aggregate..*
31a70 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63 20 28  *.** The xFunc (
31a80 66 6f 72 20 73 63 61 6c 61 72 20 66 75 6e 63 74  for scalar funct
31a90 69 6f 6e 73 29 20 6f 72 20 78 53 74 65 70 20 28  ions) or xStep (
31aa0 66 6f 72 20 61 67 67 72 65 67 61 74 65 73 29 20  for aggregates) 
31ab0 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f  parameters.** to
31ac0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
31ad0 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64  _function()] and
31ae0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
31af0 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a  _function16()].*
31b00 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c 62 61 63  * define callbac
31b10 6b 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  ks that implemen
31b20 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  t the SQL functi
31b30 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74  ons and aggregat
31b40 65 73 2e 0a 2a 2a 20 54 68 65 20 33 72 64 20 70  es..** The 3rd p
31b50 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 73  arameter to thes
31b60 65 20 63 61 6c 6c 62 61 63 6b 73 20 69 73 20 61  e callbacks is a
31b70 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
31b80 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65  ers to.** [prote
31b90 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
31ba0 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54 68  ue] objects.  Th
31bb0 65 72 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69  ere is one [sqli
31bc0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
31bd0 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61  t for.** each pa
31be0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 53  rameter to the S
31bf0 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68  QL function.  Th
31c00 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
31c10 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72   used to.** extr
31c20 61 63 74 20 76 61 6c 75 65 73 20 66 72 6f 6d 20  act values from 
31c30 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  the [sqlite3_val
31c40 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a  ue] objects..**.
31c50 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
31c60 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 68  s work only with
31c70 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
31c80 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
31c90 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d  ts..** Any attem
31ca0 70 74 20 74 6f 20 75 73 65 20 74 68 65 73 65 20  pt to use these 
31cb0 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20 5b  routines on an [
31cc0 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
31cd0 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62  te3_value].** ob
31ce0 6a 65 63 74 20 72 65 73 75 6c 74 73 20 69 6e 20  ject results in 
31cf0 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69  undefined behavi
31d00 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  or..**.** ^These
31d10 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a   routines work j
31d20 75 73 74 20 6c 69 6b 65 20 74 68 65 20 63 6f 72  ust like the cor
31d30 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75  responding [colu
31d40 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69  mn access functi
31d50 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 74 20 74  ons].** except t
31d60 68 61 74 20 20 74 68 65 73 65 20 72 6f 75 74 69  hat  these routi
31d70 6e 65 73 20 74 61 6b 65 20 61 20 73 69 6e 67 6c  nes take a singl
31d80 65 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  e [protected sql
31d90 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
31da0 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e  ct.** pointer in
31db0 73 74 65 61 64 20 6f 66 20 61 20 5b 73 71 6c 69  stead of a [sqli
31dc0 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74  te3_stmt*] point
31dd0 65 72 20 61 6e 64 20 61 6e 20 69 6e 74 65 67 65  er and an intege
31de0 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e  r column number.
31df0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
31e00 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
31e10 28 29 20 69 6e 74 65 72 66 61 63 65 20 65 78 74  () interface ext
31e20 72 61 63 74 73 20 61 20 55 54 46 2d 31 36 20 73  racts a UTF-16 s
31e30 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20  tring.** in the 
31e40 6e 61 74 69 76 65 20 62 79 74 65 2d 6f 72 64 65  native byte-orde
31e50 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20 6d 61  r of the host ma
31e60 63 68 69 6e 65 2e 20 20 5e 54 68 65 0a 2a 2a 20  chine.  ^The.** 
31e70 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
31e80 78 74 31 36 62 65 28 29 20 61 6e 64 20 73 71 6c  xt16be() and sql
31e90 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
31ea0 36 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 73  6le() interfaces
31eb0 0a 2a 2a 20 65 78 74 72 61 63 74 20 55 54 46 2d  .** extract UTF-
31ec0 31 36 20 73 74 72 69 6e 67 73 20 61 73 20 62 69  16 strings as bi
31ed0 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74  g-endian and lit
31ee0 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73 70 65  tle-endian respe
31ef0 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e  ctively..**.** ^
31f00 28 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c  (The sqlite3_val
31f10 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28  ue_numeric_type(
31f20 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65  ) interface atte
31f30 6d 70 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a  mpts to apply.**
31f40 20 6e 75 6d 65 72 69 63 20 61 66 66 69 6e 69 74   numeric affinit
31f50 79 20 74 6f 20 74 68 65 20 76 61 6c 75 65 2e 20  y to the value. 
31f60 20 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74   This means that
31f70 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 0a 2a   an attempt is.*
31f80 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65 72  * made to conver
31f90 74 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 61  t the value to a
31fa0 6e 20 69 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f  n integer or flo
31fb0 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66  ating point.  If
31fc0 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e 76 65  .** such a conve
31fd0 72 73 69 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c  rsion is possibl
31fe0 65 20 77 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f  e without loss o
31ff0 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69  f information (i
32000 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64 73  n other.** words
32010 2c 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 69  , if the value i
32020 73 20 61 20 73 74 72 69 6e 67 20 74 68 61 74 20  s a string that 
32030 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d  looks like a num
32040 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ber).** then the
32050 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70   conversion is p
32060 65 72 66 6f 72 6d 65 64 2e 20 20 4f 74 68 65 72  erformed.  Other
32070 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69  wise no conversi
32080 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 68  on occurs..** Th
32090 65 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  e [SQLITE_INTEGE
320a0 52 20 7c 20 64 61 74 61 74 79 70 65 5d 20 61 66  R | datatype] af
320b0 74 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69  ter conversion i
320c0 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a  s returned.)^.**
320d0 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61 79 20 70  .** Please pay p
320e0 61 72 74 69 63 75 6c 61 72 20 61 74 74 65 6e 74  articular attent
320f0 69 6f 6e 20 74 6f 20 74 68 65 20 66 61 63 74 20  ion to the fact 
32100 74 68 61 74 20 74 68 65 20 70 6f 69 6e 74 65 72  that the pointer
32110 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f   returned.** fro
32120 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  m [sqlite3_value
32130 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74  _blob()], [sqlit
32140 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d  e3_value_text()]
32150 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  , or.** [sqlite3
32160 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d  _value_text16()]
32170 20 63 61 6e 20 62 65 20 69 6e 76 61 6c 69 64 61   can be invalida
32180 74 65 64 20 62 79 20 61 20 73 75 62 73 65 71 75  ted by a subsequ
32190 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  ent call to.** [
321a0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
321b0 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  tes()], [sqlite3
321c0 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 29  _value_bytes16()
321d0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ], [sqlite3_valu
321e0 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72  e_text()],.** or
321f0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
32200 74 65 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a  text16()]..**.**
32210 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
32220 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66  must be called f
32230 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72  rom the same thr
32240 65 61 64 20 61 73 0a 2a 2a 20 74 68 65 20 53 51  ead as.** the SQ
32250 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20  L function that 
32260 73 75 70 70 6c 69 65 64 20 74 68 65 20 5b 73 71  supplied the [sq
32270 6c 69 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70 61  lite3_value*] pa
32280 72 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a 53 51 4c  rameters..*/.SQL
32290 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f  ITE_API const vo
322a0 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75  id *sqlite3_valu
322b0 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 76  e_blob(sqlite3_v
322c0 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41  alue*);.SQLITE_A
322d0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 76  PI int sqlite3_v
322e0 61 6c 75 65 5f 62 79 74 65 73 28 73 71 6c 69 74  alue_bytes(sqlit
322f0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49  e3_value*);.SQLI
32300 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
32310 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36  e3_value_bytes16
32320 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
32330 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 64 6f 75  ;.SQLITE_API dou
32340 62 6c 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ble sqlite3_valu
32350 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33  e_double(sqlite3
32360 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45  _value*);.SQLITE
32370 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
32380 5f 76 61 6c 75 65 5f 69 6e 74 28 73 71 6c 69 74  _value_int(sqlit
32390 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49  e3_value*);.SQLI
323a0 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69  TE_API sqlite3_i
323b0 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 76 61 6c  nt64 sqlite3_val
323c0 75 65 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33  ue_int64(sqlite3
323d0 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45  _value*);.SQLITE
323e0 5f 41 50 49 20 63 6f 6e 73 74 20 75 6e 73 69 67  _API const unsig
323f0 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65  ned char *sqlite
32400 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 73 71 6c  3_value_text(sql
32410 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51  ite3_value*);.SQ
32420 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76  LITE_API const v
32430 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c  oid *sqlite3_val
32440 75 65 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65  ue_text16(sqlite
32450 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54  3_value*);.SQLIT
32460 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64  E_API const void
32470 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   *sqlite3_value_
32480 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33  text16le(sqlite3
32490 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45  _value*);.SQLITE
324a0 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20  _API const void 
324b0 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  *sqlite3_value_t
324c0 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f  ext16be(sqlite3_
324d0 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f  value*);.SQLITE_
324e0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
324f0 76 61 6c 75 65 5f 74 79 70 65 28 73 71 6c 69 74  value_type(sqlit
32500 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49  e3_value*);.SQLI
32510 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
32520 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63  e3_value_numeric
32530 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61  _type(sqlite3_va
32540 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  lue*);../*.** CA
32550 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 41  PI3REF: Obtain A
32560 67 67 72 65 67 61 74 65 20 46 75 6e 63 74 69 6f  ggregate Functio
32570 6e 20 43 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20  n Context.**.** 
32580 49 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  Implementations 
32590 6f 66 20 61 67 67 72 65 67 61 74 65 20 53 51 4c  of aggregate SQL
325a0 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 20 74   functions use t
325b0 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 74  his.** routine t
325c0 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72  o allocate memor
325d0 79 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 74 68  y for storing th
325e0 65 69 72 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a  eir state..**.**
325f0 20 5e 54 68 65 20 66 69 72 73 74 20 74 69 6d 65   ^The first time
32600 20 74 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67   the sqlite3_agg
32610 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43  regate_context(C
32620 2c 4e 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63  ,N) routine is c
32630 61 6c 6c 65 64 20 0a 2a 2a 20 66 6f 72 20 61 20  alled .** for a 
32640 70 61 72 74 69 63 75 6c 61 72 20 61 67 67 72 65  particular aggre
32650 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 2c 20 53  gate function, S
32660 51 4c 69 74 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74  QLite.** allocat
32670 65 73 20 4e 20 6f 66 20 6d 65 6d 6f 72 79 2c 20  es N of memory, 
32680 7a 65 72 6f 65 73 20 6f 75 74 20 74 68 61 74 20  zeroes out that 
32690 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74 75  memory, and retu
326a0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a  rns a pointer.**
326b0 20 74 6f 20 74 68 65 20 6e 65 77 20 6d 65 6d 6f   to the new memo
326c0 72 79 2e 20 5e 4f 6e 20 73 65 63 6f 6e 64 20 61  ry. ^On second a
326d0 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  nd subsequent ca
326e0 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  lls to.** sqlite
326f0 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
32700 65 78 74 28 29 20 66 6f 72 20 74 68 65 20 73 61  ext() for the sa
32710 6d 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e  me aggregate fun
32720 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 2c 0a  ction instance,.
32730 2a 2a 20 74 68 65 20 73 61 6d 65 20 62 75 66 66  ** the same buff
32740 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  er is returned. 
32750 20 53 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   Sqlite3_aggrega
32760 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 69 73 20  te_context() is 
32770 6e 6f 72 6d 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c  normally.** call
32780 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68  ed once for each
32790 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74   invocation of t
327a0 68 65 20 78 53 74 65 70 20 63 61 6c 6c 62 61 63  he xStep callbac
327b0 6b 20 61 6e 64 20 74 68 65 6e 20 6f 6e 65 0a 2a  k and then one.*
327c0 2a 20 6c 61 73 74 20 74 69 6d 65 20 77 68 65 6e  * last time when
327d0 20 74 68 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c   the xFinal call
327e0 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2e  back is invoked.
327f0 20 20 5e 28 57 68 65 6e 20 6e 6f 20 72 6f 77 73    ^(When no rows
32800 20 6d 61 74 63 68 0a 2a 2a 20 61 6e 20 61 67 67   match.** an agg
32810 72 65 67 61 74 65 20 71 75 65 72 79 2c 20 74 68  regate query, th
32820 65 20 78 53 74 65 70 28 29 20 63 61 6c 6c 62 61  e xStep() callba
32830 63 6b 20 6f 66 20 74 68 65 20 61 67 67 72 65 67  ck of the aggreg
32840 61 74 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ate function.** 
32850 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
32860 73 20 6e 65 76 65 72 20 63 61 6c 6c 65 64 20 61  s never called a
32870 6e 64 20 78 46 69 6e 61 6c 28 29 20 69 73 20 63  nd xFinal() is c
32880 61 6c 6c 65 64 20 65 78 61 63 74 6c 79 20 6f 6e  alled exactly on
32890 63 65 2e 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 20  ce..** In those 
328a0 63 61 73 65 73 2c 20 73 71 6c 69 74 65 33 5f 61  cases, sqlite3_a
328b0 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
328c0 28 29 20 6d 69 67 68 74 20 62 65 20 63 61 6c 6c  () might be call
328d0 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 66 69  ed for the.** fi
328e0 72 73 74 20 74 69 6d 65 20 66 72 6f 6d 20 77 69  rst time from wi
328f0 74 68 69 6e 20 78 46 69 6e 61 6c 28 29 2e 29 5e  thin xFinal().)^
32900 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
32910 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
32920 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69  ntext(C,N) routi
32930 6e 65 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c  ne returns a NUL
32940 4c 20 70 6f 69 6e 74 65 72 20 0a 2a 2a 20 77 68  L pointer .** wh
32950 65 6e 20 66 69 72 73 74 20 63 61 6c 6c 65 64 20  en first called 
32960 69 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61  if N is less tha
32970 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65  n or equal to ze
32980 72 6f 20 6f 72 20 69 66 20 61 20 6d 65 6d 6f 72  ro or if a memor
32990 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 65 72  y.** allocate er
329a0 72 6f 72 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a 2a  ror occurs..**.*
329b0 2a 20 5e 28 54 68 65 20 61 6d 6f 75 6e 74 20 6f  * ^(The amount o
329c0 66 20 73 70 61 63 65 20 61 6c 6c 6f 63 61 74 65  f space allocate
329d0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 61 67 67  d by sqlite3_agg
329e0 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43  regate_context(C
329f0 2c 4e 29 20 69 73 0a 2a 2a 20 64 65 74 65 72 6d  ,N) is.** determ
32a00 69 6e 65 64 20 62 79 20 74 68 65 20 4e 20 70 61  ined by the N pa
32a10 72 61 6d 65 74 65 72 20 6f 6e 20 66 69 72 73 74  rameter on first
32a20 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c   successful call
32a30 2e 20 20 43 68 61 6e 67 69 6e 67 20 74 68 65 0a  .  Changing the.
32a40 2a 2a 20 76 61 6c 75 65 20 6f 66 20 4e 20 69 6e  ** value of N in
32a50 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
32a60 20 74 6f 20 73 71 6c 69 74 65 33 5f 61 67 67 72   to sqlite3_aggr
32a70 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20  egate_context() 
32a80 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 73 61  within.** the sa
32a90 6d 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e  me aggregate fun
32aa0 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 20 77  ction instance w
32ab0 69 6c 6c 20 6e 6f 74 20 72 65 73 69 7a 65 20 74  ill not resize t
32ac0 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c  he memory.** all
32ad0 6f 63 61 74 69 6f 6e 2e 29 5e 20 20 57 69 74 68  ocation.)^  With
32ae0 69 6e 20 74 68 65 20 78 46 69 6e 61 6c 20 63 61  in the xFinal ca
32af0 6c 6c 62 61 63 6b 2c 20 69 74 20 69 73 20 63 75  llback, it is cu
32b00 73 74 6f 6d 61 72 79 20 74 6f 20 73 65 74 0a 2a  stomary to set.*
32b10 2a 20 4e 3d 30 20 69 6e 20 63 61 6c 6c 73 20 74  * N=0 in calls t
32b20 6f 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  o sqlite3_aggreg
32b30 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29  ate_context(C,N)
32b40 20 73 6f 20 74 68 61 74 20 6e 6f 20 0a 2a 2a 20   so that no .** 
32b50 70 6f 69 6e 74 6c 65 73 73 20 6d 65 6d 6f 72 79  pointless memory
32b60 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 6f 63 63   allocations occ
32b70 75 72 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74  ur..**.** ^SQLit
32b80 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  e automatically 
32b90 66 72 65 65 73 20 74 68 65 20 6d 65 6d 6f 72 79  frees the memory
32ba0 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 0a 2a   allocated by .*
32bb0 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  * sqlite3_aggreg
32bc0 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 68  ate_context() wh
32bd0 65 6e 20 74 68 65 20 61 67 67 72 65 67 61 74 65  en the aggregate
32be0 20 71 75 65 72 79 20 63 6f 6e 63 6c 75 64 65 73   query concludes
32bf0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
32c00 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74  t parameter must
32c10 20 62 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68   be a copy of th
32c20 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  e.** [sqlite3_co
32c30 6e 74 65 78 74 20 7c 20 53 51 4c 20 66 75 6e 63  ntext | SQL func
32c40 74 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68  tion context] th
32c50 61 74 20 69 73 20 74 68 65 20 66 69 72 73 74 20  at is the first 
32c60 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20  parameter.** to 
32c70 74 68 65 20 78 53 74 65 70 20 6f 72 20 78 46 69  the xStep or xFi
32c80 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75  nal callback rou
32c90 74 69 6e 65 20 74 68 61 74 20 69 6d 70 6c 65 6d  tine that implem
32ca0 65 6e 74 73 20 74 68 65 20 61 67 67 72 65 67 61  ents the aggrega
32cb0 74 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a  te.** function..
32cc0 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
32cd0 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  ne must be calle
32ce0 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20  d from the same 
32cf0 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a  thread in which.
32d00 2a 2a 20 74 68 65 20 61 67 67 72 65 67 61 74 65  ** the aggregate
32d10 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73   SQL function is
32d20 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c   running..*/.SQL
32d30 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71  ITE_API void *sq
32d40 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
32d50 63 6f 6e 74 65 78 74 28 73 71 6c 69 74 65 33 5f  context(sqlite3_
32d60 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42  context*, int nB
32d70 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ytes);../*.** CA
32d80 50 49 33 52 45 46 3a 20 55 73 65 72 20 44 61 74  PI3REF: User Dat
32d90 61 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a  a For Functions.
32da0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
32db0 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 20 69  e3_user_data() i
32dc0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
32dd0 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68   a copy of.** th
32de0 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 77  e pointer that w
32df0 61 73 20 74 68 65 20 70 55 73 65 72 44 61 74 61  as the pUserData
32e00 20 70 61 72 61 6d 65 74 65 72 20 28 74 68 65 20   parameter (the 
32e10 35 74 68 20 70 61 72 61 6d 65 74 65 72 29 0a 2a  5th parameter).*
32e20 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * of the [sqlite
32e30 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
32e40 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c  n()].** and [sql
32e50 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
32e60 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e  tion16()] routin
32e70 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c  es that original
32e80 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64  ly.** registered
32e90 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
32ea0 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f   defined functio
32eb0 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  n..**.** This ro
32ec0 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61  utine must be ca
32ed0 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61  lled from the sa
32ee0 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69  me thread in whi
32ef0 63 68 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  ch.** the applic
32f00 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
32f10 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e  nction is runnin
32f20 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  g..*/.SQLITE_API
32f30 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 75   void *sqlite3_u
32f40 73 65 72 5f 64 61 74 61 28 73 71 6c 69 74 65 33  ser_data(sqlite3
32f50 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a  _context*);../*.
32f60 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74  ** CAPI3REF: Dat
32f70 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
32f80 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a   For Functions.*
32f90 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
32fa0 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e  3_context_db_han
32fb0 64 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  dle() interface 
32fc0 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f  returns a copy o
32fd0 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72  f.** the pointer
32fe0 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61 73   to the [databas
32ff0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74  e connection] (t
33000 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72  he 1st parameter
33010 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c  ).** of the [sql
33020 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
33030 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b  tion()].** and [
33040 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
33050 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75  unction16()] rou
33060 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69  tines that origi
33070 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65  nally.** registe
33080 72 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 74  red the applicat
33090 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63  ion defined func
330a0 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  tion..*/.SQLITE_
330b0 41 50 49 20 73 71 6c 69 74 65 33 20 2a 73 71 6c  API sqlite3 *sql
330c0 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f  ite3_context_db_
330d0 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 63  handle(sqlite3_c
330e0 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  ontext*);../*.**
330f0 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74   CAPI3REF: Funct
33100 69 6f 6e 20 41 75 78 69 6c 69 61 72 79 20 44 61  ion Auxiliary Da
33110 74 61 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66  ta.**.** These f
33120 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20  unctions may be 
33130 75 73 65 64 20 62 79 20 28 6e 6f 6e 2d 61 67 67  used by (non-agg
33140 72 65 67 61 74 65 29 20 53 51 4c 20 66 75 6e 63  regate) SQL func
33150 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f  tions to.** asso
33160 63 69 61 74 65 20 6d 65 74 61 64 61 74 61 20 77  ciate metadata w
33170 69 74 68 20 61 72 67 75 6d 65 6e 74 20 76 61 6c  ith argument val
33180 75 65 73 2e 20 49 66 20 74 68 65 20 73 61 6d 65  ues. If the same
33190 20 76 61 6c 75 65 20 69 73 20 70 61 73 73 65 64   value is passed
331a0 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20   to.** multiple 
331b0 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74  invocations of t
331c0 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63  he same SQL func
331d0 74 69 6f 6e 20 64 75 72 69 6e 67 20 71 75 65 72  tion during quer
331e0 79 20 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64  y execution, und
331f0 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75  er.** some circu
33200 6d 73 74 61 6e 63 65 73 20 74 68 65 20 61 73 73  mstances the ass
33210 6f 63 69 61 74 65 64 20 6d 65 74 61 64 61 74 61  ociated metadata
33220 20 6d 61 79 20 62 65 20 70 72 65 73 65 72 76 65   may be preserve
33230 64 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 0a 2a  d.  An example.*
33240 2a 20 6f 66 20 77 68 65 72 65 20 74 68 69 73 20  * of where this 
33250 6d 69 67 68 74 20 62 65 20 75 73 65 66 75 6c 20  might be useful 
33260 69 73 20 69 6e 20 61 20 72 65 67 75 6c 61 72 2d  is in a regular-
33270 65 78 70 72 65 73 73 69 6f 6e 20 6d 61 74 63 68  expression match
33280 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e  ing.** function.
33290 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 76 65   The compiled ve
332a0 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 72 65 67  rsion of the reg
332b0 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20  ular expression 
332c0 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20 61 73  can be stored as
332d0 0a 2a 2a 20 6d 65 74 61 64 61 74 61 20 61 73 73  .** metadata ass
332e0 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
332f0 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67 2e   pattern string.
33300 20 20 0a 2a 2a 20 54 68 65 6e 20 61 73 20 6c 6f    .** Then as lo
33310 6e 67 20 61 73 20 74 68 65 20 70 61 74 74 65 72  ng as the patter
33320 6e 20 73 74 72 69 6e 67 20 72 65 6d 61 69 6e 73  n string remains
33330 20 74 68 65 20 73 61 6d 65 2c 0a 2a 2a 20 74 68   the same,.** th
33340 65 20 63 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c  e compiled regul
33350 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61  ar expression ca
33360 6e 20 62 65 20 72 65 75 73 65 64 20 6f 6e 20 6d  n be reused on m
33370 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63  ultiple.** invoc
33380 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61  ations of the sa
33390 6d 65 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a  me function..**.
333a0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
333b0 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e  get_auxdata() in
333c0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
333d0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
333e0 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61 73 73   metadata.** ass
333f0 6f 63 69 61 74 65 64 20 62 79 20 74 68 65 20 73  ociated by the s
33400 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
33410 74 61 28 29 20 66 75 6e 63 74 69 6f 6e 20 77 69  ta() function wi
33420 74 68 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d  th the Nth argum
33430 65 6e 74 0a 2a 2a 20 76 61 6c 75 65 20 74 6f 20  ent.** value to 
33440 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
33450 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
33460 2e 20 5e 49 66 20 74 68 65 72 65 20 69 73 20 6e  . ^If there is n
33470 6f 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61 73  o metadata.** as
33480 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
33490 65 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d  e function argum
334a0 65 6e 74 2c 20 74 68 69 73 20 73 71 6c 69 74 65  ent, this sqlite
334b0 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_get_auxdata() 
334c0 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 65 74  interface.** ret
334d0 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  urns a NULL poin
334e0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ter..**.** ^The 
334f0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
33500 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20 69 6e 74  ata(C,N,P,X) int
33510 65 72 66 61 63 65 20 73 61 76 65 73 20 50 20 61  erface saves P a
33520 73 20 6d 65 74 61 64 61 74 61 20 66 6f 72 20 74  s metadata for t
33530 68 65 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d  he N-th.** argum
33540 65 6e 74 20 6f 66 20 74 68 65 20 61 70 70 6c 69  ent of the appli
33550 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
33560 75 6e 63 74 69 6f 6e 2e 20 20 5e 53 75 62 73 65  unction.  ^Subse
33570 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74  quent.** calls t
33580 6f 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75  o sqlite3_get_au
33590 78 64 61 74 61 28 43 2c 4e 29 20 72 65 74 75 72  xdata(C,N) retur
335a0 6e 20 50 20 66 72 6f 6d 20 74 68 65 20 6d 6f 73  n P from the mos
335b0 74 20 72 65 63 65 6e 74 0a 2a 2a 20 73 71 6c 69  t recent.** sqli
335c0 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
335d0 43 2c 4e 2c 50 2c 58 29 20 63 61 6c 6c 20 69 66  C,N,P,X) call if
335e0 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 69 73   the metadata is
335f0 20 73 74 69 6c 6c 20 76 61 6c 69 64 20 6f 72 0a   still valid or.
33600 2a 2a 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 6d  ** NULL if the m
33610 65 74 61 64 61 74 61 20 68 61 73 20 62 65 65 6e  etadata has been
33620 20 64 69 73 63 61 72 64 65 64 2e 0a 2a 2a 20 5e   discarded..** ^
33630 41 66 74 65 72 20 65 61 63 68 20 63 61 6c 6c 20  After each call 
33640 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  to sqlite3_set_a
33650 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20  uxdata(C,N,P,X) 
33660 77 68 65 72 65 20 58 20 69 73 20 6e 6f 74 20 4e  where X is not N
33670 55 4c 4c 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 77  ULL,.** SQLite w
33680 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 64  ill invoke the d
33690 65 73 74 72 75 63 74 6f 72 20 66 75 6e 63 74 69  estructor functi
336a0 6f 6e 20 58 20 77 69 74 68 20 70 61 72 61 6d 65  on X with parame
336b0 74 65 72 20 50 20 65 78 61 63 74 6c 79 0a 2a 2a  ter P exactly.**
336c0 20 6f 6e 63 65 2c 20 77 68 65 6e 20 74 68 65 20   once, when the 
336d0 6d 65 74 61 64 61 74 61 20 69 73 20 64 69 73 63  metadata is disc
336e0 61 72 64 65 64 2e 0a 2a 2a 20 53 51 4c 69 74 65  arded..** SQLite
336f0 20 69 73 20 66 72 65 65 20 74 6f 20 64 69 73 63   is free to disc
33700 61 72 64 20 74 68 65 20 6d 65 74 61 64 61 74 61  ard the metadata
33710 20 61 74 20 61 6e 79 20 74 69 6d 65 2c 20 69 6e   at any time, in
33720 63 6c 75 64 69 6e 67 3a 20 3c 75 6c 3e 0a 2a 2a  cluding: <ul>.**
33730 20 3c 6c 69 3e 20 77 68 65 6e 20 74 68 65 20 63   <li> when the c
33740 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 66 75 6e  orresponding fun
33750 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20  ction parameter 
33760 63 68 61 6e 67 65 73 2c 20 6f 72 0a 2a 2a 20 3c  changes, or.** <
33770 6c 69 3e 20 77 68 65 6e 20 5b 73 71 6c 69 74 65  li> when [sqlite
33780 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73  3_reset()] or [s
33790 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
337a0 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 66 6f 72  )] is called for
337b0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 53 51 4c   the.**      SQL
337c0 20 73 74 61 74 65 6d 65 6e 74 2c 20 6f 72 0a 2a   statement, or.*
337d0 2a 20 3c 6c 69 3e 20 77 68 65 6e 20 73 71 6c 69  * <li> when sqli
337e0 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
337f0 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 67 61  ) is invoked aga
33800 69 6e 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 70  in on the same p
33810 61 72 61 6d 65 74 65 72 2c 20 6f 72 0a 2a 2a 20  arameter, or.** 
33820 3c 6c 69 3e 20 64 75 72 69 6e 67 20 74 68 65 20  <li> during the 
33830 6f 72 69 67 69 6e 61 6c 20 73 71 6c 69 74 65 33  original sqlite3
33840 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 63  _set_auxdata() c
33850 61 6c 6c 20 77 68 65 6e 20 61 20 6d 65 6d 6f 72  all when a memor
33860 79 20 0a 2a 2a 20 20 20 20 20 20 61 6c 6c 6f 63  y .**      alloc
33870 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75  ation error occu
33880 72 73 2e 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a  rs. </ul>)^.**.*
33890 2a 20 4e 6f 74 65 20 74 68 65 20 6c 61 73 74 20  * Note the last 
338a0 62 75 6c 6c 65 74 20 69 6e 20 70 61 72 74 69 63  bullet in partic
338b0 75 6c 61 72 2e 20 20 54 68 65 20 64 65 73 74 72  ular.  The destr
338c0 75 63 74 6f 72 20 58 20 69 6e 20 0a 2a 2a 20 73  uctor X in .** s
338d0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
338e0 74 61 28 43 2c 4e 2c 50 2c 58 29 20 6d 69 67 68  ta(C,N,P,X) migh
338f0 74 20 62 65 20 63 61 6c 6c 65 64 20 69 6d 6d 65  t be called imme
33900 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 20  diately, before 
33910 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  the.** sqlite3_s
33920 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74  et_auxdata() int
33930 65 72 66 61 63 65 20 65 76 65 6e 20 72 65 74 75  erface even retu
33940 72 6e 73 2e 20 20 48 65 6e 63 65 20 73 71 6c 69  rns.  Hence sqli
33950 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
33960 29 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 63  ).** should be c
33970 61 6c 6c 65 64 20 6e 65 61 72 20 74 68 65 20 65  alled near the e
33980 6e 64 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69  nd of the functi
33990 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  on implementatio
339a0 6e 20 61 6e 64 20 74 68 65 0a 2a 2a 20 66 75 6e  n and the.** fun
339b0 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
339c0 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74 20  tion should not 
339d0 6d 61 6b 65 20 61 6e 79 20 75 73 65 20 6f 66 20  make any use of 
339e0 50 20 61 66 74 65 72 0a 2a 2a 20 73 71 6c 69 74  P after.** sqlit
339f0 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29  e3_set_auxdata()
33a00 20 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 64   has been called
33a10 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 70 72 61  ..**.** ^(In pra
33a20 63 74 69 63 65 2c 20 6d 65 74 61 64 61 74 61 20  ctice, metadata 
33a30 69 73 20 70 72 65 73 65 72 76 65 64 20 62 65 74  is preserved bet
33a40 77 65 65 6e 20 66 75 6e 63 74 69 6f 6e 20 63 61  ween function ca
33a50 6c 6c 73 20 66 6f 72 0a 2a 2a 20 66 75 6e 63 74  lls for.** funct
33a60 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 73 20 74  ion parameters t
33a70 68 61 74 20 61 72 65 20 63 6f 6d 70 69 6c 65 2d  hat are compile-
33a80 74 69 6d 65 20 63 6f 6e 73 74 61 6e 74 73 2c 20  time constants, 
33a90 69 6e 63 6c 75 64 69 6e 67 20 6c 69 74 65 72 61  including litera
33aa0 6c 0a 2a 2a 20 76 61 6c 75 65 73 20 61 6e 64 20  l.** values and 
33ab0 5b 70 61 72 61 6d 65 74 65 72 73 5d 20 61 6e 64  [parameters] and
33ac0 20 65 78 70 72 65 73 73 69 6f 6e 73 20 63 6f 6d   expressions com
33ad0 70 6f 73 65 64 20 66 72 6f 6d 20 74 68 65 20 73  posed from the s
33ae0 61 6d 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  ame.)^.**.** The
33af0 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74  se routines must
33b00 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
33b10 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20  the same thread 
33b20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20  in which.** the 
33b30 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  SQL function is 
33b40 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49  running..*/.SQLI
33b50 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c  TE_API void *sql
33b60 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
33b70 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
33b80 2a 2c 20 69 6e 74 20 4e 29 3b 0a 53 51 4c 49 54  *, int N);.SQLIT
33b90 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74  E_API void sqlit
33ba0 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 73  e3_set_auxdata(s
33bb0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
33bc0 20 69 6e 74 20 4e 2c 20 76 6f 69 64 2a 2c 20 76   int N, void*, v
33bd0 6f 69 64 20 28 2a 29 28 76 6f 69 64 2a 29 29 3b  oid (*)(void*));
33be0 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  .../*.** CAPI3RE
33bf0 46 3a 20 43 6f 6e 73 74 61 6e 74 73 20 44 65 66  F: Constants Def
33c00 69 6e 69 6e 67 20 53 70 65 63 69 61 6c 20 44 65  ining Special De
33c10 73 74 72 75 63 74 6f 72 20 42 65 68 61 76 69 6f  structor Behavio
33c20 72 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72  r.**.** These ar
33c30 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 73  e special values
33c40 20 66 6f 72 20 74 68 65 20 64 65 73 74 72 75 63   for the destruc
33c50 74 6f 72 20 74 68 61 74 20 69 73 20 70 61 73 73  tor that is pass
33c60 65 64 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20  ed in as the.** 
33c70 66 69 6e 61 6c 20 61 72 67 75 6d 65 6e 74 20 74  final argument t
33c80 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20  o routines like 
33c90 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
33ca0 62 6c 6f 62 28 29 5d 2e 20 20 5e 49 66 20 74 68  blob()].  ^If th
33cb0 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20  e destructor.** 
33cc0 61 72 67 75 6d 65 6e 74 20 69 73 20 53 51 4c 49  argument is SQLI
33cd0 54 45 5f 53 54 41 54 49 43 2c 20 69 74 20 6d 65  TE_STATIC, it me
33ce0 61 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e  ans that the con
33cf0 74 65 6e 74 20 70 6f 69 6e 74 65 72 20 69 73 20  tent pointer is 
33d00 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20 61 6e 64 20  constant.** and 
33d10 77 69 6c 6c 20 6e 65 76 65 72 20 63 68 61 6e 67  will never chang
33d20 65 2e 20 20 49 74 20 64 6f 65 73 20 6e 6f 74 20  e.  It does not 
33d30 6e 65 65 64 20 74 6f 20 62 65 20 64 65 73 74 72  need to be destr
33d40 6f 79 65 64 2e 20 20 5e 54 68 65 0a 2a 2a 20 53  oyed.  ^The.** S
33d50 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20  QLITE_TRANSIENT 
33d60 76 61 6c 75 65 20 6d 65 61 6e 73 20 74 68 61 74  value means that
33d70 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 77 69 6c   the content wil
33d80 6c 20 6c 69 6b 65 6c 79 20 63 68 61 6e 67 65 20  l likely change 
33d90 69 6e 0a 2a 2a 20 74 68 65 20 6e 65 61 72 20 66  in.** the near f
33da0 75 74 75 72 65 20 61 6e 64 20 74 68 61 74 20 53  uture and that S
33db0 51 4c 69 74 65 20 73 68 6f 75 6c 64 20 6d 61 6b  QLite should mak
33dc0 65 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74  e its own privat
33dd0 65 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65  e copy of.** the
33de0 20 63 6f 6e 74 65 6e 74 20 62 65 66 6f 72 65 20   content before 
33df0 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a  returning..**.**
33e00 20 54 68 65 20 74 79 70 65 64 65 66 20 69 73 20   The typedef is 
33e10 6e 65 63 65 73 73 61 72 79 20 74 6f 20 77 6f 72  necessary to wor
33e20 6b 20 61 72 6f 75 6e 64 20 70 72 6f 62 6c 65 6d  k around problem
33e30 73 20 69 6e 20 63 65 72 74 61 69 6e 0a 2a 2a 20  s in certain.** 
33e40 43 2b 2b 20 63 6f 6d 70 69 6c 65 72 73 2e 0a 2a  C++ compilers..*
33e50 2f 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20 28  /.typedef void (
33e60 2a 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63  *sqlite3_destruc
33e70 74 6f 72 5f 74 79 70 65 29 28 76 6f 69 64 2a 29  tor_type)(void*)
33e80 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ;.#define SQLITE
33e90 5f 53 54 41 54 49 43 20 20 20 20 20 20 28 28 73  _STATIC      ((s
33ea0 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f  qlite3_destructo
33eb0 72 5f 74 79 70 65 29 30 29 0a 23 64 65 66 69 6e  r_type)0).#defin
33ec0 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45  e SQLITE_TRANSIE
33ed0 4e 54 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64  NT   ((sqlite3_d
33ee0 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 2d  estructor_type)-
33ef0 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  1)../*.** CAPI3R
33f00 45 46 3a 20 53 65 74 74 69 6e 67 20 54 68 65 20  EF: Setting The 
33f10 52 65 73 75 6c 74 20 4f 66 20 41 6e 20 53 51 4c  Result Of An SQL
33f20 20 46 75 6e 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20   Function.**.** 
33f30 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
33f40 72 65 20 75 73 65 64 20 62 79 20 74 68 65 20 78  re used by the x
33f50 46 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20 63  Func or xFinal c
33f60 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a  allbacks that.**
33f70 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66   implement SQL f
33f80 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67  unctions and agg
33f90 72 65 67 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a  regates.  See.**
33fa0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
33fb0 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64  _function()] and
33fc0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
33fd0 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a  _function16()].*
33fe0 2a 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  * for additional
33ff0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
34000 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69  .** These functi
34010 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79 20 6d 75  ons work very mu
34020 63 68 20 6c 69 6b 65 20 74 68 65 20 5b 70 61 72  ch like the [par
34030 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 5d 20  ameter binding] 
34040 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e  family of.** fun
34050 63 74 69 6f 6e 73 20 75 73 65 64 20 74 6f 20 62  ctions used to b
34060 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 68 6f  ind values to ho
34070 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e  st parameters in
34080 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
34090 65 6e 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74  ents..** Refer t
340a0 6f 20 74 68 65 20 5b 53 51 4c 20 70 61 72 61 6d  o the [SQL param
340b0 65 74 65 72 5d 20 64 6f 63 75 6d 65 6e 74 61 74  eter] documentat
340c0 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  ion for addition
340d0 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  al information..
340e0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
340f0 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29  e3_result_blob()
34100 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
34110 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a  the result from.
34120 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  ** an applicatio
34130 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
34140 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 42 4c 4f  on to be the BLO
34150 42 20 77 68 6f 73 65 20 63 6f 6e 74 65 6e 74 20  B whose content 
34160 69 73 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f  is pointed.** to
34170 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 70   by the second p
34180 61 72 61 6d 65 74 65 72 20 61 6e 64 20 77 68 69  arameter and whi
34190 63 68 20 69 73 20 4e 20 62 79 74 65 73 20 6c 6f  ch is N bytes lo
341a0 6e 67 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  ng where N is th
341b0 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d  e.** third param
341c0 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  eter..**.** ^The
341d0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
341e0 7a 65 72 6f 62 6c 6f 62 28 29 20 69 6e 74 65 72  zeroblob() inter
341f0 66 61 63 65 73 20 73 65 74 20 74 68 65 20 72 65  faces set the re
34200 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61  sult of.** the a
34210 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
34220 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
34230 65 20 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69 6e  e a BLOB contain
34240 69 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20  ing all zero.** 
34250 62 79 74 65 73 20 61 6e 64 20 4e 20 62 79 74 65  bytes and N byte
34260 73 20 69 6e 20 73 69 7a 65 2c 20 77 68 65 72 65  s in size, where
34270 20 4e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20   N is the value 
34280 6f 66 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  of the 2nd param
34290 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  eter..**.** ^The
342a0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
342b0 64 6f 75 62 6c 65 28 29 20 69 6e 74 65 72 66 61  double() interfa
342c0 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75  ce sets the resu
342d0 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70  lt from.** an ap
342e0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
342f0 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
34300 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e   a floating poin
34310 74 20 76 61 6c 75 65 20 73 70 65 63 69 66 69 65  t value specifie
34320 64 0a 2a 2a 20 62 79 20 69 74 73 20 32 6e 64 20  d.** by its 2nd 
34330 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
34340 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
34350 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20  ult_error() and 
34360 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
34370 72 72 6f 72 31 36 28 29 20 66 75 6e 63 74 69 6f  rror16() functio
34380 6e 73 0a 2a 2a 20 63 61 75 73 65 20 74 68 65 20  ns.** cause the 
34390 69 6d 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20  implemented SQL 
343a0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f  function to thro
343b0 77 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a  w an exception..
343c0 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20  ** ^SQLite uses 
343d0 74 68 65 20 73 74 72 69 6e 67 20 70 6f 69 6e 74  the string point
343e0 65 64 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a 20  ed to by the.** 
343f0 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66  2nd parameter of
34400 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
34410 65 72 72 6f 72 28 29 20 6f 72 20 73 71 6c 69 74  error() or sqlit
34420 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
34430 36 28 29 0a 2a 2a 20 61 73 20 74 68 65 20 74 65  6().** as the te
34440 78 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d  xt of an error m
34450 65 73 73 61 67 65 2e 20 20 5e 53 51 4c 69 74 65  essage.  ^SQLite
34460 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20   interprets the 
34470 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65  error.** message
34480 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c   string from sql
34490 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
344a0 72 28 29 20 61 73 20 55 54 46 2d 38 2e 20 5e 53  r() as UTF-8. ^S
344b0 51 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70 72  QLite.** interpr
344c0 65 74 73 20 74 68 65 20 73 74 72 69 6e 67 20 66  ets the string f
344d0 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75  rom sqlite3_resu
344e0 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 61 73 20  lt_error16() as 
344f0 55 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65  UTF-16 in native
34500 0a 2a 2a 20 62 79 74 65 20 6f 72 64 65 72 2e 20  .** byte order. 
34510 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 70   ^If the third p
34520 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
34530 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
34540 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  ().** or sqlite3
34550 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
34560 29 20 69 73 20 6e 65 67 61 74 69 76 65 20 74 68  ) is negative th
34570 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20  en SQLite takes 
34580 61 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20  as the error.** 
34590 6d 65 73 73 61 67 65 20 61 6c 6c 20 74 65 78 74  message all text
345a0 20 75 70 20 74 68 72 6f 75 67 68 20 74 68 65 20   up through the 
345b0 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61  first zero chara
345c0 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  cter..** ^If the
345d0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
345e0 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75   to sqlite3_resu
345f0 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 0a 2a 2a  lt_error() or.**
34600 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
34610 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e 6f 6e  error16() is non
34620 2d 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 53  -negative then S
34630 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68 61 74  QLite takes that
34640 20 6d 61 6e 79 0a 2a 2a 20 62 79 74 65 73 20 28   many.** bytes (
34650 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 29 20  not characters) 
34660 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72  from the 2nd par
34670 61 6d 65 74 65 72 20 61 73 20 74 68 65 20 65 72  ameter as the er
34680 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 20  ror message..** 
34690 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
346a0 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20  ult_error() and 
346b0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
346c0 72 72 6f 72 31 36 28 29 0a 2a 2a 20 72 6f 75 74  rror16().** rout
346d0 69 6e 65 73 20 6d 61 6b 65 20 61 20 70 72 69 76  ines make a priv
346e0 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20  ate copy of the 
346f0 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65  error message te
34700 78 74 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65  xt before.** the
34710 79 20 72 65 74 75 72 6e 2e 20 20 48 65 6e 63 65  y return.  Hence
34720 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75  , the calling fu
34730 6e 63 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c  nction can deall
34740 6f 63 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69  ocate or.** modi
34750 66 79 20 74 68 65 20 74 65 78 74 20 61 66 74 65  fy the text afte
34760 72 20 74 68 65 79 20 72 65 74 75 72 6e 20 77 69  r they return wi
34770 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e  thout harm..** ^
34780 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
34790 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 29 20  lt_error_code() 
347a0 66 75 6e 63 74 69 6f 6e 20 63 68 61 6e 67 65 73  function changes
347b0 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 0a   the error code.
347c0 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 53  ** returned by S
347d0 51 4c 69 74 65 20 61 73 20 61 20 72 65 73 75 6c  QLite as a resul
347e0 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 69 6e  t of an error in
347f0 20 61 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 42   a function.  ^B
34800 79 20 64 65 66 61 75 6c 74 2c 0a 2a 2a 20 74 68  y default,.** th
34810 65 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20  e error code is 
34820 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20 5e  SQLITE_ERROR.  ^
34830 41 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  A subsequent cal
34840 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73  l to sqlite3_res
34850 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f  ult_error().** o
34860 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
34870 5f 65 72 72 6f 72 31 36 28 29 20 72 65 73 65 74  _error16() reset
34880 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65  s the error code
34890 20 74 6f 20 53 51 4c 49 54 45 5f 45 52 52 4f 52   to SQLITE_ERROR
348a0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
348b0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
348c0 72 5f 74 6f 6f 62 69 67 28 29 20 69 6e 74 65 72  r_toobig() inter
348d0 66 61 63 65 20 63 61 75 73 65 73 20 53 51 4c 69  face causes SQLi
348e0 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 0a 2a  te to throw an.*
348f0 2a 20 65 72 72 6f 72 20 69 6e 64 69 63 61 74 69  * error indicati
34900 6e 67 20 74 68 61 74 20 61 20 73 74 72 69 6e 67  ng that a string
34910 20 6f 72 20 42 4c 4f 42 20 69 73 20 74 6f 6f 20   or BLOB is too 
34920 6c 6f 6e 67 20 74 6f 20 72 65 70 72 65 73 65 6e  long to represen
34930 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  t..**.** ^The sq
34940 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
34950 6f 72 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74 65 72  or_nomem() inter
34960 66 61 63 65 20 63 61 75 73 65 73 20 53 51 4c 69  face causes SQLi
34970 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 0a 2a  te to throw an.*
34980 2a 20 65 72 72 6f 72 20 69 6e 64 69 63 61 74 69  * error indicati
34990 6e 67 20 74 68 61 74 20 61 20 6d 65 6d 6f 72 79  ng that a memory
349a0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c   allocation fail
349b0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
349c0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
349d0 74 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65  t() interface se
349e0 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  ts the return va
349f0 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70  lue.** of the ap
34a00 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
34a10 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
34a20 20 74 68 65 20 33 32 2d 62 69 74 20 73 69 67 6e   the 32-bit sign
34a30 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61  ed integer.** va
34a40 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65  lue given in the
34a50 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a   2nd argument..*
34a60 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
34a70 65 73 75 6c 74 5f 69 6e 74 36 34 28 29 20 69 6e  esult_int64() in
34a80 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
34a90 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a   return value.**
34aa0 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
34ab0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
34ac0 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 36  tion to be the 6
34ad0 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74  4-bit signed int
34ae0 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69  eger.** value gi
34af0 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61  ven in the 2nd a
34b00 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e  rgument..**.** ^
34b10 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
34b20 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e 74 65 72 66  lt_null() interf
34b30 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74  ace sets the ret
34b40 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20  urn value.** of 
34b50 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
34b60 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
34b70 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a   to be NULL..**.
34b80 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
34b90 72 65 73 75 6c 74 5f 74 65 78 74 28 29 2c 20 73  result_text(), s
34ba0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
34bb0 78 74 31 36 28 29 2c 0a 2a 2a 20 73 71 6c 69 74  xt16(),.** sqlit
34bc0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
34bd0 6c 65 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65  le(), and sqlite
34be0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62  3_result_text16b
34bf0 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  e() interfaces.*
34c00 2a 20 73 65 74 20 74 68 65 20 72 65 74 75 72 6e  * set the return
34c10 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 61 70   value of the ap
34c20 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
34c30 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
34c40 0a 2a 2a 20 61 20 74 65 78 74 20 73 74 72 69 6e  .** a text strin
34c50 67 20 77 68 69 63 68 20 69 73 20 72 65 70 72 65  g which is repre
34c60 73 65 6e 74 65 64 20 61 73 20 55 54 46 2d 38 2c  sented as UTF-8,
34c70 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62   UTF-16 native b
34c80 79 74 65 20 6f 72 64 65 72 2c 0a 2a 2a 20 55 54  yte order,.** UT
34c90 46 2d 31 36 20 6c 69 74 74 6c 65 20 65 6e 64 69  F-16 little endi
34ca0 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 62 69  an, or UTF-16 bi
34cb0 67 20 65 6e 64 69 61 6e 2c 20 72 65 73 70 65 63  g endian, respec
34cc0 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 53 51 4c 69  tively..** ^SQLi
34cd0 74 65 20 74 61 6b 65 73 20 74 68 65 20 74 65 78  te takes the tex
34ce0 74 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 74 68  t result from th
34cf0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 66 72  e application fr
34d00 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e 64 20 70 61  om.** the 2nd pa
34d10 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20 73  rameter of the s
34d20 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
34d30 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 2e 0a  xt* interfaces..
34d40 2a 2a 20 5e 49 66 20 74 68 65 20 33 72 64 20 70  ** ^If the 3rd p
34d50 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
34d60 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
34d70 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a  ext* interfaces.
34d80 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  ** is negative, 
34d90 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65  then SQLite take
34da0 73 20 72 65 73 75 6c 74 20 74 65 78 74 20 66 72  s result text fr
34db0 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  om the 2nd param
34dc0 65 74 65 72 0a 2a 2a 20 74 68 72 6f 75 67 68 20  eter.** through 
34dd0 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63  the first zero c
34de0 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66  haracter..** ^If
34df0 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74   the 3rd paramet
34e00 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
34e10 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69  3_result_text* i
34e20 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20  nterfaces.** is 
34e30 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68  non-negative, th
34e40 65 6e 20 61 73 20 6d 61 6e 79 20 62 79 74 65 73  en as many bytes
34e50 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73   (not characters
34e60 29 20 6f 66 20 74 68 65 20 74 65 78 74 0a 2a 2a  ) of the text.**
34e70 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74   pointed to by t
34e80 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
34e90 20 61 72 65 20 74 61 6b 65 6e 20 61 73 20 74 68   are taken as th
34ea0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
34eb0 66 69 6e 65 64 0a 2a 2a 20 66 75 6e 63 74 69 6f  fined.** functio
34ec0 6e 20 72 65 73 75 6c 74 2e 20 20 49 66 20 74 68  n result.  If th
34ed0 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  e 3rd parameter 
34ee0 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c  is non-negative,
34ef0 20 74 68 65 6e 20 69 74 0a 2a 2a 20 6d 75 73 74   then it.** must
34f00 20 62 65 20 74 68 65 20 62 79 74 65 20 6f 66 66   be the byte off
34f10 73 65 74 20 69 6e 74 6f 20 74 68 65 20 73 74 72  set into the str
34f20 69 6e 67 20 77 68 65 72 65 20 74 68 65 20 4e 55  ing where the NU
34f30 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f 75  L terminator wou
34f40 6c 64 0a 2a 2a 20 61 70 70 65 61 72 20 69 66 20  ld.** appear if 
34f50 74 68 65 20 73 74 72 69 6e 67 20 77 68 65 72 65  the string where
34f60 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 65 64 2e   NUL terminated.
34f70 20 20 49 66 20 61 6e 79 20 4e 55 4c 20 63 68 61    If any NUL cha
34f80 72 61 63 74 65 72 73 20 6f 63 63 75 72 0a 2a 2a  racters occur.**
34f90 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 20 61   in the string a
34fa0 74 20 61 20 62 79 74 65 20 6f 66 66 73 65 74 20  t a byte offset 
34fb0 74 68 61 74 20 69 73 20 6c 65 73 73 20 74 68 61  that is less tha
34fc0 6e 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  n the value of t
34fd0 68 65 20 33 72 64 0a 2a 2a 20 70 61 72 61 6d 65  he 3rd.** parame
34fe0 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 72 65  ter, then the re
34ff0 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 20 77  sulting string w
35000 69 6c 6c 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65  ill contain embe
35010 64 64 65 64 20 4e 55 4c 73 20 61 6e 64 20 74 68  dded NULs and th
35020 65 0a 2a 2a 20 72 65 73 75 6c 74 20 6f 66 20 65  e.** result of e
35030 78 70 72 65 73 73 69 6f 6e 73 20 6f 70 65 72 61  xpressions opera
35040 74 69 6e 67 20 6f 6e 20 73 74 72 69 6e 67 73 20  ting on strings 
35050 77 69 74 68 20 65 6d 62 65 64 64 65 64 20 4e 55  with embedded NU
35060 4c 73 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  Ls is undefined.
35070 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20  .** ^If the 4th 
35080 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
35090 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
350a0 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
350b0 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  .** or sqlite3_r
350c0 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 61 20  esult_blob is a 
350d0 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  non-NULL pointer
350e0 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 63 61  , then SQLite ca
350f0 6c 6c 73 20 74 68 61 74 0a 2a 2a 20 66 75 6e 63  lls that.** func
35100 74 69 6f 6e 20 61 73 20 74 68 65 20 64 65 73 74  tion as the dest
35110 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 74 65  ructor on the te
35120 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c  xt or BLOB resul
35130 74 20 77 68 65 6e 20 69 74 20 68 61 73 0a 2a 2a  t when it has.**
35140 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20   finished using 
35150 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20  that result..** 
35160 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61  ^If the 4th para
35170 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
35180 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
35190 2a 20 69 6e 74 65 72 66 61 63 65 73 20 6f 72 20  * interfaces or 
351a0 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65  to.** sqlite3_re
351b0 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65  sult_blob is the
351c0 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e   special constan
351d0 74 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c  t SQLITE_STATIC,
351e0 20 74 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20   then SQLite.** 
351f0 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65  assumes that the
35200 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65   text or BLOB re
35210 73 75 6c 74 20 69 73 20 69 6e 20 63 6f 6e 73 74  sult is in const
35220 61 6e 74 20 73 70 61 63 65 20 61 6e 64 20 64 6f  ant space and do
35230 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79 20 74  es not.** copy t
35240 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
35250 65 20 70 61 72 61 6d 65 74 65 72 20 6e 6f 72 20  e parameter nor 
35260 63 61 6c 6c 20 61 20 64 65 73 74 72 75 63 74 6f  call a destructo
35270 72 20 6f 6e 20 74 68 65 20 63 6f 6e 74 65 6e 74  r on the content
35280 0a 2a 2a 20 77 68 65 6e 20 69 74 20 68 61 73 20  .** when it has 
35290 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74  finished using t
352a0 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e  hat result..** ^
352b0 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d  If the 4th param
352c0 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
352d0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
352e0 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f   interfaces.** o
352f0 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
35300 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65  _blob is the spe
35310 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51  cial constant SQ
35320 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 0a 2a  LITE_TRANSIENT.*
35330 2a 20 74 68 65 6e 20 53 51 4c 69 74 65 20 6d 61  * then SQLite ma
35340 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  kes a copy of th
35350 65 20 72 65 73 75 6c 74 20 69 6e 74 6f 20 73 70  e result into sp
35360 61 63 65 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ace obtained fro
35370 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74  m.** from [sqlit
35380 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 65 66  e3_malloc()] bef
35390 6f 72 65 20 69 74 20 72 65 74 75 72 6e 73 2e 0a  ore it returns..
353a0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
353b0 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
353c0 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
353d0 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a   the result of.*
353e0 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * the applicatio
353f0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
35400 6f 6e 20 74 6f 20 62 65 20 61 20 63 6f 70 79 20  on to be a copy 
35410 74 68 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63  the.** [unprotec
35420 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
35430 65 5d 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66  e] object specif
35440 69 65 64 20 62 79 20 74 68 65 20 32 6e 64 20 70  ied by the 2nd p
35450 61 72 61 6d 65 74 65 72 2e 20 20 5e 54 68 65 0a  arameter.  ^The.
35460 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  ** sqlite3_resul
35470 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66  t_value() interf
35480 61 63 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79  ace makes a copy
35490 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
354a0 5f 76 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74 68  _value].** so th
354b0 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  at the [sqlite3_
354c0 76 61 6c 75 65 5d 20 73 70 65 63 69 66 69 65 64  value] specified
354d0 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65   in the paramete
354e0 72 20 6d 61 79 20 63 68 61 6e 67 65 20 6f 72 0a  r may change or.
354f0 2a 2a 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65  ** be deallocate
35500 64 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f  d after sqlite3_
35510 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 72  result_value() r
35520 65 74 75 72 6e 73 20 77 69 74 68 6f 75 74 20 68  eturns without h
35530 61 72 6d 2e 0a 2a 2a 20 5e 41 20 5b 70 72 6f 74  arm..** ^A [prot
35540 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
35550 6c 75 65 5d 20 6f 62 6a 65 63 74 20 6d 61 79 20  lue] object may 
35560 61 6c 77 61 79 73 20 62 65 20 75 73 65 64 20 77  always be used w
35570 68 65 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72  here an.** [unpr
35580 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
35590 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 69 73  value] object is
355a0 20 72 65 71 75 69 72 65 64 2c 20 73 6f 20 65 69   required, so ei
355b0 74 68 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20  ther.** kind of 
355c0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20  [sqlite3_value] 
355d0 6f 62 6a 65 63 74 20 63 61 6e 20 62 65 20 75 73  object can be us
355e0 65 64 20 77 69 74 68 20 74 68 69 73 20 69 6e 74  ed with this int
355f0 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66  erface..**.** If
35600 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
35610 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20  are called from 
35620 77 69 74 68 69 6e 20 74 68 65 20 64 69 66 66 65  within the diffe
35630 72 65 6e 74 20 74 68 72 65 61 64 0a 2a 2a 20 74  rent thread.** t
35640 68 61 6e 20 74 68 65 20 6f 6e 65 20 63 6f 6e 74  han the one cont
35650 61 69 6e 69 6e 67 20 74 68 65 20 61 70 70 6c 69  aining the appli
35660 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
35670 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 72 65 63  unction that rec
35680 65 69 76 65 64 0a 2a 2a 20 74 68 65 20 5b 73 71  eived.** the [sq
35690 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20 70  lite3_context] p
356a0 6f 69 6e 74 65 72 2c 20 74 68 65 20 72 65 73 75  ointer, the resu
356b0 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65  lts are undefine
356c0 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  d..*/.SQLITE_API
356d0 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65   void sqlite3_re
356e0 73 75 6c 74 5f 62 6c 6f 62 28 73 71 6c 69 74 65  sult_blob(sqlite
356f0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
35700 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f  t void*, int, vo
35710 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53  id(*)(void*));.S
35720 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73  QLITE_API void s
35730 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f  qlite3_result_do
35740 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  uble(sqlite3_con
35750 74 65 78 74 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a  text*, double);.
35760 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
35770 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
35780 72 72 6f 72 28 73 71 6c 69 74 65 33 5f 63 6f 6e  rror(sqlite3_con
35790 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61  text*, const cha
357a0 72 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45  r*, int);.SQLITE
357b0 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65  _API void sqlite
357c0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
357d0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
357e0 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
357f0 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  int);.SQLITE_API
35800 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65   void sqlite3_re
35810 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69  sult_error_toobi
35820 67 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  g(sqlite3_contex
35830 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  t*);.SQLITE_API 
35840 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
35850 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28  ult_error_nomem(
35860 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
35870 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  );.SQLITE_API vo
35880 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
35890 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 73 71 6c  t_error_code(sql
358a0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
358b0 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  nt);.SQLITE_API 
358c0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
358d0 75 6c 74 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f  ult_int(sqlite3_
358e0 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a  context*, int);.
358f0 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
35900 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69  sqlite3_result_i
35910 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e  nt64(sqlite3_con
35920 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 69  text*, sqlite3_i
35930 6e 74 36 34 29 3b 0a 53 51 4c 49 54 45 5f 41 50  nt64);.SQLITE_AP
35940 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  I void sqlite3_r
35950 65 73 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69 74  esult_null(sqlit
35960 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51  e3_context*);.SQ
35970 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71  LITE_API void sq
35980 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
35990 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t(sqlite3_contex
359a0 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c  t*, const char*,
359b0 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f   int, void(*)(vo
359c0 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50  id*));.SQLITE_AP
359d0 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  I void sqlite3_r
359e0 65 73 75 6c 74 5f 74 65 78 74 31 36 28 73 71 6c  esult_text16(sql
359f0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
35a00 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c  onst void*, int,
35a10 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
35a20 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  ;.SQLITE_API voi
35a30 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
35a40 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65  _text16le(sqlite
35a50 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
35a60 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69  t void*, int,voi
35a70 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51  d(*)(void*));.SQ
35a80 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71  LITE_API void sq
35a90 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
35aa0 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f 63 6f  t16be(sqlite3_co
35ab0 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f  ntext*, const vo
35ac0 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29  id*, int,void(*)
35ad0 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45  (void*));.SQLITE
35ae0 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65  _API void sqlite
35af0 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 73  3_result_value(s
35b00 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
35b10 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29   sqlite3_value*)
35b20 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  ;.SQLITE_API voi
35b30 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
35b40 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65  _zeroblob(sqlite
35b50 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20  3_context*, int 
35b60 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  n);../*.** CAPI3
35b70 52 45 46 3a 20 44 65 66 69 6e 65 20 4e 65 77 20  REF: Define New 
35b80 43 6f 6c 6c 61 74 69 6e 67 20 53 65 71 75 65 6e  Collating Sequen
35b90 63 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  ces.**.** ^These
35ba0 20 66 75 6e 63 74 69 6f 6e 73 20 61 64 64 2c 20   functions add, 
35bb0 72 65 6d 6f 76 65 2c 20 6f 72 20 6d 6f 64 69 66  remove, or modif
35bc0 79 20 61 20 5b 63 6f 6c 6c 61 74 69 6f 6e 5d 20  y a [collation] 
35bd0 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69  associated.** wi
35be0 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  th the [database
35bf0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65   connection] spe
35c00 63 69 66 69 65 64 20 61 73 20 74 68 65 20 66 69  cified as the fi
35c10 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  rst argument..**
35c20 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66  .** ^The name of
35c30 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 69   the collation i
35c40 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67  s a UTF-8 string
35c50 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 5f  .** for sqlite3_
35c60 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
35c70 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  () and sqlite3_c
35c80 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
35c90 76 32 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55 54  v2().** and a UT
35ca0 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e  F-16 string in n
35cb0 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
35cc0 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65   for sqlite3_cre
35cd0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28  ate_collation16(
35ce0 29 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6f 6e  )..** ^Collation
35cf0 20 6e 61 6d 65 73 20 74 68 61 74 20 63 6f 6d 70   names that comp
35d00 61 72 65 20 65 71 75 61 6c 20 61 63 63 6f 72 64  are equal accord
35d10 69 6e 67 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ing to [sqlite3_
35d20 73 74 72 6e 69 63 6d 70 28 29 5d 20 61 72 65 0a  strnicmp()] are.
35d30 2a 2a 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f  ** considered to
35d40 20 62 65 20 74 68 65 20 73 61 6d 65 20 6e 61 6d   be the same nam
35d50 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 74  e..**.** ^(The t
35d60 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 28 65  hird argument (e
35d70 54 65 78 74 52 65 70 29 20 6d 75 73 74 20 62 65  TextRep) must be
35d80 20 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f 6e 73   one of the cons
35d90 74 61 6e 74 73 3a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  tants:.** <ul>.*
35da0 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55  * <li> [SQLITE_U
35db0 54 46 38 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  TF8],.** <li> [S
35dc0 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 0a  QLITE_UTF16LE],.
35dd0 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
35de0 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 3c 6c 69  UTF16BE],.** <li
35df0 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d  > [SQLITE_UTF16]
35e00 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  , or.** <li> [SQ
35e10 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e  LITE_UTF16_ALIGN
35e20 45 44 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a  ED]..** </ul>)^.
35e30 2a 2a 20 5e 54 68 65 20 65 54 65 78 74 52 65 70  ** ^The eTextRep
35e40 20 61 72 67 75 6d 65 6e 74 20 64 65 74 65 72 6d   argument determ
35e50 69 6e 65 73 20 74 68 65 20 65 6e 63 6f 64 69 6e  ines the encodin
35e60 67 20 6f 66 20 73 74 72 69 6e 67 73 20 70 61 73  g of strings pas
35e70 73 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f  sed.** to the co
35e80 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
35e90 20 63 61 6c 6c 62 61 63 6b 2c 20 78 43 61 6c 6c   callback, xCall
35ea0 62 61 63 6b 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53  back..** ^The [S
35eb0 51 4c 49 54 45 5f 55 54 46 31 36 5d 20 61 6e 64  QLITE_UTF16] and
35ec0 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41   [SQLITE_UTF16_A
35ed0 4c 49 47 4e 45 44 5d 20 76 61 6c 75 65 73 20 66  LIGNED] values f
35ee0 6f 72 20 65 54 65 78 74 52 65 70 0a 2a 2a 20 66  or eTextRep.** f
35ef0 6f 72 63 65 20 73 74 72 69 6e 67 73 20 74 6f 20  orce strings to 
35f00 62 65 20 55 54 46 31 36 20 77 69 74 68 20 6e 61  be UTF16 with na
35f10 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e  tive byte order.
35f20 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
35f30 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20  _UTF16_ALIGNED] 
35f40 76 61 6c 75 65 20 66 6f 72 20 65 54 65 78 74 52  value for eTextR
35f50 65 70 20 66 6f 72 63 65 73 20 73 74 72 69 6e 67  ep forces string
35f60 73 20 74 6f 20 62 65 67 69 6e 0a 2a 2a 20 6f 6e  s to begin.** on
35f70 20 61 6e 20 65 76 65 6e 20 62 79 74 65 20 61 64   an even byte ad
35f80 64 72 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  dress..**.** ^Th
35f90 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  e fourth argumen
35fa0 74 2c 20 70 41 72 67 2c 20 69 73 20 61 6e 20 61  t, pArg, is an a
35fb0 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20  pplication data 
35fc0 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73 20  pointer that is 
35fd0 70 61 73 73 65 64 0a 2a 2a 20 74 68 72 6f 75 67  passed.** throug
35fe0 68 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61  h as the first a
35ff0 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 63  rgument to the c
36000 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
36010 6e 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a  n callback..**.*
36020 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61 72 67  * ^The fifth arg
36030 75 6d 65 6e 74 2c 20 78 43 61 6c 6c 62 61 63 6b  ument, xCallback
36040 2c 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  , is a pointer t
36050 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20  o the collating 
36060 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 5e 4d 75  function..** ^Mu
36070 6c 74 69 70 6c 65 20 63 6f 6c 6c 61 74 69 6e 67  ltiple collating
36080 20 66 75 6e 63 74 69 6f 6e 73 20 63 61 6e 20 62   functions can b
36090 65 20 72 65 67 69 73 74 65 72 65 64 20 75 73 69  e registered usi
360a0 6e 67 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65  ng the same name
360b0 20 62 75 74 0a 2a 2a 20 77 69 74 68 20 64 69 66   but.** with dif
360c0 66 65 72 65 6e 74 20 65 54 65 78 74 52 65 70 20  ferent eTextRep 
360d0 70 61 72 61 6d 65 74 65 72 73 20 61 6e 64 20 53  parameters and S
360e0 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 77  QLite will use w
360f0 68 69 63 68 65 76 65 72 0a 2a 2a 20 66 75 6e 63  hichever.** func
36100 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 74 68  tion requires th
36110 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f  e least amount o
36120 66 20 64 61 74 61 20 74 72 61 6e 73 66 6f 72 6d  f data transform
36130 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68  ation..** ^If th
36140 65 20 78 43 61 6c 6c 62 61 63 6b 20 61 72 67 75  e xCallback argu
36150 6d 65 6e 74 20 69 73 20 4e 55 4c 4c 20 74 68 65  ment is NULL the
36160 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20  n the collating 
36170 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 64  function is.** d
36180 65 6c 65 74 65 64 2e 20 20 5e 57 68 65 6e 20 61  eleted.  ^When a
36190 6c 6c 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  ll collating fun
361a0 63 74 69 6f 6e 73 20 68 61 76 69 6e 67 20 74 68  ctions having th
361b0 65 20 73 61 6d 65 20 6e 61 6d 65 20 61 72 65 20  e same name are 
361c0 64 65 6c 65 74 65 64 2c 0a 2a 2a 20 74 68 61 74  deleted,.** that
361d0 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 20 6e 6f   collation is no
361e0 20 6c 6f 6e 67 65 72 20 75 73 61 62 6c 65 2e 0a   longer usable..
361f0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 6f 6c 6c 61  **.** ^The colla
36200 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61  ting function ca
36210 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
36220 64 20 77 69 74 68 20 61 20 63 6f 70 79 20 6f 66  d with a copy of
36230 20 74 68 65 20 70 41 72 67 20 0a 2a 2a 20 61 70   the pArg .** ap
36240 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70  plication data p
36250 6f 69 6e 74 65 72 20 61 6e 64 20 77 69 74 68 20  ointer and with 
36260 74 77 6f 20 73 74 72 69 6e 67 73 20 69 6e 20 74  two strings in t
36270 68 65 20 65 6e 63 6f 64 69 6e 67 20 73 70 65 63  he encoding spec
36280 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20  ified.** by the 
36290 65 54 65 78 74 52 65 70 20 61 72 67 75 6d 65 6e  eTextRep argumen
362a0 74 2e 20 20 54 68 65 20 63 6f 6c 6c 61 74 69 6e  t.  The collatin
362b0 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20  g function must 
362c0 72 65 74 75 72 6e 20 61 6e 0a 2a 2a 20 69 6e 74  return an.** int
362d0 65 67 65 72 20 74 68 61 74 20 69 73 20 6e 65 67  eger that is neg
362e0 61 74 69 76 65 2c 20 7a 65 72 6f 2c 20 6f 72 20  ative, zero, or 
362f0 70 6f 73 69 74 69 76 65 0a 2a 2a 20 69 66 20 74  positive.** if t
36300 68 65 20 66 69 72 73 74 20 73 74 72 69 6e 67 20  he first string 
36310 69 73 20 6c 65 73 73 20 74 68 61 6e 2c 20 65 71  is less than, eq
36320 75 61 6c 20 74 6f 2c 20 6f 72 20 67 72 65 61 74  ual to, or great
36330 65 72 20 74 68 61 6e 20 74 68 65 20 73 65 63 6f  er than the seco
36340 6e 64 2c 0a 2a 2a 20 72 65 73 70 65 63 74 69 76  nd,.** respectiv
36350 65 6c 79 2e 20 20 41 20 63 6f 6c 6c 61 74 69 6e  ely.  A collatin
36360 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20  g function must 
36370 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20 74 68  always return th
36380 65 20 73 61 6d 65 20 61 6e 73 77 65 72 0a 2a 2a  e same answer.**
36390 20 67 69 76 65 6e 20 74 68 65 20 73 61 6d 65 20   given the same 
363a0 69 6e 70 75 74 73 2e 20 20 49 66 20 74 77 6f 20  inputs.  If two 
363b0 6f 72 20 6d 6f 72 65 20 63 6f 6c 6c 61 74 69 6e  or more collatin
363c0 67 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20  g functions are 
363d0 72 65 67 69 73 74 65 72 65 64 0a 2a 2a 20 74 6f  registered.** to
363e0 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 6c 61 74   the same collat
363f0 69 6f 6e 20 6e 61 6d 65 20 28 75 73 69 6e 67 20  ion name (using 
36400 64 69 66 66 65 72 65 6e 74 20 65 54 65 78 74 52  different eTextR
36410 65 70 20 76 61 6c 75 65 73 29 20 74 68 65 6e 20  ep values) then 
36420 61 6c 6c 0a 2a 2a 20 6d 75 73 74 20 67 69 76 65  all.** must give
36430 20 61 6e 20 65 71 75 69 76 61 6c 65 6e 74 20 61   an equivalent a
36440 6e 73 77 65 72 20 77 68 65 6e 20 69 6e 76 6f 6b  nswer when invok
36450 65 64 20 77 69 74 68 20 65 71 75 69 76 61 6c 65  ed with equivale
36460 6e 74 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54  nt strings..** T
36470 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  he collating fun
36480 63 74 69 6f 6e 20 6d 75 73 74 20 6f 62 65 79 20  ction must obey 
36490 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 70 72  the following pr
364a0 6f 70 65 72 74 69 65 73 20 66 6f 72 20 61 6c 6c  operties for all
364b0 0a 2a 2a 20 73 74 72 69 6e 67 73 20 41 2c 20 42  .** strings A, B
364c0 2c 20 61 6e 64 20 43 3a 0a 2a 2a 0a 2a 2a 20 3c  , and C:.**.** <
364d0 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41  ol>.** <li> If A
364e0 3d 3d 42 20 74 68 65 6e 20 42 3d 3d 41 2e 0a 2a  ==B then B==A..*
364f0 2a 20 3c 6c 69 3e 20 49 66 20 41 3d 3d 42 20 61  * <li> If A==B a
36500 6e 64 20 42 3d 3d 43 20 74 68 65 6e 20 41 3d 3d  nd B==C then A==
36510 43 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 26  C..** <li> If A&
36520 6c 74 3b 42 20 54 48 45 4e 20 42 26 67 74 3b 41  lt;B THEN B&gt;A
36530 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 26 6c  ..** <li> If A&l
36540 74 3b 42 20 61 6e 64 20 42 26 6c 74 3b 43 20 74  t;B and B&lt;C t
36550 68 65 6e 20 41 26 6c 74 3b 43 2e 0a 2a 2a 20 3c  hen A&lt;C..** <
36560 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20  /ol>.**.** If a 
36570 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
36580 6f 6e 20 66 61 69 6c 73 20 61 6e 79 20 6f 66 20  on fails any of 
36590 74 68 65 20 61 62 6f 76 65 20 63 6f 6e 73 74 72  the above constr
365a0 61 69 6e 74 73 20 61 6e 64 20 74 68 61 74 0a 2a  aints and that.*
365b0 2a 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  * collating func
365c0 74 69 6f 6e 20 69 73 20 20 72 65 67 69 73 74 65  tion is  registe
365d0 72 65 64 20 61 6e 64 20 75 73 65 64 2c 20 74 68  red and used, th
365e0 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
365f0 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 69 73 20  of SQLite.** is 
36600 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
36610 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 72   ^The sqlite3_cr
36620 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
36630 32 28 29 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73  2() works like s
36640 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
36650 6c 6c 61 74 69 6f 6e 28 29 0a 2a 2a 20 77 69 74  llation().** wit
36660 68 20 74 68 65 20 61 64 64 69 74 69 6f 6e 20 74  h the addition t
36670 68 61 74 20 74 68 65 20 78 44 65 73 74 72 6f 79  hat the xDestroy
36680 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
36690 6f 6b 65 64 20 6f 6e 20 70 41 72 67 20 77 68 65  oked on pArg whe
366a0 6e 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c 61 74 69  n.** the collati
366b0 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64  ng function is d
366c0 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e 43 6f 6c 6c  eleted..** ^Coll
366d0 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20  ating functions 
366e0 61 72 65 20 64 65 6c 65 74 65 64 20 77 68 65 6e  are deleted when
366f0 20 74 68 65 79 20 61 72 65 20 6f 76 65 72 72 69   they are overri
36700 64 64 65 6e 20 62 79 20 6c 61 74 65 72 0a 2a 2a  dden by later.**
36710 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 63 6f   calls to the co
36720 6c 6c 61 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e  llation creation
36730 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 77 68   functions or wh
36740 65 6e 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62  en the.** [datab
36750 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
36760 69 73 20 63 6c 6f 73 65 64 20 75 73 69 6e 67 20  is closed using 
36770 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29  [sqlite3_close()
36780 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 44  ]..**.** ^The xD
36790 65 73 74 72 6f 79 20 63 61 6c 6c 62 61 63 6b 20  estroy callback 
367a0 69 73 20 3c 75 3e 6e 6f 74 3c 2f 75 3e 20 63 61  is <u>not</u> ca
367b0 6c 6c 65 64 20 69 66 20 74 68 65 20 0a 2a 2a 20  lled if the .** 
367c0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
367d0 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 66 75  ollation_v2() fu
367e0 6e 63 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 41  nction fails.  A
367f0 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
36800 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74   invoke.** sqlit
36810 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
36820 69 6f 6e 5f 76 32 28 29 20 77 69 74 68 20 61 20  ion_v2() with a 
36830 6e 6f 6e 2d 4e 55 4c 4c 20 78 44 65 73 74 72 6f  non-NULL xDestro
36840 79 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c  y argument shoul
36850 64 20 0a 2a 2a 20 63 68 65 63 6b 20 74 68 65 20  d .** check the 
36860 72 65 74 75 72 6e 20 63 6f 64 65 20 61 6e 64 20  return code and 
36870 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 61  dispose of the a
36880 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20  pplication data 
36890 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 68 65 6d 73  pointer.** thems
368a0 65 6c 76 65 73 20 72 61 74 68 65 72 20 74 68 61  elves rather tha
368b0 6e 20 65 78 70 65 63 74 69 6e 67 20 53 51 4c 69  n expecting SQLi
368c0 74 65 20 74 6f 20 64 65 61 6c 20 77 69 74 68 20  te to deal with 
368d0 69 74 20 66 6f 72 20 74 68 65 6d 2e 0a 2a 2a 20  it for them..** 
368e0 54 68 69 73 20 69 73 20 64 69 66 66 65 72 65 6e  This is differen
368f0 74 20 66 72 6f 6d 20 65 76 65 72 79 20 6f 74 68  t from every oth
36900 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
36910 61 63 65 2e 20 20 54 68 65 20 69 6e 63 6f 6e 73  ace.  The incons
36920 69 73 74 65 6e 63 79 20 0a 2a 2a 20 69 73 20 75  istency .** is u
36930 6e 66 6f 72 74 75 6e 61 74 65 20 62 75 74 20 63  nfortunate but c
36940 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64  annot be changed
36950 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e   without breakin
36960 67 20 62 61 63 6b 77 61 72 64 73 20 0a 2a 2a 20  g backwards .** 
36970 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a  compatibility..*
36980 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20  *.** See also:  
36990 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69  [sqlite3_collati
369a0 6f 6e 5f 6e 65 65 64 65 64 28 29 5d 20 61 6e 64  on_needed()] and
369b0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74   [sqlite3_collat
369c0 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 5d 2e  ion_needed16()].
369d0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
369e0 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
369f0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 0a 20 20 73  e_collation(.  s
36a00 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73  qlite3*, .  cons
36a10 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a  t char *zName, .
36a20 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20    int eTextRep, 
36a30 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20  .  void *pArg,. 
36a40 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28   int(*xCompare)(
36a50 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
36a60 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
36a70 76 6f 69 64 2a 29 0a 29 3b 0a 53 51 4c 49 54 45  void*).);.SQLITE
36a80 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
36a90 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
36aa0 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 2a  n_v2(.  sqlite3*
36ab0 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  , .  const char 
36ac0 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65  *zName, .  int e
36ad0 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64  TextRep, .  void
36ae0 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78   *pArg,.  int(*x
36af0 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69  Compare)(void*,i
36b00 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69  nt,const void*,i
36b10 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 2c  nt,const void*),
36b20 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f  .  void(*xDestro
36b30 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 53 51 4c  y)(void*).);.SQL
36b40 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
36b50 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
36b60 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65  tion16(.  sqlite
36b70 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 76 6f 69  3*, .  const voi
36b80 64 20 2a 7a 4e 61 6d 65 2c 0a 20 20 69 6e 74 20  d *zName,.  int 
36b90 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69  eTextRep, .  voi
36ba0 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a  d *pArg,.  int(*
36bb0 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c  xCompare)(void*,
36bc0 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  int,const void*,
36bd0 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29  int,const void*)
36be0 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
36bf0 52 45 46 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 4e  REF: Collation N
36c00 65 65 64 65 64 20 43 61 6c 6c 62 61 63 6b 73 0a  eeded Callbacks.
36c10 2a 2a 0a 2a 2a 20 5e 54 6f 20 61 76 6f 69 64 20  **.** ^To avoid 
36c20 68 61 76 69 6e 67 20 74 6f 20 72 65 67 69 73 74  having to regist
36c30 65 72 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6f 6e  er all collation
36c40 20 73 65 71 75 65 6e 63 65 73 20 62 65 66 6f 72   sequences befor
36c50 65 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  e a database.** 
36c60 63 61 6e 20 62 65 20 75 73 65 64 2c 20 61 20 73  can be used, a s
36c70 69 6e 67 6c 65 20 63 61 6c 6c 62 61 63 6b 20 66  ingle callback f
36c80 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72  unction may be r
36c90 65 67 69 73 74 65 72 65 64 20 77 69 74 68 20 74  egistered with t
36ca0 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  he.** [database 
36cb0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 62  connection] to b
36cc0 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76  e invoked whenev
36cd0 65 72 20 61 6e 20 75 6e 64 65 66 69 6e 65 64 20  er an undefined 
36ce0 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71  collation.** seq
36cf0 75 65 6e 63 65 20 69 73 20 72 65 71 75 69 72 65  uence is require
36d00 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  d..**.** ^If the
36d10 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 65 67   function is reg
36d20 69 73 74 65 72 65 64 20 75 73 69 6e 67 20 74 68  istered using th
36d30 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74  e sqlite3_collat
36d40 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 41 50 49  ion_needed() API
36d50 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20  ,.** then it is 
36d60 70 61 73 73 65 64 20 74 68 65 20 6e 61 6d 65 73  passed the names
36d70 20 6f 66 20 75 6e 64 65 66 69 6e 65 64 20 63 6f   of undefined co
36d80 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
36d90 73 20 61 73 20 73 74 72 69 6e 67 73 0a 2a 2a 20  s as strings.** 
36da0 65 6e 63 6f 64 65 64 20 69 6e 20 55 54 46 2d 38  encoded in UTF-8
36db0 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f  . ^If sqlite3_co
36dc0 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36  llation_needed16
36dd0 28 29 20 69 73 20 75 73 65 64 2c 0a 2a 2a 20 74  () is used,.** t
36de0 68 65 20 6e 61 6d 65 73 20 61 72 65 20 70 61 73  he names are pas
36df0 73 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e  sed as UTF-16 in
36e00 20 6d 61 63 68 69 6e 65 20 6e 61 74 69 76 65 20   machine native 
36e10 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 5e  byte order..** ^
36e20 41 20 63 61 6c 6c 20 74 6f 20 65 69 74 68 65 72  A call to either
36e30 20 66 75 6e 63 74 69 6f 6e 20 72 65 70 6c 61 63   function replac
36e40 65 73 20 74 68 65 20 65 78 69 73 74 69 6e 67 20  es the existing 
36e50 63 6f 6c 6c 61 74 69 6f 6e 2d 6e 65 65 64 65 64  collation-needed
36e60 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a   callback..**.**
36e70 20 5e 28 57 68 65 6e 20 74 68 65 20 63 61 6c 6c   ^(When the call
36e80 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2c  back is invoked,
36e90 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
36ea0 65 6e 74 20 70 61 73 73 65 64 20 69 73 20 61 20  ent passed is a 
36eb0 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73  copy.** of the s
36ec0 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
36ed0 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74  o sqlite3_collat
36ee0 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 6f 72 0a  ion_needed() or.
36ef0 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  ** sqlite3_colla
36f00 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 2e  tion_needed16().
36f10 20 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67    The second arg
36f20 75 6d 65 6e 74 20 69 73 20 74 68 65 20 64 61 74  ument is the dat
36f30 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
36f40 69 6f 6e 2e 20 20 54 68 65 20 74 68 69 72 64 20  ion.  The third 
36f50 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20  argument is one 
36f60 6f 66 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d  of [SQLITE_UTF8]
36f70 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42  , [SQLITE_UTF16B
36f80 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54  E],.** or [SQLIT
36f90 45 5f 55 54 46 31 36 4c 45 5d 2c 20 69 6e 64 69  E_UTF16LE], indi
36fa0 63 61 74 69 6e 67 20 74 68 65 20 6d 6f 73 74 20  cating the most 
36fb0 64 65 73 69 72 61 62 6c 65 20 66 6f 72 6d 20 6f  desirable form o
36fc0 66 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a  f the collation.
36fd0 2a 2a 20 73 65 71 75 65 6e 63 65 20 66 75 6e 63  ** sequence func
36fe0 74 69 6f 6e 20 72 65 71 75 69 72 65 64 2e 20 20  tion required.  
36ff0 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  The fourth param
37000 65 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65  eter is the name
37010 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 71 75 69   of the.** requi
37020 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65  red collation se
37030 71 75 65 6e 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20  quence.)^.**.** 
37040 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  The callback fun
37050 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 72 65 67  ction should reg
37060 69 73 74 65 72 20 74 68 65 20 64 65 73 69 72 65  ister the desire
37070 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 75 73 69 6e  d collation usin
37080 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72  g.** [sqlite3_cr
37090 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29  eate_collation()
370a0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  ], [sqlite3_crea
370b0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29  te_collation16()
370c0 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ], or.** [sqlite
370d0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
370e0 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 53 51 4c  on_v2()]..*/.SQL
370f0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
37100 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
37110 65 64 65 64 28 0a 20 20 73 71 6c 69 74 65 33 2a  eded(.  sqlite3*
37120 2c 20 0a 20 20 76 6f 69 64 2a 2c 20 0a 20 20 76  , .  void*, .  v
37130 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c  oid(*)(void*,sql
37140 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52  ite3*,int eTextR
37150 65 70 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 0a  ep,const char*).
37160 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
37170 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74  t sqlite3_collat
37180 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 0a 20 20  ion_needed16(.  
37190 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69  sqlite3*, .  voi
371a0 64 2a 2c 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f  d*,.  void(*)(vo
371b0 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74  id*,sqlite3*,int
371c0 20 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20   eTextRep,const 
371d0 76 6f 69 64 2a 29 0a 29 3b 0a 0a 23 69 66 64 65  void*).);..#ifde
371e0 66 20 53 51 4c 49 54 45 5f 48 41 53 5f 43 4f 44  f SQLITE_HAS_COD
371f0 45 43 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79  EC./*.** Specify
37200 20 74 68 65 20 6b 65 79 20 66 6f 72 20 61 6e 20   the key for an 
37210 65 6e 63 72 79 70 74 65 64 20 64 61 74 61 62 61  encrypted databa
37220 73 65 2e 20 20 54 68 69 73 20 72 6f 75 74 69 6e  se.  This routin
37230 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 63  e should be.** c
37240 61 6c 6c 65 64 20 72 69 67 68 74 20 61 66 74 65  alled right afte
37250 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  r sqlite3_open()
37260 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65  ..**.** The code
37270 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68   to implement th
37280 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76  is API is not av
37290 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70  ailable in the p
372a0 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a  ublic release.**
372b0 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 53   of SQLite..*/.S
372c0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
372d0 6c 69 74 65 33 5f 6b 65 79 28 0a 20 20 73 71 6c  lite3_key(.  sql
372e0 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
372f0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
37300 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 65  atabase to be re
37310 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74  keyed */.  const
37320 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74   void *pKey, int
37330 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65   nKey     /* The
37340 20 6b 65 79 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54   key */.);.SQLIT
37350 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
37360 33 5f 6b 65 79 5f 76 32 28 0a 20 20 73 71 6c 69  3_key_v2(.  sqli
37370 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
37380 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
37390 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b  tabase to be rek
373a0 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  eyed */.  const 
373b0 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65 2c 20 20  char *zDbName,  
373c0 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65           /* Name
373d0 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
373e0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
373f0 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79   *pKey, int nKey
37400 20 20 20 20 20 2f 2a 20 54 68 65 20 6b 65 79 20       /* The key 
37410 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 68 61  */.);../*.** Cha
37420 6e 67 65 20 74 68 65 20 6b 65 79 20 6f 6e 20 61  nge the key on a
37430 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 2e  n open database.
37440 20 20 49 66 20 74 68 65 20 63 75 72 72 65 6e 74    If the current
37450 20 64 61 74 61 62 61 73 65 20 69 73 20 6e 6f 74   database is not
37460 0a 2a 2a 20 65 6e 63 72 79 70 74 65 64 2c 20 74  .** encrypted, t
37470 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c  his routine will
37480 20 65 6e 63 72 79 70 74 20 69 74 2e 20 20 49 66   encrypt it.  If
37490 20 70 4e 65 77 3d 3d 30 20 6f 72 20 6e 4e 65 77   pNew==0 or nNew
374a0 3d 3d 30 2c 20 74 68 65 0a 2a 2a 20 64 61 74 61  ==0, the.** data
374b0 62 61 73 65 20 69 73 20 64 65 63 72 79 70 74 65  base is decrypte
374c0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64  d..**.** The cod
374d0 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74  e to implement t
374e0 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61  his API is not a
374f0 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20  vailable in the 
37500 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a  public release.*
37510 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  * of SQLite..*/.
37520 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
37530 71 6c 69 74 65 33 5f 72 65 6b 65 79 28 0a 20 20  qlite3_rekey(.  
37540 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
37550 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
37560 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 62 65  * Database to be
37570 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f   rekeyed */.  co
37580 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20  nst void *pKey, 
37590 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20  int nKey     /* 
375a0 54 68 65 20 6e 65 77 20 6b 65 79 20 2a 2f 0a 29  The new key */.)
375b0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
375c0 20 73 71 6c 69 74 65 33 5f 72 65 6b 65 79 5f 76   sqlite3_rekey_v
375d0 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  2(.  sqlite3 *db
375e0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
375f0 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
37600 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f  to be rekeyed */
37610 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
37620 44 62 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 20  DbName,         
37630 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65    /* Name of the
37640 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63   database */.  c
37650 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c  onst void *pKey,
37660 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a   int nKey     /*
37670 20 54 68 65 20 6e 65 77 20 6b 65 79 20 2a 2f 0a   The new key */.
37680 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66  );../*.** Specif
37690 79 20 74 68 65 20 61 63 74 69 76 61 74 69 6f 6e  y the activation
376a0 20 6b 65 79 20 66 6f 72 20 61 20 53 45 45 20 64   key for a SEE d
376b0 61 74 61 62 61 73 65 2e 20 20 55 6e 6c 65 73 73  atabase.  Unless
376c0 20 0a 2a 2a 20 61 63 74 69 76 61 74 65 64 2c 20   .** activated, 
376d0 6e 6f 6e 65 20 6f 66 20 74 68 65 20 53 45 45 20  none of the SEE 
376e0 72 6f 75 74 69 6e 65 73 20 77 69 6c 6c 20 77 6f  routines will wo
376f0 72 6b 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  rk..*/.SQLITE_AP
37700 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 61  I void sqlite3_a
37710 63 74 69 76 61 74 65 5f 73 65 65 28 0a 20 20 63  ctivate_see(.  c
37720 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 73 73  onst char *zPass
37730 50 68 72 61 73 65 20 20 20 20 20 20 20 20 2f 2a  Phrase        /*
37740 20 41 63 74 69 76 61 74 69 6f 6e 20 70 68 72 61   Activation phra
37750 73 65 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69 66 0a  se */.);.#endif.
37760 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 45  .#ifdef SQLITE_E
37770 4e 41 42 4c 45 5f 43 45 52 4f 44 0a 2f 2a 0a 2a  NABLE_CEROD./*.*
37780 2a 20 53 70 65 63 69 66 79 20 74 68 65 20 61 63  * Specify the ac
37790 74 69 76 61 74 69 6f 6e 20 6b 65 79 20 66 6f 72  tivation key for
377a0 20 61 20 43 45 52 4f 44 20 64 61 74 61 62 61 73   a CEROD databas
377b0 65 2e 20 20 55 6e 6c 65 73 73 20 0a 2a 2a 20 61  e.  Unless .** a
377c0 63 74 69 76 61 74 65 64 2c 20 6e 6f 6e 65 20 6f  ctivated, none o
377d0 66 20 74 68 65 20 43 45 52 4f 44 20 72 6f 75 74  f the CEROD rout
377e0 69 6e 65 73 20 77 69 6c 6c 20 77 6f 72 6b 2e 0a  ines will work..
377f0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  */.SQLITE_API vo
37800 69 64 20 73 71 6c 69 74 65 33 5f 61 63 74 69 76  id sqlite3_activ
37810 61 74 65 5f 63 65 72 6f 64 28 0a 20 20 63 6f 6e  ate_cerod(.  con
37820 73 74 20 63 68 61 72 20 2a 7a 50 61 73 73 50 68  st char *zPassPh
37830 72 61 73 65 20 20 20 20 20 20 20 20 2f 2a 20 41  rase        /* A
37840 63 74 69 76 61 74 69 6f 6e 20 70 68 72 61 73 65  ctivation phrase
37850 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f   */.);.#endif../
37860 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
37870 75 73 70 65 6e 64 20 45 78 65 63 75 74 69 6f 6e  uspend Execution
37880 20 46 6f 72 20 41 20 53 68 6f 72 74 20 54 69 6d   For A Short Tim
37890 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  e.**.** The sqli
378a0 74 65 33 5f 73 6c 65 65 70 28 29 20 66 75 6e 63  te3_sleep() func
378b0 74 69 6f 6e 20 63 61 75 73 65 73 20 74 68 65 20  tion causes the 
378c0 63 75 72 72 65 6e 74 20 74 68 72 65 61 64 20 74  current thread t
378d0 6f 20 73 75 73 70 65 6e 64 20 65 78 65 63 75 74  o suspend execut
378e0 69 6f 6e 0a 2a 2a 20 66 6f 72 20 61 74 20 6c 65  ion.** for at le
378f0 61 73 74 20 61 20 6e 75 6d 62 65 72 20 6f 66 20  ast a number of 
37900 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 73 70 65  milliseconds spe
37910 63 69 66 69 65 64 20 69 6e 20 69 74 73 20 70 61  cified in its pa
37920 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49  rameter..**.** I
37930 66 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  f the operating 
37940 73 79 73 74 65 6d 20 64 6f 65 73 20 6e 6f 74 20  system does not 
37950 73 75 70 70 6f 72 74 20 73 6c 65 65 70 20 72 65  support sleep re
37960 71 75 65 73 74 73 20 77 69 74 68 0a 2a 2a 20 6d  quests with.** m
37970 69 6c 6c 69 73 65 63 6f 6e 64 20 74 69 6d 65 20  illisecond time 
37980 72 65 73 6f 6c 75 74 69 6f 6e 2c 20 74 68 65 6e  resolution, then
37990 20 74 68 65 20 74 69 6d 65 20 77 69 6c 6c 20 62   the time will b
379a0 65 20 72 6f 75 6e 64 65 64 20 75 70 20 74 6f 0a  e rounded up to.
379b0 2a 2a 20 74 68 65 20 6e 65 61 72 65 73 74 20 73  ** the nearest s
379c0 65 63 6f 6e 64 2e 20 54 68 65 20 6e 75 6d 62 65  econd. The numbe
379d0 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  r of millisecond
379e0 73 20 6f 66 20 73 6c 65 65 70 20 61 63 74 75 61  s of sleep actua
379f0 6c 6c 79 0a 2a 2a 20 72 65 71 75 65 73 74 65 64  lly.** requested
37a00 20 66 72 6f 6d 20 74 68 65 20 6f 70 65 72 61 74   from the operat
37a10 69 6e 67 20 73 79 73 74 65 6d 20 69 73 20 72 65  ing system is re
37a20 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53  turned..**.** ^S
37a30 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73  QLite implements
37a40 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   this interface 
37a50 62 79 20 63 61 6c 6c 69 6e 67 20 74 68 65 20 78  by calling the x
37a60 53 6c 65 65 70 28 29 0a 2a 2a 20 6d 65 74 68 6f  Sleep().** metho
37a70 64 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74  d of the default
37a80 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
37a90 62 6a 65 63 74 2e 20 20 49 66 20 74 68 65 20 78  bject.  If the x
37aa0 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 0a 2a  Sleep() method.*
37ab0 2a 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74  * of the default
37ac0 20 56 46 53 20 69 73 20 6e 6f 74 20 69 6d 70 6c   VFS is not impl
37ad0 65 6d 65 6e 74 65 64 20 63 6f 72 72 65 63 74 6c  emented correctl
37ae0 79 2c 20 6f 72 20 6e 6f 74 20 69 6d 70 6c 65 6d  y, or not implem
37af0 65 6e 74 65 64 20 61 74 0a 2a 2a 20 61 6c 6c 2c  ented at.** all,
37b00 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
37b10 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6c  or of sqlite3_sl
37b20 65 65 70 28 29 20 6d 61 79 20 64 65 76 69 61 74  eep() may deviat
37b30 65 20 66 72 6f 6d 20 74 68 65 20 64 65 73 63 72  e from the descr
37b40 69 70 74 69 6f 6e 0a 2a 2a 20 69 6e 20 74 68 65  iption.** in the
37b50 20 70 72 65 76 69 6f 75 73 20 70 61 72 61 67 72   previous paragr
37b60 61 70 68 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  aphs..*/.SQLITE_
37b70 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
37b80 73 6c 65 65 70 28 69 6e 74 29 3b 0a 0a 2f 2a 0a  sleep(int);../*.
37b90 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d  ** CAPI3REF: Nam
37ba0 65 20 4f 66 20 54 68 65 20 46 6f 6c 64 65 72 20  e Of The Folder 
37bb0 48 6f 6c 64 69 6e 67 20 54 65 6d 70 6f 72 61 72  Holding Temporar
37bc0 79 20 46 69 6c 65 73 0a 2a 2a 0a 2a 2a 20 5e 28  y Files.**.** ^(
37bd0 49 66 20 74 68 69 73 20 67 6c 6f 62 61 6c 20 76  If this global v
37be0 61 72 69 61 62 6c 65 20 69 73 20 6d 61 64 65 20  ariable is made 
37bf0 74 6f 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74  to point to a st
37c00 72 69 6e 67 20 77 68 69 63 68 20 69 73 0a 2a 2a  ring which is.**
37c10 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 66   the name of a f
37c20 6f 6c 64 65 72 20 28 61 2e 6b 2e 61 2e 20 64 69  older (a.k.a. di
37c30 72 65 63 74 6f 72 79 29 2c 20 74 68 65 6e 20 61  rectory), then a
37c40 6c 6c 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c  ll temporary fil
37c50 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79  es.** created by
37c60 20 53 51 4c 69 74 65 20 77 68 65 6e 20 75 73 69   SQLite when usi
37c70 6e 67 20 61 20 62 75 69 6c 74 2d 69 6e 20 5b 73  ng a built-in [s
37c80 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 56 46 53  qlite3_vfs | VFS
37c90 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 70 6c 61  ].** will be pla
37ca0 63 65 64 20 69 6e 20 74 68 61 74 20 64 69 72 65  ced in that dire
37cb0 63 74 6f 72 79 2e 29 5e 20 20 5e 49 66 20 74 68  ctory.)^  ^If th
37cc0 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69  is variable.** i
37cd0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
37ce0 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 70 65  , then SQLite pe
37cf0 72 66 6f 72 6d 73 20 61 20 73 65 61 72 63 68 20  rforms a search 
37d00 66 6f 72 20 61 6e 20 61 70 70 72 6f 70 72 69 61  for an appropria
37d10 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20  te.** temporary 
37d20 66 69 6c 65 20 64 69 72 65 63 74 6f 72 79 2e 0a  file directory..
37d30 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20  **.** It is not 
37d40 73 61 66 65 20 74 6f 20 72 65 61 64 20 6f 72 20  safe to read or 
37d50 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69  modify this vari
37d60 61 62 6c 65 20 69 6e 20 6d 6f 72 65 20 74 68 61  able in more tha
37d70 6e 20 6f 6e 65 0a 2a 2a 20 74 68 72 65 61 64 20  n one.** thread 
37d80 61 74 20 61 20 74 69 6d 65 2e 20 20 49 74 20 69  at a time.  It i
37d90 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 72 65  s not safe to re
37da0 61 64 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69  ad or modify thi
37db0 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69 66  s variable.** if
37dc0 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   a [database con
37dd0 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e  nection] is bein
37de0 67 20 75 73 65 64 20 61 74 20 74 68 65 20 73 61  g used at the sa
37df0 6d 65 20 74 69 6d 65 20 69 6e 20 61 20 73 65 70  me time in a sep
37e00 61 72 61 74 65 0a 2a 2a 20 74 68 72 65 61 64 2e  arate.** thread.
37e10 0a 2a 2a 20 49 74 20 69 73 20 69 6e 74 65 6e 64  .** It is intend
37e20 65 64 20 74 68 61 74 20 74 68 69 73 20 76 61 72  ed that this var
37e30 69 61 62 6c 65 20 62 65 20 73 65 74 20 6f 6e 63  iable be set onc
37e40 65 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 20  e.** as part of 
37e50 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69  process initiali
37e60 7a 61 74 69 6f 6e 20 61 6e 64 20 62 65 66 6f 72  zation and befor
37e70 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74  e any SQLite int
37e80 65 72 66 61 63 65 0a 2a 2a 20 72 6f 75 74 69 6e  erface.** routin
37e90 65 73 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c  es have been cal
37ea0 6c 65 64 20 61 6e 64 20 74 68 61 74 20 74 68 69  led and that thi
37eb0 73 20 76 61 72 69 61 62 6c 65 20 72 65 6d 61 69  s variable remai
37ec0 6e 20 75 6e 63 68 61 6e 67 65 64 0a 2a 2a 20 74  n unchanged.** t
37ed0 68 65 72 65 61 66 74 65 72 2e 0a 2a 2a 0a 2a 2a  hereafter..**.**
37ee0 20 5e 54 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72   ^The [temp_stor
37ef0 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67  e_directory prag
37f00 6d 61 5d 20 6d 61 79 20 6d 6f 64 69 66 79 20 74  ma] may modify t
37f10 68 69 73 20 76 61 72 69 61 62 6c 65 20 61 6e 64  his variable and
37f20 20 63 61 75 73 65 0a 2a 2a 20 69 74 20 74 6f 20   cause.** it to 
37f30 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20  point to memory 
37f40 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
37f50 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 2e 20  qlite3_malloc]. 
37f60 20 5e 46 75 72 74 68 65 72 6d 6f 72 65 2c 0a 2a   ^Furthermore,.*
37f70 2a 20 74 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72  * the [temp_stor
37f80 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67  e_directory prag
37f90 6d 61 5d 20 61 6c 77 61 79 73 20 61 73 73 75 6d  ma] always assum
37fa0 65 73 20 74 68 61 74 20 61 6e 79 20 73 74 72 69  es that any stri
37fb0 6e 67 0a 2a 2a 20 74 68 61 74 20 74 68 69 73 20  ng.** that this 
37fc0 76 61 72 69 61 62 6c 65 20 70 6f 69 6e 74 73 20  variable points 
37fd0 74 6f 20 69 73 20 68 65 6c 64 20 69 6e 20 6d 65  to is held in me
37fe0 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
37ff0 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  om .** [sqlite3_
38000 6d 61 6c 6c 6f 63 5d 20 61 6e 64 20 74 68 65 20  malloc] and the 
38010 70 72 61 67 6d 61 20 6d 61 79 20 61 74 74 65 6d  pragma may attem
38020 70 74 20 74 6f 20 66 72 65 65 20 74 68 61 74 20  pt to free that 
38030 6d 65 6d 6f 72 79 0a 2a 2a 20 75 73 69 6e 67 20  memory.** using 
38040 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5d 2e 0a  [sqlite3_free]..
38050 2a 2a 20 48 65 6e 63 65 2c 20 69 66 20 74 68 69  ** Hence, if thi
38060 73 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d 6f  s variable is mo
38070 64 69 66 69 65 64 20 64 69 72 65 63 74 6c 79 2c  dified directly,
38080 20 65 69 74 68 65 72 20 69 74 20 73 68 6f 75 6c   either it shoul
38090 64 20 62 65 0a 2a 2a 20 6d 61 64 65 20 4e 55 4c  d be.** made NUL
380a0 4c 20 6f 72 20 6d 61 64 65 20 74 6f 20 70 6f 69  L or made to poi
380b0 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74  nt to memory obt
380c0 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
380d0 74 65 33 5f 6d 61 6c 6c 6f 63 5d 0a 2a 2a 20 6f  te3_malloc].** o
380e0 72 20 65 6c 73 65 20 74 68 65 20 75 73 65 20 6f  r else the use o
380f0 66 20 74 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72  f the [temp_stor
38100 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67  e_directory prag
38110 6d 61 5d 20 73 68 6f 75 6c 64 20 62 65 20 61 76  ma] should be av
38120 6f 69 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e  oided..**.** <b>
38130 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20  Note to Windows 
38140 52 75 6e 74 69 6d 65 20 75 73 65 72 73 3a 3c 2f  Runtime users:</
38150 62 3e 20 20 54 68 65 20 74 65 6d 70 6f 72 61 72  b>  The temporar
38160 79 20 64 69 72 65 63 74 6f 72 79 20 6d 75 73 74  y directory must
38170 20 62 65 20 73 65 74 0a 2a 2a 20 70 72 69 6f 72   be set.** prior
38180 20 74 6f 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c   to calling [sql
38190 69 74 65 33 5f 6f 70 65 6e 5d 20 6f 72 20 5b 73  ite3_open] or [s
381a0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 5d 2e  qlite3_open_v2].
381b0 20 20 4f 74 68 65 72 77 69 73 65 2c 20 76 61 72    Otherwise, var
381c0 69 6f 75 73 0a 2a 2a 20 66 65 61 74 75 72 65 73  ious.** features
381d0 20 74 68 61 74 20 72 65 71 75 69 72 65 20 74 68   that require th
381e0 65 20 75 73 65 20 6f 66 20 74 65 6d 70 6f 72 61  e use of tempora
381f0 72 79 20 66 69 6c 65 73 20 6d 61 79 20 66 61 69  ry files may fai
38200 6c 2e 20 20 48 65 72 65 20 69 73 20 61 6e 0a 2a  l.  Here is an.*
38210 2a 20 65 78 61 6d 70 6c 65 20 6f 66 20 68 6f 77  * example of how
38220 20 74 6f 20 64 6f 20 74 68 69 73 20 75 73 69 6e   to do this usin
38230 67 20 43 2b 2b 20 77 69 74 68 20 74 68 65 20 57  g C++ with the W
38240 69 6e 64 6f 77 73 20 52 75 6e 74 69 6d 65 3a 0a  indows Runtime:.
38250 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
38260 65 3e 3c 70 72 65 3e 0a 2a 2a 20 4c 50 43 57 53  e><pre>.** LPCWS
38270 54 52 20 7a 50 61 74 68 20 3d 20 57 69 6e 64 6f  TR zPath = Windo
38280 77 73 3a 3a 53 74 6f 72 61 67 65 3a 3a 41 70 70  ws::Storage::App
38290 6c 69 63 61 74 69 6f 6e 44 61 74 61 3a 3a 43 75  licationData::Cu
382a0 72 72 65 6e 74 2d 3e 0a 2a 2a 20 26 6e 62 73 70  rrent->.** &nbsp
382b0 3b 20 20 20 20 20 54 65 6d 70 6f 72 61 72 79 46  ;     TemporaryF
382c0 6f 6c 64 65 72 2d 3e 50 61 74 68 2d 3e 44 61 74  older->Path->Dat
382d0 61 28 29 3b 0a 2a 2a 20 63 68 61 72 20 7a 50 61  a();.** char zPa
382e0 74 68 42 75 66 26 23 39 31 3b 4d 41 58 5f 50 41  thBuf&#91;MAX_PA
382f0 54 48 20 2b 20 31 26 23 39 33 3b 3b 0a 2a 2a 20  TH + 1&#93;;.** 
38300 6d 65 6d 73 65 74 28 7a 50 61 74 68 42 75 66 2c  memset(zPathBuf,
38310 20 30 2c 20 73 69 7a 65 6f 66 28 7a 50 61 74 68   0, sizeof(zPath
38320 42 75 66 29 29 3b 0a 2a 2a 20 57 69 64 65 43 68  Buf));.** WideCh
38330 61 72 54 6f 4d 75 6c 74 69 42 79 74 65 28 43 50  arToMultiByte(CP
38340 5f 55 54 46 38 2c 20 30 2c 20 7a 50 61 74 68 2c  _UTF8, 0, zPath,
38350 20 2d 31 2c 20 7a 50 61 74 68 42 75 66 2c 20 73   -1, zPathBuf, s
38360 69 7a 65 6f 66 28 7a 50 61 74 68 42 75 66 29 2c  izeof(zPathBuf),
38370 0a 2a 2a 20 26 6e 62 73 70 3b 20 20 20 20 20 4e  .** &nbsp;     N
38380 55 4c 4c 2c 20 4e 55 4c 4c 29 3b 0a 2a 2a 20 73  ULL, NULL);.** s
38390 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 65  qlite3_temp_dire
383a0 63 74 6f 72 79 20 3d 20 73 71 6c 69 74 65 33 5f  ctory = sqlite3_
383b0 6d 70 72 69 6e 74 66 28 22 25 73 22 2c 20 7a 50  mprintf("%s", zP
383c0 61 74 68 42 75 66 29 3b 0a 2a 2a 20 3c 2f 70 72  athBuf);.** </pr
383d0 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
383e0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68  */.SQLITE_API ch
383f0 61 72 20 2a 73 71 6c 69 74 65 33 5f 74 65 6d 70  ar *sqlite3_temp
38400 5f 64 69 72 65 63 74 6f 72 79 3b 0a 0a 2f 2a 0a  _directory;../*.
38410 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d  ** CAPI3REF: Nam
38420 65 20 4f 66 20 54 68 65 20 46 6f 6c 64 65 72 20  e Of The Folder 
38430 48 6f 6c 64 69 6e 67 20 44 61 74 61 62 61 73 65  Holding Database
38440 20 46 69 6c 65 73 0a 2a 2a 0a 2a 2a 20 5e 28 49   Files.**.** ^(I
38450 66 20 74 68 69 73 20 67 6c 6f 62 61 6c 20 76 61  f this global va
38460 72 69 61 62 6c 65 20 69 73 20 6d 61 64 65 20 74  riable is made t
38470 6f 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72  o point to a str
38480 69 6e 67 20 77 68 69 63 68 20 69 73 0a 2a 2a 20  ing which is.** 
38490 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 66 6f  the name of a fo
384a0 6c 64 65 72 20 28 61 2e 6b 2e 61 2e 20 64 69 72  lder (a.k.a. dir
384b0 65 63 74 6f 72 79 29 2c 20 74 68 65 6e 20 61 6c  ectory), then al
384c0 6c 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 73  l database files
384d0 0a 2a 2a 20 73 70 65 63 69 66 69 65 64 20 77 69  .** specified wi
384e0 74 68 20 61 20 72 65 6c 61 74 69 76 65 20 70 61  th a relative pa
384f0 74 68 6e 61 6d 65 20 61 6e 64 20 63 72 65 61 74  thname and creat
38500 65 64 20 6f 72 20 61 63 63 65 73 73 65 64 20 62  ed or accessed b
38510 79 0a 2a 2a 20 53 51 4c 69 74 65 20 77 68 65 6e  y.** SQLite when
38520 20 75 73 69 6e 67 20 61 20 62 75 69 6c 74 2d 69   using a built-i
38530 6e 20 77 69 6e 64 6f 77 73 20 5b 73 71 6c 69 74  n windows [sqlit
38540 65 33 5f 76 66 73 20 7c 20 56 46 53 5d 20 77 69  e3_vfs | VFS] wi
38550 6c 6c 20 62 65 20 61 73 73 75 6d 65 64 0a 2a 2a  ll be assumed.**
38560 20 74 6f 20 62 65 20 72 65 6c 61 74 69 76 65 20   to be relative 
38570 74 6f 20 74 68 61 74 20 64 69 72 65 63 74 6f 72  to that director
38580 79 2e 29 5e 20 5e 49 66 20 74 68 69 73 20 76 61  y.)^ ^If this va
38590 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c  riable is a NULL
385a0 0a 2a 2a 20 70 6f 69 6e 74 65 72 2c 20 74 68 65  .** pointer, the
385b0 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73  n SQLite assumes
385c0 20 74 68 61 74 20 61 6c 6c 20 64 61 74 61 62 61   that all databa
385d0 73 65 20 66 69 6c 65 73 20 73 70 65 63 69 66 69  se files specifi
385e0 65 64 0a 2a 2a 20 77 69 74 68 20 61 20 72 65 6c  ed.** with a rel
385f0 61 74 69 76 65 20 70 61 74 68 6e 61 6d 65 20 61  ative pathname a
38600 72 65 20 72 65 6c 61 74 69 76 65 20 74 6f 20 74  re relative to t
38610 68 65 20 63 75 72 72 65 6e 74 20 64 69 72 65 63  he current direc
38620 74 6f 72 79 0a 2a 2a 20 66 6f 72 20 74 68 65 20  tory.** for the 
38630 70 72 6f 63 65 73 73 2e 20 20 4f 6e 6c 79 20 74  process.  Only t
38640 68 65 20 77 69 6e 64 6f 77 73 20 56 46 53 20 6d  he windows VFS m
38650 61 6b 65 73 20 75 73 65 20 6f 66 20 74 68 69 73  akes use of this
38660 20 67 6c 6f 62 61 6c 0a 2a 2a 20 76 61 72 69 61   global.** varia
38670 62 6c 65 3b 20 69 74 20 69 73 20 69 67 6e 6f 72  ble; it is ignor
38680 65 64 20 62 79 20 74 68 65 20 75 6e 69 78 20 56  ed by the unix V
38690 46 53 2e 0a 2a 2a 0a 2a 2a 20 43 68 61 6e 67 69  FS..**.** Changi
386a0 6e 67 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  ng the value of 
386b0 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 77 68  this variable wh
386c0 69 6c 65 20 61 20 64 61 74 61 62 61 73 65 20 63  ile a database c
386d0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 0a 2a 2a 20  onnection is.** 
386e0 6f 70 65 6e 20 63 61 6e 20 72 65 73 75 6c 74 20  open can result 
386f0 69 6e 20 61 20 63 6f 72 72 75 70 74 20 64 61 74  in a corrupt dat
38700 61 62 61 73 65 2e 0a 2a 2a 0a 2a 2a 20 49 74 20  abase..**.** It 
38710 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 72  is not safe to r
38720 65 61 64 20 6f 72 20 6d 6f 64 69 66 79 20 74 68  ead or modify th
38730 69 73 20 76 61 72 69 61 62 6c 65 20 69 6e 20 6d  is variable in m
38740 6f 72 65 20 74 68 61 6e 20 6f 6e 65 0a 2a 2a 20  ore than one.** 
38750 74 68 72 65 61 64 20 61 74 20 61 20 74 69 6d 65  thread at a time
38760 2e 20 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66  .  It is not saf
387