System.Data.SQLite
Hex Artifact Content
Not logged in

Artifact c67060b9cca483d60fc035000c33ffc4c96e33fc:


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 33 2d 31 32 2d 30        "2013-12-0
1630: 33 20 31 39 3a 34 39 3a 35 35 20 65 63 61 37 64  3 19:49:55 eca7d
1640: 33 66 31 36 31 32 63 37 61 30 30 39 61 39 65 34  3f1612c7a009a9e4
1650: 65 66 38 39 66 37 36 66 39 62 37 65 32 37 35 64  ef89f76f9b7e275d
1660: 31 65 36 22 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  1e6"../*.** 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 0a 2a 2a 20 5e 54 68 65  er P..**.** ^The
1d2c0 20 66 69 72 73 74 20 74 69 6d 65 20 74 68 69 73   first time this
1d2d0 20 72 6f 75 74 69 6e 65 20 69 73 20 69 6e 76 6f   routine is invo
1d2e0 6b 65 64 20 28 65 69 74 68 65 72 20 69 6e 74 65  ked (either inte
1d2f0 72 6e 61 6c 6c 79 20 6f 72 20 62 79 0a 2a 2a 20  rnally or by.** 
1d300 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 29  the application)
1d310 20 74 68 65 20 50 52 4e 47 20 69 73 20 73 65 65   the PRNG is see
1d320 64 65 64 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d  ded using random
1d330 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 0a 2a 2a  ness obtained.**
1d340 20 66 72 6f 6d 20 74 68 65 20 78 52 61 6e 64 6f   from the xRando
1d350 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20  mness method of 
1d360 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c  the default [sql
1d370 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
1d380 2e 0a 2a 2a 20 5e 4f 6e 20 61 6c 6c 20 73 75 62  ..** ^On all sub
1d390 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69  sequent invocati
1d3a0 6f 6e 73 2c 20 74 68 65 20 70 73 65 75 64 6f 2d  ons, the pseudo-
1d3b0 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67 65  randomness is ge
1d3c0 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72  nerated.** inter
1d3d0 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f 75  nally and withou
1d3e0 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20 74 68  t recourse to th
1d3f0 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  e [sqlite3_vfs] 
1d400 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d  xRandomness.** m
1d410 65 74 68 6f 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45  ethod..*/.SQLITE
1d420 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65  _API void sqlite
1d430 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e 74  3_randomness(int
1d440 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f   N, void *P);../
1d450 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
1d460 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75 74 68  ompile-Time Auth
1d470 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 61  orization Callba
1d480 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  cks.**.** ^This 
1d490 72 6f 75 74 69 6e 65 20 72 65 67 69 73 74 65 72  routine register
1d4a0 73 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 20  s an authorizer 
1d4b0 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 61 20  callback with a 
1d4c0 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64  particular.** [d
1d4d0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1d4e0 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 64 20 69 6e  on], supplied in
1d4f0 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
1d500 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 61 75 74  ent..** ^The aut
1d510 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1d520 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 20 53   is invoked as S
1d530 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72  QL statements ar
1d540 65 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64  e being compiled
1d550 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  .** by [sqlite3_
1d560 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74  prepare()] or it
1d570 73 20 76 61 72 69 61 6e 74 73 20 5b 73 71 6c 69  s variants [sqli
1d580 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1d590 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  ],.** [sqlite3_p
1d5a0 72 65 70 61 72 65 31 36 28 29 5d 20 61 6e 64 20  repare16()] and 
1d5b0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1d5c0 31 36 5f 76 32 28 29 5d 2e 20 20 5e 41 74 20 76  16_v2()].  ^At v
1d5d0 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73  arious.** points
1d5e0 20 64 75 72 69 6e 67 20 74 68 65 20 63 6f 6d 70   during the comp
1d5f0 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c  ilation process,
1d600 20 61 73 20 6c 6f 67 69 63 20 69 73 20 62 65 69   as logic is bei
1d610 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f  ng created.** to
1d620 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73   perform various
1d630 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 20 61 75   actions, the au
1d640 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1d650 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a  k is invoked to.
1d660 2a 2a 20 73 65 65 20 69 66 20 74 68 6f 73 65 20  ** see if those 
1d670 61 63 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f  actions are allo
1d680 77 65 64 2e 20 20 5e 54 68 65 20 61 75 74 68 6f  wed.  ^The autho
1d690 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 73  rizer callback s
1d6a0 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20  hould.** return 
1d6b0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61  [SQLITE_OK] to a
1d6c0 6c 6c 6f 77 20 74 68 65 20 61 63 74 69 6f 6e 2c  llow the action,
1d6d0 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
1d6e0 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68 65   to disallow the
1d6f0 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 61 63 74  .** specific act
1d700 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74 68  ion but allow th
1d710 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
1d720 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62  to continue to b
1d730 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f  e.** compiled, o
1d740 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20  r [SQLITE_DENY] 
1d750 74 6f 20 63 61 75 73 65 20 74 68 65 20 65 6e 74  to cause the ent
1d760 69 72 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ire SQL statemen
1d770 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63  t to be.** rejec
1d780 74 65 64 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ted with an erro
1d790 72 2e 20 20 5e 49 66 20 74 68 65 20 61 75 74 68  r.  ^If the auth
1d7a0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1d7b0 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76  returns.** any v
1d7c0 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e 20  alue other than 
1d7d0 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c  [SQLITE_IGNORE],
1d7e0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72   [SQLITE_OK], or
1d7f0 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a   [SQLITE_DENY].*
1d800 2a 20 74 68 65 6e 20 74 68 65 20 5b 73 71 6c 69  * then the [sqli
1d810 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1d820 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20  ] or equivalent 
1d830 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65  call that trigge
1d840 72 65 64 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f  red.** the autho
1d850 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20  rizer will fail 
1d860 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65  with an error me
1d870 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65  ssage..**.** Whe
1d880 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  n the callback r
1d890 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
1d8a0 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74  K], that means t
1d8b0 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20  he operation.** 
1d8c0 72 65 71 75 65 73 74 65 64 20 69 73 20 6f 6b 2e  requested is ok.
1d8d0 20 20 5e 57 68 65 6e 20 74 68 65 20 63 61 6c 6c    ^When the call
1d8e0 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51  back returns [SQ
1d8f0 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a  LITE_DENY], the.
1d900 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
1d910 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75  are_v2()] or equ
1d920 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61  ivalent call tha
1d930 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65 0a  t triggered the.
1d940 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69  ** authorizer wi
1d950 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20  ll fail with an 
1d960 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 65 78  error message ex
1d970 70 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a  plaining that.**
1d980 20 61 63 63 65 73 73 20 69 73 20 64 65 6e 69 65   access is denie
1d990 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  d. .**.** ^The f
1d9a0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
1d9b0 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  o the authorizer
1d9c0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63   callback is a c
1d9d0 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69 72 64  opy of the third
1d9e0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f  .** parameter to
1d9f0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74   the sqlite3_set
1da00 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 20 69 6e  _authorizer() in
1da10 74 65 72 66 61 63 65 2e 20 5e 54 68 65 20 73 65  terface. ^The se
1da20 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a  cond parameter.*
1da30 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  * to the callbac
1da40 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  k is an integer 
1da50 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61  [SQLITE_COPY | a
1da60 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74  ction code] that
1da70 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68   specifies.** th
1da80 65 20 70 61 72 74 69 63 75 6c 61 72 20 61 63 74  e particular act
1da90 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72  ion to be author
1daa0 69 7a 65 64 2e 20 5e 54 68 65 20 74 68 69 72 64  ized. ^The third
1dab0 20 74 68 72 6f 75 67 68 20 73 69 78 74 68 20 70   through sixth p
1dac0 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20  arameters.** to 
1dad0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 72 65  the callback are
1dae0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
1daf0 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 63 6f   strings that co
1db00 6e 74 61 69 6e 20 61 64 64 69 74 69 6f 6e 61 6c  ntain additional
1db10 0a 2a 2a 20 64 65 74 61 69 6c 73 20 61 62 6f 75  .** details abou
1db20 74 20 74 68 65 20 61 63 74 69 6f 6e 20 74 6f 20  t the action to 
1db30 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a  be authorized..*
1db40 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74  *.** ^If the act
1db50 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c  ion code is [SQL
1db60 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e 64  ITE_READ].** and
1db70 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
1db80 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 49 47  turns [SQLITE_IG
1db90 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 0a 2a  NORE] then the.*
1dba0 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
1dbb0 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65 6e 74  ement] statement
1dbc0 20 69 73 20 63 6f 6e 73 74 72 75 63 74 65 64 20   is constructed 
1dbd0 74 6f 20 73 75 62 73 74 69 74 75 74 65 0a 2a 2a  to substitute.**
1dbe0 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e   a NULL value in
1dbf0 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20 74 61   place of the ta
1dc00 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20  ble column that 
1dc10 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 62 65  would have.** be
1dc20 65 6e 20 72 65 61 64 20 69 66 20 5b 53 51 4c 49  en read if [SQLI
1dc30 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20  TE_OK] had been 
1dc40 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 5b  returned.  The [
1dc50 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a  SQLITE_IGNORE].*
1dc60 2a 20 72 65 74 75 72 6e 20 63 61 6e 20 62 65 20  * return can be 
1dc70 75 73 65 64 20 74 6f 20 64 65 6e 79 20 61 6e 20  used to deny an 
1dc80 75 6e 74 72 75 73 74 65 64 20 75 73 65 72 20 61  untrusted user a
1dc90 63 63 65 73 73 20 74 6f 20 69 6e 64 69 76 69 64  ccess to individ
1dca0 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f  ual.** columns o
1dcb0 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 20 5e 49  f a table..** ^I
1dcc0 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64  f the action cod
1dcd0 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 44 45 4c  e is [SQLITE_DEL
1dce0 45 54 45 5d 20 61 6e 64 20 74 68 65 20 63 61 6c  ETE] and the cal
1dcf0 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a  lback returns.**
1dd00 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
1dd10 20 74 68 65 6e 20 74 68 65 20 5b 44 45 4c 45 54   then the [DELET
1dd20 45 5d 20 6f 70 65 72 61 74 69 6f 6e 20 70 72 6f  E] operation pro
1dd30 63 65 65 64 73 20 62 75 74 20 74 68 65 0a 2a 2a  ceeds but the.**
1dd40 20 5b 74 72 75 6e 63 61 74 65 20 6f 70 74 69 6d   [truncate optim
1dd50 69 7a 61 74 69 6f 6e 5d 20 69 73 20 64 69 73 61  ization] is disa
1dd60 62 6c 65 64 20 61 6e 64 20 61 6c 6c 20 72 6f 77  bled and all row
1dd70 73 20 61 72 65 20 64 65 6c 65 74 65 64 20 69 6e  s are deleted in
1dd80 64 69 76 69 64 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a  dividually..**.*
1dd90 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20  * An authorizer 
1dda0 69 73 20 75 73 65 64 20 77 68 65 6e 20 5b 73 71  is used when [sq
1ddb0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20  lite3_prepare | 
1ddc0 70 72 65 70 61 72 69 6e 67 5d 0a 2a 2a 20 53 51  preparing].** SQ
1ddd0 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 66 72 6f  L statements fro
1dde0 6d 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73  m an untrusted s
1ddf0 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73 75 72 65  ource, to ensure
1de00 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 73 74   that the SQL st
1de10 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e  atements.** do n
1de20 6f 74 20 74 72 79 20 74 6f 20 61 63 63 65 73 73  ot try to access
1de30 20 64 61 74 61 20 74 68 65 79 20 61 72 65 20 6e   data they are n
1de40 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73 65  ot allowed to se
1de50 65 2c 20 6f 72 20 74 68 61 74 20 74 68 65 79 20  e, or that they 
1de60 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79 20 74 6f  do not.** try to
1de70 20 65 78 65 63 75 74 65 20 6d 61 6c 69 63 69 6f   execute malicio
1de80 75 73 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68  us statements th
1de90 61 74 20 64 61 6d 61 67 65 20 74 68 65 20 64 61  at damage the da
1dea0 74 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a 20  tabase.  For.** 
1deb0 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c  example, an appl
1dec0 69 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f  ication may allo
1ded0 77 20 61 20 75 73 65 72 20 74 6f 20 65 6e 74 65  w a user to ente
1dee0 72 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 53  r arbitrary.** S
1def0 51 4c 20 71 75 65 72 69 65 73 20 66 6f 72 20 65  QL queries for e
1df00 76 61 6c 75 61 74 69 6f 6e 20 62 79 20 61 20 64  valuation by a d
1df10 61 74 61 62 61 73 65 2e 20 20 42 75 74 20 74 68  atabase.  But th
1df20 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f  e application do
1df30 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74  es.** not want t
1df40 68 65 20 75 73 65 72 20 74 6f 20 62 65 20 61 62  he user to be ab
1df50 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72 62 69 74  le to make arbit
1df60 72 61 72 79 20 63 68 61 6e 67 65 73 20 74 6f 20  rary changes to 
1df70 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e  the.** database.
1df80 20 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20    An authorizer 
1df90 63 6f 75 6c 64 20 74 68 65 6e 20 62 65 20 70 75  could then be pu
1dfa0 74 20 69 6e 20 70 6c 61 63 65 20 77 68 69 6c 65  t in place while
1dfb0 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e 74   the.** user-ent
1dfc0 65 72 65 64 20 53 51 4c 20 69 73 20 62 65 69 6e  ered SQL is bein
1dfd0 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  g [sqlite3_prepa
1dfe0 72 65 20 7c 20 70 72 65 70 61 72 65 64 5d 20 74  re | prepared] t
1dff0 68 61 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77 73  hat.** disallows
1e000 20 65 76 65 72 79 74 68 69 6e 67 20 65 78 63 65   everything exce
1e010 70 74 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74  pt [SELECT] stat
1e020 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70  ements..**.** Ap
1e030 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
1e040 6e 65 65 64 20 74 6f 20 70 72 6f 63 65 73 73 20  need to process 
1e050 53 51 4c 20 66 72 6f 6d 20 75 6e 74 72 75 73 74  SQL from untrust
1e060 65 64 20 73 6f 75 72 63 65 73 0a 2a 2a 20 6d 69  ed sources.** mi
1e070 67 68 74 20 61 6c 73 6f 20 63 6f 6e 73 69 64 65  ght also conside
1e080 72 20 6c 6f 77 65 72 69 6e 67 20 72 65 73 6f 75  r lowering resou
1e090 72 63 65 20 6c 69 6d 69 74 73 20 75 73 69 6e 67  rce limits using
1e0a0 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28   [sqlite3_limit(
1e0b0 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69 74 69  )].** and limiti
1e0c0 6e 67 20 64 61 74 61 62 61 73 65 20 73 69 7a 65  ng database size
1e0d0 20 75 73 69 6e 67 20 74 68 65 20 5b 6d 61 78 5f   using the [max_
1e0e0 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41  page_count] [PRA
1e0f0 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64 64 69 74  GMA].** in addit
1e100 69 6f 6e 20 74 6f 20 75 73 69 6e 67 20 61 6e 20  ion to using an 
1e110 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a  authorizer..**.*
1e120 2a 20 5e 28 4f 6e 6c 79 20 61 20 73 69 6e 67 6c  * ^(Only a singl
1e130 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6e  e authorizer can
1e140 20 62 65 20 69 6e 20 70 6c 61 63 65 20 6f 6e 20   be in place on 
1e150 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  a database conne
1e160 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20 74 69  ction.** at a ti
1e170 6d 65 2e 20 20 45 61 63 68 20 63 61 6c 6c 20 74  me.  Each call t
1e180 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  o sqlite3_set_au
1e190 74 68 6f 72 69 7a 65 72 20 6f 76 65 72 72 69 64  thorizer overrid
1e1a0 65 73 20 74 68 65 0a 2a 2a 20 70 72 65 76 69 6f  es the.** previo
1e1b0 75 73 20 63 61 6c 6c 2e 29 5e 20 20 5e 44 69 73  us call.)^  ^Dis
1e1c0 61 62 6c 65 20 74 68 65 20 61 75 74 68 6f 72 69  able the authori
1e1d0 7a 65 72 20 62 79 20 69 6e 73 74 61 6c 6c 69 6e  zer by installin
1e1e0 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62 61 63  g a NULL callbac
1e1f0 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72  k..** The author
1e200 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c 65 64  izer is disabled
1e210 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a   by default..**.
1e220 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65  ** The authorize
1e230 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20  r callback must 
1e240 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20  not do anything 
1e250 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79  that will modify
1e260 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
1e270 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74   connection that
1e280 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 61 75 74   invoked the aut
1e290 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1e2a0 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b  ..** Note that [
1e2b0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1e2c0 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  v2()] and [sqlit
1e2d0 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20  e3_step()] both 
1e2e0 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20  modify their.** 
1e2f0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1e300 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61  ions for the mea
1e310 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22  ning of "modify"
1e320 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61   in this paragra
1e330 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20  ph..**.** ^When 
1e340 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1e350 5f 76 32 28 29 5d 20 69 73 20 75 73 65 64 20 74  _v2()] is used t
1e360 6f 20 70 72 65 70 61 72 65 20 61 20 73 74 61 74  o prepare a stat
1e370 65 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a 20 73 74  ement, the.** st
1e380 61 74 65 6d 65 6e 74 20 6d 69 67 68 74 20 62 65  atement might be
1e390 20 72 65 2d 70 72 65 70 61 72 65 64 20 64 75 72   re-prepared dur
1e3a0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ing [sqlite3_ste
1e3b0 70 28 29 5d 20 64 75 65 20 74 6f 20 61 20 0a 2a  p()] due to a .*
1e3c0 2a 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e  * schema change.
1e3d0 20 20 48 65 6e 63 65 2c 20 74 68 65 20 61 70 70    Hence, the app
1e3e0 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  lication should 
1e3f0 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 0a  ensure that the.
1e400 2a 2a 20 63 6f 72 72 65 63 74 20 61 75 74 68 6f  ** correct autho
1e410 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72  rizer callback r
1e420 65 6d 61 69 6e 73 20 69 6e 20 70 6c 61 63 65 20  emains in place 
1e430 64 75 72 69 6e 67 20 74 68 65 20 5b 73 71 6c 69  during the [sqli
1e440 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a  te3_step()]..**.
1e450 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68  ** ^Note that th
1e460 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1e470 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
1e480 20 6f 6e 6c 79 20 64 75 72 69 6e 67 0a 2a 2a 20   only during.** 
1e490 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1e4a0 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61  ()] or its varia
1e4b0 6e 74 73 2e 20 20 41 75 74 68 6f 72 69 7a 61 74  nts.  Authorizat
1e4c0 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20 70 65  ion is not.** pe
1e4d0 72 66 6f 72 6d 65 64 20 64 75 72 69 6e 67 20 73  rformed during s
1e4e0 74 61 74 65 6d 65 6e 74 20 65 76 61 6c 75 61 74  tatement evaluat
1e4f0 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f  ion in [sqlite3_
1e500 73 74 65 70 28 29 5d 2c 20 75 6e 6c 65 73 73 0a  step()], unless.
1e510 2a 2a 20 61 73 20 73 74 61 74 65 64 20 69 6e 20  ** as stated in 
1e520 74 68 65 20 70 72 65 76 69 6f 75 73 20 70 61 72  the previous par
1e530 61 67 72 61 70 68 2c 20 73 71 6c 69 74 65 33 5f  agraph, sqlite3_
1e540 73 74 65 70 28 29 20 69 6e 76 6f 6b 65 73 0a 2a  step() invokes.*
1e550 2a 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  * sqlite3_prepar
1e560 65 5f 76 32 28 29 20 74 6f 20 72 65 70 72 65 70  e_v2() to reprep
1e570 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74 20  are a statement 
1e580 61 66 74 65 72 20 61 20 73 63 68 65 6d 61 20 63  after a schema c
1e590 68 61 6e 67 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45  hange..*/.SQLITE
1e5a0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
1e5b0 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28  _set_authorizer(
1e5c0 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69  .  sqlite3*,.  i
1e5d0 6e 74 20 28 2a 78 41 75 74 68 29 28 76 6f 69 64  nt (*xAuth)(void
1e5e0 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72  *,int,const char
1e5f0 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f  *,const char*,co
1e600 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20  nst char*,const 
1e610 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a  char*),.  void *
1e620 70 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a  pUserData.);../*
1e630 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75  .** CAPI3REF: Au
1e640 74 68 6f 72 69 7a 65 72 20 52 65 74 75 72 6e 20  thorizer Return 
1e650 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20  Codes.**.** The 
1e660 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
1e670 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72  horizer | author
1e680 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75  izer callback fu
1e690 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20  nction] must.** 
1e6a0 72 65 74 75 72 6e 20 65 69 74 68 65 72 20 5b 53  return either [S
1e6b0 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65  QLITE_OK] or one
1e6c0 20 6f 66 20 74 68 65 73 65 20 74 77 6f 20 63 6f   of these two co
1e6d0 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72 64 65 72  nstants in order
1e6e0 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53 51  .** to signal SQ
1e6f0 4c 69 74 65 20 77 68 65 74 68 65 72 20 6f 72 20  Lite whether or 
1e700 6e 6f 74 20 74 68 65 20 61 63 74 69 6f 6e 20 69  not the action i
1e710 73 20 70 65 72 6d 69 74 74 65 64 2e 20 20 53 65  s permitted.  Se
1e720 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  e the.** [sqlite
1e730 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
1e740 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 64 6f   | authorizer do
1e750 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72  cumentation] for
1e760 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69   additional.** i
1e770 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
1e780 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 49  * Note that SQLI
1e790 54 45 5f 49 47 4e 4f 52 45 20 69 73 20 61 6c 73  TE_IGNORE is als
1e7a0 6f 20 75 73 65 64 20 61 73 20 61 20 5b 53 51 4c  o used as a [SQL
1e7b0 49 54 45 5f 52 4f 4c 4c 42 41 43 4b 20 7c 20 72  ITE_ROLLBACK | r
1e7c0 65 74 75 72 6e 20 63 6f 64 65 5d 0a 2a 2a 20 66  eturn code].** f
1e7d0 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33  rom the [sqlite3
1e7e0 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63  _vtab_on_conflic
1e7f0 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a  t()] interface..
1e800 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1e810 45 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a 20  E_DENY   1   /* 
1e820 41 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74  Abort the SQL st
1e830 61 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e 20  atement with an 
1e840 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65  error */.#define
1e850 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32   SQLITE_IGNORE 2
1e860 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f     /* Don't allo
1e870 77 20 61 63 63 65 73 73 2c 20 62 75 74 20 64 6f  w access, but do
1e880 6e 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e 20  n't generate an 
1e890 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  error */../*.** 
1e8a0 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72  CAPI3REF: Author
1e8b0 69 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64 65  izer Action Code
1e8c0 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  s.**.** The [sql
1e8d0 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
1e8e0 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65  zer()] interface
1e8f0 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c   registers a cal
1e900 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a  lback function.*
1e910 2a 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65  * that is invoke
1e920 64 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 20 63  d to authorize c
1e930 65 72 74 61 69 6e 20 53 51 4c 20 73 74 61 74 65  ertain SQL state
1e940 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20 54  ment actions.  T
1e950 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72  he.** second par
1e960 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 61  ameter to the ca
1e970 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74  llback is an int
1e980 65 67 65 72 20 63 6f 64 65 20 74 68 61 74 20 73  eger code that s
1e990 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 61 74  pecifies.** what
1e9a0 20 61 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67   action is being
1e9b0 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68   authorized.  Th
1e9c0 65 73 65 20 61 72 65 20 74 68 65 20 69 6e 74 65  ese are the inte
1e9d0 67 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 65 73  ger action codes
1e9e0 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 75 74   that.** the aut
1e9f0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1ea00 20 6d 61 79 20 62 65 20 70 61 73 73 65 64 2e 0a   may be passed..
1ea10 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 74 69  **.** These acti
1ea20 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 20 73  on code values s
1ea30 69 67 6e 69 66 79 20 77 68 61 74 20 6b 69 6e 64  ignify what kind
1ea40 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 69 73   of operation is
1ea50 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72   to be.** author
1ea60 69 7a 65 64 2e 20 20 54 68 65 20 33 72 64 20 61  ized.  The 3rd a
1ea70 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  nd 4th parameter
1ea80 73 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69  s to the authori
1ea90 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61  zation.** callba
1eaa0 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c  ck function will
1eab0 20 62 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f   be parameters o
1eac0 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67  r NULL depending
1ead0 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 68 65   on which of the
1eae0 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20 75  se.** codes is u
1eaf0 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  sed as the secon
1eb00 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 28  d parameter.  ^(
1eb10 54 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  The 5th paramete
1eb20 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68  r to the.** auth
1eb30 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1eb40 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
1eb50 68 65 20 64 61 74 61 62 61 73 65 20 28 22 6d 61  he database ("ma
1eb60 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20  in", "temp",.** 
1eb70 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61  etc.) if applica
1eb80 62 6c 65 2e 29 5e 20 20 5e 54 68 65 20 36 74 68  ble.)^  ^The 6th
1eb90 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
1eba0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1ebb0 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20  lback.** is the 
1ebc0 6e 61 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e 65  name of the inne
1ebd0 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f  r-most trigger o
1ebe0 72 20 76 69 65 77 20 74 68 61 74 20 69 73 20 72  r view that is r
1ebf0 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a  esponsible for.*
1ec00 2a 20 74 68 65 20 61 63 63 65 73 73 20 61 74 74  * the access att
1ec10 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20  empt or NULL if 
1ec20 74 68 69 73 20 61 63 63 65 73 73 20 61 74 74 65  this access atte
1ec30 6d 70 74 20 69 73 20 64 69 72 65 63 74 6c 79 20  mpt is directly 
1ec40 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65  from.** top-leve
1ec50 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f  l SQL code..*/./
1ec60 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1ec70 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1ec80 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20  *********** 3rd 
1ec90 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68  ************ 4th
1eca0 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64   ***********/.#d
1ecb0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
1ecc0 41 54 45 5f 49 4e 44 45 58 20 20 20 20 20 20 20  ATE_INDEX       
1ecd0 20 20 20 31 20 20 20 2f 2a 20 49 6e 64 65 78 20     1   /* Index 
1ece0 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
1ecf0 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
1ed00 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
1ed10 54 45 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20  TE_TABLE        
1ed20 20 20 32 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e    2   /* Table N
1ed30 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
1ed40 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1ed50 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
1ed60 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20  E_TEMP_INDEX    
1ed70 20 33 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61   3   /* Index Na
1ed80 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61  me      Table Na
1ed90 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
1eda0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
1edb0 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20  _TEMP_TABLE     
1edc0 34 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  4   /* Table Nam
1edd0 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
1ede0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1edf0 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
1ee00 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 35  TEMP_TRIGGER   5
1ee10 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
1ee20 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
1ee30 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1ee40 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
1ee50 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 36 20  EMP_VIEW      6 
1ee60 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
1ee70 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1ee80 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1ee90 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 52  SQLITE_CREATE_TR
1eea0 49 47 47 45 52 20 20 20 20 20 20 20 20 37 20 20  IGGER        7  
1eeb0 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65   /* Trigger Name
1eec0 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
1eed0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1eee0 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 49 45  QLITE_CREATE_VIE
1eef0 57 20 20 20 20 20 20 20 20 20 20 20 38 20 20 20  W           8   
1ef00 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20  /* View Name    
1ef10 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1ef20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1ef30 4c 49 54 45 5f 44 45 4c 45 54 45 20 20 20 20 20  LITE_DELETE     
1ef40 20 20 20 20 20 20 20 20 20 20 20 39 20 20 20 2f             9   /
1ef50 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
1ef60 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1ef70 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1ef80 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20  ITE_DROP_INDEX  
1ef90 20 20 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a           10   /*
1efa0 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
1efb0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1efc0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1efd0 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20 20  TE_DROP_TABLE   
1efe0 20 20 20 20 20 20 20 20 31 31 20 20 20 2f 2a 20          11   /* 
1eff0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1f000 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1f010 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1f020 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45  E_DROP_TEMP_INDE
1f030 58 20 20 20 20 20 20 31 32 20 20 20 2f 2a 20 49  X      12   /* I
1f040 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54  ndex Name      T
1f050 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
1f060 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1f070 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45  _DROP_TEMP_TABLE
1f080 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20 54 61        13   /* Ta
1f090 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
1f0a0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1f0b0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1f0c0 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47 45  DROP_TEMP_TRIGGE
1f0d0 52 20 20 20 20 31 34 20 20 20 2f 2a 20 54 72 69  R    14   /* Tri
1f0e0 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62  gger Name    Tab
1f0f0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
1f100 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1f110 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20 20 20  ROP_TEMP_VIEW   
1f120 20 20 20 20 31 35 20 20 20 2f 2a 20 56 69 65 77      15   /* View
1f130 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c   Name       NULL
1f140 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1f150 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
1f160 4f 50 5f 54 52 49 47 47 45 52 20 20 20 20 20 20  OP_TRIGGER      
1f170 20 20 20 31 36 20 20 20 2f 2a 20 54 72 69 67 67     16   /* Trigg
1f180 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65  er Name    Table
1f190 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
1f1a0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
1f1b0 50 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20  P_VIEW          
1f1c0 20 20 31 37 20 20 20 2f 2a 20 56 69 65 77 20 4e    17   /* View N
1f1d0 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  ame       NULL  
1f1e0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1f1f0 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53 45  fine SQLITE_INSE
1f200 52 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20  RT              
1f210 20 31 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   18   /* Table N
1f220 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
1f230 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1f240 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 41 47 4d  ine SQLITE_PRAGM
1f250 41 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  A               
1f260 31 39 20 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e  19   /* Pragma N
1f270 61 6d 65 20 20 20 20 20 31 73 74 20 61 72 67 20  ame     1st arg 
1f280 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69  or NULL */.#defi
1f290 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 20 20  ne SQLITE_READ  
1f2a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
1f2b0 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  0   /* Table Nam
1f2c0 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61  e      Column Na
1f2d0 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
1f2e0 65 20 53 51 4c 49 54 45 5f 53 45 4c 45 43 54 20  e SQLITE_SELECT 
1f2f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 31                21
1f300 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20     /* NULL      
1f310 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1f320 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1f330 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 41 43 54   SQLITE_TRANSACT
1f340 49 4f 4e 20 20 20 20 20 20 20 20 20 20 32 32 20  ION          22 
1f350 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20    /* Operation  
1f360 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1f370 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1f380 53 51 4c 49 54 45 5f 55 50 44 41 54 45 20 20 20  SQLITE_UPDATE   
1f390 20 20 20 20 20 20 20 20 20 20 20 20 32 33 20 20              23  
1f3a0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
1f3b0 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20      Column Name 
1f3c0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1f3d0 51 4c 49 54 45 5f 41 54 54 41 43 48 20 20 20 20  QLITE_ATTACH    
1f3e0 20 20 20 20 20 20 20 20 20 20 20 32 34 20 20 20             24   
1f3f0 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20 20 20  /* Filename     
1f400 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1f410 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1f420 4c 49 54 45 5f 44 45 54 41 43 48 20 20 20 20 20  LITE_DETACH     
1f430 20 20 20 20 20 20 20 20 20 20 32 35 20 20 20 2f            25   /
1f440 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20  * Database Name 
1f450 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1f460 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1f470 49 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20  ITE_ALTER_TABLE 
1f480 20 20 20 20 20 20 20 20 20 32 36 20 20 20 2f 2a           26   /*
1f490 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20   Database Name  
1f4a0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1f4b0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1f4c0 54 45 5f 52 45 49 4e 44 45 58 20 20 20 20 20 20  TE_REINDEX      
1f4d0 20 20 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20          27   /* 
1f4e0 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
1f4f0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1f500 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1f510 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20 20 20  E_ANALYZE       
1f520 20 20 20 20 20 20 20 32 38 20 20 20 2f 2a 20 54         28   /* T
1f530 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
1f540 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1f550 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1f560 5f 43 52 45 41 54 45 5f 56 54 41 42 4c 45 20 20  _CREATE_VTABLE  
1f570 20 20 20 20 20 20 32 39 20 20 20 2f 2a 20 54 61        29   /* Ta
1f580 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f  ble Name      Mo
1f590 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f  dule Name     */
1f5a0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1f5b0 44 52 4f 50 5f 56 54 41 42 4c 45 20 20 20 20 20  DROP_VTABLE     
1f5c0 20 20 20 20 20 33 30 20 20 20 2f 2a 20 54 61 62       30   /* Tab
1f5d0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64  le Name      Mod
1f5e0 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a  ule Name     */.
1f5f0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
1f600 55 4e 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20  UNCTION         
1f610 20 20 20 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c      31   /* NULL
1f620 20 20 20 20 20 20 20 20 20 20 20 20 46 75 6e 63              Func
1f630 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23  tion Name   */.#
1f640 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 41  define SQLITE_SA
1f650 56 45 50 4f 49 4e 54 20 20 20 20 20 20 20 20 20  VEPOINT         
1f660 20 20 20 33 32 20 20 20 2f 2a 20 4f 70 65 72 61     32   /* Opera
1f670 74 69 6f 6e 20 20 20 20 20 20 20 53 61 76 65 70  tion       Savep
1f680 6f 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64  oint Name  */.#d
1f690 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50  efine SQLITE_COP
1f6a0 59 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  Y               
1f6b0 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e     0   /* No lon
1f6c0 67 65 72 20 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a  ger used */../*.
1f6d0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 72 61  ** CAPI3REF: Tra
1f6e0 63 69 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c 69  cing And Profili
1f6f0 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a  ng Functions.**.
1f700 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
1f710 73 20 72 65 67 69 73 74 65 72 20 63 61 6c 6c 62  s register callb
1f720 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74 68  ack functions th
1f730 61 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 66  at can be used f
1f740 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e  or.** tracing an
1f750 64 20 70 72 6f 66 69 6c 69 6e 67 20 74 68 65 20  d profiling the 
1f760 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c  execution of SQL
1f770 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a   statements..**.
1f780 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b  ** ^The callback
1f790 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74   function regist
1f7a0 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  ered by sqlite3_
1f7b0 74 72 61 63 65 28 29 20 69 73 20 69 6e 76 6f 6b  trace() is invok
1f7c0 65 64 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75 73  ed at.** various
1f7d0 20 74 69 6d 65 73 20 77 68 65 6e 20 61 6e 20 53   times when an S
1f7e0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  QL statement is 
1f7f0 62 65 69 6e 67 20 72 75 6e 20 62 79 20 5b 73 71  being run by [sq
1f800 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a  lite3_step()]..*
1f810 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74  * ^The sqlite3_t
1f820 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 20  race() callback 
1f830 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20  is invoked with 
1f840 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69 6e  a UTF-8 renderin
1f850 67 20 6f 66 20 74 68 65 0a 2a 2a 20 53 51 4c 20  g of the.** SQL 
1f860 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61  statement text a
1f870 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  s the statement 
1f880 66 69 72 73 74 20 62 65 67 69 6e 73 20 65 78 65  first begins exe
1f890 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64  cuting..** ^(Add
1f8a0 69 74 69 6f 6e 61 6c 20 73 71 6c 69 74 65 33 5f  itional sqlite3_
1f8b0 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b  trace() callback
1f8c0 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a  s might occur.**
1f8d0 20 61 73 20 65 61 63 68 20 74 72 69 67 67 65 72   as each trigger
1f8e0 65 64 20 73 75 62 70 72 6f 67 72 61 6d 20 69 73  ed subprogram is
1f8f0 20 65 6e 74 65 72 65 64 2e 20 20 54 68 65 20 63   entered.  The c
1f900 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74 72 69  allbacks for tri
1f910 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e  ggers.** contain
1f920 20 61 20 55 54 46 2d 38 20 53 51 4c 20 63 6f 6d   a UTF-8 SQL com
1f930 6d 65 6e 74 20 74 68 61 74 20 69 64 65 6e 74 69  ment that identi
1f940 66 69 65 73 20 74 68 65 20 74 72 69 67 67 65 72  fies the trigger
1f950 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53  .)^.**.** The [S
1f960 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 49 5a 45  QLITE_TRACE_SIZE
1f970 5f 4c 49 4d 49 54 5d 20 63 6f 6d 70 69 6c 65 2d  _LIMIT] compile-
1f980 74 69 6d 65 20 6f 70 74 69 6f 6e 20 63 61 6e 20  time option can 
1f990 62 65 20 75 73 65 64 20 74 6f 20 6c 69 6d 69 74  be used to limit
1f9a0 0a 2a 2a 20 74 68 65 20 6c 65 6e 67 74 68 20 6f  .** the length o
1f9b0 66 20 5b 62 6f 75 6e 64 20 70 61 72 61 6d 65 74  f [bound paramet
1f9c0 65 72 5d 20 65 78 70 61 6e 73 69 6f 6e 20 69 6e  er] expansion in
1f9d0 20 74 68 65 20 6f 75 74 70 75 74 20 6f 66 20 73   the output of s
1f9e0 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 2e 0a  qlite3_trace()..
1f9f0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62  **.** ^The callb
1fa00 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67  ack function reg
1fa10 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74  istered by sqlit
1fa20 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 69 73 20  e3_profile() is 
1fa30 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61  invoked.** as ea
1fa40 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ch SQL statement
1fa50 20 66 69 6e 69 73 68 65 73 2e 20 20 5e 54 68 65   finishes.  ^The
1fa60 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63   profile callbac
1fa70 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68  k contains.** th
1fa80 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65  e original state
1fa90 6d 65 6e 74 20 74 65 78 74 20 61 6e 64 20 61 6e  ment text and an
1faa0 20 65 73 74 69 6d 61 74 65 20 6f 66 20 77 61 6c   estimate of wal
1fab0 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20  l-clock time.** 
1fac0 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74  of how long that
1fad0 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20   statement took 
1fae0 74 6f 20 72 75 6e 2e 20 20 5e 54 68 65 20 70 72  to run.  ^The pr
1faf0 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 0a 2a  ofile callback.*
1fb00 2a 20 74 69 6d 65 20 69 73 20 69 6e 20 75 6e 69  * time is in uni
1fb10 74 73 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64  ts of nanosecond
1fb20 73 2c 20 68 6f 77 65 76 65 72 20 74 68 65 20 63  s, however the c
1fb30 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74  urrent implement
1fb40 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6f 6e 6c 79  ation.** is only
1fb50 20 63 61 70 61 62 6c 65 20 6f 66 20 6d 69 6c 6c   capable of mill
1fb60 69 73 65 63 6f 6e 64 20 72 65 73 6f 6c 75 74 69  isecond resoluti
1fb70 6f 6e 20 73 6f 20 74 68 65 20 73 69 78 20 6c 65  on so the six le
1fb80 61 73 74 20 73 69 67 6e 69 66 69 63 61 6e 74 0a  ast significant.
1fb90 2a 2a 20 64 69 67 69 74 73 20 69 6e 20 74 68 65  ** digits in the
1fba0 20 74 69 6d 65 20 61 72 65 20 6d 65 61 6e 69 6e   time are meanin
1fbb0 67 6c 65 73 73 2e 20 20 46 75 74 75 72 65 20 76  gless.  Future v
1fbc0 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
1fbd0 65 0a 2a 2a 20 6d 69 67 68 74 20 70 72 6f 76 69  e.** might provi
1fbe0 64 65 20 67 72 65 61 74 65 72 20 72 65 73 6f 6c  de greater resol
1fbf0 75 74 69 6f 6e 20 6f 6e 20 74 68 65 20 70 72 6f  ution on the pro
1fc00 66 69 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20  filer callback. 
1fc10 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   The.** sqlite3_
1fc20 70 72 6f 66 69 6c 65 28 29 20 66 75 6e 63 74 69  profile() functi
1fc30 6f 6e 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64  on is considered
1fc40 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e   experimental an
1fc50 64 20 69 73 0a 2a 2a 20 73 75 62 6a 65 63 74 20  d is.** subject 
1fc60 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 66 75 74  to change in fut
1fc70 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
1fc80 53 51 4c 69 74 65 2e 0a 2a 2f 0a 53 51 4c 49 54  SQLite..*/.SQLIT
1fc90 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69  E_API void *sqli
1fca0 74 65 33 5f 74 72 61 63 65 28 73 71 6c 69 74 65  te3_trace(sqlite
1fcb0 33 2a 2c 20 76 6f 69 64 28 2a 78 54 72 61 63 65  3*, void(*xTrace
1fcc0 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68  )(void*,const ch
1fcd0 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51  ar*), void*);.SQ
1fce0 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f  LITE_API SQLITE_
1fcf0 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 76 6f 69  EXPERIMENTAL voi
1fd00 64 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f 66 69  d *sqlite3_profi
1fd10 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20  le(sqlite3*,.   
1fd20 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65 29 28  void(*xProfile)(
1fd30 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72  void*,const char
1fd40 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  *,sqlite3_uint64
1fd50 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a  ), void*);../*.*
1fd60 2a 20 43 41 50 49 33 52 45 46 3a 20 51 75 65 72  * CAPI3REF: Quer
1fd70 79 20 50 72 6f 67 72 65 73 73 20 43 61 6c 6c 62  y Progress Callb
1fd80 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  acks.**.** ^The 
1fd90 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73  sqlite3_progress
1fda0 5f 68 61 6e 64 6c 65 72 28 44 2c 4e 2c 58 2c 50  _handler(D,N,X,P
1fdb0 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73  ) interface caus
1fdc0 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a  es the callback.
1fdd0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20 74 6f  ** function X to
1fde0 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 65 72 69   be invoked peri
1fdf0 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 6e 67 20  odically during 
1fe00 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 63 61 6c  long running cal
1fe10 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ls to.** [sqlite
1fe20 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69  3_exec()], [sqli
1fe30 74 65 33 5f 73 74 65 70 28 29 5d 20 61 6e 64 20  te3_step()] and 
1fe40 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62  [sqlite3_get_tab
1fe50 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 64 61 74  le()] for.** dat
1fe60 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1fe70 20 44 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20   D.  An example 
1fe80 75 73 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20  use for this.** 
1fe90 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 6f 20  interface is to 
1fea0 6b 65 65 70 20 61 20 47 55 49 20 75 70 64 61 74  keep a GUI updat
1feb0 65 64 20 64 75 72 69 6e 67 20 61 20 6c 61 72 67  ed during a larg
1fec0 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e  e query..**.** ^
1fed0 54 68 65 20 70 61 72 61 6d 65 74 65 72 20 50 20  The parameter P 
1fee0 69 73 20 70 61 73 73 65 64 20 74 68 72 6f 75 67  is passed throug
1fef0 68 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61  h as the only pa
1ff00 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 0a  rameter to the .
1ff10 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  ** callback func
1ff20 74 69 6f 6e 20 58 2e 20 20 5e 54 68 65 20 70 61  tion X.  ^The pa
1ff30 72 61 6d 65 74 65 72 20 4e 20 69 73 20 74 68 65  rameter N is the
1ff40 20 61 70 70 72 6f 78 69 6d 61 74 65 20 6e 75 6d   approximate num
1ff50 62 65 72 20 6f 66 20 0a 2a 2a 20 5b 76 69 72 74  ber of .** [virt
1ff60 75 61 6c 20 6d 61 63 68 69 6e 65 20 69 6e 73 74  ual machine inst
1ff70 72 75 63 74 69 6f 6e 73 5d 20 74 68 61 74 20 61  ructions] that a
1ff80 72 65 20 65 76 61 6c 75 61 74 65 64 20 62 65 74  re evaluated bet
1ff90 77 65 65 6e 20 73 75 63 63 65 73 73 69 76 65 0a  ween successive.
1ffa0 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f  ** invocations o
1ffb0 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 58  f the callback X
1ffc0 2e 20 20 5e 49 66 20 4e 20 69 73 20 6c 65 73 73  .  ^If N is less
1ffd0 20 74 68 61 6e 20 6f 6e 65 20 74 68 65 6e 20 74   than one then t
1ffe0 68 65 20 70 72 6f 67 72 65 73 73 0a 2a 2a 20 68  he progress.** h
1fff0 61 6e 64 6c 65 72 20 69 73 20 64 69 73 61 62 6c  andler is disabl
20000 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20  ed..**.** ^Only 
20010 61 20 73 69 6e 67 6c 65 20 70 72 6f 67 72 65 73  a single progres
20020 73 20 68 61 6e 64 6c 65 72 20 6d 61 79 20 62 65  s handler may be
20030 20 64 65 66 69 6e 65 64 20 61 74 20 6f 6e 65 20   defined at one 
20040 74 69 6d 65 20 70 65 72 0a 2a 2a 20 5b 64 61 74  time per.** [dat
20050 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
20060 5d 3b 20 73 65 74 74 69 6e 67 20 61 20 6e 65 77  ]; setting a new
20070 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
20080 72 20 63 61 6e 63 65 6c 73 20 74 68 65 0a 2a 2a  r cancels the.**
20090 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53 65 74 74   old one.  ^Sett
200a0 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 58 20  ing parameter X 
200b0 74 6f 20 4e 55 4c 4c 20 64 69 73 61 62 6c 65 73  to NULL disables
200c0 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 61   the progress ha
200d0 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 70  ndler..** ^The p
200e0 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20  rogress handler 
200f0 69 73 20 61 6c 73 6f 20 64 69 73 61 62 6c 65 64  is also disabled
20100 20 62 79 20 73 65 74 74 69 6e 67 20 4e 20 74 6f   by setting N to
20110 20 61 20 76 61 6c 75 65 20 6c 65 73 73 0a 2a 2a   a value less.**
20120 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e   than 1..**.** ^
20130 49 66 20 74 68 65 20 70 72 6f 67 72 65 73 73 20  If the progress 
20140 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
20150 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f   non-zero, the o
20160 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69  peration is.** i
20170 6e 74 65 72 72 75 70 74 65 64 2e 20 20 54 68 69  nterrupted.  Thi
20180 73 20 66 65 61 74 75 72 65 20 63 61 6e 20 62 65  s feature can be
20190 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65   used to impleme
201a0 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22  nt a.** "Cancel"
201b0 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49   button on a GUI
201c0 20 70 72 6f 67 72 65 73 73 20 64 69 61 6c 6f 67   progress dialog
201d0 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20   box..**.** The 
201e0 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
201f0 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e   callback must n
20200 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74  ot do anything t
20210 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a  hat will modify.
20220 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
20230 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20  connection that 
20240 69 6e 76 6f 6b 65 64 20 74 68 65 20 70 72 6f 67  invoked the prog
20250 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a  ress handler..**
20260 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69   Note that [sqli
20270 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
20280 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73  ] and [sqlite3_s
20290 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69  tep()] both modi
202a0 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61  fy their.** data
202b0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
202c0 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67   for the meaning
202d0 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20   of "modify" in 
202e0 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a  this paragraph..
202f0 2a 2a 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  **.*/.SQLITE_API
20300 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 70 72   void sqlite3_pr
20310 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 73  ogress_handler(s
20320 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e  qlite3*, int, in
20330 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69  t(*)(void*), voi
20340 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
20350 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20  3REF: Opening A 
20360 4e 65 77 20 44 61 74 61 62 61 73 65 20 43 6f 6e  New Database Con
20370 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54  nection.**.** ^T
20380 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 70  hese routines op
20390 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 64 61 74  en an SQLite dat
203a0 61 62 61 73 65 20 66 69 6c 65 20 61 73 20 73 70  abase file as sp
203b0 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 0a  ecified by the .
203c0 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75  ** filename argu
203d0 6d 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c 65 6e  ment. ^The filen
203e0 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ame argument is 
203f0 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55  interpreted as U
20400 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69  TF-8 for.** sqli
20410 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73  te3_open() and s
20420 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
20430 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36 20 69   and as UTF-16 i
20440 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74  n the native byt
20450 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20 73  e.** order for s
20460 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e  qlite3_open16().
20470 20 5e 28 41 20 5b 64 61 74 61 62 61 73 65 20 63   ^(A [database c
20480 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c  onnection] handl
20490 65 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20  e is usually.** 
204a0 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 70 44  returned in *ppD
204b0 62 2c 20 65 76 65 6e 20 69 66 20 61 6e 20 65 72  b, even if an er
204c0 72 6f 72 20 6f 63 63 75 72 73 2e 20 20 54 68 65  ror occurs.  The
204d0 20 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e 20   only exception 
204e0 69 73 20 74 68 61 74 0a 2a 2a 20 69 66 20 53 51  is that.** if SQ
204f0 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74  Lite is unable t
20500 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72  o allocate memor
20510 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73  y to hold the [s
20520 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a  qlite3] object,.
20530 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62  ** a NULL will b
20540 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a  e written into *
20550 70 70 44 62 20 69 6e 73 74 65 61 64 20 6f 66 20  ppDb instead of 
20560 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
20570 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62   [sqlite3].** ob
20580 6a 65 63 74 2e 29 5e 20 5e 28 49 66 20 74 68 65  ject.)^ ^(If the
20590 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
205a0 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 72 65 61  ned (and/or crea
205b0 74 65 64 29 20 73 75 63 63 65 73 73 66 75 6c 6c  ted) successfull
205c0 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49  y, then.** [SQLI
205d0 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e  TE_OK] is return
205e0 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61  ed.  Otherwise a
205f0 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  n [error code] i
20600 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 5e 54  s returned.)^ ^T
20610 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  he.** [sqlite3_e
20620 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c  rrmsg()] or [sql
20630 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d  ite3_errmsg16()]
20640 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 65   routines can be
20650 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a   used to obtain.
20660 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61  ** an English la
20670 6e 67 75 61 67 65 20 64 65 73 63 72 69 70 74 69  nguage descripti
20680 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20  on of the error 
20690 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c  following a fail
206a0 75 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66  ure of any.** of
206b0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65   the sqlite3_ope
206c0 6e 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  n() routines..**
206d0 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74  .** ^The default
206e0 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 74 68   encoding for th
206f0 65 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20  e database will 
20700 62 65 20 55 54 46 2d 38 20 69 66 0a 2a 2a 20 73  be UTF-8 if.** s
20710 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72  qlite3_open() or
20720 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
20730 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 6e 64  () is called and
20740 0a 2a 2a 20 55 54 46 2d 31 36 20 69 6e 20 74 68  .** UTF-16 in th
20750 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  e native byte or
20760 64 65 72 20 69 66 20 73 71 6c 69 74 65 33 5f 6f  der if sqlite3_o
20770 70 65 6e 31 36 28 29 20 69 73 20 75 73 65 64 2e  pen16() is used.
20780 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f  .**.** Whether o
20790 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f  r not an error o
207a0 63 63 75 72 73 20 77 68 65 6e 20 69 74 20 69 73  ccurs when it is
207b0 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75 72 63   opened, resourc
207c0 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64  es.** associated
207d0 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62   with the [datab
207e0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
207f0 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62 65  handle should be
20800 20 72 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20   released by.** 
20810 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73  passing it to [s
20820 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20  qlite3_close()] 
20830 77 68 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f  when it is no lo
20840 6e 67 65 72 20 72 65 71 75 69 72 65 64 2e 0a 2a  nger required..*
20850 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
20860 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74 65 72  _open_v2() inter
20870 66 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20  face works like 
20880 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a  sqlite3_open().*
20890 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74  * except that it
208a0 20 61 63 63 65 70 74 73 20 74 77 6f 20 61 64 64   accepts two add
208b0 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65  itional paramete
208c0 72 73 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  rs for additiona
208d0 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65  l control.** ove
208e0 72 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61  r the new databa
208f0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  se connection.  
20900 5e 28 54 68 65 20 66 6c 61 67 73 20 70 61 72 61  ^(The flags para
20910 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69  meter to.** sqli
20920 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 63 61  te3_open_v2() ca
20930 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a  n take one of.**
20940 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74   the following t
20950 68 72 65 65 20 76 61 6c 75 65 73 2c 20 6f 70 74  hree values, opt
20960 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64  ionally combined
20970 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53   with the .** [S
20980 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54  QLITE_OPEN_NOMUT
20990 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45  EX], [SQLITE_OPE
209a0 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53  N_FULLMUTEX], [S
209b0 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45  QLITE_OPEN_SHARE
209c0 44 43 41 43 48 45 5d 2c 0a 2a 2a 20 5b 53 51 4c  DCACHE],.** [SQL
209d0 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45  ITE_OPEN_PRIVATE
209e0 43 41 43 48 45 5d 2c 20 61 6e 64 2f 6f 72 20 5b  CACHE], and/or [
209f0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d  SQLITE_OPEN_URI]
20a00 20 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20   flags:)^.**.** 
20a10 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53  <dl>.** ^(<dt>[S
20a20 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
20a30 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NLY]</dt>.** <dd
20a40 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73  >The database is
20a50 20 6f 70 65 6e 65 64 20 69 6e 20 72 65 61 64 2d   opened in read-
20a60 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20 74  only mode.  If t
20a70 68 65 20 64 61 74 61 62 61 73 65 20 64 6f 65 73  he database does
20a80 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20   not.** already 
20a90 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20  exist, an error 
20aa0 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64  is returned.</dd
20ab0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e  >)^.**.** ^(<dt>
20ac0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
20ad0 44 57 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20  DWRITE]</dt>.** 
20ae0 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65  <dd>The database
20af0 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72   is opened for r
20b00 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69  eading and writi
20b10 6e 67 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20  ng if possible, 
20b20 6f 72 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e  or reading.** on
20b30 6c 79 20 69 66 20 74 68 65 20 66 69 6c 65 20 69  ly if the file i
20b40 73 20 77 72 69 74 65 20 70 72 6f 74 65 63 74 65  s write protecte
20b50 64 20 62 79 20 74 68 65 20 6f 70 65 72 61 74 69  d by the operati
20b60 6e 67 20 73 79 73 74 65 6d 2e 20 20 49 6e 20 65  ng system.  In e
20b70 69 74 68 65 72 0a 2a 2a 20 63 61 73 65 20 74 68  ither.** case th
20b80 65 20 64 61 74 61 62 61 73 65 20 6d 75 73 74 20  e database must 
20b90 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 6f  already exist, o
20ba0 74 68 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f  therwise an erro
20bb0 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f  r is returned.</
20bc0 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64  dd>)^.**.** ^(<d
20bd0 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  t>[SQLITE_OPEN_R
20be0 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c  EADWRITE] | [SQL
20bf0 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d  ITE_OPEN_CREATE]
20c00 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
20c10 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
20c20 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20  ned for reading 
20c30 61 6e 64 20 77 72 69 74 69 6e 67 2c 20 61 6e 64  and writing, and
20c40 20 69 73 20 63 72 65 61 74 65 64 20 69 66 0a 2a   is created if.*
20c50 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c  * it does not al
20c60 72 65 61 64 79 20 65 78 69 73 74 2e 20 54 68 69  ready exist. Thi
20c70 73 20 69 73 20 74 68 65 20 62 65 68 61 76 69 6f  s is the behavio
20c80 72 20 74 68 61 74 20 69 73 20 61 6c 77 61 79 73  r that is always
20c90 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c   used for.** sql
20ca0 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20  ite3_open() and 
20cb0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
20cc0 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c  .</dd>)^.** </dl
20cd0 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33  >.**.** If the 3
20ce0 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
20cf0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
20d00 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20  ) is not one of 
20d10 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69  the.** combinati
20d20 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20  ons shown above 
20d30 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69  optionally combi
20d40 6e 65 64 20 77 69 74 68 20 6f 74 68 65 72 0a 2a  ned with other.*
20d50 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  * [SQLITE_OPEN_R
20d60 45 41 44 4f 4e 4c 59 20 7c 20 53 51 4c 49 54 45  EADONLY | SQLITE
20d70 5f 4f 50 45 4e 5f 2a 20 62 69 74 73 5d 0a 2a 2a  _OPEN_* bits].**
20d80 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
20d90 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  or is undefined.
20da0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b  .**.** ^If the [
20db0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55  SQLITE_OPEN_NOMU
20dc0 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74  TEX] flag is set
20dd0 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  , then the datab
20de0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
20df0 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68 65 20 6d  * opens in the m
20e00 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72  ulti-thread [thr
20e10 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20  eading mode] as 
20e20 6c 6f 6e 67 20 61 73 20 74 68 65 20 73 69 6e 67  long as the sing
20e30 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64  le-thread.** mod
20e40 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 73  e has not been s
20e50 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69  et at compile-ti
20e60 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65  me or start-time
20e70 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53  .  ^If the.** [S
20e80 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d  QLITE_OPEN_FULLM
20e90 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65  UTEX] flag is se
20ea0 74 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  t then the datab
20eb0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f  ase connection o
20ec0 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73  pens.** in the s
20ed0 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61  erialized [threa
20ee0 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73  ding mode] unles
20ef0 73 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 20  s single-thread 
20f00 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  was.** previousl
20f10 79 20 73 65 6c 65 63 74 65 64 20 61 74 20 63 6f  y selected at co
20f20 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74  mpile-time or st
20f30 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68  art-time..** ^Th
20f40 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53  e [SQLITE_OPEN_S
20f50 48 41 52 45 44 43 41 43 48 45 5d 20 66 6c 61 67  HAREDCACHE] flag
20f60 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74 61   causes the data
20f70 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
20f80 74 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c  to be.** eligibl
20f90 65 20 74 6f 20 75 73 65 20 5b 73 68 61 72 65 64  e to use [shared
20fa0 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65   cache mode], re
20fb0 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74  gardless of whet
20fc0 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65  her or not share
20fd0 64 0a 2a 2a 20 63 61 63 68 65 20 69 73 20 65 6e  d.** cache is en
20fe0 61 62 6c 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  abled using [sql
20ff0 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72  ite3_enable_shar
21000 65 64 5f 63 61 63 68 65 28 29 5d 2e 20 20 5e 54  ed_cache()].  ^T
21010 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  he.** [SQLITE_OP
21020 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d  EN_PRIVATECACHE]
21030 20 66 6c 61 67 20 63 61 75 73 65 73 20 74 68 65   flag causes the
21040 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
21050 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70  tion to not.** p
21060 61 72 74 69 63 69 70 61 74 65 20 69 6e 20 5b 73  articipate in [s
21070 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65  hared cache mode
21080 5d 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 20  ] even if it is 
21090 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  enabled..**.** ^
210a0 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  The fourth param
210b0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
210c0 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 74 68 65  open_v2() is the
210d0 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20   name of the.** 
210e0 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
210f0 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65  ject that define
21100 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  s the operating 
21110 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65  system interface
21120 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77   that.** the new
21130 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
21140 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e  tion should use.
21150 20 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68    ^If the fourth
21160 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a   parameter is.**
21170 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
21180 74 68 65 6e 20 74 68 65 20 64 65 66 61 75 6c 74  then the default
21190 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
211a0 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e 0a 2a  bject is used..*
211b0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c  *.** ^If the fil
211c0 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72  ename is ":memor
211d0 79 3a 22 2c 20 74 68 65 6e 20 61 20 70 72 69 76  y:", then a priv
211e0 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 20 69  ate, temporary i
211f0 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73  n-memory databas
21200 65 0a 2a 2a 20 69 73 20 63 72 65 61 74 65 64 20  e.** is created 
21210 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69  for the connecti
21220 6f 6e 2e 20 20 5e 54 68 69 73 20 69 6e 2d 6d 65  on.  ^This in-me
21230 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20 77 69  mory database wi
21240 6c 6c 20 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a  ll vanish when.*
21250 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  * the database c
21260 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f  onnection is clo
21270 73 65 64 2e 20 20 46 75 74 75 72 65 20 76 65 72  sed.  Future ver
21280 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20  sions of SQLite 
21290 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73  might.** make us
212a0 65 20 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c 20  e of additional 
212b0 73 70 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65  special filename
212c0 73 20 74 68 61 74 20 62 65 67 69 6e 20 77 69 74  s that begin wit
212d0 68 20 74 68 65 20 22 3a 22 20 63 68 61 72 61 63  h the ":" charac
212e0 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65  ter..** It is re
212f0 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 77  commended that w
21300 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 66  hen a database f
21310 69 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79  ilename actually
21320 20 64 6f 65 73 20 62 65 67 69 6e 20 77 69 74 68   does begin with
21330 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61 72 61 63  .** a ":" charac
21340 74 65 72 20 79 6f 75 20 73 68 6f 75 6c 64 20 70  ter you should p
21350 72 65 66 69 78 20 74 68 65 20 66 69 6c 65 6e 61  refix the filena
21360 6d 65 20 77 69 74 68 20 61 20 70 61 74 68 6e 61  me with a pathna
21370 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e  me such as.** ".
21380 2f 22 20 74 6f 20 61 76 6f 69 64 20 61 6d 62 69  /" to avoid ambi
21390 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  guity..**.** ^If
213a0 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73   the filename is
213b0 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
213c0 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65  , then a private
213d0 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f  , temporary.** o
213e0 6e 2d 64 69 73 6b 20 64 61 74 61 62 61 73 65 20  n-disk database 
213f0 77 69 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e  will be created.
21400 20 20 5e 54 68 69 73 20 70 72 69 76 61 74 65 20    ^This private 
21410 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65  database will be
21420 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  .** automaticall
21430 79 20 64 65 6c 65 74 65 64 20 61 73 20 73 6f 6f  y deleted as soo
21440 6e 20 61 73 20 74 68 65 20 64 61 74 61 62 61 73  n as the databas
21450 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
21460 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  closed..**.** [[
21470 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 69 6e  URI filenames in
21480 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d   sqlite3_open()]
21490 5d 20 3c 68 33 3e 55 52 49 20 46 69 6c 65 6e 61  ] <h3>URI Filena
214a0 6d 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e  mes</h3>.**.** ^
214b0 49 66 20 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65  If [URI filename
214c0 5d 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e  ] interpretation
214d0 20 69 73 20 65 6e 61 62 6c 65 64 2c 20 61 6e 64   is enabled, and
214e0 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72   the filename ar
214f0 67 75 6d 65 6e 74 0a 2a 2a 20 62 65 67 69 6e 73  gument.** begins
21500 20 77 69 74 68 20 22 66 69 6c 65 3a 22 2c 20 74   with "file:", t
21510 68 65 6e 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  hen the filename
21520 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20   is interpreted 
21530 61 73 20 61 20 55 52 49 2e 20 5e 55 52 49 0a 2a  as a URI. ^URI.*
21540 2a 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72  * filename inter
21550 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61  pretation is ena
21560 62 6c 65 64 20 69 66 20 74 68 65 20 5b 53 51 4c  bled if the [SQL
21570 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c  ITE_OPEN_URI] fl
21580 61 67 20 69 73 0a 2a 2a 20 73 65 74 20 69 6e 20  ag is.** set in 
21590 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d  the fourth argum
215a0 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f  ent to sqlite3_o
215b0 70 65 6e 5f 76 32 28 29 2c 20 6f 72 20 69 66 20  pen_v2(), or if 
215c0 69 74 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65  it has.** been e
215d0 6e 61 62 6c 65 64 20 67 6c 6f 62 61 6c 6c 79 20  nabled globally 
215e0 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54  using the [SQLIT
215f0 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 20 6f 70  E_CONFIG_URI] op
21600 74 69 6f 6e 20 77 69 74 68 20 74 68 65 0a 2a 2a  tion with the.**
21610 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
21620 28 29 5d 20 6d 65 74 68 6f 64 20 6f 72 20 62 79  ()] method or by
21630 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 45   the [SQLITE_USE
21640 5f 55 52 49 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  _URI] compile-ti
21650 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 41 73  me option..** As
21660 20 6f 66 20 53 51 4c 69 74 65 20 76 65 72 73 69   of SQLite versi
21670 6f 6e 20 33 2e 37 2e 37 2c 20 55 52 49 20 66 69  on 3.7.7, URI fi
21680 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74  lename interpret
21690 61 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20  ation is turned 
216a0 6f 66 66 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c  off.** by defaul
216b0 74 2c 20 62 75 74 20 66 75 74 75 72 65 20 72 65  t, but future re
216c0 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
216d0 20 6d 69 67 68 74 20 65 6e 61 62 6c 65 20 55 52   might enable UR
216e0 49 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e  I filename.** in
216f0 74 65 72 70 72 65 74 61 74 69 6f 6e 20 62 79 20  terpretation by 
21700 64 65 66 61 75 6c 74 2e 20 20 53 65 65 20 22 5b  default.  See "[
21710 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 5d 22 20  URI filenames]" 
21720 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  for additional.*
21730 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  * information..*
21740 2a 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d  *.** URI filenam
21750 65 73 20 61 72 65 20 70 61 72 73 65 64 20 61 63  es are parsed ac
21760 63 6f 72 64 69 6e 67 20 74 6f 20 52 46 43 20 33  cording to RFC 3
21770 39 38 36 2e 20 5e 49 66 20 74 68 65 20 55 52 49  986. ^If the URI
21780 20 63 6f 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a 20   contains an.** 
21790 61 75 74 68 6f 72 69 74 79 2c 20 74 68 65 6e 20  authority, then 
217a0 69 74 20 6d 75 73 74 20 62 65 20 65 69 74 68 65  it must be eithe
217b0 72 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  r an empty strin
217c0 67 20 6f 72 20 74 68 65 20 73 74 72 69 6e 67 20  g or the string 
217d0 0a 2a 2a 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2e  .** "localhost".
217e0 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72 69   ^If the authori
217f0 74 79 20 69 73 20 6e 6f 74 20 61 6e 20 65 6d 70  ty is not an emp
21800 74 79 20 73 74 72 69 6e 67 20 6f 72 20 22 6c 6f  ty string or "lo
21810 63 61 6c 68 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a  calhost", an .**
21820 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e   error is return
21830 65 64 20 74 6f 20 74 68 65 20 63 61 6c 6c 65 72  ed to the caller
21840 2e 20 5e 54 68 65 20 66 72 61 67 6d 65 6e 74 20  . ^The fragment 
21850 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55  component of a U
21860 52 49 2c 20 69 66 20 0a 2a 2a 20 70 72 65 73 65  RI, if .** prese
21870 6e 74 2c 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a  nt, is ignored..
21880 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73  **.** ^SQLite us
21890 65 73 20 74 68 65 20 70 61 74 68 20 63 6f 6d 70  es the path comp
218a0 6f 6e 65 6e 74 20 6f 66 20 74 68 65 20 55 52 49  onent of the URI
218b0 20 61 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   as the name of 
218c0 74 68 65 20 64 69 73 6b 20 66 69 6c 65 0a 2a 2a  the disk file.**
218d0 20 77 68 69 63 68 20 63 6f 6e 74 61 69 6e 73 20   which contains 
218e0 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 5e 49  the database. ^I
218f0 66 20 74 68 65 20 70 61 74 68 20 62 65 67 69 6e  f the path begin
21900 73 20 77 69 74 68 20 61 20 27 2f 27 20 63 68 61  s with a '/' cha
21910 72 61 63 74 65 72 2c 20 0a 2a 2a 20 74 68 65 6e  racter, .** then
21920 20 69 74 20 69 73 20 69 6e 74 65 72 70 72 65 74   it is interpret
21930 65 64 20 61 73 20 61 6e 20 61 62 73 6f 6c 75 74  ed as an absolut
21940 65 20 70 61 74 68 2e 20 5e 49 66 20 74 68 65 20  e path. ^If the 
21950 70 61 74 68 20 64 6f 65 73 20 6e 6f 74 20 62 65  path does not be
21960 67 69 6e 20 0a 2a 2a 20 77 69 74 68 20 61 20 27  gin .** with a '
21970 2f 27 20 28 6d 65 61 6e 69 6e 67 20 74 68 61 74  /' (meaning that
21980 20 74 68 65 20 61 75 74 68 6f 72 69 74 79 20 73   the authority s
21990 65 63 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65  ection is omitte
219a0 64 20 66 72 6f 6d 20 74 68 65 20 55 52 49 29 0a  d from the URI).
219b0 2a 2a 20 74 68 65 6e 20 74 68 65 20 70 61 74 68  ** then the path
219c0 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20   is interpreted 
219d0 61 73 20 61 20 72 65 6c 61 74 69 76 65 20 70 61  as a relative pa
219e0 74 68 2e 20 0a 2a 2a 20 5e 4f 6e 20 77 69 6e 64  th. .** ^On wind
219f0 6f 77 73 2c 20 74 68 65 20 66 69 72 73 74 20 63  ows, the first c
21a00 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 6e 20 61  omponent of an a
21a10 62 73 6f 6c 75 74 65 20 70 61 74 68 20 0a 2a 2a  bsolute path .**
21a20 20 69 73 20 61 20 64 72 69 76 65 20 73 70 65 63   is a drive spec
21a30 69 66 69 63 61 74 69 6f 6e 20 28 65 2e 67 2e 20  ification (e.g. 
21a40 22 43 3a 22 29 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 63  "C:")..**.** [[c
21a50 6f 72 65 20 55 52 49 20 71 75 65 72 79 20 70 61  ore URI query pa
21a60 72 61 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20 54 68  rameters]].** Th
21a70 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e  e query componen
21a80 74 20 6f 66 20 61 20 55 52 49 20 6d 61 79 20 63  t of a URI may c
21a90 6f 6e 74 61 69 6e 20 70 61 72 61 6d 65 74 65 72  ontain parameter
21aa0 73 20 74 68 61 74 20 61 72 65 20 69 6e 74 65 72  s that are inter
21ab0 70 72 65 74 65 64 0a 2a 2a 20 65 69 74 68 65 72  preted.** either
21ac0 20 62 79 20 53 51 4c 69 74 65 20 69 74 73 65 6c   by SQLite itsel
21ad0 66 2c 20 6f 72 20 62 79 20 61 20 5b 56 46 53 20  f, or by a [VFS 
21ae0 7c 20 63 75 73 74 6f 6d 20 56 46 53 20 69 6d 70  | custom VFS imp
21af0 6c 65 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a 2a  lementation]..**
21b00 20 53 51 4c 69 74 65 20 69 6e 74 65 72 70 72 65   SQLite interpre
21b10 74 73 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  ts the following
21b20 20 74 68 72 65 65 20 71 75 65 72 79 20 70 61 72   three query par
21b30 61 6d 65 74 65 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ameters:.**.** <
21b40 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62  ul>.**   <li> <b
21b50 3e 76 66 73 3c 2f 62 3e 3a 20 5e 54 68 65 20 22  >vfs</b>: ^The "
21b60 76 66 73 22 20 70 61 72 61 6d 65 74 65 72 20 6d  vfs" parameter m
21b70 61 79 20 62 65 20 75 73 65 64 20 74 6f 20 73 70  ay be used to sp
21b80 65 63 69 66 79 20 74 68 65 20 6e 61 6d 65 20 6f  ecify the name o
21b90 66 0a 2a 2a 20 20 20 20 20 61 20 56 46 53 20 6f  f.**     a VFS o
21ba0 62 6a 65 63 74 20 74 68 61 74 20 70 72 6f 76 69  bject that provi
21bb0 64 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e  des the operatin
21bc0 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61  g system interfa
21bd0 63 65 20 74 68 61 74 20 73 68 6f 75 6c 64 0a 2a  ce that should.*
21be0 2a 20 20 20 20 20 62 65 20 75 73 65 64 20 74 6f  *     be used to
21bf0 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61   access the data
21c00 62 61 73 65 20 66 69 6c 65 20 6f 6e 20 64 69 73  base file on dis
21c10 6b 2e 20 5e 49 66 20 74 68 69 73 20 6f 70 74 69  k. ^If this opti
21c20 6f 6e 20 69 73 20 73 65 74 20 74 6f 0a 2a 2a 20  on is set to.** 
21c30 20 20 20 20 61 6e 20 65 6d 70 74 79 20 73 74 72      an empty str
21c40 69 6e 67 20 74 68 65 20 64 65 66 61 75 6c 74 20  ing the default 
21c50 56 46 53 20 6f 62 6a 65 63 74 20 69 73 20 75 73  VFS object is us
21c60 65 64 2e 20 5e 53 70 65 63 69 66 79 69 6e 67 20  ed. ^Specifying 
21c70 61 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20 20  an unknown.**   
21c80 20 20 56 46 53 20 69 73 20 61 6e 20 65 72 72 6f    VFS is an erro
21c90 72 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f  r. ^If sqlite3_o
21ca0 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64  pen_v2() is used
21cb0 20 61 6e 64 20 74 68 65 20 76 66 73 20 6f 70 74   and the vfs opt
21cc0 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 70 72  ion is.**     pr
21cd0 65 73 65 6e 74 2c 20 74 68 65 6e 20 74 68 65 20  esent, then the 
21ce0 56 46 53 20 73 70 65 63 69 66 69 65 64 20 62 79  VFS specified by
21cf0 20 74 68 65 20 6f 70 74 69 6f 6e 20 74 61 6b 65   the option take
21d00 73 20 70 72 65 63 65 64 65 6e 63 65 20 6f 76 65  s precedence ove
21d10 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 76 61 6c  r.**     the val
21d20 75 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  ue passed as the
21d30 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
21d40 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  r to sqlite3_ope
21d50 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20  n_v2()..**.**   
21d60 3c 6c 69 3e 20 3c 62 3e 6d 6f 64 65 3c 2f 62 3e  <li> <b>mode</b>
21d70 3a 20 5e 28 54 68 65 20 6d 6f 64 65 20 70 61 72  : ^(The mode par
21d80 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73 65  ameter may be se
21d90 74 20 74 6f 20 65 69 74 68 65 72 20 22 72 6f 22  t to either "ro"
21da0 2c 20 22 72 77 22 2c 0a 2a 2a 20 20 20 20 20 22  , "rw",.**     "
21db0 72 77 63 22 2c 20 6f 72 20 22 6d 65 6d 6f 72 79  rwc", or "memory
21dc0 22 2e 20 41 74 74 65 6d 70 74 69 6e 67 20 74 6f  ". Attempting to
21dd0 20 73 65 74 20 69 74 20 74 6f 20 61 6e 79 20 6f   set it to any o
21de0 74 68 65 72 20 76 61 6c 75 65 20 69 73 0a 2a 2a  ther value is.**
21df0 20 20 20 20 20 61 6e 20 65 72 72 6f 72 29 5e 2e       an error)^.
21e00 20 0a 2a 2a 20 20 20 20 20 5e 49 66 20 22 72 6f   .**     ^If "ro
21e10 22 20 69 73 20 73 70 65 63 69 66 69 65 64 2c 20  " is specified, 
21e20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  then the databas
21e30 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20  e is opened for 
21e40 72 65 61 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 20  read-only .**   
21e50 20 20 61 63 63 65 73 73 2c 20 6a 75 73 74 20 61    access, just a
21e60 73 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45  s if the [SQLITE
21e70 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20  _OPEN_READONLY] 
21e80 66 6c 61 67 20 68 61 64 20 62 65 65 6e 20 73 65  flag had been se
21e90 74 20 69 6e 20 74 68 65 20 0a 2a 2a 20 20 20 20  t in the .**    
21ea0 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
21eb0 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
21ec0 76 32 28 29 2e 20 5e 49 66 20 74 68 65 20 6d 6f  v2(). ^If the mo
21ed0 64 65 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74  de option is set
21ee0 20 74 6f 20 0a 2a 2a 20 20 20 20 20 22 72 77 22   to .**     "rw"
21ef0 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  , then the datab
21f00 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f  ase is opened fo
21f10 72 20 72 65 61 64 2d 77 72 69 74 65 20 28 62 75  r read-write (bu
21f20 74 20 6e 6f 74 20 63 72 65 61 74 65 29 20 0a 2a  t not create) .*
21f30 2a 20 20 20 20 20 61 63 63 65 73 73 2c 20 61 73  *     access, as
21f40 20 69 66 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f   if SQLITE_OPEN_
21f50 52 45 41 44 57 52 49 54 45 20 28 62 75 74 20 6e  READWRITE (but n
21f60 6f 74 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  ot SQLITE_OPEN_C
21f70 52 45 41 54 45 29 20 68 61 64 20 0a 2a 2a 20 20  REATE) had .**  
21f80 20 20 20 62 65 65 6e 20 73 65 74 2e 20 5e 56 61     been set. ^Va
21f90 6c 75 65 20 22 72 77 63 22 20 69 73 20 65 71 75  lue "rwc" is equ
21fa0 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69  ivalent to setti
21fb0 6e 67 20 62 6f 74 68 20 0a 2a 2a 20 20 20 20 20  ng both .**     
21fc0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
21fd0 57 52 49 54 45 20 61 6e 64 20 53 51 4c 49 54 45  WRITE and SQLITE
21fe0 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2e 20 20 5e  _OPEN_CREATE.  ^
21ff0 49 66 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69  If the mode opti
22000 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 73 65 74  on is.**     set
22010 20 74 6f 20 22 6d 65 6d 6f 72 79 22 20 74 68 65   to "memory" the
22020 6e 20 61 20 70 75 72 65 20 5b 69 6e 2d 6d 65 6d  n a pure [in-mem
22030 6f 72 79 20 64 61 74 61 62 61 73 65 5d 20 74 68  ory database] th
22040 61 74 20 6e 65 76 65 72 20 72 65 61 64 73 0a 2a  at never reads.*
22050 2a 20 20 20 20 20 6f 72 20 77 72 69 74 65 73 20  *     or writes 
22060 66 72 6f 6d 20 64 69 73 6b 20 69 73 20 75 73 65  from disk is use
22070 64 2e 20 5e 49 74 20 69 73 20 61 6e 20 65 72 72  d. ^It is an err
22080 6f 72 20 74 6f 20 73 70 65 63 69 66 79 20 61 20  or to specify a 
22090 76 61 6c 75 65 20 66 6f 72 0a 2a 2a 20 20 20 20  value for.**    
220a0 20 74 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65   the mode parame
220b0 74 65 72 20 74 68 61 74 20 69 73 20 6c 65 73 73  ter that is less
220c0 20 72 65 73 74 72 69 63 74 69 76 65 20 74 68 61   restrictive tha
220d0 6e 20 74 68 61 74 20 73 70 65 63 69 66 69 65 64  n that specified
220e0 20 62 79 0a 2a 2a 20 20 20 20 20 74 68 65 20 66   by.**     the f
220f0 6c 61 67 73 20 70 61 73 73 65 64 20 69 6e 20 74  lags passed in t
22100 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
22110 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  er to sqlite3_op
22120 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20  en_v2()..**.**  
22130 20 3c 6c 69 3e 20 3c 62 3e 63 61 63 68 65 3c 2f   <li> <b>cache</
22140 62 3e 3a 20 5e 54 68 65 20 63 61 63 68 65 20 70  b>: ^The cache p
22150 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20  arameter may be 
22160 73 65 74 20 74 6f 20 65 69 74 68 65 72 20 22 73  set to either "s
22170 68 61 72 65 64 22 20 6f 72 0a 2a 2a 20 20 20 20  hared" or.**    
22180 20 22 70 72 69 76 61 74 65 22 2e 20 5e 53 65 74   "private". ^Set
22190 74 69 6e 67 20 69 74 20 74 6f 20 22 73 68 61 72  ting it to "shar
221a0 65 64 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e  ed" is equivalen
221b0 74 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65  t to setting the
221c0 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f  .**     SQLITE_O
221d0 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20  PEN_SHAREDCACHE 
221e0 62 69 74 20 69 6e 20 74 68 65 20 66 6c 61 67 73  bit in the flags
221f0 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64   argument passed
22200 20 74 6f 0a 2a 2a 20 20 20 20 20 73 71 6c 69 74   to.**     sqlit
22210 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 53  e3_open_v2(). ^S
22220 65 74 74 69 6e 67 20 74 68 65 20 63 61 63 68 65  etting the cache
22230 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 22 70   parameter to "p
22240 72 69 76 61 74 65 22 20 69 73 20 0a 2a 2a 20 20  rivate" is .**  
22250 20 20 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f     equivalent to
22260 20 73 65 74 74 69 6e 67 20 74 68 65 20 53 51 4c   setting the SQL
22270 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45  ITE_OPEN_PRIVATE
22280 43 41 43 48 45 20 62 69 74 2e 0a 2a 2a 20 20 20  CACHE bit..**   
22290 20 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70    ^If sqlite3_op
222a0 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64 20  en_v2() is used 
222b0 61 6e 64 20 74 68 65 20 22 63 61 63 68 65 22 20  and the "cache" 
222c0 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 72 65  parameter is pre
222d0 73 65 6e 74 20 69 6e 0a 2a 2a 20 20 20 20 20 61  sent in.**     a
222e0 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 2c 20 69   URI filename, i
222f0 74 73 20 76 61 6c 75 65 20 6f 76 65 72 72 69 64  ts value overrid
22300 65 73 20 61 6e 79 20 62 65 68 61 76 69 6f 72 20  es any behavior 
22310 72 65 71 75 65 73 74 65 64 20 62 79 20 73 65 74  requested by set
22320 74 69 6e 67 0a 2a 2a 20 20 20 20 20 53 51 4c 49  ting.**     SQLI
22330 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
22340 41 43 48 45 20 6f 72 20 53 51 4c 49 54 45 5f 4f  ACHE or SQLITE_O
22350 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20  PEN_SHAREDCACHE 
22360 66 6c 61 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  flag..** </ul>.*
22370 2a 0a 2a 2a 20 5e 53 70 65 63 69 66 79 69 6e 67  *.** ^Specifying
22380 20 61 6e 20 75 6e 6b 6e 6f 77 6e 20 70 61 72 61   an unknown para
22390 6d 65 74 65 72 20 69 6e 20 74 68 65 20 71 75 65  meter in the que
223a0 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20  ry component of 
223b0 61 20 55 52 49 20 69 73 20 6e 6f 74 20 61 6e 0a  a URI is not an.
223c0 2a 2a 20 65 72 72 6f 72 2e 20 20 46 75 74 75 72  ** error.  Futur
223d0 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
223e0 4c 69 74 65 20 6d 69 67 68 74 20 75 6e 64 65 72  Lite might under
223f0 73 74 61 6e 64 20 61 64 64 69 74 69 6f 6e 61 6c  stand additional
22400 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65   query.** parame
22410 74 65 72 73 2e 20 20 53 65 65 20 22 5b 71 75 65  ters.  See "[que
22420 72 79 20 70 61 72 61 6d 65 74 65 72 73 20 77 69  ry parameters wi
22430 74 68 20 73 70 65 63 69 61 6c 20 6d 65 61 6e 69  th special meani
22440 6e 67 20 74 6f 20 53 51 4c 69 74 65 5d 22 20 66  ng to SQLite]" f
22450 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c  or.** additional
22460 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
22470 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61  .** [[URI filena
22480 6d 65 20 65 78 61 6d 70 6c 65 73 5d 5d 20 3c 68  me examples]] <h
22490 33 3e 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65  3>URI filename e
224a0 78 61 6d 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a 0a  xamples</h3>.**.
224b0 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72  ** <table border
224c0 3d 22 31 22 20 61 6c 69 67 6e 3d 63 65 6e 74 65  ="1" align=cente
224d0 72 20 63 65 6c 6c 70 61 64 64 69 6e 67 3d 35 3e  r cellpadding=5>
224e0 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 55 52 49  .** <tr><th> URI
224f0 20 66 69 6c 65 6e 61 6d 65 73 20 3c 74 68 3e 20   filenames <th> 
22500 52 65 73 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e 3c  Results.** <tr><
22510 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62  td> file:data.db
22520 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20   <td> .**       
22530 20 20 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65     Open the file
22540 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68   "data.db" in th
22550 65 20 63 75 72 72 65 6e 74 20 64 69 72 65 63 74  e current direct
22560 6f 72 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  ory..** <tr><td>
22570 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64   file:/home/fred
22580 2f 64 61 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a 20  /data.db<br>.** 
22590 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f           file://
225a0 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
225b0 64 62 20 3c 62 72 3e 20 0a 2a 2a 20 20 20 20 20  db <br> .**     
225c0 20 20 20 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63 61       file://loca
225d0 6c 68 6f 73 74 2f 68 6f 6d 65 2f 66 72 65 64 2f  lhost/home/fred/
225e0 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 3c 74 64  data.db <br> <td
225f0 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f  > .**          O
22600 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  pen the database
22610 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65   file "/home/fre
22620 64 2f 64 61 74 61 2e 64 62 22 2e 0a 2a 2a 20 3c  d/data.db"..** <
22630 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f 64  tr><td> file://d
22640 61 72 6b 73 74 61 72 2f 68 6f 6d 65 2f 66 72 65  arkstar/home/fre
22650 64 2f 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a  d/data.db <td> .
22660 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20 65  **          An e
22670 72 72 6f 72 2e 20 22 64 61 72 6b 73 74 61 72 22  rror. "darkstar"
22680 20 69 73 20 6e 6f 74 20 61 20 72 65 63 6f 67 6e   is not a recogn
22690 69 7a 65 64 20 61 75 74 68 6f 72 69 74 79 2e 0a  ized authority..
226a0 2a 2a 20 3c 74 72 3e 3c 74 64 20 73 74 79 6c 65  ** <tr><td style
226b0 3d 22 77 68 69 74 65 2d 73 70 61 63 65 3a 6e 6f  ="white-space:no
226c0 77 72 61 70 22 3e 20 0a 2a 2a 20 20 20 20 20 20  wrap"> .**      
226d0 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f 44      file:///C:/D
226e0 6f 63 75 6d 65 6e 74 73 25 32 30 61 6e 64 25 32  ocuments%20and%2
226f0 30 53 65 74 74 69 6e 67 73 2f 66 72 65 64 2f 44  0Settings/fred/D
22700 65 73 6b 74 6f 70 2f 64 61 74 61 2e 64 62 0a 2a  esktop/data.db.*
22710 2a 20 20 20 20 20 3c 74 64 3e 20 57 69 6e 64 6f  *     <td> Windo
22720 77 73 20 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74 68  ws only: Open th
22730 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22  e file "data.db"
22740 20 6f 6e 20 66 72 65 64 27 73 20 64 65 73 6b 74   on fred's deskt
22750 6f 70 20 6f 6e 20 64 72 69 76 65 0a 2a 2a 20 20  op on drive.**  
22760 20 20 20 20 20 20 20 20 43 3a 2e 20 4e 6f 74 65          C:. Note
22770 20 74 68 61 74 20 74 68 65 20 25 32 30 20 65 73   that the %20 es
22780 63 61 70 69 6e 67 20 69 6e 20 74 68 69 73 20 65  caping in this e
22790 78 61 6d 70 6c 65 20 69 73 20 6e 6f 74 20 73 74  xample is not st
227a0 72 69 63 74 6c 79 20 0a 2a 2a 20 20 20 20 20 20  rictly .**      
227b0 20 20 20 20 6e 65 63 65 73 73 61 72 79 20 2d 20      necessary - 
227c0 73 70 61 63 65 20 63 68 61 72 61 63 74 65 72 73  space characters
227d0 20 63 61 6e 20 62 65 20 75 73 65 64 20 6c 69 74   can be used lit
227e0 65 72 61 6c 6c 79 0a 2a 2a 20 20 20 20 20 20 20  erally.**       
227f0 20 20 20 69 6e 20 55 52 49 20 66 69 6c 65 6e 61     in URI filena
22800 6d 65 73 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  mes..** <tr><td>
22810 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f   file:data.db?mo
22820 64 65 3d 72 6f 26 63 61 63 68 65 3d 70 72 69 76  de=ro&cache=priv
22830 61 74 65 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20  ate <td> .**    
22840 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20        Open file 
22850 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65  "data.db" in the
22860 20 63 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f   current directo
22870 72 79 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79  ry for read-only
22880 20 61 63 63 65 73 73 2e 0a 2a 2a 20 20 20 20 20   access..**     
22890 20 20 20 20 20 52 65 67 61 72 64 6c 65 73 73 20       Regardless 
228a0 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
228b0 74 20 73 68 61 72 65 64 2d 63 61 63 68 65 20 6d  t shared-cache m
228c0 6f 64 65 20 69 73 20 65 6e 61 62 6c 65 64 20 62  ode is enabled b
228d0 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 65  y.**          de
228e0 66 61 75 6c 74 2c 20 75 73 65 20 61 20 70 72 69  fault, use a pri
228f0 76 61 74 65 20 63 61 63 68 65 2e 0a 2a 2a 20 3c  vate cache..** <
22900 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f  tr><td> file:/ho
22910 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3f  me/fred/data.db?
22920 76 66 73 3d 75 6e 69 78 2d 6e 6f 6c 6f 63 6b 20  vfs=unix-nolock 
22930 3c 74 64 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20  <td>.**         
22940 20 4f 70 65 6e 20 66 69 6c 65 20 22 2f 68 6f 6d   Open file "/hom
22950 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e  e/fred/data.db".
22960 20 55 73 65 20 74 68 65 20 73 70 65 63 69 61 6c   Use the special
22970 20 56 46 53 20 22 75 6e 69 78 2d 6e 6f 6c 6f 63   VFS "unix-noloc
22980 6b 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  k"..** <tr><td> 
22990 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64  file:data.db?mod
229a0 65 3d 72 65 61 64 6f 6e 6c 79 20 3c 74 64 3e 20  e=readonly <td> 
229b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20  .**          An 
229c0 65 72 72 6f 72 2e 20 22 72 65 61 64 6f 6e 6c 79  error. "readonly
229d0 22 20 69 73 20 6e 6f 74 20 61 20 76 61 6c 69 64  " is not a valid
229e0 20 6f 70 74 69 6f 6e 20 66 6f 72 20 74 68 65 20   option for the 
229f0 22 6d 6f 64 65 22 20 70 61 72 61 6d 65 74 65 72  "mode" parameter
22a00 2e 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a  ..** </table>.**
22a10 0a 2a 2a 20 5e 55 52 49 20 68 65 78 61 64 65 63  .** ^URI hexadec
22a20 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 75  imal escape sequ
22a30 65 6e 63 65 73 20 28 25 48 48 29 20 61 72 65 20  ences (%HH) are 
22a40 73 75 70 70 6f 72 74 65 64 20 77 69 74 68 69 6e  supported within
22a50 20 74 68 65 20 70 61 74 68 20 61 6e 64 0a 2a 2a   the path and.**
22a60 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74   query component
22a70 73 20 6f 66 20 61 20 55 52 49 2e 20 41 20 68 65  s of a URI. A he
22a80 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65  xadecimal escape
22a90 20 73 65 71 75 65 6e 63 65 20 63 6f 6e 73 69 73   sequence consis
22aa0 74 73 20 6f 66 20 61 0a 2a 2a 20 70 65 72 63 65  ts of a.** perce
22ab0 6e 74 20 73 69 67 6e 20 2d 20 22 25 22 20 2d 20  nt sign - "%" - 
22ac0 66 6f 6c 6c 6f 77 65 64 20 62 79 20 65 78 61 63  followed by exac
22ad0 74 6c 79 20 74 77 6f 20 68 65 78 61 64 65 63 69  tly two hexadeci
22ae0 6d 61 6c 20 64 69 67 69 74 73 20 0a 2a 2a 20 73  mal digits .** s
22af0 70 65 63 69 66 79 69 6e 67 20 61 6e 20 6f 63 74  pecifying an oct
22b00 65 74 20 76 61 6c 75 65 2e 20 5e 42 65 66 6f 72  et value. ^Befor
22b10 65 20 74 68 65 20 70 61 74 68 20 6f 72 20 71 75  e the path or qu
22b20 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f  ery components o
22b30 66 20 61 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e  f a.** URI filen
22b40 61 6d 65 20 61 72 65 20 69 6e 74 65 72 70 72 65  ame are interpre
22b50 74 65 64 2c 20 74 68 65 79 20 61 72 65 20 65 6e  ted, they are en
22b60 63 6f 64 65 64 20 75 73 69 6e 67 20 55 54 46 2d  coded using UTF-
22b70 38 20 61 6e 64 20 61 6c 6c 20 0a 2a 2a 20 68 65  8 and all .** he
22b80 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65  xadecimal escape
22b90 20 73 65 71 75 65 6e 63 65 73 20 72 65 70 6c 61   sequences repla
22ba0 63 65 64 20 62 79 20 61 20 73 69 6e 67 6c 65 20  ced by a single 
22bb0 62 79 74 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20  byte containing 
22bc0 74 68 65 0a 2a 2a 20 63 6f 72 72 65 73 70 6f 6e  the.** correspon
22bd0 64 69 6e 67 20 6f 63 74 65 74 2e 20 49 66 20 74  ding octet. If t
22be0 68 69 73 20 70 72 6f 63 65 73 73 20 67 65 6e 65  his process gene
22bf0 72 61 74 65 73 20 61 6e 20 69 6e 76 61 6c 69 64  rates an invalid
22c00 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 2c   UTF-8 encoding,
22c10 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 73 20  .** the results 
22c20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
22c30 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20  *.** <b>Note to 
22c40 57 69 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f  Windows users:</
22c50 62 3e 20 20 54 68 65 20 65 6e 63 6f 64 69 6e 67  b>  The encoding
22c60 20 75 73 65 64 20 66 6f 72 20 74 68 65 20 66 69   used for the fi
22c70 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a  lename argument.
22c80 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70  ** of sqlite3_op
22c90 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  en() and sqlite3
22ca0 5f 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73 74 20  _open_v2() must 
22cb0 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68  be UTF-8, not wh
22cc0 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61  atever.** codepa
22cd0 67 65 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20  ge is currently 
22ce0 64 65 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61  defined.  Filena
22cf0 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69  mes containing i
22d00 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20  nternational.** 
22d10 63 68 61 72 61 63 74 65 72 73 20 6d 75 73 74 20  characters must 
22d20 62 65 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20  be converted to 
22d30 55 54 46 2d 38 20 70 72 69 6f 72 20 74 6f 20 70  UTF-8 prior to p
22d40 61 73 73 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f  assing them into
22d50 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  .** sqlite3_open
22d60 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  () or sqlite3_op
22d70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c  en_v2()..**.** <
22d80 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77  b>Note to Window
22d90 73 20 52 75 6e 74 69 6d 65 20 75 73 65 72 73 3a  s Runtime users:
22da0 3c 2f 62 3e 20 20 54 68 65 20 74 65 6d 70 6f 72  </b>  The tempor
22db0 61 72 79 20 64 69 72 65 63 74 6f 72 79 20 6d 75  ary directory mu
22dc0 73 74 20 62 65 20 73 65 74 0a 2a 2a 20 70 72 69  st be set.** pri
22dd0 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20 73 71  or to calling sq
22de0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20  lite3_open() or 
22df0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
22e00 29 2e 20 20 4f 74 68 65 72 77 69 73 65 2c 20 76  ).  Otherwise, v
22e10 61 72 69 6f 75 73 0a 2a 2a 20 66 65 61 74 75 72  arious.** featur
22e20 65 73 20 74 68 61 74 20 72 65 71 75 69 72 65 20  es that require 
22e30 74 68 65 20 75 73 65 20 6f 66 20 74 65 6d 70 6f  the use of tempo
22e40 72 61 72 79 20 66 69 6c 65 73 20 6d 61 79 20 66  rary files may f
22e50 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ail..**.** See a
22e60 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 74 65  lso: [sqlite3_te
22e70 6d 70 5f 64 69 72 65 63 74 6f 72 79 5d 0a 2a 2f  mp_directory].*/
22e80 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
22e90 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20  sqlite3_open(.  
22ea0 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65  const char *file
22eb0 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62  name,   /* Datab
22ec0 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54  ase filename (UT
22ed0 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65  F-8) */.  sqlite
22ee0 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20  3 **ppDb        
22ef0 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65    /* OUT: SQLite
22f00 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b   db handle */.);
22f10 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
22f20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a  sqlite3_open16(.
22f30 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69    const void *fi
22f40 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74  lename,   /* Dat
22f50 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28  abase filename (
22f60 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c  UTF-16) */.  sql
22f70 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20  ite3 **ppDb     
22f80 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c       /* OUT: SQL
22f90 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f  ite db handle */
22fa0 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .);.SQLITE_API i
22fb0 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  nt sqlite3_open_
22fc0 76 32 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  v2(.  const char
22fd0 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a   *filename,   /*
22fe0 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   Database filena
22ff0 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20  me (UTF-8) */.  
23000 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c 20  sqlite3 **ppDb, 
23010 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20          /* OUT: 
23020 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65  SQLite db handle
23030 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c   */.  int flags,
23040 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
23050 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73   Flags */.  cons
23060 74 20 63 68 61 72 20 2a 7a 56 66 73 20 20 20 20  t char *zVfs    
23070 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56      /* Name of V
23080 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65  FS module to use
23090 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.);../*.** CA
230a0 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 56  PI3REF: Obtain V
230b0 61 6c 75 65 73 20 46 6f 72 20 55 52 49 20 50 61  alues For URI Pa
230c0 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 54  rameters.**.** T
230d0 68 65 73 65 20 61 72 65 20 75 74 69 6c 69 74 79  hese are utility
230e0 20 72 6f 75 74 69 6e 65 73 2c 20 75 73 65 66 75   routines, usefu
230f0 6c 20 74 6f 20 56 46 53 20 69 6d 70 6c 65 6d 65  l to VFS impleme
23100 6e 74 61 74 69 6f 6e 73 2c 20 74 68 61 74 20 63  ntations, that c
23110 68 65 63 6b 0a 2a 2a 20 74 6f 20 73 65 65 20 69  heck.** to see i
23120 66 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c  f a database fil
23130 65 20 77 61 73 20 61 20 55 52 49 20 74 68 61 74  e was a URI that
23140 20 63 6f 6e 74 61 69 6e 65 64 20 61 20 73 70 65   contained a spe
23150 63 69 66 69 63 20 71 75 65 72 79 20 0a 2a 2a 20  cific query .** 
23160 70 61 72 61 6d 65 74 65 72 2c 20 61 6e 64 20 69  parameter, and i
23170 66 20 73 6f 20 6f 62 74 61 69 6e 73 20 74 68 65  f so obtains the
23180 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20 71   value of that q
23190 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 2e 0a  uery parameter..
231a0 2a 2a 0a 2a 2a 20 49 66 20 46 20 69 73 20 74 68  **.** If F is th
231b0 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e  e database filen
231c0 61 6d 65 20 70 6f 69 6e 74 65 72 20 70 61 73 73  ame pointer pass
231d0 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65  ed into the xOpe
231e0 6e 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 0a 2a  n() method of .*
231f0 2a 20 61 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  * a VFS implemen
23200 74 61 74 69 6f 6e 20 77 68 65 6e 20 74 68 65 20  tation when the 
23210 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20  flags parameter 
23220 74 6f 20 78 4f 70 65 6e 28 29 20 68 61 73 20 6f  to xOpen() has o
23230 6e 65 20 6f 72 20 0a 2a 2a 20 6d 6f 72 65 20 6f  ne or .** more o
23240 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  f the [SQLITE_OP
23250 45 4e 5f 55 52 49 5d 20 6f 72 20 5b 53 51 4c 49  EN_URI] or [SQLI
23260 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d  TE_OPEN_MAIN_DB]
23270 20 62 69 74 73 20 73 65 74 20 61 6e 64 0a 2a 2a   bits set and.**
23280 20 50 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f   P is the name o
23290 66 20 74 68 65 20 71 75 65 72 79 20 70 61 72 61  f the query para
232a0 6d 65 74 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 73  meter, then.** s
232b0 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d  qlite3_uri_param
232c0 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e  eter(F,P) return
232d0 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  s the value of t
232e0 68 65 20 50 0a 2a 2a 20 70 61 72 61 6d 65 74 65  he P.** paramete
232f0 72 20 69 66 20 69 74 20 65 78 69 73 74 73 20 6f  r if it exists o
23300 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  r a NULL pointer
23310 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 20 61   if P does not a
23320 70 70 65 61 72 20 61 73 20 61 20 0a 2a 2a 20 71  ppear as a .** q
23330 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f  uery parameter o
23340 6e 20 46 2e 20 20 49 66 20 50 20 69 73 20 61 20  n F.  If P is a 
23350 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20  query parameter 
23360 6f 66 20 46 0a 2a 2a 20 68 61 73 20 6e 6f 20 65  of F.** has no e
23370 78 70 6c 69 63 69 74 20 76 61 6c 75 65 2c 20 74  xplicit value, t
23380 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  hen sqlite3_uri_
23390 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72  parameter(F,P) r
233a0 65 74 75 72 6e 73 0a 2a 2a 20 61 20 70 6f 69 6e  eturns.** a poin
233b0 74 65 72 20 74 6f 20 61 6e 20 65 6d 70 74 79 20  ter to an empty 
233c0 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68  string..**.** Th
233d0 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f  e sqlite3_uri_bo
233e0 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75  olean(F,P,B) rou
233f0 74 69 6e 65 20 61 73 73 75 6d 65 73 20 74 68 61  tine assumes tha
23400 74 20 50 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e  t P is a boolean
23410 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 61 6e  .** parameter an
23420 64 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28  d returns true (
23430 31 29 20 6f 72 20 66 61 6c 73 65 20 28 30 29 20  1) or false (0) 
23440 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 74 68 65  according to the
23450 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 50 2e 20   value.** of P. 
23460 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69   The sqlite3_uri
23470 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20  _boolean(F,P,B) 
23480 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
23490 74 72 75 65 20 28 31 29 20 69 66 20 74 68 65 0a  true (1) if the.
234a0 2a 2a 20 76 61 6c 75 65 20 6f 66 20 71 75 65 72  ** value of quer
234b0 79 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 73  y parameter P is
234c0 20 6f 6e 65 20 6f 66 20 22 79 65 73 22 2c 20 22   one of "yes", "
234d0 74 72 75 65 22 2c 20 6f 72 20 22 6f 6e 22 20 69  true", or "on" i
234e0 6e 20 61 6e 79 0a 2a 2a 20 63 61 73 65 20 6f 72  n any.** case or
234f0 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 62 65   if the value be
23500 67 69 6e 73 20 77 69 74 68 20 61 20 6e 6f 6e 2d  gins with a non-
23510 7a 65 72 6f 20 6e 75 6d 62 65 72 2e 20 20 54 68  zero number.  Th
23520 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72  e .** sqlite3_ur
23530 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29  i_boolean(F,P,B)
23540 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
23550 73 20 66 61 6c 73 65 20 28 30 29 20 69 66 20 74  s false (0) if t
23560 68 65 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 71  he value of.** q
23570 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 50  uery parameter P
23580 20 69 73 20 6f 6e 65 20 6f 66 20 22 6e 6f 22 2c   is one of "no",
23590 20 22 66 61 6c 73 65 22 2c 20 6f 72 20 22 6f 66   "false", or "of
235a0 66 22 20 69 6e 20 61 6e 79 20 63 61 73 65 20 6f  f" in any case o
235b0 72 0a 2a 2a 20 69 66 20 74 68 65 20 76 61 6c 75  r.** if the valu
235c0 65 20 62 65 67 69 6e 73 20 77 69 74 68 20 61 20  e begins with a 
235d0 6e 75 6d 65 72 69 63 20 7a 65 72 6f 2e 20 20 49  numeric zero.  I
235e0 66 20 50 20 69 73 20 6e 6f 74 20 61 20 71 75 65  f P is not a que
235f0 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  ry.** parameter 
23600 6f 6e 20 46 20 6f 72 20 69 66 20 74 68 65 20 76  on F or if the v
23610 61 6c 75 65 20 6f 66 20 50 20 69 73 20 64 6f 65  alue of P is doe
23620 73 20 6e 6f 74 20 6d 61 74 63 68 20 61 6e 79 20  s not match any 
23630 6f 66 20 74 68 65 0a 2a 2a 20 61 62 6f 76 65 2c  of the.** above,
23640 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72   then sqlite3_ur
23650 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29  i_boolean(F,P,B)
23660 20 72 65 74 75 72 6e 73 20 28 42 21 3d 30 29 2e   returns (B!=0).
23670 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
23680 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 46 2c 50  e3_uri_int64(F,P
23690 2c 44 29 20 72 6f 75 74 69 6e 65 20 63 6f 6e 76  ,D) routine conv
236a0 65 72 74 73 20 74 68 65 20 76 61 6c 75 65 20 6f  erts the value o
236b0 66 20 50 20 69 6e 74 6f 20 61 0a 2a 2a 20 36 34  f P into a.** 64
236c0 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
236d0 67 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20  ger and returns 
236e0 74 68 61 74 20 69 6e 74 65 67 65 72 2c 20 6f 72  that integer, or
236f0 20 44 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74   D if P does not
23700 0a 2a 2a 20 65 78 69 73 74 2e 20 20 49 66 20 74  .** exist.  If t
23710 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69 73  he value of P is
23720 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72   something other
23730 20 74 68 61 6e 20 61 6e 20 69 6e 74 65 67 65 72   than an integer
23740 2c 20 74 68 65 6e 0a 2a 2a 20 7a 65 72 6f 20 69  , then.** zero i
23750 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 0a  s returned..** .
23760 2a 2a 20 49 66 20 46 20 69 73 20 61 20 4e 55 4c  ** If F is a NUL
23770 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20  L pointer, then 
23780 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61  sqlite3_uri_para
23790 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72  meter(F,P) retur
237a0 6e 73 20 4e 55 4c 4c 20 61 6e 64 0a 2a 2a 20 73  ns NULL and.** s
237b0 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65  qlite3_uri_boole
237c0 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 72 6e  an(F,P,B) return
237d0 73 20 42 2e 20 20 49 66 20 46 20 69 73 20 6e 6f  s B.  If F is no
237e0 74 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  t a NULL pointer
237f0 20 61 6e 64 0a 2a 2a 20 69 73 20 6e 6f 74 20 61   and.** is not a
23800 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 70   database file p
23810 61 74 68 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20  athname pointer 
23820 74 68 61 74 20 53 51 4c 69 74 65 20 70 61 73 73  that SQLite pass
23830 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65  ed into the xOpe
23840 6e 0a 2a 2a 20 56 46 53 20 6d 65 74 68 6f 64 2c  n.** VFS method,
23850 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
23860 6f 72 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69  or of this routi
23870 6e 65 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20  ne is undefined 
23880 61 6e 64 20 70 72 6f 62 61 62 6c 79 0a 2a 2a 20  and probably.** 
23890 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2f 0a  undesirable..*/.
238a0 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
238b0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 75   char *sqlite3_u
238c0 72 69 5f 70 61 72 61 6d 65 74 65 72 28 63 6f 6e  ri_parameter(con
238d0 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61  st char *zFilena
238e0 6d 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  me, const char *
238f0 7a 50 61 72 61 6d 29 3b 0a 53 51 4c 49 54 45 5f  zParam);.SQLITE_
23900 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
23910 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 63 6f 6e 73  uri_boolean(cons
23920 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20 63  t char *zFile, c
23930 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61  onst char *zPara
23940 6d 2c 20 69 6e 74 20 62 44 65 66 61 75 6c 74 29  m, int bDefault)
23950 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c  ;.SQLITE_API sql
23960 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
23970 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 63 6f 6e  e3_uri_int64(con
23980 73 74 20 63 68 61 72 2a 2c 20 63 6f 6e 73 74 20  st char*, const 
23990 63 68 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69  char*, sqlite3_i
239a0 6e 74 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43  nt64);.../*.** C
239b0 41 50 49 33 52 45 46 3a 20 45 72 72 6f 72 20 43  API3REF: Error C
239c0 6f 64 65 73 20 41 6e 64 20 4d 65 73 73 61 67 65  odes And Message
239d0 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
239e0 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69  ite3_errcode() i
239f0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
23a00 20 74 68 65 20 6e 75 6d 65 72 69 63 20 5b 72 65   the numeric [re
23a10 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a  sult code] or.**
23a20 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
23a30 74 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20  t code] for the 
23a40 6d 6f 73 74 20 72 65 63 65 6e 74 20 66 61 69 6c  most recent fail
23a50 65 64 20 73 71 6c 69 74 65 33 5f 2a 20 41 50 49  ed sqlite3_* API
23a60 20 63 61 6c 6c 0a 2a 2a 20 61 73 73 6f 63 69 61   call.** associa
23a70 74 65 64 20 77 69 74 68 20 61 20 5b 64 61 74 61  ted with a [data
23a80 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
23a90 2e 20 49 66 20 61 20 70 72 69 6f 72 20 41 50 49  . If a prior API
23aa0 20 63 61 6c 6c 20 66 61 69 6c 65 64 0a 2a 2a 20   call failed.** 
23ab0 62 75 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63  but the most rec
23ac0 65 6e 74 20 41 50 49 20 63 61 6c 6c 20 73 75 63  ent API call suc
23ad0 63 65 65 64 65 64 2c 20 74 68 65 20 72 65 74 75  ceeded, the retu
23ae0 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 0a 2a 2a  rn value from.**
23af0 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65   sqlite3_errcode
23b00 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  () is undefined.
23b10 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65    ^The sqlite3_e
23b20 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28  xtended_errcode(
23b30 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69  ).** interface i
23b40 73 20 74 68 65 20 73 61 6d 65 20 65 78 63 65 70  s the same excep
23b50 74 20 74 68 61 74 20 69 74 20 61 6c 77 61 79 73  t that it always
23b60 20 72 65 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a   returns the .**
23b70 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
23b80 74 20 63 6f 64 65 5d 20 65 76 65 6e 20 77 68 65  t code] even whe
23b90 6e 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  n extended resul
23ba0 74 20 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64  t codes are.** d
23bb0 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  isabled..**.** ^
23bc0 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 6d  The sqlite3_errm
23bd0 73 67 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  sg() and sqlite3
23be0 5f 65 72 72 6d 73 67 31 36 28 29 20 72 65 74 75  _errmsg16() retu
23bf0 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75  rn English-langu
23c00 61 67 65 0a 2a 2a 20 74 65 78 74 20 74 68 61 74  age.** text that
23c10 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65   describes the e
23c20 72 72 6f 72 2c 20 61 73 20 65 69 74 68 65 72 20  rror, as either 
23c30 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20  UTF-8 or UTF-16 
23c40 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a  respectively..**
23c50 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c   ^(Memory to hol
23c60 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  d the error mess
23c70 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61  age string is ma
23c80 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79  naged internally
23c90 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
23ca0 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65  tion does not ne
23cb0 65 64 20 74 6f 20 77 6f 72 72 79 20 61 62 6f 75  ed to worry abou
23cc0 74 20 66 72 65 65 69 6e 67 20 74 68 65 20 72 65  t freeing the re
23cd0 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72  sult..** However
23ce0 2c 20 74 68 65 20 65 72 72 6f 72 20 73 74 72 69  , the error stri
23cf0 6e 67 20 6d 69 67 68 74 20 62 65 20 6f 76 65 72  ng might be over
23d00 77 72 69 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c  written or deall
23d10 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20 73 75 62  ocated by.** sub
23d20 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
23d30 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e   other SQLite in
23d40 74 65 72 66 61 63 65 20 66 75 6e 63 74 69 6f 6e  terface function
23d50 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  s.)^.**.** ^The 
23d60 73 71 6c 69 74 65 33 5f 65 72 72 73 74 72 28 29  sqlite3_errstr()
23d70 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
23d80 6e 73 20 74 68 65 20 45 6e 67 6c 69 73 68 2d 6c  ns the English-l
23d90 61 6e 67 75 61 67 65 20 74 65 78 74 0a 2a 2a 20  anguage text.** 
23da0 74 68 61 74 20 64 65 73 63 72 69 62 65 73 20 74  that describes t
23db0 68 65 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d  he [result code]
23dc0 2c 20 61 73 20 55 54 46 2d 38 2e 0a 2a 2a 20 5e  , as UTF-8..** ^
23dd0 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20  (Memory to hold 
23de0 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
23df0 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61  e string is mana
23e00 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a  ged internally.*
23e10 2a 20 61 6e 64 20 6d 75 73 74 20 6e 6f 74 20 62  * and must not b
23e20 65 20 66 72 65 65 64 20 62 79 20 74 68 65 20 61  e freed by the a
23e30 70 70 6c 69 63 61 74 69 6f 6e 29 5e 2e 0a 2a 2a  pplication)^..**
23e40 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 73 65 72  .** When the ser
23e50 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69  ialized [threadi
23e60 6e 67 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75  ng mode] is in u
23e70 73 65 2c 20 69 74 20 6d 69 67 68 74 20 62 65 20  se, it might be 
23e80 74 68 65 0a 2a 2a 20 63 61 73 65 20 74 68 61 74  the.** case that
23e90 20 61 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20   a second error 
23ea0 6f 63 63 75 72 73 20 6f 6e 20 61 20 73 65 70 61  occurs on a sepa
23eb0 72 61 74 65 20 74 68 72 65 61 64 20 69 6e 20 62  rate thread in b
23ec0 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69  etween.** the ti
23ed0 6d 65 20 6f 66 20 74 68 65 20 66 69 72 73 74 20  me of the first 
23ee0 65 72 72 6f 72 20 61 6e 64 20 74 68 65 20 63 61  error and the ca
23ef0 6c 6c 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65  ll to these inte
23f00 72 66 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20  rfaces..** When 
23f10 74 68 61 74 20 68 61 70 70 65 6e 73 2c 20 74 68  that happens, th
23f20 65 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 77  e second error w
23f30 69 6c 6c 20 62 65 20 72 65 70 6f 72 74 65 64 20  ill be reported 
23f40 73 69 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20 69  since these.** i
23f50 6e 74 65 72 66 61 63 65 73 20 61 6c 77 61 79 73  nterfaces always
23f60 20 72 65 70 6f 72 74 20 74 68 65 20 6d 6f 73 74   report the most
23f70 20 72 65 63 65 6e 74 20 72 65 73 75 6c 74 2e 20   recent result. 
23f80 20 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69   To avoid.** thi
23f90 73 2c 20 65 61 63 68 20 74 68 72 65 61 64 20 63  s, each thread c
23fa0 61 6e 20 6f 62 74 61 69 6e 20 65 78 63 6c 75 73  an obtain exclus
23fb0 69 76 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b  ive use of the [
23fc0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
23fd0 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76  ion] D.** by inv
23fe0 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d  oking [sqlite3_m
23ff0 75 74 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c  utex_enter]([sql
24000 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44  ite3_db_mutex](D
24010 29 29 20 62 65 66 6f 72 65 20 62 65 67 69 6e 6e  )) before beginn
24020 69 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20  ing.** to use D 
24030 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71  and invoking [sq
24040 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76  lite3_mutex_leav
24050 65 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d  e]([sqlite3_db_m
24060 75 74 65 78 5d 28 44 29 29 20 61 66 74 65 72 0a  utex](D)) after.
24070 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20  ** all calls to 
24080 74 68 65 20 69 6e 74 65 72 66 61 63 65 73 20 6c  the interfaces l
24090 69 73 74 65 64 20 68 65 72 65 20 61 72 65 20 63  isted here are c
240a0 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  ompleted..**.** 
240b0 49 66 20 61 6e 20 69 6e 74 65 72 66 61 63 65 20  If an interface 
240c0 66 61 69 6c 73 20 77 69 74 68 20 53 51 4c 49 54  fails with SQLIT
240d0 45 5f 4d 49 53 55 53 45 2c 20 74 68 61 74 20 6d  E_MISUSE, that m
240e0 65 61 6e 73 20 74 68 65 20 69 6e 74 65 72 66 61  eans the interfa
240f0 63 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65  ce.** was invoke
24100 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 62 79  d incorrectly by
24110 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
24120 2e 20 20 49 6e 20 74 68 61 74 20 63 61 73 65 2c  .  In that case,
24130 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f   the.** error co
24140 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65 20 6d  de and message m
24150 61 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65  ay or may not be
24160 20 73 65 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f   set..*/.SQLITE_
24170 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
24180 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20  errcode(sqlite3 
24190 2a 64 62 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  *db);.SQLITE_API
241a0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74   int sqlite3_ext
241b0 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 73 71  ended_errcode(sq
241c0 6c 69 74 65 33 20 2a 64 62 29 3b 0a 53 51 4c 49  lite3 *db);.SQLI
241d0 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61  TE_API const cha
241e0 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  r *sqlite3_errms
241f0 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a 53 51 4c  g(sqlite3*);.SQL
24200 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f  ITE_API const vo
24210 69 64 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d  id *sqlite3_errm
24220 73 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a  sg16(sqlite3*);.
24230 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
24240 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65   char *sqlite3_e
24250 72 72 73 74 72 28 69 6e 74 29 3b 0a 0a 2f 2a 0a  rrstr(int);../*.
24260 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c  ** CAPI3REF: SQL
24270 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63   Statement Objec
24280 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  t.** KEYWORDS: {
24290 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
242a0 6e 74 7d 20 7b 70 72 65 70 61 72 65 64 20 73 74  nt} {prepared st
242b0 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20  atements}.**.** 
242c0 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  An instance of t
242d0 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65  his object repre
242e0 73 65 6e 74 73 20 61 20 73 69 6e 67 6c 65 20 53  sents a single S
242f0 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a  QL statement..**
24300 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20   This object is 
24310 76 61 72 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20  variously known 
24320 61 73 20 61 20 22 70 72 65 70 61 72 65 64 20 73  as a "prepared s
24330 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 61 0a 2a  tatement" or a.*
24340 2a 20 22 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20  * "compiled SQL 
24350 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 73 69  statement" or si
24360 6d 70 6c 79 20 61 73 20 61 20 22 73 74 61 74 65  mply as a "state
24370 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ment"..**.** The
24380 20 6c 69 66 65 20 6f 66 20 61 20 73 74 61 74 65   life of a state
24390 6d 65 6e 74 20 6f 62 6a 65 63 74 20 67 6f 65 73  ment object goes
243a0 20 73 6f 6d 65 74 68 69 6e 67 20 6c 69 6b 65 20   something like 
243b0 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e  this:.**.** <ol>
243c0 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 20  .** <li> Create 
243d0 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67  the object using
243e0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
243f0 65 5f 76 32 28 29 5d 20 6f 72 20 61 20 72 65 6c  e_v2()] or a rel
24400 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 66 75 6e  ated.**      fun
24410 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42  ction..** <li> B
24420 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 5b 68  ind values to [h
24430 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 5d 20  ost parameters] 
24440 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65  using the sqlite
24450 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20  3_bind_*().**   
24460 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a     interfaces..*
24470 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20 53  * <li> Run the S
24480 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73  QL by calling [s
24490 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f  qlite3_step()] o
244a0 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73  ne or more times
244b0 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20  ..** <li> Reset 
244c0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 75 73  the statement us
244d0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ing [sqlite3_res
244e0 65 74 28 29 5d 20 74 68 65 6e 20 67 6f 20 62 61  et()] then go ba
244f0 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73 74  ck.**      to st
24500 65 70 20 32 2e 20 20 44 6f 20 74 68 69 73 20 7a  ep 2.  Do this z
24510 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65  ero or more time
24520 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72  s..** <li> Destr
24530 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73  oy the object us
24540 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  ing [sqlite3_fin
24550 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f  alize()]..** </o
24560 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72 20 74  l>.**.** Refer t
24570 6f 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20  o documentation 
24580 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 6d 65  on individual me
24590 74 68 6f 64 73 20 61 62 6f 76 65 20 66 6f 72 20  thods above for 
245a0 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e  additional.** in
245b0 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79  formation..*/.ty
245c0 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
245d0 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69 74 65  ite3_stmt sqlite
245e0 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43  3_stmt;../*.** C
245f0 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d  API3REF: Run-tim
24600 65 20 4c 69 6d 69 74 73 0a 2a 2a 0a 2a 2a 20 5e  e Limits.**.** ^
24610 28 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20  (This interface 
24620 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a 65 20  allows the size 
24630 6f 66 20 76 61 72 69 6f 75 73 20 63 6f 6e 73 74  of various const
24640 72 75 63 74 73 20 74 6f 20 62 65 20 6c 69 6d 69  ructs to be limi
24650 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e  ted.** on a conn
24660 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63  ection by connec
24670 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 54 68 65  tion basis.  The
24680 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
24690 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61   is the.** [data
246a0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
246b0 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 69 73 20   whose limit is 
246c0 74 6f 20 62 65 20 73 65 74 20 6f 72 20 71 75 65  to be set or que
246d0 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65  ried.  The.** se
246e0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
246f0 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69  s one of the [li
24700 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 5d 20  mit categories] 
24710 74 68 61 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a  that define a.**
24720 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74 72   class of constr
24730 75 63 74 73 20 74 6f 20 62 65 20 73 69 7a 65 20  ucts to be size 
24740 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 20 74 68  limited.  The th
24750 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ird parameter is
24760 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69   the.** new limi
24770 74 20 66 6f 72 20 74 68 61 74 20 63 6f 6e 73 74  t for that const
24780 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49  ruct.)^.**.** ^I
24790 66 20 74 68 65 20 6e 65 77 20 6c 69 6d 69 74 20  f the new limit 
247a0 69 73 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75  is a negative nu
247b0 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d 69 74 20  mber, the limit 
247c0 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a  is unchanged..**
247d0 20 5e 28 46 6f 72 20 65 61 63 68 20 6c 69 6d 69   ^(For each limi
247e0 74 20 63 61 74 65 67 6f 72 79 20 53 51 4c 49 54  t category SQLIT
247f0 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45 3c  E_LIMIT_<i>NAME<
24800 2f 69 3e 20 74 68 65 72 65 20 69 73 20 61 20 0a  /i> there is a .
24810 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68 61 72  ** [limits | har
24820 64 20 75 70 70 65 72 20 62 6f 75 6e 64 5d 0a 2a  d upper bound].*
24830 2a 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65  * set at compile
24840 2d 74 69 6d 65 20 62 79 20 61 20 43 20 70 72 65  -time by a C pre
24850 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20  processor macro 
24860 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69 74  called.** [limit
24870 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41 58 5f 3c  s | SQLITE_MAX_<
24880 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20  i>NAME</i>]..** 
24890 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69  (The "_LIMIT_" i
248a0 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 20 63 68  n the name is ch
248b0 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22  anged to "_MAX_"
248c0 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70 74  .))^.** ^Attempt
248d0 73 20 74 6f 20 69 6e 63 72 65 61 73 65 20 61 20  s to increase a 
248e0 6c 69 6d 69 74 20 61 62 6f 76 65 20 69 74 73 20  limit above its 
248f0 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64  hard upper bound
24900 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79   are.** silently
24910 20 74 72 75 6e 63 61 74 65 64 20 74 6f 20 74 68   truncated to th
24920 65 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75  e hard upper bou
24930 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61 72  nd..**.** ^Regar
24940 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72  dless of whether
24950 20 6f 72 20 6e 6f 74 20 74 68 65 20 6c 69 6d 69   or not the limi
24960 74 20 77 61 73 20 63 68 61 6e 67 65 64 2c 20 74  t was changed, t
24970 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  he .** [sqlite3_
24980 6c 69 6d 69 74 28 29 5d 20 69 6e 74 65 72 66 61  limit()] interfa
24990 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 70  ce returns the p
249a0 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 68  rior value of th
249b0 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65 6e  e limit..** ^Hen
249c0 63 65 2c 20 74 6f 20 66 69 6e 64 20 74 68 65 20  ce, to find the 
249d0 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66  current value of
249e0 20 61 20 6c 69 6d 69 74 20 77 69 74 68 6f 75 74   a limit without
249f0 20 63 68 61 6e 67 69 6e 67 20 69 74 2c 0a 2a 2a   changing it,.**
24a00 20 73 69 6d 70 6c 79 20 69 6e 76 6f 6b 65 20 74   simply invoke t
24a10 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 77 69  his interface wi
24a20 74 68 20 74 68 65 20 74 68 69 72 64 20 70 61 72  th the third par
24a30 61 6d 65 74 65 72 20 73 65 74 20 74 6f 20 2d 31  ameter set to -1
24a40 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d 65  ..**.** Run-time
24a50 20 6c 69 6d 69 74 73 20 61 72 65 20 69 6e 74 65   limits are inte
24a60 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20  nded for use in 
24a70 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  applications tha
24a80 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68  t manage.** both
24a90 20 74 68 65 69 72 20 6f 77 6e 20 69 6e 74 65 72   their own inter
24aa0 6e 61 6c 20 64 61 74 61 62 61 73 65 20 61 6e 64  nal database and
24ab0 20 61 6c 73 6f 20 64 61 74 61 62 61 73 65 73 20   also databases 
24ac0 74 68 61 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c  that are control
24ad0 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73  led.** by untrus
24ae0 74 65 64 20 65 78 74 65 72 6e 61 6c 20 73 6f 75  ted external sou
24af0 72 63 65 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c  rces.  An exampl
24b00 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69  e application mi
24b10 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 65 62 20  ght be a.** web 
24b20 62 72 6f 77 73 65 72 20 74 68 61 74 20 68 61 73  browser that has
24b30 20 69 74 73 20 6f 77 6e 20 64 61 74 61 62 61 73   its own databas
24b40 65 73 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 68  es for storing h
24b50 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65  istory and.** se
24b60 70 61 72 61 74 65 20 64 61 74 61 62 61 73 65 73  parate databases
24b70 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a   controlled by J
24b80 61 76 61 53 63 72 69 70 74 20 61 70 70 6c 69 63  avaScript applic
24b90 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65  ations downloade
24ba0 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e 74  d.** off the Int
24bb0 65 72 6e 65 74 2e 20 20 54 68 65 20 69 6e 74 65  ernet.  The inte
24bc0 72 6e 61 6c 20 64 61 74 61 62 61 73 65 73 20 63  rnal databases c
24bd0 61 6e 20 62 65 20 67 69 76 65 6e 20 74 68 65 0a  an be given the.
24be0 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66 61 75 6c  ** large, defaul
24bf0 74 20 6c 69 6d 69 74 73 2e 20 20 44 61 74 61 62  t limits.  Datab
24c00 61 73 65 73 20 6d 61 6e 61 67 65 64 20 62 79 20  ases managed by 
24c10 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73  external sources
24c20 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e   can.** be given
24c30 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69   much smaller li
24c40 6d 69 74 73 20 64 65 73 69 67 6e 65 64 20 74 6f  mits designed to
24c50 20 70 72 65 76 65 6e 74 20 61 20 64 65 6e 69 61   prevent a denia
24c60 6c 20 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a 20  l of service.** 
24c70 61 74 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70  attack.  Develop
24c80 65 72 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 77  ers might also w
24c90 61 6e 74 20 74 6f 20 75 73 65 20 74 68 65 20 5b  ant to use the [
24ca0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
24cb0 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74  orizer()].** int
24cc0 65 72 66 61 63 65 20 74 6f 20 66 75 72 74 68 65  erface to furthe
24cd0 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73  r control untrus
24ce0 74 65 64 20 53 51 4c 2e 20 20 54 68 65 20 73 69  ted SQL.  The si
24cf0 7a 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  ze of the databa
24d00 73 65 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79  se.** created by
24d10 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73 63   an untrusted sc
24d20 72 69 70 74 20 63 61 6e 20 62 65 20 63 6f 6e 74  ript can be cont
24d30 61 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65 0a  ained using the.
24d40 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75  ** [max_page_cou
24d50 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a  nt] [PRAGMA]..**
24d60 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65  .** New run-time
24d70 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65   limit categorie
24d80 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69  s may be added i
24d90 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
24da0 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  s..*/.SQLITE_API
24db0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 6d   int sqlite3_lim
24dc0 69 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  it(sqlite3*, int
24dd0 20 69 64 2c 20 69 6e 74 20 6e 65 77 56 61 6c 29   id, int newVal)
24de0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
24df0 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 6d 69  F: Run-Time Limi
24e00 74 20 43 61 74 65 67 6f 72 69 65 73 0a 2a 2a 20  t Categories.** 
24e10 4b 45 59 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74  KEYWORDS: {limit
24e20 20 63 61 74 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d   category} {*lim
24e30 69 74 20 63 61 74 65 67 6f 72 69 65 73 7d 0a 2a  it categories}.*
24e40 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
24e50 61 6e 74 73 20 64 65 66 69 6e 65 20 76 61 72 69  ants define vari
24e60 6f 75 73 20 70 65 72 66 6f 72 6d 61 6e 63 65 20  ous performance 
24e70 6c 69 6d 69 74 73 0a 2a 2a 20 74 68 61 74 20 63  limits.** that c
24e80 61 6e 20 62 65 20 6c 6f 77 65 72 65 64 20 61 74  an be lowered at
24e90 20 72 75 6e 2d 74 69 6d 65 20 75 73 69 6e 67 20   run-time using 
24ea0 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29  [sqlite3_limit()
24eb0 5d 2e 0a 2a 2a 20 54 68 65 20 73 79 6e 6f 70 73  ]..** The synops
24ec0 69 73 20 6f 66 20 74 68 65 20 6d 65 61 6e 69 6e  is of the meanin
24ed0 67 73 20 6f 66 20 74 68 65 20 76 61 72 69 6f 75  gs of the variou
24ee0 73 20 6c 69 6d 69 74 73 20 69 73 20 73 68 6f 77  s limits is show
24ef0 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69  n below..** Addi
24f00 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69  tional informati
24f10 6f 6e 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20  on is available 
24f20 61 74 20 5b 6c 69 6d 69 74 73 20 7c 20 4c 69 6d  at [limits | Lim
24f30 69 74 73 20 69 6e 20 53 51 4c 69 74 65 5d 2e 0a  its in SQLite]..
24f40 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b  **.** <dl>.** [[
24f50 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e  SQLITE_LIMIT_LEN
24f60 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  GTH]] ^(<dt>SQLI
24f70 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c  TE_LIMIT_LENGTH<
24f80 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
24f90 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20  maximum size of 
24fa0 61 6e 79 20 73 74 72 69 6e 67 20 6f 72 20 42 4c  any string or BL
24fb0 4f 42 20 6f 72 20 74 61 62 6c 65 20 72 6f 77 2c  OB or table row,
24fc0 20 69 6e 20 62 79 74 65 73 2e 3c 64 64 3e 29 5e   in bytes.<dd>)^
24fd0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
24fe0 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48  LIMIT_SQL_LENGTH
24ff0 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
25000 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48  LIMIT_SQL_LENGTH
25010 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
25020 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   maximum length 
25030 6f 66 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  of an SQL statem
25040 65 6e 74 2c 20 69 6e 20 62 79 74 65 73 2e 3c 2f  ent, in bytes.</
25050 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
25060 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d  LITE_LIMIT_COLUM
25070 4e 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  N]] ^(<dt>SQLITE
25080 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64  _LIMIT_COLUMN</d
25090 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
250a0 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
250b0 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61 62  columns in a tab
250c0 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72  le definition or
250d0 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c   in the.** resul
250e0 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45  t set of a [SELE
250f0 43 54 5d 20 6f 72 20 74 68 65 20 6d 61 78 69 6d  CT] or the maxim
25100 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  um number of col
25110 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65 78  umns in an index
25120 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44  .** or in an ORD
25130 45 52 20 42 59 20 6f 72 20 47 52 4f 55 50 20 42  ER BY or GROUP B
25140 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 29 5e  Y clause.</dd>)^
25150 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
25160 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48  LIMIT_EXPR_DEPTH
25170 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
25180 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48  LIMIT_EXPR_DEPTH
25190 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
251a0 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f   maximum depth o
251b0 66 20 74 68 65 20 70 61 72 73 65 20 74 72 65 65  f the parse tree
251c0 20 6f 6e 20 61 6e 79 20 65 78 70 72 65 73 73 69   on any expressi
251d0 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  on.</dd>)^.**.**
251e0 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
251f0 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 5d  COMPOUND_SELECT]
25200 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
25210 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45  IMIT_COMPOUND_SE
25220 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  LECT</dt>.** <dd
25230 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
25240 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20  ber of terms in 
25250 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43  a compound SELEC
25260 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64  T statement.</dd
25270 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
25280 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50  TE_LIMIT_VDBE_OP
25290 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
252a0 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f 64  LIMIT_VDBE_OP</d
252b0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
252c0 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
252d0 69 6e 73 74 72 75 63 74 69 6f 6e 73 20 69 6e 20  instructions in 
252e0 61 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e  a virtual machin
252f0 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 65  e program.** use
25300 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61  d to implement a
25310 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  n SQL statement.
25320 20 20 54 68 69 73 20 6c 69 6d 69 74 20 69 73 20    This limit is 
25330 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 0a 2a 2a  not currently.**
25340 20 65 6e 66 6f 72 63 65 64 2c 20 74 68 6f 75 67   enforced, thoug
25350 68 20 74 68 61 74 20 6d 69 67 68 74 20 62 65 20  h that might be 
25360 61 64 64 65 64 20 69 6e 20 73 6f 6d 65 20 66 75  added in some fu
25370 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a  ture release of.
25380 2a 2a 20 53 51 4c 69 74 65 2e 3c 2f 64 64 3e 29  ** SQLite.</dd>)
25390 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
253a0 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f  _LIMIT_FUNCTION_
253b0 41 52 47 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  ARG]] ^(<dt>SQLI
253c0 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f  TE_LIMIT_FUNCTIO
253d0 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  N_ARG</dt>.** <d
253e0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
253f0 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74  mber of argument
25400 73 20 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e  s on a function.
25410 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
25420 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54  SQLITE_LIMIT_ATT
25430 41 43 48 45 44 5d 5d 20 5e 28 3c 64 74 3e 53 51  ACHED]] ^(<dt>SQ
25440 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43  LITE_LIMIT_ATTAC
25450 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  HED</dt>.** <dd>
25460 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
25470 65 72 20 6f 66 20 5b 41 54 54 41 43 48 20 7c 20  er of [ATTACH | 
25480 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73  attached databas
25490 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  es].)^</dd>.**.*
254a0 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
254b0 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45  _LIKE_PATTERN_LE
254c0 4e 47 54 48 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e  NGTH]].** ^(<dt>
254d0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b  SQLITE_LIMIT_LIK
254e0 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48  E_PATTERN_LENGTH
254f0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
25500 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   maximum length 
25510 6f 66 20 74 68 65 20 70 61 74 74 65 72 6e 20 61  of the pattern a
25520 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b  rgument to the [
25530 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f  LIKE] or.** [GLO
25540 42 5d 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f 64  B] operators.</d
25550 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
25560 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42  ITE_LIMIT_VARIAB
25570 4c 45 5f 4e 55 4d 42 45 52 5d 5d 0a 2a 2a 20 5e  LE_NUMBER]].** ^
25580 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
25590 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45  T_VARIABLE_NUMBE
255a0 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  R</dt>.** <dd>Th
255b0 65 20 6d 61 78 69 6d 75 6d 20 69 6e 64 65 78 20  e maximum index 
255c0 6e 75 6d 62 65 72 20 6f 66 20 61 6e 79 20 5b 70  number of any [p
255d0 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 61 6e 20  arameter] in an 
255e0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 29 5e  SQL statement.)^
255f0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
25600 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45  LIMIT_TRIGGER_DE
25610 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  PTH]] ^(<dt>SQLI
25620 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52  TE_LIMIT_TRIGGER
25630 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  _DEPTH</dt>.** <
25640 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64  dd>The maximum d
25650 65 70 74 68 20 6f 66 20 72 65 63 75 72 73 69 6f  epth of recursio
25660 6e 20 66 6f 72 20 74 72 69 67 67 65 72 73 2e 3c  n for triggers.<
25670 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a  /dd>)^.** </dl>.
25680 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
25690 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20  E_LIMIT_LENGTH  
256a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
256b0 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    0.#define SQLI
256c0 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e  TE_LIMIT_SQL_LEN
256d0 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20  GTH             
256e0 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c     1.#define SQL
256f0 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e  ITE_LIMIT_COLUMN
25700 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
25710 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
25720 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f  LITE_LIMIT_EXPR_
25730 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20  DEPTH           
25740 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53       3.#define S
25750 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50  QLITE_LIMIT_COMP
25760 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 20 20  OUND_SELECT     
25770 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20        4.#define 
25780 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42  SQLITE_LIMIT_VDB
25790 45 5f 4f 50 20 20 20 20 20 20 20 20 20 20 20 20  E_OP            
257a0 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65         5.#define
257b0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55   SQLITE_LIMIT_FU
257c0 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 20 20  NCTION_ARG      
257d0 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e          6.#defin
257e0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41  e SQLITE_LIMIT_A
257f0 54 54 41 43 48 45 44 20 20 20 20 20 20 20 20 20  TTACHED         
25800 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 69           7.#defi
25810 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
25820 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e  LIKE_PATTERN_LEN
25830 47 54 48 20 20 20 20 20 20 20 38 0a 23 64 65 66  GTH       8.#def
25840 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
25850 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52  _VARIABLE_NUMBER
25860 20 20 20 20 20 20 20 20 20 20 20 39 0a 23 64 65             9.#de
25870 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
25880 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 20  T_TRIGGER_DEPTH 
25890 20 20 20 20 20 20 20 20 20 20 20 31 30 0a 0a 2f             10../
258a0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
258b0 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20  ompiling An SQL 
258c0 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45 59  Statement.** KEY
258d0 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74 61 74  WORDS: {SQL stat
258e0 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a  ement compiler}.
258f0 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 65  **.** To execute
25900 20 61 6e 20 53 51 4c 20 71 75 65 72 79 2c 20 69   an SQL query, i
25910 74 20 6d 75 73 74 20 66 69 72 73 74 20 62 65 20  t must first be 
25920 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61 20  compiled into a 
25930 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f  byte-code.** pro
25940 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f  gram using one o
25950 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
25960 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
25970 74 20 61 72 67 75 6d 65 6e 74 2c 20 22 64 62 22  t argument, "db"
25980 2c 20 69 73 20 61 20 5b 64 61 74 61 62 61 73 65  , is a [database
25990 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74   connection] obt
259a0 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20  ained from a.** 
259b0 70 72 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c  prior successful
259c0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
259d0 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69  3_open()], [sqli
259e0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6f  te3_open_v2()] o
259f0 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70  r.** [sqlite3_op
25a00 65 6e 31 36 28 29 5d 2e 20 20 54 68 65 20 64 61  en16()].  The da
25a10 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
25a20 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61 76 65 20  n must not have 
25a30 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a  been closed..**.
25a40 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72  ** The second ar
25a50 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20  gument, "zSql", 
25a60 69 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  is the statement
25a70 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c   to be compiled,
25a80 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65   encoded.** as e
25a90 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55  ither UTF-8 or U
25aa0 54 46 2d 31 36 2e 20 20 54 68 65 20 73 71 6c 69  TF-16.  The sqli
25ab0 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 61 6e  te3_prepare() an
25ac0 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  d sqlite3_prepar
25ad0 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72 66  e_v2().** interf
25ae0 61 63 65 73 20 75 73 65 20 55 54 46 2d 38 2c 20  aces use UTF-8, 
25af0 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
25b00 61 72 65 31 36 28 29 20 61 6e 64 20 73 71 6c 69  are16() and sqli
25b10 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
25b20 28 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31 36  ().** use UTF-16
25b30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
25b40 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20 69  nByte argument i
25b50 73 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 6f  s less than zero
25b60 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20 72  , then zSql is r
25b70 65 61 64 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a  ead up to the.**
25b80 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d   first zero term
25b90 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e 42 79 74  inator. ^If nByt
25ba0 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  e is non-negativ
25bb0 65 2c 20 74 68 65 6e 20 69 74 20 69 73 20 74 68  e, then it is th
25bc0 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 6e 75 6d  e maximum.** num
25bd0 62 65 72 20 6f 66 20 20 62 79 74 65 73 20 72 65  ber of  bytes re
25be0 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e  ad from zSql.  ^
25bf0 57 68 65 6e 20 6e 42 79 74 65 20 69 73 20 6e 6f  When nByte is no
25c00 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 0a  n-negative, the.
25c10 2a 2a 20 7a 53 71 6c 20 73 74 72 69 6e 67 20 65  ** zSql string e
25c20 6e 64 73 20 61 74 20 65 69 74 68 65 72 20 74 68  nds at either th
25c30 65 20 66 69 72 73 74 20 27 5c 30 30 30 27 20 6f  e first '\000' o
25c40 72 20 27 5c 75 30 30 30 30 27 20 63 68 61 72 61  r '\u0000' chara
25c50 63 74 65 72 20 6f 72 0a 2a 2a 20 74 68 65 20 6e  cter or.** the n
25c60 42 79 74 65 2d 74 68 20 62 79 74 65 2c 20 77 68  Byte-th byte, wh
25c70 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69  ichever comes fi
25c80 72 73 74 2e 20 49 66 20 74 68 65 20 63 61 6c 6c  rst. If the call
25c90 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20 74 68 61 74  er knows.** that
25ca0 20 74 68 65 20 73 75 70 70 6c 69 65 64 20 73 74   the supplied st
25cb0 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d  ring is nul-term
25cc0 69 6e 61 74 65 64 2c 20 74 68 65 6e 20 74 68 65  inated, then the
25cd0 72 65 20 69 73 20 61 20 73 6d 61 6c 6c 0a 2a 2a  re is a small.**
25ce0 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 61 64 76   performance adv
25cf0 61 6e 74 61 67 65 20 74 6f 20 62 65 20 67 61 69  antage to be gai
25d00 6e 65 64 20 62 79 20 70 61 73 73 69 6e 67 20 61  ned by passing a
25d10 6e 20 6e 42 79 74 65 20 70 61 72 61 6d 65 74 65  n nByte paramete
25d20 72 20 74 68 61 74 0a 2a 2a 20 69 73 20 65 71 75  r that.** is equ
25d30 61 6c 20 74 6f 20 74 68 65 20 6e 75 6d 62 65 72  al to the number
25d40 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
25d50 20 69 6e 70 75 74 20 73 74 72 69 6e 67 20 3c 69   input string <i
25d60 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a  >including</i>.*
25d70 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69 6e  * the nul-termin
25d80 61 74 6f 72 20 62 79 74 65 73 20 61 73 20 74 68  ator bytes as th
25d90 69 73 20 73 61 76 65 73 20 53 51 4c 69 74 65 20  is saves SQLite 
25da0 66 72 6f 6d 20 68 61 76 69 6e 67 20 74 6f 0a 2a  from having to.*
25db0 2a 20 6d 61 6b 65 20 61 20 63 6f 70 79 20 6f 66  * make a copy of
25dc0 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e   the input strin
25dd0 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a 54  g..**.** ^If pzT
25de0 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20  ail is not NULL 
25df0 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73 20  then *pzTail is 
25e00 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f  made to point to
25e10 20 74 68 65 20 66 69 72 73 74 20 62 79 74 65 0a   the first byte.
25e20 2a 2a 20 70 61 73 74 20 74 68 65 20 65 6e 64 20  ** past the end 
25e30 6f 66 20 74 68 65 20 66 69 72 73 74 20 53 51 4c  of the first SQL
25e40 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53   statement in zS
25e50 71 6c 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69  ql.  These routi
25e60 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70  nes only.** comp
25e70 69 6c 65 20 74 68 65 20 66 69 72 73 74 20 73 74  ile the first st
25e80 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c  atement in zSql,
25e90 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c   so *pzTail is l
25ea0 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 0a  eft pointing to.
25eb0 2a 2a 20 77 68 61 74 20 72 65 6d 61 69 6e 73 20  ** what remains 
25ec0 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a  uncompiled..**.*
25ed0 2a 20 5e 2a 70 70 53 74 6d 74 20 69 73 20 6c 65  * ^*ppStmt is le
25ee0 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61  ft pointing to a
25ef0 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70 61   compiled [prepa
25f00 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
25f10 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78  hat can be.** ex
25f20 65 63 75 74 65 64 20 75 73 69 6e 67 20 5b 73 71  ecuted using [sq
25f30 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 20 20  lite3_step()].  
25f40 5e 49 66 20 74 68 65 72 65 20 69 73 20 61 6e 20  ^If there is an 
25f50 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69  error, *ppStmt i
25f60 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c  s set.** to NULL
25f70 2e 20 20 5e 49 66 20 74 68 65 20 69 6e 70 75 74  .  ^If the input
25f80 20 74 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e   text contains n
25f90 6f 20 53 51 4c 20 28 69 66 20 74 68 65 20 69 6e  o SQL (if the in
25fa0 70 75 74 20 69 73 20 61 6e 20 65 6d 70 74 79 0a  put is an empty.
25fb0 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20 61 20 63  ** string or a c
25fc0 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70 70  omment) then *pp
25fd0 53 74 6d 74 20 69 73 20 73 65 74 20 74 6f 20 4e  Stmt is set to N
25fe0 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c  ULL..** The call
25ff0 69 6e 67 20 70 72 6f 63 65 64 75 72 65 20 69 73  ing procedure is
26000 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72   responsible for
26010 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f   deleting the co
26020 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74  mpiled.** SQL st
26030 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73  atement using [s
26040 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
26050 29 5d 20 61 66 74 65 72 20 69 74 20 68 61 73 20  )] after it has 
26060 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74  finished with it
26070 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 6d 61 79 20  ..** ppStmt may 
26080 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a  not be NULL..**.
26090 2a 2a 20 5e 4f 6e 20 73 75 63 63 65 73 73 2c 20  ** ^On success, 
260a0 74 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70  the sqlite3_prep
260b0 61 72 65 28 29 20 66 61 6d 69 6c 79 20 6f 66 20  are() family of 
260c0 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
260d0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20  [SQLITE_OK];.** 
260e0 6f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72  otherwise an [er
260f0 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74  ror code] is ret
26100 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  urned..**.** The
26110 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
26120 5f 76 32 28 29 20 61 6e 64 20 73 71 6c 69 74 65  _v2() and sqlite
26130 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
26140 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 0a   interfaces are.
26150 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66  ** recommended f
26160 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72  or all new progr
26170 61 6d 73 2e 20 54 68 65 20 74 77 6f 20 6f 6c 64  ams. The two old
26180 65 72 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  er interfaces ar
26190 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a 20 66 6f  e retained.** fo
261a0 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70  r backwards comp
261b0 61 74 69 62 69 6c 69 74 79 2c 20 62 75 74 20 74  atibility, but t
261c0 68 65 69 72 20 75 73 65 20 69 73 20 64 69 73 63  heir use is disc
261d0 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e 20  ouraged..** ^In 
261e0 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
261f0 63 65 73 2c 20 74 68 65 20 70 72 65 70 61 72 65  ces, the prepare
26200 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74  d statement.** t
26210 68 61 74 20 69 73 20 72 65 74 75 72 6e 65 64 20  hat is returned 
26220 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74  (the [sqlite3_st
26230 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74  mt] object) cont
26240 61 69 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74  ains a copy of t
26250 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53  he.** original S
26260 51 4c 20 74 65 78 74 2e 20 54 68 69 73 20 63 61  QL text. This ca
26270 75 73 65 73 20 74 68 65 20 5b 73 71 6c 69 74 65  uses the [sqlite
26280 33 5f 73 74 65 70 28 29 5d 20 69 6e 74 65 72 66  3_step()] interf
26290 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65  ace to.** behave
262a0 20 64 69 66 66 65 72 65 6e 74 6c 79 20 69 6e 20   differently in 
262b0 74 68 72 65 65 20 77 61 79 73 3a 0a 2a 2a 0a 2a  three ways:.**.*
262c0 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a  * <ol>.** <li>.*
262d0 2a 20 5e 49 66 20 74 68 65 20 64 61 74 61 62 61  * ^If the databa
262e0 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65  se schema change
262f0 73 2c 20 69 6e 73 74 65 61 64 20 6f 66 20 72 65  s, instead of re
26300 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f  turning [SQLITE_
26310 53 43 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a  SCHEMA] as it.**
26320 20 61 6c 77 61 79 73 20 75 73 65 64 20 74 6f 20   always used to 
26330 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  do, [sqlite3_ste
26340 70 28 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61  p()] will automa
26350 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c  tically recompil
26360 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61  e the SQL.** sta
26370 74 65 6d 65 6e 74 20 61 6e 64 20 74 72 79 20 74  tement and try t
26380 6f 20 72 75 6e 20 69 74 20 61 67 61 69 6e 2e 20  o run it again. 
26390 41 73 20 6d 61 6e 79 20 61 73 20 5b 53 51 4c 49  As many as [SQLI
263a0 54 45 5f 4d 41 58 5f 53 43 48 45 4d 41 5f 52 45  TE_MAX_SCHEMA_RE
263b0 54 52 59 5d 0a 2a 2a 20 72 65 74 72 69 65 73 20  TRY].** retries 
263c0 77 69 6c 6c 20 6f 63 63 75 72 20 62 65 66 6f 72  will occur befor
263d0 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  e sqlite3_step()
263e0 20 67 69 76 65 73 20 75 70 20 61 6e 64 20 72 65   gives up and re
263f0 74 75 72 6e 73 20 61 6e 20 65 72 72 6f 72 2e 0a  turns an error..
26400 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c  ** </li>.**.** <
26410 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61 6e 20  li>.** ^When an 
26420 65 72 72 6f 72 20 6f 63 63 75 72 73 2c 20 5b 73  error occurs, [s
26430 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77  qlite3_step()] w
26440 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f  ill return one o
26450 66 20 74 68 65 20 64 65 74 61 69 6c 65 64 0a 2a  f the detailed.*
26460 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20  * [error codes] 
26470 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72  or [extended err
26480 6f 72 20 63 6f 64 65 73 5d 2e 20 20 5e 54 68 65  or codes].  ^The
26490 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72   legacy behavior
264a0 20 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b 73 71   was that.** [sq
264b0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 6f  lite3_step()] wo
264c0 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20  uld only return 
264d0 61 20 67 65 6e 65 72 69 63 20 5b 53 51 4c 49 54  a generic [SQLIT
264e0 45 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c 74 20  E_ERROR] result 
264f0 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 74 68 65 20  code.** and the 
26500 61 70 70 6c 69 63 61 74 69 6f 6e 20 77 6f 75 6c  application woul
26510 64 20 68 61 76 65 20 74 6f 20 6d 61 6b 65 20 61  d have to make a
26520 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 20   second call to 
26530 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
26540 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 74 6f  ].** in order to
26550 20 66 69 6e 64 20 74 68 65 20 75 6e 64 65 72 6c   find the underl
26560 79 69 6e 67 20 63 61 75 73 65 20 6f 66 20 74 68  ying cause of th
26570 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69 74 68 20  e problem. With 
26580 74 68 65 20 22 76 32 22 20 70 72 65 70 61 72 65  the "v2" prepare
26590 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2c 20  .** interfaces, 
265a0 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 72  the underlying r
265b0 65 61 73 6f 6e 20 66 6f 72 20 74 68 65 20 65 72  eason for the er
265c0 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 20  ror is returned 
265d0 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20  immediately..** 
265e0 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  </li>.**.** <li>
265f0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 70 65 63  .** ^If the spec
26600 69 66 69 63 20 76 61 6c 75 65 20 62 6f 75 6e 64  ific value bound
26610 20 74 6f 20 5b 70 61 72 61 6d 65 74 65 72 20 7c   to [parameter |
26620 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 5d   host parameter]
26630 20 69 6e 20 74 68 65 20 0a 2a 2a 20 57 48 45 52   in the .** WHER
26640 45 20 63 6c 61 75 73 65 20 6d 69 67 68 74 20 69  E clause might i
26650 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 63 68 6f  nfluence the cho
26660 69 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61  ice of query pla
26670 6e 20 66 6f 72 20 61 20 73 74 61 74 65 6d 65 6e  n for a statemen
26680 74 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 73  t,.** then the s
26690 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65  tatement will be
266a0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72   automatically r
266b0 65 63 6f 6d 70 69 6c 65 64 2c 20 61 73 20 69 66  ecompiled, as if
266c0 20 74 68 65 72 65 20 68 61 64 20 62 65 65 6e 20   there had been 
266d0 0a 2a 2a 20 61 20 73 63 68 65 6d 61 20 63 68 61  .** a schema cha
266e0 6e 67 65 2c 20 6f 6e 20 74 68 65 20 66 69 72 73  nge, on the firs
266f0 74 20 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  t  [sqlite3_step
26700 28 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77 69  ()] call followi
26710 6e 67 20 61 6e 79 20 63 68 61 6e 67 65 0a 2a 2a  ng any change.**
26720 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
26730 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 62 69 6e  _bind_text | bin
26740 64 69 6e 67 73 5d 20 6f 66 20 74 68 61 74 20 5b  dings] of that [
26750 70 61 72 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a 20  parameter]. .** 
26760 5e 54 68 65 20 73 70 65 63 69 66 69 63 20 76 61  ^The specific va
26770 6c 75 65 20 6f 66 20 57 48 45 52 45 2d 63 6c 61  lue of WHERE-cla
26780 75 73 65 20 5b 70 61 72 61 6d 65 74 65 72 5d 20  use [parameter] 
26790 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20  might influence 
267a0 74 68 65 20 0a 2a 2a 20 63 68 6f 69 63 65 20 6f  the .** choice o
267b0 66 20 71 75 65 72 79 20 70 6c 61 6e 20 69 66 20  f query plan if 
267c0 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73  the parameter is
267d0 20 74 68 65 20 6c 65 66 74 2d 68 61 6e 64 20 73   the left-hand s
267e0 69 64 65 20 6f 66 20 61 20 5b 4c 49 4b 45 5d 0a  ide of a [LIKE].
267f0 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20 6f 70 65  ** or [GLOB] ope
26800 72 61 74 6f 72 20 6f 72 20 69 66 20 74 68 65 20  rator or if the 
26810 70 61 72 61 6d 65 74 65 72 20 69 73 20 63 6f 6d  parameter is com
26820 70 61 72 65 64 20 74 6f 20 61 6e 20 69 6e 64 65  pared to an inde
26830 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e  xed column.** an
26840 64 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 45 4e  d the [SQLITE_EN
26850 41 42 4c 45 5f 53 54 41 54 33 5d 20 63 6f 6d 70  ABLE_STAT3] comp
26860 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
26870 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 3c  is enabled..** <
26880 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f  /li>.** </ol>.*/
26890 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
268a0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
268b0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
268c0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
268d0 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
268e0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
268f0 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
26900 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
26910 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  -8 encoded */.  
26920 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
26930 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
26940 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
26950 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
26960 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
26970 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
26980 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
26990 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
269a0 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  r **pzTail     /
269b0 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
269c0 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
269d0 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53   of zSql */.);.S
269e0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
269f0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
26a00 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
26a10 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
26a20 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a  atabase handle *
26a30 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
26a40 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53  zSql,       /* S
26a50 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54  QL statement, UT
26a60 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20  F-8 encoded */. 
26a70 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20   int nByte,     
26a80 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
26a90 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53  mum length of zS
26aa0 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a  ql in bytes. */.
26ab0 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a    sqlite3_stmt *
26ac0 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54  *ppStmt,  /* OUT
26ad0 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  : Statement hand
26ae0 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  le */.  const ch
26af0 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20  ar **pzTail     
26b00 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20  /* OUT: Pointer 
26b10 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f  to unused portio
26b20 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a  n of zSql */.);.
26b30 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
26b40 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
26b50 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
26b60 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
26b70 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a  atabase handle *
26b80 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
26b90 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53  zSql,       /* S
26ba0 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54  QL statement, UT
26bb0 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  F-16 encoded */.
26bc0 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
26bd0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
26be0 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
26bf0 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
26c00 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
26c10 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
26c20 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
26c30 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
26c40 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  oid **pzTail    
26c50 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
26c60 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
26c70 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
26c80 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
26c90 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
26ca0 36 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20  6_v2(.  sqlite3 
26cb0 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
26cc0 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64  /* Database hand
26cd0 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  le */.  const vo
26ce0 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20  id *zSql,       
26cf0 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  /* SQL statement
26d00 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64  , UTF-16 encoded
26d10 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
26d20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
26d30 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
26d40 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
26d50 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
26d60 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
26d70 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
26d80 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
26d90 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c  st void **pzTail
26da0 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
26db0 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
26dc0 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
26dd0 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.);../*.** CAPI
26de0 33 52 45 46 3a 20 52 65 74 72 69 65 76 69 6e 67  3REF: Retrieving
26df0 20 53 74 61 74 65 6d 65 6e 74 20 53 51 4c 0a 2a   Statement SQL.*
26e00 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 72  *.** ^This inter
26e10 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64  face can be used
26e20 20 74 6f 20 72 65 74 72 69 65 76 65 20 61 20 73   to retrieve a s
26e30 61 76 65 64 20 63 6f 70 79 20 6f 66 20 74 68 65  aved copy of the
26e40 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20 53 51 4c   original.** SQL
26e50 20 74 65 78 74 20 75 73 65 64 20 74 6f 20 63 72   text used to cr
26e60 65 61 74 65 20 61 20 5b 70 72 65 70 61 72 65 64  eate a [prepared
26e70 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 66 20 74   statement] if t
26e80 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 77 61  hat statement wa
26e90 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 75 73  s.** compiled us
26ea0 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69  ing either [sqli
26eb0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
26ec0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ] or [sqlite3_pr
26ed0 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a  epare16_v2()]..*
26ee0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  /.SQLITE_API con
26ef0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
26f00 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d  _sql(sqlite3_stm
26f10 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
26f20 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65  * CAPI3REF: Dete
26f30 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20  rmine If An SQL 
26f40 53 74 61 74 65 6d 65 6e 74 20 57 72 69 74 65 73  Statement Writes
26f50 20 54 68 65 20 44 61 74 61 62 61 73 65 0a 2a 2a   The Database.**
26f60 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
26f70 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 58  _stmt_readonly(X
26f80 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
26f90 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65  rns true (non-ze
26fa0 72 6f 29 20 69 66 0a 2a 2a 20 61 6e 64 20 6f 6e  ro) if.** and on
26fb0 6c 79 20 69 66 20 74 68 65 20 5b 70 72 65 70 61  ly if the [prepa
26fc0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 58  red statement] X
26fd0 20 6d 61 6b 65 73 20 6e 6f 20 64 69 72 65 63 74   makes no direct
26fe0 20 63 68 61 6e 67 65 73 20 74 6f 0a 2a 2a 20 74   changes to.** t
26ff0 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
27000 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e  e database file.
27010 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
27020 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   [application-de
27030 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
27040 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69 72 74  ons] or.** [virt
27050 75 61 6c 20 74 61 62 6c 65 73 5d 20 6d 69 67 68  ual tables] migh
27060 74 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74  t change the dat
27070 61 62 61 73 65 20 69 6e 64 69 72 65 63 74 6c 79  abase indirectly
27080 20 61 73 20 61 20 73 69 64 65 20 65 66 66 65 63   as a side effec
27090 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72 20 65 78  t.  .** ^(For ex
270a0 61 6d 70 6c 65 2c 20 69 66 20 61 6e 20 61 70 70  ample, if an app
270b0 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 73  lication defines
270c0 20 61 20 66 75 6e 63 74 69 6f 6e 20 22 65 76 61   a function "eva
270d0 6c 28 29 22 20 74 68 61 74 20 0a 2a 2a 20 63 61  l()" that .** ca
270e0 6c 6c 73 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  lls [sqlite3_exe
270f0 63 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 66  c()], then the f
27100 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 20 73 74 61  ollowing SQL sta
27110 74 65 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a 2a 20  tement would.** 
27120 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62  change the datab
27130 61 73 65 20 66 69 6c 65 20 74 68 72 6f 75 67 68  ase file through
27140 20 73 69 64 65 2d 65 66 66 65 63 74 73 3a 0a 2a   side-effects:.*
27150 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
27160 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 53 45 4c  ><pre>.**    SEL
27170 45 43 54 20 65 76 61 6c 28 27 44 45 4c 45 54 45  ECT eval('DELETE
27180 20 46 52 4f 4d 20 74 31 27 29 20 46 52 4f 4d 20   FROM t1') FROM 
27190 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  t2;.** </pre></b
271a0 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
271b0 20 42 75 74 20 62 65 63 61 75 73 65 20 74 68 65   But because the
271c0 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
271d0 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 68 61  ent does not cha
271e0 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65  nge the database
271f0 20 66 69 6c 65 0a 2a 2a 20 64 69 72 65 63 74 6c   file.** directl
27200 79 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  y, sqlite3_stmt_
27210 72 65 61 64 6f 6e 6c 79 28 29 20 77 6f 75 6c 64  readonly() would
27220 20 73 74 69 6c 6c 20 72 65 74 75 72 6e 20 74 72   still return tr
27230 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72 61  ue.)^.**.** ^Tra
27240 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c  nsaction control
27250 20 73 74 61 74 65 6d 65 6e 74 73 20 73 75 63 68   statements such
27260 20 61 73 20 5b 42 45 47 49 4e 5d 2c 20 5b 43 4f   as [BEGIN], [CO
27270 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41 43 4b  MMIT], [ROLLBACK
27280 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f 49 4e 54  ],.** [SAVEPOINT
27290 5d 2c 20 61 6e 64 20 5b 52 45 4c 45 41 53 45 5d  ], and [RELEASE]
272a0 20 63 61 75 73 65 20 73 71 6c 69 74 65 33 5f 73   cause sqlite3_s
272b0 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74  tmt_readonly() t
272c0 6f 20 72 65 74 75 72 6e 20 74 72 75 65 2c 0a 2a  o return true,.*
272d0 2a 20 73 69 6e 63 65 20 74 68 65 20 73 74 61 74  * since the stat
272e0 65 6d 65 6e 74 73 20 74 68 65 6d 73 65 6c 76 65  ements themselve
272f0 73 20 64 6f 20 6e 6f 74 20 61 63 74 75 61 6c 6c  s do not actuall
27300 79 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74  y modify the dat
27310 61 62 61 73 65 20 62 75 74 0a 2a 2a 20 72 61 74  abase but.** rat
27320 68 65 72 20 74 68 65 79 20 63 6f 6e 74 72 6f 6c  her they control
27330 20 74 68 65 20 74 69 6d 69 6e 67 20 6f 66 20 77   the timing of w
27340 68 65 6e 20 6f 74 68 65 72 20 73 74 61 74 65 6d  hen other statem
27350 65 6e 74 73 20 6d 6f 64 69 66 79 20 74 68 65 20  ents modify the 
27360 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 5e  .** database.  ^
27370 54 68 65 20 5b 41 54 54 41 43 48 5d 20 61 6e 64  The [ATTACH] and
27380 20 5b 44 45 54 41 43 48 5d 20 73 74 61 74 65 6d   [DETACH] statem
27390 65 6e 74 73 20 61 6c 73 6f 20 63 61 75 73 65 0a  ents also cause.
273a0 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  ** sqlite3_stmt_
273b0 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65  readonly() to re
273c0 74 75 72 6e 20 74 72 75 65 20 73 69 6e 63 65 2c  turn true since,
273d0 20 77 68 69 6c 65 20 74 68 6f 73 65 20 73 74 61   while those sta
273e0 74 65 6d 65 6e 74 73 0a 2a 2a 20 63 68 61 6e 67  tements.** chang
273f0 65 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74  e the configurat
27400 69 6f 6e 20 6f 66 20 61 20 64 61 74 61 62 61 73  ion of a databas
27410 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74 68  e connection, th
27420 65 79 20 64 6f 20 6e 6f 74 20 6d 61 6b 65 20 0a  ey do not make .
27430 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68  ** changes to th
27440 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
27450 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 73 20   database files 
27460 6f 6e 20 64 69 73 6b 2e 0a 2a 2f 0a 53 51 4c 49  on disk..*/.SQLI
27470 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
27480 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
27490 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
274a0 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
274b0 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e  PI3REF: Determin
274c0 65 20 49 66 20 41 20 50 72 65 70 61 72 65 64 20  e If A Prepared 
274d0 53 74 61 74 65 6d 65 6e 74 20 48 61 73 20 42 65  Statement Has Be
274e0 65 6e 20 52 65 73 65 74 0a 2a 2a 0a 2a 2a 20 5e  en Reset.**.** ^
274f0 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  The sqlite3_stmt
27500 5f 62 75 73 79 28 53 29 20 69 6e 74 65 72 66 61  _busy(S) interfa
27510 63 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20  ce returns true 
27520 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 20 74 68  (non-zero) if th
27530 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
27540 74 61 74 65 6d 65 6e 74 5d 20 53 20 68 61 73 20  tatement] S has 
27550 62 65 65 6e 20 73 74 65 70 70 65 64 20 61 74 20  been stepped at 
27560 6c 65 61 73 74 20 6f 6e 63 65 20 75 73 69 6e 67  least once using
27570 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74   .** [sqlite3_st
27580 65 70 28 53 29 5d 20 62 75 74 20 68 61 73 20 6e  ep(S)] but has n
27590 6f 74 20 72 75 6e 20 74 6f 20 63 6f 6d 70 6c 65  ot run to comple
275a0 74 69 6f 6e 20 61 6e 64 2f 6f 72 20 68 61 73 20  tion and/or has 
275b0 6e 6f 74 20 0a 2a 2a 20 62 65 65 6e 20 72 65 73  not .** been res
275c0 65 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  et using [sqlite
275d0 33 5f 72 65 73 65 74 28 53 29 5d 2e 20 20 5e 54  3_reset(S)].  ^T
275e0 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  he sqlite3_stmt_
275f0 62 75 73 79 28 53 29 0a 2a 2a 20 69 6e 74 65 72  busy(S).** inter
27600 66 61 63 65 20 72 65 74 75 72 6e 73 20 66 61 6c  face returns fal
27610 73 65 20 69 66 20 53 20 69 73 20 61 20 4e 55 4c  se if S is a NUL
27620 4c 20 70 6f 69 6e 74 65 72 2e 20 20 49 66 20 53  L pointer.  If S
27630 20 69 73 20 6e 6f 74 20 61 20 0a 2a 2a 20 4e 55   is not a .** NU
27640 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 69  LL pointer and i
27650 73 20 6e 6f 74 20 61 20 70 6f 69 6e 74 65 72 20  s not a pointer 
27660 74 6f 20 61 20 76 61 6c 69 64 20 5b 70 72 65 70  to a valid [prep
27670 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a  ared statement].
27680 2a 2a 20 6f 62 6a 65 63 74 2c 20 74 68 65 6e 20  ** object, then 
27690 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
276a0 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72  undefined and pr
276b0 6f 62 61 62 6c 79 20 75 6e 64 65 73 69 72 61 62  obably undesirab
276c0 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  le..**.** This i
276d0 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20  nterface can be 
276e0 75 73 65 64 20 69 6e 20 63 6f 6d 62 69 6e 61 74  used in combinat
276f0 69 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78  ion [sqlite3_nex
27700 74 5f 73 74 6d 74 28 29 5d 0a 2a 2a 20 74 6f 20  t_stmt()].** to 
27710 6c 6f 63 61 74 65 20 61 6c 6c 20 70 72 65 70 61  locate all prepa
27720 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 20 61  red statements a
27730 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61  ssociated with a
27740 20 64 61 74 61 62 61 73 65 20 0a 2a 2a 20 63 6f   database .** co
27750 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 61 72  nnection that ar
27760 65 20 69 6e 20 6e 65 65 64 20 6f 66 20 62 65 69  e in need of bei
27770 6e 67 20 72 65 73 65 74 2e 20 20 54 68 69 73 20  ng reset.  This 
27780 63 61 6e 20 62 65 20 75 73 65 64 2c 0a 2a 2a 20  can be used,.** 
27790 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 6e 20  for example, in 
277a0 64 69 61 67 6e 6f 73 74 69 63 20 72 6f 75 74 69  diagnostic routi
277b0 6e 65 73 20 74 6f 20 73 65 61 72 63 68 20 66 6f  nes to search fo
277c0 72 20 70 72 65 70 61 72 65 64 20 0a 2a 2a 20 73  r prepared .** s
277d0 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 61  tatements that a
277e0 72 65 20 68 6f 6c 64 69 6e 67 20 61 20 74 72 61  re holding a tra
277f0 6e 73 61 63 74 69 6f 6e 20 6f 70 65 6e 2e 0a 2a  nsaction open..*
27800 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
27810 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75   sqlite3_stmt_bu
27820 73 79 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  sy(sqlite3_stmt*
27830 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
27840 45 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20  EF: Dynamically 
27850 54 79 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65  Typed Value Obje
27860 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ct.** KEYWORDS: 
27870 7b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  {protected sqlit
27880 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f  e3_value} {unpro
27890 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
278a0 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  alue}.**.** SQLi
278b0 74 65 20 75 73 65 73 20 74 68 65 20 73 71 6c 69  te uses the sqli
278c0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
278d0 20 74 6f 20 72 65 70 72 65 73 65 6e 74 20 61 6c   to represent al
278e0 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74  l values.** that
278f0 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20 69   can be stored i
27900 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62  n a database tab
27910 6c 65 2e 20 53 51 4c 69 74 65 20 75 73 65 73 20  le. SQLite uses 
27920 64 79 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a  dynamic typing.*
27930 2a 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73  * for the values
27940 20 69 74 20 73 74 6f 72 65 73 2e 20 20 5e 56 61   it stores.  ^Va
27950 6c 75 65 73 20 73 74 6f 72 65 64 20 69 6e 20 73  lues stored in s
27960 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
27970 65 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69  ects.** can be i
27980 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e  ntegers, floatin
27990 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20  g point values, 
279a0 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20  strings, BLOBs, 
279b0 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41  or NULL..**.** A
279c0 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  n sqlite3_value 
279d0 6f 62 6a 65 63 74 20 6d 61 79 20 62 65 20 65 69  object may be ei
279e0 74 68 65 72 20 22 70 72 6f 74 65 63 74 65 64 22  ther "protected"
279f0 20 6f 72 20 22 75 6e 70 72 6f 74 65 63 74 65 64   or "unprotected
27a00 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72  "..** Some inter
27a10 66 61 63 65 73 20 72 65 71 75 69 72 65 20 61 20  faces require a 
27a20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
27a30 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65 72 20  3_value.  Other 
27a40 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 77 69  interfaces.** wi
27a50 6c 6c 20 61 63 63 65 70 74 20 65 69 74 68 65 72  ll accept either
27a60 20 61 20 70 72 6f 74 65 63 74 65 64 20 6f 72 20   a protected or 
27a70 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73  an unprotected s
27a80 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a  qlite3_value..**
27a90 20 45 76 65 72 79 20 69 6e 74 65 72 66 61 63 65   Every interface
27aa0 20 74 68 61 74 20 61 63 63 65 70 74 73 20 73 71   that accepts sq
27ab0 6c 69 74 65 33 5f 76 61 6c 75 65 20 61 72 67 75  lite3_value argu
27ac0 6d 65 6e 74 73 20 73 70 65 63 69 66 69 65 73 0a  ments specifies.
27ad0 2a 2a 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  ** whether or no
27ae0 74 20 69 74 20 72 65 71 75 69 72 65 73 20 61 20  t it requires a 
27af0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
27b00 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54  3_value..**.** T
27b10 68 65 20 74 65 72 6d 73 20 22 70 72 6f 74 65 63  he terms "protec
27b20 74 65 64 22 20 61 6e 64 20 22 75 6e 70 72 6f 74  ted" and "unprot
27b30 65 63 74 65 64 22 20 72 65 66 65 72 20 74 6f 20  ected" refer to 
27b40 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a  whether or not.*
27b50 2a 20 61 20 6d 75 74 65 78 20 69 73 20 68 65 6c  * a mutex is hel
27b60 64 2e 20 20 41 6e 20 69 6e 74 65 72 6e 61 6c 20  d.  An internal 
27b70 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f  mutex is held fo
27b80 72 20 61 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a  r a protected.**
27b90 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
27ba0 62 6a 65 63 74 20 62 75 74 20 6e 6f 20 6d 75 74  bject but no mut
27bb0 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61  ex is held for a
27bc0 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a  n unprotected.**
27bd0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
27be0 62 6a 65 63 74 2e 20 20 49 66 20 53 51 4c 69 74  bject.  If SQLit
27bf0 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f  e is compiled to
27c00 20 62 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61   be single-threa
27c10 64 65 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51  ded.** (with [SQ
27c20 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
27c30 30 5d 20 61 6e 64 20 77 69 74 68 20 5b 73 71 6c  0] and with [sql
27c40 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28  ite3_threadsafe(
27c50 29 5d 20 72 65 74 75 72 6e 69 6e 67 20 30 29 0a  )] returning 0).
27c60 2a 2a 20 6f 72 20 69 66 20 53 51 4c 69 74 65 20  ** or if SQLite 
27c70 69 73 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66  is run in one of
27c80 20 72 65 64 75 63 65 64 20 6d 75 74 65 78 20 6d   reduced mutex m
27c90 6f 64 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45  odes .** [SQLITE
27ca0 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
27cb0 52 45 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45  READ] or [SQLITE
27cc0 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
27cd0 45 41 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65  EAD].** then the
27ce0 72 65 20 69 73 20 6e 6f 20 64 69 73 74 69 6e 63  re is no distinc
27cf0 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f  tion between pro
27d00 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f  tected and unpro
27d10 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65  tected.** sqlite
27d20 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20  3_value objects 
27d30 61 6e 64 20 74 68 65 79 20 63 61 6e 20 62 65 20  and they can be 
27d40 75 73 65 64 20 69 6e 74 65 72 63 68 61 6e 67 65  used interchange
27d50 61 62 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a  ably.  However,.
27d60 2a 2a 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63  ** for maximum c
27d70 6f 64 65 20 70 6f 72 74 61 62 69 6c 69 74 79 20  ode portability 
27d80 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  it is recommende
27d90 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69  d that applicati
27da0 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b  ons.** still mak
27db0 65 20 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f  e the distinctio
27dc0 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63  n between protec
27dd0 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63  ted and unprotec
27de0 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  ted.** sqlite3_v
27df0 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 65 76 65  alue objects eve
27e00 6e 20 77 68 65 6e 20 6e 6f 74 20 73 74 72 69 63  n when not stric
27e10 74 6c 79 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a  tly required..**
27e20 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
27e30 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 74  _value objects t
27e40 68 61 74 20 61 72 65 20 70 61 73 73 65 64 20 61  hat are passed a
27e50 73 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 74  s parameters int
27e60 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65  o the.** impleme
27e70 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 61 70 70 6c  ntation of [appl
27e80 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
27e90 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 61  SQL functions] a
27ea0 72 65 20 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a  re protected..**
27eb0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61   ^The sqlite3_va
27ec0 6c 75 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72  lue object retur
27ed0 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74  ned by.** [sqlit
27ee0 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28  e3_column_value(
27ef0 29 5d 20 69 73 20 75 6e 70 72 6f 74 65 63 74 65  )] is unprotecte
27f00 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 74 65  d..** Unprotecte
27f10 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  d sqlite3_value 
27f20 6f 62 6a 65 63 74 73 20 6d 61 79 20 6f 6e 6c 79  objects may only
27f30 20 62 65 20 75 73 65 64 20 77 69 74 68 0a 2a 2a   be used with.**
27f40 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
27f50 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73  _value()] and [s
27f60 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75  qlite3_bind_valu
27f70 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71  e()]..** The [sq
27f80 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62  lite3_value_blob
27f90 20 7c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65   | sqlite3_value
27fa0 5f 74 79 70 65 28 29 5d 20 66 61 6d 69 6c 79 20  _type()] family 
27fb0 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  of.** interfaces
27fc0 20 72 65 71 75 69 72 65 20 70 72 6f 74 65 63 74   require protect
27fd0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
27fe0 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70   objects..*/.typ
27ff0 65 64 65 66 20 73 74 72 75 63 74 20 4d 65 6d 20  edef struct Mem 
28000 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a  sqlite3_value;..
28010 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
28020 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e  SQL Function Con
28030 74 65 78 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a  text Object.**.*
28040 2a 20 54 68 65 20 63 6f 6e 74 65 78 74 20 69 6e  * The context in
28050 20 77 68 69 63 68 20 61 6e 20 53 51 4c 20 66 75   which an SQL fu
28060 6e 63 74 69 6f 6e 20 65 78 65 63 75 74 65 73 20  nction executes 
28070 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a  is stored in an.
28080 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ** sqlite3_conte
28090 78 74 20 6f 62 6a 65 63 74 2e 20 20 5e 41 20 70  xt object.  ^A p
280a0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 73 71 6c  ointer to an sql
280b0 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a  ite3_context obj
280c0 65 63 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73  ect.** is always
280d0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
280e0 20 74 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e   to [application
280f0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
28100 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20  ctions]..** The 
28110 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
28120 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
28130 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
28140 77 69 6c 6c 20 70 61 73 73 20 74 68 69 73 0a 2a  will pass this.*
28150 2a 20 70 6f 69 6e 74 65 72 20 74 68 72 6f 75 67  * pointer throug
28160 68 20 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20  h into calls to 
28170 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
28180 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 72 65  int | sqlite3_re
28190 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  sult()],.** [sql
281a0 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
281b0 6f 6e 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69  ontext()], [sqli
281c0 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d  te3_user_data()]
281d0 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  ,.** [sqlite3_co
281e0 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28  ntext_db_handle(
281f0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65 74  )], [sqlite3_get
28200 5f 61 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20  _auxdata()],.** 
28210 61 6e 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f  and/or [sqlite3_
28220 73 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a  set_auxdata()]..
28230 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
28240 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t sqlite3_contex
28250 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t sqlite3_contex
28260 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  t;../*.** CAPI3R
28270 45 46 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c 75  EF: Binding Valu
28280 65 73 20 54 6f 20 50 72 65 70 61 72 65 64 20 53  es To Prepared S
28290 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59  tatements.** KEY
282a0 57 4f 52 44 53 3a 20 7b 68 6f 73 74 20 70 61 72  WORDS: {host par
282b0 61 6d 65 74 65 72 7d 20 7b 68 6f 73 74 20 70 61  ameter} {host pa
282c0 72 61 6d 65 74 65 72 73 7d 20 7b 68 6f 73 74 20  rameters} {host 
282d0 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a  parameter name}.
282e0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51  ** KEYWORDS: {SQ
282f0 4c 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 53 51  L parameter} {SQ
28300 4c 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 70  L parameters} {p
28310 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67  arameter binding
28320 7d 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 65  }.**.** ^(In the
28330 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
28340 65 78 74 20 69 6e 70 75 74 20 74 6f 20 5b 73 71  ext input to [sq
28350 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
28360 28 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69  ()] and its vari
28370 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c  ants,.** literal
28380 73 20 6d 61 79 20 62 65 20 72 65 70 6c 61 63 65  s may be replace
28390 64 20 62 79 20 61 20 5b 70 61 72 61 6d 65 74 65  d by a [paramete
283a0 72 5d 20 74 68 61 74 20 6d 61 74 63 68 65 73 20  r] that matches 
283b0 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67  one of following
283c0 0a 2a 2a 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a  .** templates:.*
283d0 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
283e0 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e  >  ?.** <li>  ?N
283f0 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56  NN.** <li>  :VVV
28400 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a  .** <li>  @VVV.*
28410 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20  * <li>  $VVV.** 
28420 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74  </ul>.**.** In t
28430 68 65 20 74 65 6d 70 6c 61 74 65 73 20 61 62 6f  he templates abo
28440 76 65 2c 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e  ve, NNN represen
28450 74 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6c 69  ts an integer li
28460 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56  teral,.** and VV
28470 56 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20  V represents an 
28480 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 69 64 65  alphanumeric ide
28490 6e 74 69 66 69 65 72 2e 29 5e 20 20 5e 54 68 65  ntifier.)^  ^The
284a0 20 76 61 6c 75 65 73 20 6f 66 20 74 68 65 73 65   values of these
284b0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20 28  .** parameters (
284c0 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73  also called "hos
284d0 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65  t parameter name
284e0 73 22 20 6f 72 20 22 53 51 4c 20 70 61 72 61 6d  s" or "SQL param
284f0 65 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62  eters").** can b
28500 65 20 73 65 74 20 75 73 69 6e 67 20 74 68 65 20  e set using the 
28510 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
28520 20 72 6f 75 74 69 6e 65 73 20 64 65 66 69 6e 65   routines define
28530 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54  d here..**.** ^T
28540 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
28550 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  t to the sqlite3
28560 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e  _bind_*() routin
28570 65 73 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20  es is always.** 
28580 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
28590 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20   [sqlite3_stmt] 
285a0 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20  object returned 
285b0 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  from.** [sqlite3
285c0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
285d0 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 0a  r its variants..
285e0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e  **.** ^The secon
285f0 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
28600 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 53  e index of the S
28610 51 4c 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  QL parameter to 
28620 62 65 20 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20  be set..** ^The 
28630 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20 70 61 72  leftmost SQL par
28640 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e  ameter has an in
28650 64 65 78 20 6f 66 20 31 2e 20 20 5e 57 68 65 6e  dex of 1.  ^When
28660 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a   the same named.
28670 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  ** SQL parameter
28680 20 69 73 20 75 73 65 64 20 6d 6f 72 65 20 74 68   is used more th
28690 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20  an once, second 
286a0 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 0a 2a  and subsequent.*
286b0 2a 20 6f 63 63 75 72 72 65 6e 63 65 73 20 68 61  * occurrences ha
286c0 76 65 20 74 68 65 20 73 61 6d 65 20 69 6e 64 65  ve the same inde
286d0 78 20 61 73 20 74 68 65 20 66 69 72 73 74 20 6f  x as the first o
286e0 63 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54  ccurrence..** ^T
286f0 68 65 20 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d  he index for nam
28700 65 64 20 70 61 72 61 6d 65 74 65 72 73 20 63 61  ed parameters ca
28710 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75  n be looked up u
28720 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  sing the.** [sql
28730 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
28740 74 65 72 5f 69 6e 64 65 78 28 29 5d 20 41 50 49  ter_index()] API
28750 20 69 66 20 64 65 73 69 72 65 64 2e 20 20 5e 54   if desired.  ^T
28760 68 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20  he index.** for 
28770 22 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65 72  "?NNN" parameter
28780 73 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f  s is the value o
28790 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e  f NNN..** ^The N
287a0 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74 20 62 65  NN value must be
287b0 20 62 65 74 77 65 65 6e 20 31 20 61 6e 64 20 74   between 1 and t
287c0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  he [sqlite3_limi
287d0 74 28 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65  t()].** paramete
287e0 72 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  r [SQLITE_LIMIT_
287f0 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d  VARIABLE_NUMBER]
28800 20 28 64 65 66 61 75 6c 74 20 76 61 6c 75 65 3a   (default value:
28810 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   999)..**.** ^Th
28820 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
28830 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 74 6f   is the value to
28840 20 62 69 6e 64 20 74 6f 20 74 68 65 20 70 61 72   bind to the par
28850 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74  ameter..** ^If t
28860 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
28870 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  er to sqlite3_bi
28880 6e 64 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c  nd_text() or sql
28890 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
288a0 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  ().** or sqlite3
288b0 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20  _bind_blob() is 
288c0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  a NULL pointer t
288d0 68 65 6e 20 74 68 65 20 66 6f 75 72 74 68 20 70  hen the fourth p
288e0 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 73 20 69  arameter.** is i
288f0 67 6e 6f 72 65 64 20 61 6e 64 20 74 68 65 20 65  gnored and the e
28900 6e 64 20 72 65 73 75 6c 74 20 69 73 20 74 68 65  nd result is the
28910 20 73 61 6d 65 20 61 73 20 73 71 6c 69 74 65 33   same as sqlite3
28920 5f 62 69 6e 64 5f 6e 75 6c 6c 28 29 2e 0a 2a 2a  _bind_null()..**
28930 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f 73 65 20 72  .** ^(In those r
28940 6f 75 74 69 6e 65 73 20 74 68 61 74 20 68 61 76  outines that hav
28950 65 20 61 20 66 6f 75 72 74 68 20 61 72 67 75 6d  e a fourth argum
28960 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 65 20 69  ent, its value i
28970 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20  s the.** number 
28980 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  of bytes in the 
28990 70 61 72 61 6d 65 74 65 72 2e 20 20 54 6f 20 62  parameter.  To b
289a0 65 20 63 6c 65 61 72 3a 20 74 68 65 20 76 61 6c  e clear: the val
289b0 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d  ue is the.** num
289c0 62 65 72 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c  ber of <u>bytes<
289d0 2f 75 3e 20 69 6e 20 74 68 65 20 76 61 6c 75 65  /u> in the value
289e0 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72  , not the number
289f0 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 29   of characters.)
28a00 5e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 6f 75  ^.** ^If the fou
28a10 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
28a20 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
28a30 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  xt() or sqlite3_
28a40 62 69 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a  bind_text16().**
28a50 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
28a60 65 6e 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66  en the length of
28a70 20 74 68 65 20 73 74 72 69 6e 67 20 69 73 0a 2a   the string is.*
28a80 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
28a90 62 79 74 65 73 20 75 70 20 74 6f 20 74 68 65 20  bytes up to the 
28aa0 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69  first zero termi
28ab0 6e 61 74 6f 72 2e 0a 2a 2a 20 49 66 20 74 68 65  nator..** If the
28ac0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
28ad0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  r to sqlite3_bin
28ae0 64 5f 62 6c 6f 62 28 29 20 69 73 20 6e 65 67 61  d_blob() is nega
28af0 74 69 76 65 2c 20 74 68 65 6e 0a 2a 2a 20 74 68  tive, then.** th
28b00 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e  e behavior is un
28b10 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 61  defined..** If a
28b20 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 66 6f   non-negative fo
28b30 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
28b40 73 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 71  s provided to sq
28b50 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
28b60 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  ).** or sqlite3_
28b70 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 74 68  bind_text16() th
28b80 65 6e 20 74 68 61 74 20 70 61 72 61 6d 65 74 65  en that paramete
28b90 72 20 6d 75 73 74 20 62 65 20 74 68 65 20 62 79  r must be the by
28ba0 74 65 20 6f 66 66 73 65 74 0a 2a 2a 20 77 68 65  te offset.** whe
28bb0 72 65 20 74 68 65 20 4e 55 4c 20 74 65 72 6d 69  re the NUL termi
28bc0 6e 61 74 6f 72 20 77 6f 75 6c 64 20 6f 63 63 75  nator would occu
28bd0 72 20 61 73 73 75 6d 69 6e 67 20 74 68 65 20 73  r assuming the s
28be0 74 72 69 6e 67 20 77 65 72 65 20 4e 55 4c 0a 2a  tring were NUL.*
28bf0 2a 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 49  * terminated.  I
28c00 66 20 61 6e 79 20 4e 55 4c 20 63 68 61 72 61 63  f any NUL charac
28c10 74 65 72 73 20 6f 63 63 75 72 20 61 74 20 62 79  ters occur at by
28c20 74 65 20 6f 66 66 73 65 74 73 20 6c 65 73 73 20  te offsets less 
28c30 74 68 61 6e 20 0a 2a 2a 20 74 68 65 20 76 61 6c  than .** the val
28c40 75 65 20 6f 66 20 74 68 65 20 66 6f 75 72 74 68  ue of the fourth
28c50 20 70 61 72 61 6d 65 74 65 72 20 74 68 65 6e 20   parameter then 
28c60 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74  the resulting st
28c70 72 69 6e 67 20 76 61 6c 75 65 20 77 69 6c 6c 0a  ring value will.
28c80 2a 2a 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64  ** contain embed
28c90 64 65 64 20 4e 55 4c 73 2e 20 20 54 68 65 20 72  ded NULs.  The r
28ca0 65 73 75 6c 74 20 6f 66 20 65 78 70 72 65 73 73  esult of express
28cb0 69 6f 6e 73 20 69 6e 76 6f 6c 76 69 6e 67 20 73  ions involving s
28cc0 74 72 69 6e 67 73 0a 2a 2a 20 77 69 74 68 20 65  trings.** with e
28cd0 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 69 73 20  mbedded NULs is 
28ce0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
28cf0 20 5e 54 68 65 20 66 69 66 74 68 20 61 72 67 75   ^The fifth argu
28d00 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
28d10 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 20 73 71 6c  bind_blob(), sql
28d20 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29  ite3_bind_text()
28d30 2c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33  , and.** sqlite3
28d40 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 69  _bind_text16() i
28d50 73 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 75  s a destructor u
28d60 73 65 64 20 74 6f 20 64 69 73 70 6f 73 65 20 6f  sed to dispose o
28d70 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a  f the BLOB or.**
28d80 20 73 74 72 69 6e 67 20 61 66 74 65 72 20 53 51   string after SQ
28d90 4c 69 74 65 20 68 61 73 20 66 69 6e 69 73 68 65  Lite has finishe
28da0 64 20 77 69 74 68 20 69 74 2e 20 20 5e 54 68 65  d with it.  ^The
28db0 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 63   destructor is c
28dc0 61 6c 6c 65 64 0a 2a 2a 20 74 6f 20 64 69 73 70  alled.** to disp
28dd0 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20  ose of the BLOB 
28de0 6f 72 20 73 74 72 69 6e 67 20 65 76 65 6e 20 69  or string even i
28df0 66 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 73 71  f the call to sq
28e00 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28  lite3_bind_blob(
28e10 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69  ),.** sqlite3_bi
28e20 6e 64 5f 74 65 78 74 28 29 2c 20 6f 72 20 73 71  nd_text(), or sq
28e30 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
28e40 36 28 29 20 66 61 69 6c 73 2e 20 20 0a 2a 2a 20  6() fails.  .** 
28e50 5e 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72  ^If the fifth ar
28e60 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65  gument is.** the
28e70 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 20 5b   special value [
28e80 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20  SQLITE_STATIC], 
28e90 74 68 65 6e 20 53 51 4c 69 74 65 20 61 73 73 75  then SQLite assu
28ea0 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  mes that the.** 
28eb0 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69  information is i
28ec0 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61  n static, unmana
28ed0 67 65 64 20 73 70 61 63 65 20 61 6e 64 20 64 6f  ged space and do
28ee0 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62  es not need to b
28ef0 65 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20  e freed..** ^If 
28f00 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65  the fifth argume
28f10 6e 74 20 68 61 73 20 74 68 65 20 76 61 6c 75 65  nt has the value
28f20 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45   [SQLITE_TRANSIE
28f30 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c  NT], then.** SQL
28f40 69 74 65 20 6d 61 6b 65 73 20 69 74 73 20 6f 77  ite makes its ow
28f50 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f  n private copy o
28f60 66 20 74 68 65 20 64 61 74 61 20 69 6d 6d 65 64  f the data immed
28f70 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a  iately, before.*
28f80 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  * the sqlite3_bi
28f90 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20 72  nd_*() routine r
28fa0 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  eturns..**.** ^T
28fb0 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
28fc0 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69  zeroblob() routi
28fd0 6e 65 20 62 69 6e 64 73 20 61 20 42 4c 4f 42 20  ne binds a BLOB 
28fe0 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74 68 61 74  of length N that
28ff0 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20 77 69  .** is filled wi
29000 74 68 20 7a 65 72 6f 65 73 2e 20 20 5e 41 20 7a  th zeroes.  ^A z
29010 65 72 6f 62 6c 6f 62 20 75 73 65 73 20 61 20 66  eroblob uses a f
29020 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d  ixed amount of m
29030 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61  emory.** (just a
29040 6e 20 69 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c  n integer to hol
29050 64 20 69 74 73 20 73 69 7a 65 29 20 77 68 69 6c  d its size) whil
29060 65 20 69 74 20 69 73 20 62 65 69 6e 67 20 70 72  e it is being pr
29070 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f  ocessed..** Zero
29080 62 6c 6f 62 73 20 61 72 65 20 69 6e 74 65 6e 64  blobs are intend
29090 65 64 20 74 6f 20 73 65 72 76 65 20 61 73 20 70  ed to serve as p
290a0 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20  laceholders for 
290b0 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63  BLOBs whose.** c
290c0 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74 65 72 20  ontent is later 
290d0 77 72 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a  written using.**
290e0 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f   [sqlite3_blob_o
290f0 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61  pen | incrementa
29100 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74  l BLOB I/O] rout
29110 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61  ines..** ^A nega
29120 74 69 76 65 20 76 61 6c 75 65 20 66 6f 72 20 74  tive value for t
29130 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75  he zeroblob resu
29140 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65  lts in a zero-le
29150 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a  ngth BLOB..**.**
29160 20 5e 49 66 20 61 6e 79 20 6f 66 20 74 68 65 20   ^If any of the 
29170 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
29180 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61   routines are ca
29190 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c  lled with a NULL
291a0 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f 72 20   pointer.** for 
291b0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
291c0 61 74 65 6d 65 6e 74 5d 20 6f 72 20 77 69 74 68  atement] or with
291d0 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74   a prepared stat
291e0 65 6d 65 6e 74 20 66 6f 72 20 77 68 69 63 68 0a  ement for which.
291f0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
29200 28 29 5d 20 68 61 73 20 62 65 65 6e 20 63 61 6c  ()] has been cal
29210 6c 65 64 20 6d 6f 72 65 20 72 65 63 65 6e 74 6c  led more recentl
29220 79 20 74 68 61 6e 20 5b 73 71 6c 69 74 65 33 5f  y than [sqlite3_
29230 72 65 73 65 74 28 29 5d 2c 0a 2a 2a 20 74 68 65  reset()],.** the
29240 6e 20 74 68 65 20 63 61 6c 6c 20 77 69 6c 6c 20  n the call will 
29250 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4d  return [SQLITE_M
29260 49 53 55 53 45 5d 2e 20 20 49 66 20 61 6e 79 20  ISUSE].  If any 
29270 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 28 29 0a  sqlite3_bind_().
29280 2a 2a 20 72 6f 75 74 69 6e 65 20 69 73 20 70 61  ** routine is pa
29290 73 73 65 64 20 61 20 5b 70 72 65 70 61 72 65 64  ssed a [prepared
292a0 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
292b0 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69   has been finali
292c0 7a 65 64 2c 20 74 68 65 0a 2a 2a 20 72 65 73 75  zed, the.** resu
292d0 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20  lt is undefined 
292e0 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 68 61 72  and probably har
292f0 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e  mful..**.** ^Bin
29300 64 69 6e 67 73 20 61 72 65 20 6e 6f 74 20 63 6c  dings are not cl
29310 65 61 72 65 64 20 62 79 20 74 68 65 20 5b 73 71  eared by the [sq
29320 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 72  lite3_reset()] r
29330 6f 75 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f  outine..** ^Unbo
29340 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73 20 61  und parameters a
29350 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  re interpreted a
29360 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54  s NULL..**.** ^T
29370 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
29380 2a 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  * routines retur
29390 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e  n [SQLITE_OK] on
293a0 20 73 75 63 63 65 73 73 20 6f 72 20 61 6e 0a 2a   success or an.*
293b0 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  * [error code] i
293c0 66 20 61 6e 79 74 68 69 6e 67 20 67 6f 65 73 20  f anything goes 
293d0 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49  wrong..** ^[SQLI
293e0 54 45 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 74  TE_RANGE] is ret
293f0 75 72 6e 65 64 20 69 66 20 74 68 65 20 70 61 72  urned if the par
29400 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20  ameter.** index 
29410 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e  is out of range.
29420 20 20 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d    ^[SQLITE_NOMEM
29430 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66  ] is returned if
29440 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e   malloc() fails.
29450 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
29460 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
29470 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29  arameter_count()
29480 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
29490 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
294a0 6d 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69  me()], and [sqli
294b0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
294c0 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a  er_index()]..*/.
294d0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
294e0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
294f0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
29500 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  int, const void*
29510 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29  , int n, void(*)
29520 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45  (void*));.SQLITE
29530 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
29540 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73 71 6c  _bind_double(sql
29550 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
29560 20 64 6f 75 62 6c 65 29 3b 0a 53 51 4c 49 54 45   double);.SQLITE
29570 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
29580 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65  _bind_int(sqlite
29590 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e  3_stmt*, int, in
295a0 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  t);.SQLITE_API i
295b0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
295c0 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74  int64(sqlite3_st
295d0 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65  mt*, int, sqlite
295e0 33 5f 69 6e 74 36 34 29 3b 0a 53 51 4c 49 54 45  3_int64);.SQLITE
295f0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
29600 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69 74  _bind_null(sqlit
29610 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a  e3_stmt*, int);.
29620 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
29630 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
29640 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
29650 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a  int, const char*
29660 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29  , int n, void(*)
29670 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45  (void*));.SQLITE
29680 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
29690 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 73 71 6c  _bind_text16(sql
296a0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
296b0 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
296c0 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  t, void(*)(void*
296d0 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  ));.SQLITE_API i
296e0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
296f0 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74  value(sqlite3_st
29700 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
29710 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
29720 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
29730 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72  sqlite3_bind_zer
29740 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74  oblob(sqlite3_st
29750 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29  mt*, int, int n)
29760 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
29770 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c  F: Number Of SQL
29780 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a   Parameters.**.*
29790 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20  * ^This routine 
297a0 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 66  can be used to f
297b0 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ind the number o
297c0 66 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  f [SQL parameter
297d0 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 72 65 70  s].** in a [prep
297e0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
297f0 20 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73    SQL parameters
29800 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74   are tokens of t
29810 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20  he.** form "?", 
29820 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20  "?NNN", ":AAA", 
29830 22 24 41 41 41 22 2c 20 6f 72 20 22 40 41 41 41  "$AAA", or "@AAA
29840 22 20 74 68 61 74 20 73 65 72 76 65 20 61 73 0a  " that serve as.
29850 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20  ** placeholders 
29860 66 6f 72 20 76 61 6c 75 65 73 20 74 68 61 74 20  for values that 
29870 61 72 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  are [sqlite3_bin
29880 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a  d_blob | bound].
29890 2a 2a 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65  ** to the parame
298a0 74 65 72 73 20 61 74 20 61 20 6c 61 74 65 72 20  ters at a later 
298b0 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  time..**.** ^(Th
298c0 69 73 20 72 6f 75 74 69 6e 65 20 61 63 74 75 61  is routine actua
298d0 6c 6c 79 20 72 65 74 75 72 6e 73 20 74 68 65 20  lly returns the 
298e0 69 6e 64 65 78 20 6f 66 20 74 68 65 20 6c 61 72  index of the lar
298f0 67 65 73 74 20 28 72 69 67 68 74 6d 6f 73 74 29  gest (rightmost)
29900 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 46  .** parameter. F
29910 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63  or all forms exc
29920 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77  ept ?NNN, this w
29930 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20 74  ill correspond t
29940 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20  o the.** number 
29950 6f 66 20 75 6e 69 71 75 65 20 70 61 72 61 6d 65  of unique parame
29960 74 65 72 73 2e 20 20 49 66 20 70 61 72 61 6d 65  ters.  If parame
29970 74 65 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e  ters of the ?NNN
29980 20 66 6f 72 6d 20 61 72 65 20 75 73 65 64 2c 0a   form are used,.
29990 2a 2a 20 74 68 65 72 65 20 6d 61 79 20 62 65 20  ** there may be 
299a0 67 61 70 73 20 69 6e 20 74 68 65 20 6c 69 73 74  gaps in the list
299b0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  .)^.**.** See al
299c0 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  so: [sqlite3_bin
299d0 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62  d_blob|sqlite3_b
299e0 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ind()],.** [sqli
299f0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
29a00 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a  er_name()], and.
29a10 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
29a20 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
29a30 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ()]..*/.SQLITE_A
29a40 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  PI int sqlite3_b
29a50 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f  ind_parameter_co
29a60 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  unt(sqlite3_stmt
29a70 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
29a80 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48  REF: Name Of A H
29a90 6f 73 74 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a  ost Parameter.**
29aa0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
29ab0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
29ac0 6e 61 6d 65 28 50 2c 4e 29 20 69 6e 74 65 72 66  name(P,N) interf
29ad0 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74  ace returns.** t
29ae0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e  he name of the N
29af0 2d 74 68 20 5b 53 51 4c 20 70 61 72 61 6d 65 74  -th [SQL paramet
29b00 65 72 5d 20 69 6e 20 74 68 65 20 5b 70 72 65 70  er] in the [prep
29b10 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
29b20 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20 70 61 72 61  P..** ^(SQL para
29b30 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f  meters of the fo
29b40 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41  rm "?NNN" or ":A
29b50 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72  AA" or "@AAA" or
29b60 20 22 24 41 41 41 22 0a 2a 2a 20 68 61 76 65 20   "$AAA".** have 
29b70 61 20 6e 61 6d 65 20 77 68 69 63 68 20 69 73 20  a name which is 
29b80 74 68 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e  the string "?NNN
29b90 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22  " or ":AAA" or "
29ba0 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a  @AAA" or "$AAA".
29bb0 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  ** respectively.
29bc0 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  .** In other wor
29bd0 64 73 2c 20 74 68 65 20 69 6e 69 74 69 61 6c 20  ds, the initial 
29be0 22 3a 22 20 6f 72 20 22 24 22 20 6f 72 20 22 40  ":" or "$" or "@
29bf0 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69  " or "?".** is i
29c00 6e 63 6c 75 64 65 64 20 61 73 20 70 61 72 74 20  ncluded as part 
29c10 6f 66 20 74 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a  of the name.)^.*
29c20 2a 20 5e 50 61 72 61 6d 65 74 65 72 73 20 6f 66  * ^Parameters of
29c30 20 74 68 65 20 66 6f 72 6d 20 22 3f 22 20 77 69   the form "?" wi
29c40 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e  thout a followin
29c50 67 20 69 6e 74 65 67 65 72 20 68 61 76 65 20 6e  g integer have n
29c60 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72  o name.** and ar
29c70 65 20 72 65 66 65 72 72 65 64 20 74 6f 20 61 73  e referred to as
29c80 20 22 6e 61 6d 65 6c 65 73 73 22 20 6f 72 20 22   "nameless" or "
29c90 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65  anonymous parame
29ca0 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ters"..**.** ^Th
29cb0 65 20 66 69 72 73 74 20 68 6f 73 74 20 70 61 72  e first host par
29cc0 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e  ameter has an in
29cd0 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e  dex of 1, not 0.
29ce0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 76  .**.** ^If the v
29cf0 61 6c 75 65 20 4e 20 69 73 20 6f 75 74 20 6f 66  alue N is out of
29d00 20 72 61 6e 67 65 20 6f 72 20 69 66 20 74 68 65   range or if the
29d10 20 4e 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20   N-th parameter 
29d20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20  is.** nameless, 
29d30 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74  then NULL is ret
29d40 75 72 6e 65 64 2e 20 20 5e 54 68 65 20 72 65 74  urned.  ^The ret
29d50 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 0a  urned string is.
29d60 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20 55 54 46  ** always in UTF
29d70 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e  -8 encoding even
29d80 20 69 66 20 74 68 65 20 6e 61 6d 65 64 20 70 61   if the named pa
29d90 72 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f  rameter was.** o
29da0 72 69 67 69 6e 61 6c 6c 79 20 73 70 65 63 69 66  riginally specif
29db0 69 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e  ied as UTF-16 in
29dc0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
29dd0 65 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  e16()] or.** [sq
29de0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
29df0 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  v2()]..**.** See
29e00 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
29e10 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
29e20 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73  3_bind()],.** [s
29e30 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
29e40 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20  meter_count()], 
29e50 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
29e60 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
29e70 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49  ndex()]..*/.SQLI
29e80 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61  TE_API const cha
29e90 72 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  r *sqlite3_bind_
29ea0 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73  parameter_name(s
29eb0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
29ec0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
29ed0 52 45 46 3a 20 49 6e 64 65 78 20 4f 66 20 41 20  REF: Index Of A 
29ee0 50 61 72 61 6d 65 74 65 72 20 57 69 74 68 20 41  Parameter With A
29ef0 20 47 69 76 65 6e 20 4e 61 6d 65 0a 2a 2a 0a 2a   Given Name.**.*
29f00 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20 69 6e  * ^Return the in
29f10 64 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 70 61  dex of an SQL pa
29f20 72 61 6d 65 74 65 72 20 67 69 76 65 6e 20 69 74  rameter given it
29f30 73 20 6e 61 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a  s name.  ^The.**
29f40 20 69 6e 64 65 78 20 76 61 6c 75 65 20 72 65 74   index value ret
29f50 75 72 6e 65 64 20 69 73 20 73 75 69 74 61 62 6c  urned is suitabl
29f60 65 20 66 6f 72 20 75 73 65 20 61 73 20 74 68 65  e for use as the
29f70 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d   second.** param
29f80 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
29f90 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74  _bind_blob|sqlit
29fa0 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20 5e 41 20  e3_bind()].  ^A 
29fb0 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72  zero.** is retur
29fc0 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74 63 68 69  ned if no matchi
29fd0 6e 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  ng parameter is 
29fe0 66 6f 75 6e 64 2e 20 20 5e 54 68 65 20 70 61 72  found.  ^The par
29ff0 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d  ameter.** name m
2a000 75 73 74 20 62 65 20 67 69 76 65 6e 20 69 6e 20  ust be given in 
2a010 55 54 46 2d 38 20 65 76 65 6e 20 69 66 20 74 68  UTF-8 even if th
2a020 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65  e original state
2a030 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65 70  ment.** was prep
2a040 61 72 65 64 20 66 72 6f 6d 20 55 54 46 2d 31 36  ared from UTF-16
2a050 20 74 65 78 74 20 75 73 69 6e 67 20 5b 73 71 6c   text using [sql
2a060 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
2a070 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  2()]..**.** See 
2a080 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62  also: [sqlite3_b
2a090 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33  ind_blob|sqlite3
2a0a0 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71  _bind()],.** [sq
2a0b0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2a0c0 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61  eter_count()], a
2a0d0 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  nd.** [sqlite3_b
2a0e0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
2a0f0 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54  dex()]..*/.SQLIT
2a100 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
2a110 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2a120 5f 69 6e 64 65 78 28 73 71 6c 69 74 65 33 5f 73  _index(sqlite3_s
2a130 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  tmt*, const char
2a140 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a   *zName);../*.**
2a150 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74   CAPI3REF: Reset
2a160 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e   All Bindings On
2a170 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74   A Prepared Stat
2a180 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e  ement.**.** ^Con
2a190 74 72 61 72 79 20 74 6f 20 74 68 65 20 69 6e 74  trary to the int
2a1a0 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20  uition of many, 
2a1b0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2a1c0 5d 20 64 6f 65 73 20 6e 6f 74 20 72 65 73 65 74  ] does not reset
2a1d0 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33  .** the [sqlite3
2a1e0 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e  _bind_blob | bin
2a1f0 64 69 6e 67 73 5d 20 6f 6e 20 61 20 5b 70 72 65  dings] on a [pre
2a200 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2a210 2e 0a 2a 2a 20 5e 55 73 65 20 74 68 69 73 20 72  ..** ^Use this r
2a220 6f 75 74 69 6e 65 20 74 6f 20 72 65 73 65 74 20  outine to reset 
2a230 61 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d 65 74  all host paramet
2a240 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a  ers to NULL..*/.
2a250 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
2a260 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e  qlite3_clear_bin
2a270 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74  dings(sqlite3_st
2a280 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  mt*);../*.** CAP
2a290 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66  I3REF: Number Of
2a2a0 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65   Columns In A Re
2a2b0 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e  sult Set.**.** ^
2a2c0 52 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65  Return the numbe
2a2d0 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
2a2e0 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 72  the result set r
2a2f0 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a  eturned by the.*
2a300 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
2a310 65 6d 65 6e 74 5d 2e 20 5e 54 68 69 73 20 72 6f  ement]. ^This ro
2a320 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20  utine returns 0 
2a330 69 66 20 70 53 74 6d 74 20 69 73 20 61 6e 20 53  if pStmt is an S
2a340 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  QL.** statement 
2a350 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 72 65  that does not re
2a360 74 75 72 6e 20 64 61 74 61 20 28 66 6f 72 20 65  turn data (for e
2a370 78 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41 54  xample an [UPDAT
2a380 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  E])..**.** See a
2a390 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61  lso: [sqlite3_da
2a3a0 74 61 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 53  ta_count()].*/.S
2a3b0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
2a3c0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75  lite3_column_cou
2a3d0 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  nt(sqlite3_stmt 
2a3e0 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
2a3f0 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e  CAPI3REF: Column
2a400 20 4e 61 6d 65 73 20 49 6e 20 41 20 52 65 73 75   Names In A Resu
2a410 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  lt Set.**.** ^Th
2a420 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ese routines ret
2a430 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 61 73 73  urn the name ass
2a440 69 67 6e 65 64 20 74 6f 20 61 20 70 61 72 74 69  igned to a parti
2a450 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  cular column.** 
2a460 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  in the result se
2a470 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20  t of a [SELECT] 
2a480 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 54 68 65  statement.  ^The
2a490 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2a4a0 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66  name().** interf
2a4b0 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
2a4c0 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d  inter to a zero-
2a4d0 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
2a4e0 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 73   string.** and s
2a4f0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
2a500 6d 65 31 36 28 29 20 72 65 74 75 72 6e 73 20 61  me16() returns a
2a510 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65   pointer to a ze
2a520 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
2a530 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20   UTF-16 string. 
2a540 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61   ^The first para
2a550 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 70 72  meter is the [pr
2a560 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2a570 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70 6c 65 6d  ].** that implem
2a580 65 6e 74 73 20 74 68 65 20 5b 53 45 4c 45 43 54  ents the [SELECT
2a590 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 5e 54 68  ] statement. ^Th
2a5a0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
2a5b0 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6c  er is the.** col
2a5c0 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 5e 54 68  umn number.  ^Th
2a5d0 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d  e leftmost colum
2a5e0 6e 20 69 73 20 6e 75 6d 62 65 72 20 30 2e 0a 2a  n is number 0..*
2a5f0 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e  *.** ^The return
2a600 65 64 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65  ed string pointe
2a610 72 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c  r is valid until
2a620 20 65 69 74 68 65 72 20 74 68 65 20 5b 70 72 65   either the [pre
2a630 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2a640 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f 79 65 64  .** is destroyed
2a650 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   by [sqlite3_fin
2a660 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69  alize()] or unti
2a670 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  l the statement 
2a680 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  is automatically
2a690 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20 62  .** reprepared b
2a6a0 79 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c  y the first call
2a6b0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
2a6c0 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69  p()] for a parti
2a6d0 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20  cular run.** or 
2a6e0 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20 63  until the next c
2a6f0 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  all to.** sqlite
2a700 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20  3_column_name() 
2a710 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  or sqlite3_colum
2a720 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20 74 68  n_name16() on th
2a730 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a  e same column..*
2a740 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33  *.** ^If sqlite3
2a750 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 20  _malloc() fails 
2a760 64 75 72 69 6e 67 20 74 68 65 20 70 72 6f 63 65  during the proce
2a770 73 73 69 6e 67 20 6f 66 20 65 69 74 68 65 72 20  ssing of either 
2a780 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 20  routine.** (for 
2a790 65 78 61 6d 70 6c 65 20 64 75 72 69 6e 67 20 61  example during a
2a7a0 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d   conversion from
2a7b0 20 55 54 46 2d 38 20 74 6f 20 55 54 46 2d 31 36   UTF-8 to UTF-16
2a7c0 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c  ) then a.** NULL
2a7d0 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75   pointer is retu
2a7e0 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  rned..**.** ^The
2a7f0 20 6e 61 6d 65 20 6f 66 20 61 20 72 65 73 75 6c   name of a resul
2a800 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20  t column is the 
2a810 76 61 6c 75 65 20 6f 66 20 74 68 65 20 22 41 53  value of the "AS
2a820 22 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a 2a 20  " clause for.** 
2a830 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 66 20  that column, if 
2a840 74 68 65 72 65 20 69 73 20 61 6e 20 41 53 20 63  there is an AS c
2a850 6c 61 75 73 65 2e 20 20 49 66 20 74 68 65 72 65  lause.  If there
2a860 20 69 73 20 6e 6f 20 41 53 20 63 6c 61 75 73 65   is no AS clause
2a870 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e 61 6d  .** then the nam
2a880 65 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20  e of the column 
2a890 69 73 20 75 6e 73 70 65 63 69 66 69 65 64 20 61  is unspecified a
2a8a0 6e 64 20 6d 61 79 20 63 68 61 6e 67 65 20 66 72  nd may change fr
2a8b0 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 61 73  om.** one releas
2a8c0 65 20 6f 66 20 53 51 4c 69 74 65 20 74 6f 20 74  e of SQLite to t
2a8d0 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a 53 51 4c 49  he next..*/.SQLI
2a8e0 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61  TE_API const cha
2a8f0 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
2a900 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  n_name(sqlite3_s
2a910 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 53 51  tmt*, int N);.SQ
2a920 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76  LITE_API const v
2a930 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
2a940 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  umn_name16(sqlit
2a950 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29  e3_stmt*, int N)
2a960 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2a970 46 3a 20 53 6f 75 72 63 65 20 4f 66 20 44 61 74  F: Source Of Dat
2a980 61 20 49 6e 20 41 20 51 75 65 72 79 20 52 65 73  a In A Query Res
2a990 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  ult.**.** ^These
2a9a0 20 72 6f 75 74 69 6e 65 73 20 70 72 6f 76 69 64   routines provid
2a9b0 65 20 61 20 6d 65 61 6e 73 20 74 6f 20 64 65 74  e a means to det
2a9c0 65 72 6d 69 6e 65 20 74 68 65 20 64 61 74 61 62  ermine the datab
2a9d0 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 0a  ase, table, and.
2a9e0 2a 2a 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20  ** table column 
2a9f0 74 68 61 74 20 69 73 20 74 68 65 20 6f 72 69 67  that is the orig
2aa00 69 6e 20 6f 66 20 61 20 70 61 72 74 69 63 75 6c  in of a particul
2aa10 61 72 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  ar result column
2aa20 20 69 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d 20   in.** [SELECT] 
2aa30 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54  statement..** ^T
2aa40 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64  he name of the d
2aa50 61 74 61 62 61 73 65 20 6f 72 20 74 61 62 6c 65  atabase or table
2aa60 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62   or column can b
2aa70 65 20 72 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a  e returned as.**
2aa80 20 65 69 74 68 65 72 20 61 20 55 54 46 2d 38 20   either a UTF-8 
2aa90 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67  or UTF-16 string
2aaa0 2e 20 20 5e 54 68 65 20 5f 64 61 74 61 62 61 73  .  ^The _databas
2aab0 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  e_ routines retu
2aac0 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  rn.** the databa
2aad0 73 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61  se name, the _ta
2aae0 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65  ble_ routines re
2aaf0 74 75 72 6e 20 74 68 65 20 74 61 62 6c 65 20 6e  turn the table n
2ab00 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20  ame, and.** the 
2ab10 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73  origin_ routines
2ab20 20 72 65 74 75 72 6e 20 74 68 65 20 63 6f 6c 75   return the colu
2ab30 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65  mn name..** ^The
2ab40 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
2ab50 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20   is valid until 
2ab60 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
2ab70 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65 73 74  atement] is dest
2ab80 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b  royed.** using [
2ab90 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2aba0 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65  ()] or until the
2abb0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75   statement is au
2abc0 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72  tomatically.** r
2abd0 65 70 72 65 70 61 72 65 64 20 62 79 20 74 68 65  eprepared by the
2abe0 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b   first call to [
2abf0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2ac00 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72  for a particular
2ac10 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c   run.** or until
2ac20 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d   the same inform
2ac30 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74  ation is request
2ac40 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61  ed.** again in a
2ac50 20 64 69 66 66 65 72 65 6e 74 20 65 6e 63 6f 64   different encod
2ac60 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ing..**.** ^The 
2ac70 6e 61 6d 65 73 20 72 65 74 75 72 6e 65 64 20 61  names returned a
2ac80 72 65 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  re the original 
2ac90 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65 73  un-aliased names
2aca0 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74 61 62   of the.** datab
2acb0 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20  ase, table, and 
2acc0 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54  column..**.** ^T
2acd0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
2ace0 74 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72  t to these inter
2acf0 66 61 63 65 73 20 69 73 20 61 20 5b 70 72 65 70  faces is a [prep
2ad00 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
2ad10 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74  .** ^These funct
2ad20 69 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e 66 6f  ions return info
2ad30 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68  rmation about th
2ad40 65 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c  e Nth result col
2ad50 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 0a  umn returned by.
2ad60 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  ** the statement
2ad70 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  , where N is the
2ad80 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e   second function
2ad90 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54   argument..** ^T
2ada0 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c  he left-most col
2adb0 75 6d 6e 20 69 73 20 63 6f 6c 75 6d 6e 20 30 20  umn is column 0 
2adc0 66 6f 72 20 74 68 65 73 65 20 72 6f 75 74 69 6e  for these routin
2add0 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  es..**.** ^If th
2ade0 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74  e Nth column ret
2adf0 75 72 6e 65 64 20 62 79 20 74 68 65 20 73 74 61  urned by the sta
2ae00 74 65 6d 65 6e 74 20 69 73 20 61 6e 20 65 78 70  tement is an exp
2ae10 72 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75  ression or.** su
2ae20 62 71 75 65 72 79 20 61 6e 64 20 69 73 20 6e 6f  bquery and is no
2ae30 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65  t a column value
2ae40 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68  , then all of th
2ae50 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65  ese functions re
2ae60 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e  turn.** NULL.  ^
2ae70 54 68 65 73 65 20 72 6f 75 74 69 6e 65 20 6d 69  These routine mi
2ae80 67 68 74 20 61 6c 73 6f 20 72 65 74 75 72 6e 20  ght also return 
2ae90 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79  NULL if a memory
2aea0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f   allocation erro
2aeb0 72 0a 2a 2a 20 6f 63 63 75 72 73 2e 20 20 5e 4f  r.** occurs.  ^O
2aec0 74 68 65 72 77 69 73 65 2c 20 74 68 65 79 20 72  therwise, they r
2aed0 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 6f  eturn the name o
2aee0 66 20 74 68 65 20 61 74 74 61 63 68 65 64 20 64  f the attached d
2aef0 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 0a  atabase, table,.
2af00 2a 2a 20 6f 72 20 63 6f 6c 75 6d 6e 20 74 68 61  ** or column tha
2af10 74 20 71 75 65 72 79 20 72 65 73 75 6c 74 20 63  t query result c
2af20 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74 72 61 63  olumn was extrac
2af30 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20  ted from..**.** 
2af40 5e 41 73 20 77 69 74 68 20 61 6c 6c 20 6f 74 68  ^As with all oth
2af50 65 72 20 53 51 4c 69 74 65 20 41 50 49 73 2c 20  er SQLite APIs, 
2af60 74 68 6f 73 65 20 77 68 6f 73 65 20 6e 61 6d 65  those whose name
2af70 73 20 65 6e 64 20 77 69 74 68 20 22 31 36 22 20  s end with "16" 
2af80 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36  return.** UTF-16
2af90 20 65 6e 63 6f 64 65 64 20 73 74 72 69 6e 67 73   encoded strings
2afa0 20 61 6e 64 20 74 68 65 20 6f 74 68 65 72 20 66   and the other f
2afb0 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20  unctions return 
2afc0 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  UTF-8..**.** ^Th
2afd0 65 73 65 20 41 50 49 73 20 61 72 65 20 6f 6e 6c  ese APIs are onl
2afe0 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74  y available if t
2aff0 68 65 20 6c 69 62 72 61 72 79 20 77 61 73 20 63  he library was c
2b000 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65  ompiled with the
2b010 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42  .** [SQLITE_ENAB
2b020 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41  LE_COLUMN_METADA
2b030 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 73  TA] C-preprocess
2b040 6f 72 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a  or symbol..**.**
2b050 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20   If two or more 
2b060 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65  threads call one
2b070 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 73   or more of thes
2b080 65 20 72 6f 75 74 69 6e 65 73 20 61 67 61 69 6e  e routines again
2b090 73 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70  st the same.** p
2b0a0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2b0b0 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20  t and column at 
2b0c0 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68  the same time th
2b0d0 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  en the results a
2b0e0 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e  re.** undefined.
2b0f0 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72  .**.** If two or
2b100 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61   more threads ca
2b110 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a  ll one or more.*
2b120 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
2b130 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 20  n_database_name 
2b140 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74  | column metadat
2b150 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a  a interfaces].**
2b160 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 5b 70   for the same [p
2b170 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2b180 74 5d 20 61 6e 64 20 72 65 73 75 6c 74 20 63 6f  t] and result co
2b190 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74 68 65 20 73  lumn.** at the s
2b1a0 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68  ame time then th
2b1b0 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
2b1c0 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 53 51 4c 49  defined..*/.SQLI
2b1d0 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61  TE_API const cha
2b1e0 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
2b1f0 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 28  n_database_name(
2b200 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
2b210 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  t);.SQLITE_API c
2b220 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
2b230 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61  e3_column_databa
2b240 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65  se_name16(sqlite
2b250 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51  3_stmt*,int);.SQ
2b260 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63  LITE_API const c
2b270 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
2b280 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73  umn_table_name(s
2b290 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
2b2a0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
2b2b0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
2b2c0 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e  3_column_table_n
2b2d0 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
2b2e0 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45  mt*,int);.SQLITE
2b2f0 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20  _API const char 
2b300 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
2b310 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69  origin_name(sqli
2b320 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
2b330 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
2b340 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
2b350 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d  olumn_origin_nam
2b360 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
2b370 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  *,int);../*.** C
2b380 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61 72 65  API3REF: Declare
2b390 64 20 44 61 74 61 74 79 70 65 20 4f 66 20 41 20  d Datatype Of A 
2b3a0 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a  Query Result.**.
2b3b0 2a 2a 20 5e 28 54 68 65 20 66 69 72 73 74 20 70  ** ^(The first p
2b3c0 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 5b 70  arameter is a [p
2b3d0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2b3e0 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 73  t]..** If this s
2b3f0 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 53  tatement is a [S
2b400 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
2b410 20 61 6e 64 20 74 68 65 20 4e 74 68 20 63 6f 6c   and the Nth col
2b420 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65  umn of the.** re
2b430 74 75 72 6e 65 64 20 72 65 73 75 6c 74 20 73 65  turned result se
2b440 74 20 6f 66 20 74 68 61 74 20 5b 53 45 4c 45 43  t of that [SELEC
2b450 54 5d 20 69 73 20 61 20 74 61 62 6c 65 20 63 6f  T] is a table co
2b460 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20  lumn (not an.** 
2b470 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75  expression or su
2b480 62 71 75 65 72 79 29 20 74 68 65 6e 20 74 68 65  bquery) then the
2b490 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 20 6f   declared type o
2b4a0 66 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63  f the table.** c
2b4b0 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75 72 6e 65  olumn is returne
2b4c0 64 2e 29 5e 20 20 5e 49 66 20 74 68 65 20 4e 74  d.)^  ^If the Nt
2b4d0 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  h column of the 
2b4e0 72 65 73 75 6c 74 20 73 65 74 20 69 73 20 61 6e  result set is an
2b4f0 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f  .** expression o
2b500 72 20 73 75 62 71 75 65 72 79 2c 20 74 68 65 6e  r subquery, then
2b510 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
2b520 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20  is returned..** 
2b530 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74  ^The returned st
2b540 72 69 6e 67 20 69 73 20 61 6c 77 61 79 73 20 55  ring is always U
2b550 54 46 2d 38 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a  TF-8 encoded..**
2b560 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c  .** ^(For exampl
2b570 65 2c 20 67 69 76 65 6e 20 74 68 65 20 64 61 74  e, given the dat
2b580 61 62 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a  abase schema:.**
2b590 0a 2a 2a 20 43 52 45 41 54 45 20 54 41 42 4c 45  .** CREATE TABLE
2b5a0 20 74 31 28 63 31 20 56 41 52 49 41 4e 54 29 3b   t1(c1 VARIANT);
2b5b0 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66  .**.** and the f
2b5c0 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d 65  ollowing stateme
2b5d0 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65  nt to be compile
2b5e0 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20  d:.**.** SELECT 
2b5f0 63 31 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20  c1 + 1, c1 FROM 
2b600 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72  t1;.**.** this r
2b610 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20 72 65 74  outine would ret
2b620 75 72 6e 20 74 68 65 20 73 74 72 69 6e 67 20 22  urn the string "
2b630 56 41 52 49 41 4e 54 22 20 66 6f 72 20 74 68 65  VARIANT" for the
2b640 20 73 65 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a   second result.*
2b650 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c  * column (i==1),
2b660 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e   and a NULL poin
2b670 74 65 72 20 66 6f 72 20 74 68 65 20 66 69 72 73  ter for the firs
2b680 74 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  t result column 
2b690 28 69 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20  (i==0).)^.**.** 
2b6a0 5e 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e  ^SQLite uses dyn
2b6b0 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20 74 79  amic run-time ty
2b6c0 70 69 6e 67 2e 20 20 5e 53 6f 20 6a 75 73 74 20  ping.  ^So just 
2b6d0 62 65 63 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e  because a column
2b6e0 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72 65 64 20  .** is declared 
2b6f0 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70 61 72  to contain a par
2b700 74 69 63 75 6c 61 72 20 74 79 70 65 20 64 6f 65  ticular type doe
2b710 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74 20  s not mean that 
2b720 74 68 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72  the.** data stor
2b730 65 64 20 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d  ed in that colum
2b740 6e 20 69 73 20 6f 66 20 74 68 65 20 64 65 63 6c  n is of the decl
2b750 61 72 65 64 20 74 79 70 65 2e 20 20 53 51 4c 69  ared type.  SQLi
2b760 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c  te is.** strongl
2b770 79 20 74 79 70 65 64 2c 20 62 75 74 20 74 68 65  y typed, but the
2b780 20 74 79 70 69 6e 67 20 69 73 20 64 79 6e 61 6d   typing is dynam
2b790 69 63 20 6e 6f 74 20 73 74 61 74 69 63 2e 20 20  ic not static.  
2b7a0 5e 54 79 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f  ^Type.** is asso
2b7b0 63 69 61 74 65 64 20 77 69 74 68 20 69 6e 64 69  ciated with indi
2b7c0 76 69 64 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e  vidual values, n
2b7d0 6f 74 20 77 69 74 68 20 74 68 65 20 63 6f 6e 74  ot with the cont
2b7e0 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64 20 74  ainers.** used t
2b7f0 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c  o hold those val
2b800 75 65 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ues..*/.SQLITE_A
2b810 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  PI const char *s
2b820 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65  qlite3_column_de
2b830 63 6c 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73  cltype(sqlite3_s
2b840 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54  tmt*,int);.SQLIT
2b850 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64  E_API const void
2b860 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2b870 5f 64 65 63 6c 74 79 70 65 31 36 28 73 71 6c 69  _decltype16(sqli
2b880 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
2b890 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2b8a0 20 45 76 61 6c 75 61 74 65 20 41 6e 20 53 51 4c   Evaluate An SQL
2b8b0 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a   Statement.**.**
2b8c0 20 41 66 74 65 72 20 61 20 5b 70 72 65 70 61 72   After a [prepar
2b8d0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 68 61  ed statement] ha
2b8e0 73 20 62 65 65 6e 20 70 72 65 70 61 72 65 64 20  s been prepared 
2b8f0 75 73 69 6e 67 20 65 69 74 68 65 72 0a 2a 2a 20  using either.** 
2b900 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2b910 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  _v2()] or [sqlit
2b920 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
2b930 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65  )] or one of the
2b940 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72   legacy.** inter
2b950 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 70  faces [sqlite3_p
2b960 72 65 70 61 72 65 28 29 5d 20 6f 72 20 5b 73 71  repare()] or [sq
2b970 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
2b980 29 5d 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f  )], this functio
2b990 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 20 63 61 6c  n.** must be cal
2b9a0 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  led one or more 
2b9b0 74 69 6d 65 73 20 74 6f 20 65 76 61 6c 75 61 74  times to evaluat
2b9c0 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2e  e the statement.
2b9d0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61 69  .**.** The detai
2b9e0 6c 73 20 6f 66 20 74 68 65 20 62 65 68 61 76 69  ls of the behavi
2b9f0 6f 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  or of the sqlite
2ba00 33 5f 73 74 65 70 28 29 20 69 6e 74 65 72 66 61  3_step() interfa
2ba10 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20  ce depend.** on 
2ba20 77 68 65 74 68 65 72 20 74 68 65 20 73 74 61 74  whether the stat
2ba30 65 6d 65 6e 74 20 77 61 73 20 70 72 65 70 61 72  ement was prepar
2ba40 65 64 20 75 73 69 6e 67 20 74 68 65 20 6e 65 77  ed using the new
2ba50 65 72 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  er "v2" interfac
2ba60 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  e.** [sqlite3_pr
2ba70 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
2ba80 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2ba90 31 36 5f 76 32 28 29 5d 20 6f 72 20 74 68 65 20  16_v2()] or the 
2baa0 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20  older legacy.** 
2bab0 69 6e 74 65 72 66 61 63 65 20 5b 73 71 6c 69 74  interface [sqlit
2bac0 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e  e3_prepare()] an
2bad0 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  d [sqlite3_prepa
2bae0 72 65 31 36 28 29 5d 2e 20 20 54 68 65 20 75 73  re16()].  The us
2baf0 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20  e of the.** new 
2bb00 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 69  "v2" interface i
2bb10 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f  s recommended fo
2bb20 72 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f  r new applicatio
2bb30 6e 73 20 62 75 74 20 74 68 65 20 6c 65 67 61 63  ns but the legac
2bb40 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 77  y.** interface w
2bb50 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20  ill continue to 
2bb60 62 65 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a  be supported..**
2bb70 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 6c 65 67 61  .** ^In the lega
2bb80 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68  cy interface, th
2bb90 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 77  e return value w
2bba0 69 6c 6c 20 62 65 20 65 69 74 68 65 72 20 5b 53  ill be either [S
2bbb0 51 4c 49 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20  QLITE_BUSY],.** 
2bbc0 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b  [SQLITE_DONE], [
2bbd0 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51  SQLITE_ROW], [SQ
2bbe0 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20  LITE_ERROR], or 
2bbf0 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e  [SQLITE_MISUSE].
2bc00 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 22 76  .** ^With the "v
2bc10 32 22 20 69 6e 74 65 72 66 61 63 65 2c 20 61 6e  2" interface, an
2bc20 79 20 6f 66 20 74 68 65 20 6f 74 68 65 72 20 5b  y of the other [
2bc30 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6f 72  result codes] or
2bc40 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
2bc50 73 75 6c 74 20 63 6f 64 65 73 5d 20 6d 69 67 68  sult codes] migh
2bc60 74 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73  t be returned as
2bc70 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53   well..**.** ^[S
2bc80 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65 61 6e  QLITE_BUSY] mean
2bc90 73 20 74 68 61 74 20 74 68 65 20 64 61 74 61 62  s that the datab
2bca0 61 73 65 20 65 6e 67 69 6e 65 20 77 61 73 20 75  ase engine was u
2bcb0 6e 61 62 6c 65 20 74 6f 20 61 63 71 75 69 72 65  nable to acquire
2bcc0 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
2bcd0 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64 73 20   locks it needs 
2bce0 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e 20 20  to do its job.  
2bcf0 5e 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e  ^If the statemen
2bd00 74 20 69 73 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a  t is a [COMMIT].
2bd10 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f 75 74  ** or occurs out
2bd20 73 69 64 65 20 6f 66 20 61 6e 20 65 78 70 6c 69  side of an expli
2bd30 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c  cit transaction,
2bd40 20 74 68 65 6e 20 79 6f 75 20 63 61 6e 20 72 65   then you can re
2bd50 74 72 79 20 74 68 65 0a 2a 2a 20 73 74 61 74 65  try the.** state
2bd60 6d 65 6e 74 2e 20 20 49 66 20 74 68 65 20 73 74  ment.  If the st
2bd70 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20 61  atement is not a
2bd80 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f 63   [COMMIT] and oc
2bd90 63 75 72 73 20 77 69 74 68 69 6e 20 61 6e 0a 2a  curs within an.*
2bda0 2a 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73  * explicit trans
2bdb0 61 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f 75 20  action then you 
2bdc0 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 6b 20  should rollback 
2bdd0 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  the transaction 
2bde0 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e  before.** contin
2bdf0 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51  uing..**.** ^[SQ
2be00 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73  LITE_DONE] means
2be10 20 74 68 61 74 20 74 68 65 20 73 74 61 74 65 6d   that the statem
2be20 65 6e 74 20 68 61 73 20 66 69 6e 69 73 68 65 64  ent has finished
2be30 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20 73 75   executing.** su
2be40 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 73 71 6c  ccessfully.  sql
2be50 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75  ite3_step() shou
2be60 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64  ld not be called
2be70 20 61 67 61 69 6e 20 6f 6e 20 74 68 69 73 20 76   again on this v
2be80 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e  irtual.** machin
2be90 65 20 77 69 74 68 6f 75 74 20 66 69 72 73 74 20  e without first 
2bea0 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
2beb0 5f 72 65 73 65 74 28 29 5d 20 74 6f 20 72 65 73  _reset()] to res
2bec0 65 74 20 74 68 65 20 76 69 72 74 75 61 6c 0a 2a  et the virtual.*
2bed0 2a 20 6d 61 63 68 69 6e 65 20 62 61 63 6b 20 74  * machine back t
2bee0 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74  o its initial st
2bef0 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ate..**.** ^If t
2bf00 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
2bf10 20 62 65 69 6e 67 20 65 78 65 63 75 74 65 64 20   being executed 
2bf20 72 65 74 75 72 6e 73 20 61 6e 79 20 64 61 74 61  returns any data
2bf30 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 52  , then [SQLITE_R
2bf40 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e  OW].** is return
2bf50 65 64 20 65 61 63 68 20 74 69 6d 65 20 61 20 6e  ed each time a n
2bf60 65 77 20 72 6f 77 20 6f 66 20 64 61 74 61 20 69  ew row of data i
2bf70 73 20 72 65 61 64 79 20 66 6f 72 20 70 72 6f 63  s ready for proc
2bf80 65 73 73 69 6e 67 20 62 79 20 74 68 65 0a 2a 2a  essing by the.**
2bf90 20 63 61 6c 6c 65 72 2e 20 54 68 65 20 76 61 6c   caller. The val
2bfa0 75 65 73 20 6d 61 79 20 62 65 20 61 63 63 65 73  ues may be acces
2bfb0 73 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 63  sed using the [c
2bfc0 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e  olumn access fun
2bfd0 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69  ctions]..** sqli
2bfe0 74 65 33 5f 73 74 65 70 28 29 20 69 73 20 63 61  te3_step() is ca
2bff0 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f 20 72 65  lled again to re
2c000 74 72 69 65 76 65 20 74 68 65 20 6e 65 78 74 20  trieve the next 
2c010 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a  row of data..**.
2c020 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 45 52 52 4f  ** ^[SQLITE_ERRO
2c030 52 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 61 20  R] means that a 
2c040 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20 28  run-time error (
2c050 73 75 63 68 20 61 73 20 61 20 63 6f 6e 73 74 72  such as a constr
2c060 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f  aint.** violatio
2c070 6e 29 20 68 61 73 20 6f 63 63 75 72 72 65 64 2e  n) has occurred.
2c080 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29    sqlite3_step()
2c090 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63   should not be c
2c0a0 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a  alled again on.*
2c0b0 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69  * the VM. More i
2c0c0 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62  nformation may b
2c0d0 65 20 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69  e found by calli
2c0e0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  ng [sqlite3_errm
2c0f0 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20  sg()]..** ^With 
2c100 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72  the legacy inter
2c110 66 61 63 65 2c 20 61 20 6d 6f 72 65 20 73 70 65  face, a more spe
2c120 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65  cific error code
2c130 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a   (for example,.*
2c140 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52  * [SQLITE_INTERR
2c150 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 43  UPT], [SQLITE_SC
2c160 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f 43  HEMA], [SQLITE_C
2c170 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f 20  ORRUPT], and so 
2c180 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62 65  forth).** can be
2c190 20 6f 62 74 61 69 6e 65 64 20 62 79 20 63 61 6c   obtained by cal
2c1a0 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  ling [sqlite3_re
2c1b0 73 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a  set()] on the.**
2c1c0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2c1d0 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20 74 68 65 20  ment].  ^In the 
2c1e0 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 0a  "v2" interface,.
2c1f0 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63  ** the more spec
2c200 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20  ific error code 
2c210 69 73 20 72 65 74 75 72 6e 65 64 20 64 69 72 65  is returned dire
2c220 63 74 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f  ctly by sqlite3_
2c230 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53  step()..**.** [S
2c240 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65  QLITE_MISUSE] me
2c250 61 6e 73 20 74 68 61 74 20 74 68 65 20 74 68 69  ans that the thi
2c260 73 20 72 6f 75 74 69 6e 65 20 77 61 73 20 63 61  s routine was ca
2c270 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70 72 69 61  lled inappropria
2c280 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73  tely..** Perhaps
2c290 20 69 74 20 77 61 73 20 63 61 6c 6c 65 64 20 6f   it was called o
2c2a0 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  n a [prepared st
2c2b0 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61  atement] that ha
2c2c0 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62 65 65  s.** already bee
2c2d0 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  n [sqlite3_final
2c2e0 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d  ize | finalized]
2c2f0 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20   or on one that 
2c300 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  had.** previousl
2c310 79 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49  y returned [SQLI
2c320 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51  TE_ERROR] or [SQ
2c330 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20  LITE_DONE].  Or 
2c340 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74  it could.** be t
2c350 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65  he case that the
2c360 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
2c370 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62 65 69  onnection is bei
2c380 6e 67 20 75 73 65 64 20 62 79 20 74 77 6f 20 6f  ng used by two o
2c390 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61 64  r.** more thread
2c3a0 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 6d 6f  s at the same mo
2c3b0 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a  ment in time..**
2c3c0 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20 76 65 72 73  .** For all vers
2c3d0 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 75  ions of SQLite u
2c3e0 70 20 74 6f 20 61 6e 64 20 69 6e 63 6c 75 64 69  p to and includi
2c3f0 6e 67 20 33 2e 36 2e 32 33 2e 31 2c 20 61 20 63  ng 3.6.23.1, a c
2c400 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
2c410 65 33 5f 72 65 73 65 74 28 29 5d 20 77 61 73 20  e3_reset()] was 
2c420 72 65 71 75 69 72 65 64 20 61 66 74 65 72 20 73  required after s
2c430 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 72 65  qlite3_step() re
2c440 74 75 72 6e 65 64 20 61 6e 79 74 68 69 6e 67 0a  turned anything.
2c450 2a 2a 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  ** other than [S
2c460 51 4c 49 54 45 5f 52 4f 57 5d 20 62 65 66 6f 72  QLITE_ROW] befor
2c470 65 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e 74  e any subsequent
2c480 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a   invocation of.*
2c490 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  * sqlite3_step()
2c4a0 2e 20 20 46 61 69 6c 75 72 65 20 74 6f 20 72 65  .  Failure to re
2c4b0 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65 64  set the prepared
2c4c0 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67   statement using
2c4d0 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65   .** [sqlite3_re
2c4e0 73 65 74 28 29 5d 20 77 6f 75 6c 64 20 72 65 73  set()] would res
2c4f0 75 6c 74 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54  ult in an [SQLIT
2c500 45 5f 4d 49 53 55 53 45 5d 20 72 65 74 75 72 6e  E_MISUSE] return
2c510 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33   from.** sqlite3
2c520 5f 73 74 65 70 28 29 2e 20 20 42 75 74 20 61 66  _step().  But af
2c530 74 65 72 20 76 65 72 73 69 6f 6e 20 33 2e 36 2e  ter version 3.6.
2c540 32 33 2e 31 2c 20 73 71 6c 69 74 65 33 5f 73 74  23.1, sqlite3_st
2c550 65 70 28 29 20 62 65 67 61 6e 0a 2a 2a 20 63 61  ep() began.** ca
2c560 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  lling [sqlite3_r
2c570 65 73 65 74 28 29 5d 20 61 75 74 6f 6d 61 74 69  eset()] automati
2c580 63 61 6c 6c 79 20 69 6e 20 74 68 69 73 20 63 69  cally in this ci
2c590 72 63 75 6d 73 74 61 6e 63 65 20 72 61 74 68 65  rcumstance rathe
2c5a0 72 0a 2a 2a 20 74 68 61 6e 20 72 65 74 75 72 6e  r.** than return
2c5b0 69 6e 67 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  ing [SQLITE_MISU
2c5c0 53 45 5d 2e 20 20 54 68 69 73 20 69 73 20 6e 6f  SE].  This is no
2c5d0 74 20 63 6f 6e 73 69 64 65 72 65 64 20 61 20 63  t considered a c
2c5e0 6f 6d 70 61 74 69 62 69 6c 69 74 79 0a 2a 2a 20  ompatibility.** 
2c5f0 62 72 65 61 6b 20 62 65 63 61 75 73 65 20 61 6e  break because an
2c600 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 68  y application th
2c610 61 74 20 65 76 65 72 20 72 65 63 65 69 76 65 73  at ever receives
2c620 20 61 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53   an SQLITE_MISUS
2c630 45 20 65 72 72 6f 72 0a 2a 2a 20 69 73 20 62 72  E error.** is br
2c640 6f 6b 65 6e 20 62 79 20 64 65 66 69 6e 69 74 69  oken by definiti
2c650 6f 6e 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45  on.  The [SQLITE
2c660 5f 4f 4d 49 54 5f 41 55 54 4f 52 45 53 45 54 5d  _OMIT_AUTORESET]
2c670 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
2c680 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20 62 65 20 75  tion.** can be u
2c690 73 65 64 20 74 6f 20 72 65 73 74 6f 72 65 20 74  sed to restore t
2c6a0 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69  he legacy behavi
2c6b0 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f  or..**.** <b>Goo
2c6c0 66 79 20 49 6e 74 65 72 66 61 63 65 20 41 6c 65  fy Interface Ale
2c6d0 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 20 6c  rt:</b> In the l
2c6e0 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c  egacy interface,
2c6f0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65   the sqlite3_ste
2c700 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c 77 61 79  p().** API alway
2c710 73 20 72 65 74 75 72 6e 73 20 61 20 67 65 6e 65  s returns a gene
2c720 72 69 63 20 65 72 72 6f 72 20 63 6f 64 65 2c 20  ric error code, 
2c730 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20  [SQLITE_ERROR], 
2c740 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a  following any.**
2c750 20 65 72 72 6f 72 20 6f 74 68 65 72 20 74 68 61   error other tha
2c760 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  n [SQLITE_BUSY] 
2c770 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  and [SQLITE_MISU
2c780 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20 63  SE].  You must c
2c790 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  all.** [sqlite3_
2c7a0 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c  reset()] or [sql
2c7b0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
2c7c0 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e   in order to fin
2c7d0 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20  d one of the.** 
2c7e0 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20  specific [error 
2c7f0 63 6f 64 65 73 5d 20 74 68 61 74 20 62 65 74 74  codes] that bett
2c800 65 72 20 64 65 73 63 72 69 62 65 73 20 74 68 65  er describes the
2c810 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64   error..** We ad
2c820 6d 69 74 20 74 68 61 74 20 74 68 69 73 20 69 73  mit that this is
2c830 20 61 20 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e   a goofy design.
2c840 20 20 54 68 65 20 70 72 6f 62 6c 65 6d 20 68 61    The problem ha
2c850 73 20 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20  s been fixed.** 
2c860 77 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e  with the "v2" in
2c870 74 65 72 66 61 63 65 2e 20 20 49 66 20 79 6f 75  terface.  If you
2c880 20 70 72 65 70 61 72 65 20 61 6c 6c 20 6f 66 20   prepare all of 
2c890 79 6f 75 72 20 53 51 4c 20 73 74 61 74 65 6d 65  your SQL stateme
2c8a0 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20 65 69 74  nts.** using eit
2c8b0 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  her [sqlite3_pre
2c8c0 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73  pare_v2()] or [s
2c8d0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2c8e0 5f 76 32 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a  _v2()] instead.*
2c8f0 2a 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 20  * of the legacy 
2c900 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2c910 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
2c920 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 69 6e  _prepare16()] in
2c930 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20 74 68 65  terfaces,.** the
2c940 6e 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69  n the more speci
2c950 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73  fic [error codes
2c960 5d 20 61 72 65 20 72 65 74 75 72 6e 65 64 20 64  ] are returned d
2c970 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71  irectly.** by sq
2c980 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 54  lite3_step().  T
2c990 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 22 76  he use of the "v
2c9a0 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  2" interface is 
2c9b0 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f 0a  recommended..*/.
2c9c0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
2c9d0 71 6c 69 74 65 33 5f 73 74 65 70 28 73 71 6c 69  qlite3_step(sqli
2c9e0 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
2c9f0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d  ** CAPI3REF: Num
2ca00 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
2ca10 6e 20 61 20 72 65 73 75 6c 74 20 73 65 74 0a 2a  n a result set.*
2ca20 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2ca30 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20  3_data_count(P) 
2ca40 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2ca50 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
2ca60 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a 2a  columns in the.*
2ca70 2a 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66  * current row of
2ca80 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
2ca90 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  of [prepared sta
2caa0 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 49  tement] P..** ^I
2cab0 66 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  f prepared state
2cac0 6d 65 6e 74 20 50 20 64 6f 65 73 20 6e 6f 74 20  ment P does not 
2cad0 68 61 76 65 20 72 65 73 75 6c 74 73 20 72 65 61  have results rea
2cae0 64 79 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20  dy to return.** 
2caf0 28 76 69 61 20 63 61 6c 6c 73 20 74 6f 20 74 68  (via calls to th
2cb00 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e [sqlite3_colum
2cb10 6e 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f  n_int | sqlite3_
2cb20 63 6f 6c 75 6d 6e 5f 2a 28 29 5d 20 6f 66 0a 2a  column_*()] of.*
2cb30 2a 20 69 6e 74 65 72 66 61 63 65 73 29 20 74 68  * interfaces) th
2cb40 65 6e 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  en sqlite3_data_
2cb50 63 6f 75 6e 74 28 50 29 20 72 65 74 75 72 6e 73  count(P) returns
2cb60 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69   0..** ^The sqli
2cb70 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50  te3_data_count(P
2cb80 29 20 72 6f 75 74 69 6e 65 20 61 6c 73 6f 20 72  ) routine also r
2cb90 65 74 75 72 6e 73 20 30 20 69 66 20 50 20 69 73  eturns 0 if P is
2cba0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
2cbb0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2cbc0 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72  _data_count(P) r
2cbd0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30  outine returns 0
2cbe0 20 69 66 20 74 68 65 20 70 72 65 76 69 6f 75 73   if the previous
2cbf0 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
2cc00 69 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72 65  ite3_step](P) re
2cc10 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 44  turned [SQLITE_D
2cc20 4f 4e 45 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69  ONE].  ^The sqli
2cc30 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50  te3_data_count(P
2cc40 29 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75 72 6e  ).** will return
2cc50 20 6e 6f 6e 2d 7a 65 72 6f 20 69 66 20 70 72 65   non-zero if pre
2cc60 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 5b 73  vious call to [s
2cc70 71 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29 20  qlite3_step](P) 
2cc80 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c  returned.** [SQL
2cc90 49 54 45 5f 52 4f 57 5d 2c 20 65 78 63 65 70 74  ITE_ROW], except
2cca0 20 69 6e 20 74 68 65 20 63 61 73 65 20 6f 66 20   in the case of 
2ccb0 74 68 65 20 5b 50 52 41 47 4d 41 20 69 6e 63 72  the [PRAGMA incr
2ccc0 65 6d 65 6e 74 61 6c 5f 76 61 63 75 75 6d 5d 0a  emental_vacuum].
2ccd0 2a 2a 20 77 68 65 72 65 20 69 74 20 61 6c 77 61  ** where it alwa
2cce0 79 73 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20  ys returns zero 
2ccf0 73 69 6e 63 65 20 65 61 63 68 20 73 74 65 70 20  since each step 
2cd00 6f 66 20 74 68 61 74 20 6d 75 6c 74 69 2d 73 74  of that multi-st
2cd10 65 70 0a 2a 2a 20 70 72 61 67 6d 61 20 72 65 74  ep.** pragma ret
2cd20 75 72 6e 73 20 30 20 63 6f 6c 75 6d 6e 73 20 6f  urns 0 columns o
2cd30 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 65  f data..**.** Se
2cd40 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
2cd50 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d  _column_count()]
2cd60 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
2cd70 6e 74 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  nt sqlite3_data_
2cd80 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  count(sqlite3_st
2cd90 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
2cda0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e  ** CAPI3REF: Fun
2cdb0 64 61 6d 65 6e 74 61 6c 20 44 61 74 61 74 79 70  damental Datatyp
2cdc0 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  es.** KEYWORDS: 
2cdd0 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a  SQLITE_TEXT.**.*
2cde0 2a 20 5e 28 45 76 65 72 79 20 76 61 6c 75 65 20  * ^(Every value 
2cdf0 69 6e 20 53 51 4c 69 74 65 20 68 61 73 20 6f 6e  in SQLite has on
2ce00 65 20 6f 66 20 66 69 76 65 20 66 75 6e 64 61 6d  e of five fundam
2ce10 65 6e 74 61 6c 20 64 61 74 61 74 79 70 65 73 3a  ental datatypes:
2ce20 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
2ce30 6c 69 3e 20 36 34 2d 62 69 74 20 73 69 67 6e 65  li> 64-bit signe
2ce40 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69  d integer.** <li
2ce50 3e 20 36 34 2d 62 69 74 20 49 45 45 45 20 66 6c  > 64-bit IEEE fl
2ce60 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d  oating point num
2ce70 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69  ber.** <li> stri
2ce80 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a  ng.** <li> BLOB.
2ce90 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20  ** <li> NULL.** 
2cea0 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  </ul>)^.**.** Th
2ceb0 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ese constants ar
2cec0 65 20 63 6f 64 65 73 20 66 6f 72 20 65 61 63 68  e codes for each
2ced0 20 6f 66 20 74 68 6f 73 65 20 74 79 70 65 73 2e   of those types.
2cee0 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
2cef0 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45 58 54   the SQLITE_TEXT
2cf00 20 63 6f 6e 73 74 61 6e 74 20 77 61 73 20 61 6c   constant was al
2cf10 73 6f 20 75 73 65 64 20 69 6e 20 53 51 4c 69 74  so used in SQLit
2cf20 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66  e version 2.** f
2cf30 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20  or a completely 
2cf40 64 69 66 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e  different meanin
2cf50 67 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68 61  g.  Software tha
2cf60 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20  t links against 
2cf70 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76  both.** SQLite v
2cf80 65 72 73 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c  ersion 2 and SQL
2cf90 69 74 65 20 76 65 72 73 69 6f 6e 20 33 20 73 68  ite version 3 sh
2cfa0 6f 75 6c 64 20 75 73 65 20 53 51 4c 49 54 45 33  ould use SQLITE3
2cfb0 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51  _TEXT, not.** SQ
2cfc0 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64  LITE_TEXT..*/.#d
2cfd0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54  efine SQLITE_INT
2cfe0 45 47 45 52 20 20 31 0a 23 64 65 66 69 6e 65 20  EGER  1.#define 
2cff0 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 20  SQLITE_FLOAT    
2d000 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
2d010 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 66  _BLOB     4.#def
2d020 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20  ine SQLITE_NULL 
2d030 20 20 20 20 35 0a 23 69 66 64 65 66 20 53 51 4c      5.#ifdef SQL
2d040 49 54 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 66  ITE_TEXT.# undef
2d050 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c   SQLITE_TEXT.#el
2d060 73 65 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  se.# define SQLI
2d070 54 45 5f 54 45 58 54 20 20 20 20 20 33 0a 23 65  TE_TEXT     3.#e
2d080 6e 64 69 66 0a 23 64 65 66 69 6e 65 20 53 51 4c  ndif.#define SQL
2d090 49 54 45 33 5f 54 45 58 54 20 20 20 20 20 33 0a  ITE3_TEXT     3.
2d0a0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2d0b0 20 52 65 73 75 6c 74 20 56 61 6c 75 65 73 20 46   Result Values F
2d0c0 72 6f 6d 20 41 20 51 75 65 72 79 0a 2a 2a 20 4b  rom A Query.** K
2d0d0 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e  EYWORDS: {column
2d0e0 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e   access function
2d0f0 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  s}.**.** These r
2d100 6f 75 74 69 6e 65 73 20 66 6f 72 6d 20 74 68 65  outines form the
2d110 20 22 72 65 73 75 6c 74 20 73 65 74 22 20 69 6e   "result set" in
2d120 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e  terface..**.** ^
2d130 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
2d140 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f  eturn informatio
2d150 6e 20 61 62 6f 75 74 20 61 20 73 69 6e 67 6c 65  n about a single
2d160 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63   column of the c
2d170 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74  urrent.** result
2d180 20 72 6f 77 20 6f 66 20 61 20 71 75 65 72 79 2e   row of a query.
2d190 20 20 5e 49 6e 20 65 76 65 72 79 20 63 61 73 65    ^In every case
2d1a0 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
2d1b0 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ent is a pointer
2d1c0 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72 65 70  .** to the [prep
2d1d0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2d1e0 74 68 61 74 20 69 73 20 62 65 69 6e 67 20 65 76  that is being ev
2d1f0 61 6c 75 61 74 65 64 20 28 74 68 65 20 5b 73 71  aluated (the [sq
2d200 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20  lite3_stmt*].** 
2d210 74 68 61 74 20 77 61 73 20 72 65 74 75 72 6e 65  that was returne
2d220 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
2d230 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
2d240 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69   one of its vari
2d250 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65  ants).** and the
2d260 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
2d270 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66   is the index of
2d280 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20   the column for 
2d290 77 68 69 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f  which informatio
2d2a0 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72  n.** should be r
2d2b0 65 74 75 72 6e 65 64 2e 20 5e 54 68 65 20 6c 65  eturned. ^The le
2d2c0 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66  ftmost column of
2d2d0 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
2d2e0 68 61 73 20 74 68 65 20 69 6e 64 65 78 20 30 2e  has the index 0.
2d2f0 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d 62 65 72 20  .** ^The number 
2d300 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68  of columns in th
2d310 65 20 72 65 73 75 6c 74 20 63 61 6e 20 62 65 20  e result can be 
2d320 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67  determined using
2d330 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
2d340 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a  umn_count()]..**
2d350 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73  .** If the SQL s
2d360 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f  tatement does no
2d370 74 20 63 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e  t currently poin
2d380 74 20 74 6f 20 61 20 76 61 6c 69 64 20 72 6f 77  t to a valid row
2d390 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 63  , or if the.** c
2d3a0 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f  olumn index is o
2d3b0 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65  ut of range, the
2d3c0 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66   result is undef
2d3d0 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72  ined..** These r
2d3e0 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79  outines may only
2d3f0 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20   be called when 
2d400 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
2d410 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
2d420 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20  te3_step()] has 
2d430 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45  returned [SQLITE
2d440 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68 65  _ROW] and neithe
2d450 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  r.** [sqlite3_re
2d460 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69  set()] nor [sqli
2d470 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
2d480 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64  have been called
2d490 20 73 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a   subsequently..*
2d4a0 2a 20 49 66 20 61 6e 79 20 6f 66 20 74 68 65 73  * If any of thes
2d4b0 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63  e routines are c
2d4c0 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c  alled after [sql
2d4d0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
2d4e0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  .** [sqlite3_fin
2d4f0 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65  alize()] or afte
2d500 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  r [sqlite3_step(
2d510 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 0a  )] has returned.
2d520 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68  ** something oth
2d530 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
2d540 52 4f 57 5d 2c 20 74 68 65 20 72 65 73 75 6c 74  ROW], the result
2d550 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
2d560 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 5f  .** If [sqlite3_
2d570 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69  step()] or [sqli
2d580 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20  te3_reset()] or 
2d590 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
2d5a0 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c  e()].** are call
2d5b0 65 64 20 66 72 6f 6d 20 61 20 64 69 66 66 65 72  ed from a differ
2d5c0 65 6e 74 20 74 68 72 65 61 64 20 77 68 69 6c 65  ent thread while
2d5d0 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f   any of these ro
2d5e0 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65  utines.** are pe
2d5f0 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20  nding, then the 
2d600 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
2d610 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  fined..**.** ^Th
2d620 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
2d630 5f 74 79 70 65 28 29 20 72 6f 75 74 69 6e 65 20  _type() routine 
2d640 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b  returns the.** [
2d650 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c  SQLITE_INTEGER |
2d660 20 64 61 74 61 74 79 70 65 20 63 6f 64 65 5d 20   datatype code] 
2d670 66 6f 72 20 74 68 65 20 69 6e 69 74 69 61 6c 20  for the initial 
2d680 64 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20  data type.** of 
2d690 74 68 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  the result colum
2d6a0 6e 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65  n.  ^The returne
2d6b0 64 20 76 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f  d value is one o
2d6c0 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  f [SQLITE_INTEGE
2d6d0 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46  R],.** [SQLITE_F
2d6e0 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54  LOAT], [SQLITE_T
2d6f0 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c  EXT], [SQLITE_BL
2d700 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  OB], or [SQLITE_
2d710 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75  NULL].  The valu
2d720 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79  e.** returned by
2d730 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2d740 74 79 70 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d  type() is only m
2d750 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20  eaningful if no 
2d760 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69  type.** conversi
2d770 6f 6e 73 20 68 61 76 65 20 6f 63 63 75 72 72 65  ons have occurre
2d780 64 20 61 73 20 64 65 73 63 72 69 62 65 64 20 62  d as described b
2d790 65 6c 6f 77 2e 20 20 41 66 74 65 72 20 61 20 74  elow.  After a t
2d7a0 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a  ype conversion,.
2d7b0 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  ** the value ret
2d7c0 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
2d7d0 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69  _column_type() i
2d7e0 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 46 75  s undefined.  Fu
2d7f0 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73  ture.** versions
2d800 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 63   of SQLite may c
2d810 68 61 6e 67 65 20 74 68 65 20 62 65 68 61 76 69  hange the behavi
2d820 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f  or of sqlite3_co
2d830 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66  lumn_type().** f
2d840 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70 65 20  ollowing a type 
2d850 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a  conversion..**.*
2d860 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
2d870 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54   is a BLOB or UT
2d880 46 2d 38 20 73 74 72 69 6e 67 20 74 68 65 6e 20  F-8 string then 
2d890 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  the sqlite3_colu
2d8a0 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f  mn_bytes().** ro
2d8b0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
2d8c0 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
2d8d0 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f  s in that BLOB o
2d8e0 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66  r string..** ^If
2d8f0 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
2d900 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2c 20   UTF-16 string, 
2d910 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
2d920 75 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e 76  umn_bytes() conv
2d930 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69  erts.** the stri
2d940 6e 67 20 74 6f 20 55 54 46 2d 38 20 61 6e 64 20  ng to UTF-8 and 
2d950 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65  then returns the
2d960 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
2d970 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
2d980 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63  ult is a numeric
2d990 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69   value then sqli
2d9a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2d9b0 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69  () uses.** [sqli
2d9c0 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20  te3_snprintf()] 
2d9d0 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20  to convert that 
2d9e0 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 38  value to a UTF-8
2d9f0 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75   string and retu
2da00 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65  rns.** the numbe
2da10 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
2da20 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49  at string..** ^I
2da30 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
2da40 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74  NULL, then sqlit
2da50 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2da60 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a  ) returns zero..
2da70 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  **.** ^If the re
2da80 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f  sult is a BLOB o
2da90 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20  r UTF-16 string 
2daa0 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33  then the sqlite3
2dab0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
2dac0 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74  ).** routine ret
2dad0 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
2dae0 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74  of bytes in that
2daf0 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e   BLOB or string.
2db00 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
2db10 6c 74 20 69 73 20 61 20 55 54 46 2d 38 20 73 74  lt is a UTF-8 st
2db20 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74  ring, then sqlit
2db30 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
2db40 36 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20  6() converts.** 
2db50 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54  the string to UT
2db60 46 2d 31 36 20 61 6e 64 20 74 68 65 6e 20 72 65  F-16 and then re
2db70 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
2db80 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49   of bytes..** ^I
2db90 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
2dba0 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20  a numeric value 
2dbb0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
2dbc0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 75 73  umn_bytes16() us
2dbd0 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  es.** [sqlite3_s
2dbe0 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f  nprintf()] to co
2dbf0 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 65  nvert that value
2dc00 20 74 6f 20 61 20 55 54 46 2d 31 36 20 73 74 72   to a UTF-16 str
2dc10 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a  ing and returns.
2dc20 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
2dc30 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 73   bytes in that s
2dc40 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68  tring..** ^If th
2dc50 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c  e result is NULL
2dc60 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  , then sqlite3_c
2dc70 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
2dc80 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a  returns zero..**
2dc90 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 73 20  .** ^The values 
2dca0 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
2dcb0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2dcc0 73 28 29 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73 71  s()] and .** [sq
2dcd0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2dce0 65 73 31 36 28 29 5d 20 64 6f 20 6e 6f 74 20 69  es16()] do not i
2dcf0 6e 63 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20  nclude the zero 
2dd00 74 65 72 6d 69 6e 61 74 6f 72 73 20 61 74 20 74  terminators at t
2dd10 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65  he end.** of the
2dd20 20 73 74 72 69 6e 67 2e 20 20 5e 46 6f 72 20 63   string.  ^For c
2dd30 6c 61 72 69 74 79 3a 20 74 68 65 20 76 61 6c 75  larity: the valu
2dd40 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  es returned by.*
2dd50 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
2dd60 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20 5b  n_bytes()] and [
2dd70 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2dd80 79 74 65 73 31 36 28 29 5d 20 61 72 65 20 74 68  ytes16()] are th
2dd90 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62  e number of.** b
2dda0 79 74 65 73 20 69 6e 20 74 68 65 20 73 74 72 69  ytes in the stri
2ddb0 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62  ng, not the numb
2ddc0 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73  er of characters
2ddd0 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67 73  ..**.** ^Strings
2dde0 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
2ddf0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2de00 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  () and sqlite3_c
2de10 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a  olumn_text16(),.
2de20 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79 20 73 74  ** even empty st
2de30 72 69 6e 67 73 2c 20 61 72 65 20 61 6c 77 61 79  rings, are alway
2de40 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  s zero-terminate
2de50 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 0a  d.  ^The return.
2de60 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71  ** value from sq
2de70 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
2de80 62 28 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c  b() for a zero-l
2de90 65 6e 67 74 68 20 42 4c 4f 42 20 69 73 20 61 20  ength BLOB is a 
2dea0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
2deb0 0a 2a 2a 20 5e 54 68 65 20 6f 62 6a 65 63 74 20  .** ^The object 
2dec0 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
2ded0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
2dee0 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75  e()] is an.** [u
2def0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
2df00 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
2df10 2e 20 20 41 6e 20 75 6e 70 72 6f 74 65 63 74 65  .  An unprotecte
2df20 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  d sqlite3_value 
2df30 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e  object.** may on
2df40 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68 20  ly be used with 
2df50 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61  [sqlite3_bind_va
2df60 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  lue()] and [sqli
2df70 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
2df80 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b  ()]..** If the [
2df90 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
2dfa0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
2dfb0 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  t returned by.**
2dfc0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2dfd0 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 73 65  _value()] is use
2dfe0 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 72 20 77  d in any other w
2dff0 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63 61  ay, including ca
2e000 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e  lls.** to routin
2e010 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33  es like [sqlite3
2e020 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b  _value_int()], [
2e030 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
2e040 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71  xt()],.** or [sq
2e050 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
2e060 73 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 62  s()], then the b
2e070 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66  ehavior is undef
2e080 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ined..**.** Thes
2e090 65 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d  e routines attem
2e0a0 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68  pt to convert th
2e0b0 65 20 76 61 6c 75 65 20 77 68 65 72 65 20 61 70  e value where ap
2e0c0 70 72 6f 70 72 69 61 74 65 2e 20 20 5e 46 6f 72  propriate.  ^For
2e0d0 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66 20  .** example, if 
2e0e0 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70  the internal rep
2e0f0 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 46  resentation is F
2e100 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 78 74 20  LOAT and a text 
2e110 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71  result.** is req
2e120 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 33  uested, [sqlite3
2e130 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 20  _snprintf()] is 
2e140 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20  used internally 
2e150 74 6f 20 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a  to perform the.*
2e160 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74  * conversion aut
2e170 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 5e 28 54  omatically.  ^(T
2e180 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62  he following tab
2e190 6c 65 20 64 65 74 61 69 6c 73 20 74 68 65 20 63  le details the c
2e1a0 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68  onversions.** th
2e1b0 61 74 20 61 72 65 20 61 70 70 6c 69 65 64 3a 0a  at are applied:.
2e1c0 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
2e1d0 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72  e>.** <table bor
2e1e0 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e  der="1">.** <tr>
2e1f0 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72  <th> Internal<br
2e200 3e 54 79 70 65 20 3c 74 68 3e 20 52 65 71 75 65  >Type <th> Reque
2e210 73 74 65 64 3c 62 72 3e 54 79 70 65 20 3c 74 68  sted<br>Type <th
2e220 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a  >  Conversion.**
2e230 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
2e240 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  LL    <td> INTEG
2e250 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  ER   <td> Result
2e260 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64   is 0.** <tr><td
2e270 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
2e280 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 52   FLOAT    <td> R
2e290 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20  esult is 0.0.** 
2e2a0 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
2e2b0 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20    <td>   TEXT   
2e2c0 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
2e2d0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  a NULL pointer.*
2e2e0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
2e2f0 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20      <td>   BLOB 
2e300 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
2e310 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
2e320 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54  .** <tr><td> INT
2e330 45 47 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41  EGER  <td>  FLOA
2e340 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72  T    <td> Conver
2e350 74 20 66 72 6f 6d 20 69 6e 74 65 67 65 72 20 74  t from integer t
2e360 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c  o float.** <tr><
2e370 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64  td> INTEGER  <td
2e380 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  >   TEXT    <td>
2e390 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67   ASCII rendering
2e3a0 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65 72 0a   of the integer.
2e3b0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45  ** <tr><td> INTE
2e3c0 47 45 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42  GER  <td>   BLOB
2e3d0 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73      <td> Same as
2e3e0 20 49 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a   INTEGER->TEXT.*
2e3f0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41  * <tr><td>  FLOA
2e400 54 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52  T   <td> INTEGER
2e410 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74     <td> [CAST] t
2e420 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72  o INTEGER.** <tr
2e430 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c  ><td>  FLOAT   <
2e440 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
2e450 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69  d> ASCII renderi
2e460 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a  ng of the float.
2e470 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f  ** <tr><td>  FLO
2e480 41 54 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42  AT   <td>   BLOB
2e490 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20      <td> [CAST] 
2e4a0 74 6f 20 42 4c 4f 42 0a 2a 2a 20 3c 74 72 3e 3c  to BLOB.** <tr><
2e4b0 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64  td>  TEXT    <td
2e4c0 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e  > INTEGER   <td>
2e4d0 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47   [CAST] to INTEG
2e4e0 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ER.** <tr><td>  
2e4f0 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 46 4c  TEXT    <td>  FL
2e500 4f 41 54 20 20 20 20 3c 74 64 3e 20 5b 43 41 53  OAT    <td> [CAS
2e510 54 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74  T] to REAL.** <t
2e520 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20  r><td>  TEXT    
2e530 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c  <td>   BLOB    <
2e540 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a  td> No change.**
2e550 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20   <tr><td>  BLOB 
2e560 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20     <td> INTEGER 
2e570 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f    <td> [CAST] to
2e580 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e   INTEGER.** <tr>
2e590 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74  <td>  BLOB    <t
2e5a0 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64  d>  FLOAT    <td
2e5b0 3e 20 5b 43 41 53 54 5d 20 74 6f 20 52 45 41 4c  > [CAST] to REAL
2e5c0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c  .** <tr><td>  BL
2e5d0 4f 42 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58  OB    <td>   TEX
2e5e0 54 20 20 20 20 3c 74 64 3e 20 41 64 64 20 61 20  T    <td> Add a 
2e5f0 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20  zero terminator 
2e600 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74  if needed.** </t
2e610 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b  able>.** </block
2e620 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54  quote>)^.**.** T
2e630 68 65 20 74 61 62 6c 65 20 61 62 6f 76 65 20 6d  he table above m
2e640 61 6b 65 73 20 72 65 66 65 72 65 6e 63 65 20 74  akes reference t
2e650 6f 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62  o standard C lib
2e660 72 61 72 79 20 66 75 6e 63 74 69 6f 6e 73 20 61  rary functions a
2e670 74 6f 69 28 29 0a 2a 2a 20 61 6e 64 20 61 74 6f  toi().** and ato
2e680 66 28 29 2e 20 20 53 51 4c 69 74 65 20 64 6f 65  f().  SQLite doe
2e690 73 20 6e 6f 74 20 72 65 61 6c 6c 79 20 75 73 65  s not really use
2e6a0 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
2e6b0 2e 20 20 49 74 20 68 61 73 20 69 74 73 0a 2a 2a  .  It has its.**
2e6c0 20 6f 77 6e 20 65 71 75 69 76 61 6c 65 6e 74 20   own equivalent 
2e6d0 69 6e 74 65 72 6e 61 6c 20 72 6f 75 74 69 6e 65  internal routine
2e6e0 73 2e 20 20 54 68 65 20 61 74 6f 69 28 29 20 61  s.  The atoi() a
2e6f0 6e 64 20 61 74 6f 66 28 29 20 6e 61 6d 65 73 20  nd atof() names 
2e700 61 72 65 0a 2a 2a 20 75 73 65 64 20 69 6e 20 74  are.** used in t
2e710 68 65 20 74 61 62 6c 65 20 66 6f 72 20 62 72 65  he table for bre
2e720 76 69 74 79 20 61 6e 64 20 62 65 63 61 75 73 65  vity and because
2e730 20 74 68 65 79 20 61 72 65 20 66 61 6d 69 6c 69   they are famili
2e740 61 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20  ar to most.** C 
2e750 70 72 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a  programmers..**.
2e760 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 77 68 65  ** Note that whe
2e770 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  n type conversio
2e780 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65  ns occur, pointe
2e790 72 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 70  rs returned by p
2e7a0 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f  rior.** calls to
2e7b0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2e7c0 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f  blob(), sqlite3_
2e7d0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61  column_text(), a
2e7e0 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  nd/or.** sqlite3
2e7f0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
2e800 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 69 64 61   may be invalida
2e810 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e  ted..** Type con
2e820 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69  versions and poi
2e830 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f  nter invalidatio
2e840 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a  ns might occur.*
2e850 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69  * in the followi
2e860 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20  ng cases:.**.** 
2e870 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  <ul>.** <li> The
2e880 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74   initial content
2e890 20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 73   is a BLOB and s
2e8a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2e8b0 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20  xt() or.**      
2e8c0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2e8d0 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65  ext16() is calle
2e8e0 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69  d.  A zero-termi
2e8f0 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20  nator might.**  
2e900 20 20 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61      need to be a
2e910 64 64 65 64 20 74 6f 20 74 68 65 20 73 74 72 69  dded to the stri
2e920 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e  ng.</li>.** <li>
2e930 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e   The initial con
2e940 74 65 6e 74 20 69 73 20 55 54 46 2d 38 20 74 65  tent is UTF-8 te
2e950 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  xt and sqlite3_c
2e960 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
2e970 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74  or.**      sqlit
2e980 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
2e990 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54  () is called.  T
2e9a0 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20  he content must 
2e9b0 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20  be converted.** 
2e9c0 20 20 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c       to UTF-16.<
2e9d0 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  /li>.** <li> The
2e9e0 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74   initial content
2e9f0 20 69 73 20 55 54 46 2d 31 36 20 74 65 78 74 20   is UTF-16 text 
2ea00 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
2ea10 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a  mn_bytes() or.**
2ea20 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f        sqlite3_co
2ea30 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 63  lumn_text() is c
2ea40 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74  alled.  The cont
2ea50 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76  ent must be conv
2ea60 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f  erted.**      to
2ea70 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20   UTF-8.</li>.** 
2ea80 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e  </ul>.**.** ^Con
2ea90 76 65 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e  versions between
2eaa0 20 55 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54   UTF-16be and UT
2eab0 46 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79  F-16le are alway
2eac0 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20  s done in place 
2ead0 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e  and do.** not in
2eae0 76 61 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72  validate a prior
2eaf0 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68   pointer, though
2eb00 20 6f 66 20 63 6f 75 72 73 65 20 74 68 65 20 63   of course the c
2eb10 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75  ontent of the bu
2eb20 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65  ffer.** that the
2eb30 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 72   prior pointer r
2eb40 65 66 65 72 65 6e 63 65 73 20 77 69 6c 6c 20 68  eferences will h
2eb50 61 76 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65  ave been modifie
2eb60 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a  d.  Other kinds.
2eb70 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e  ** of conversion
2eb80 20 61 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61   are done in pla
2eb90 63 65 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f  ce when it is po
2eba0 73 73 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65  ssible, but some
2ebb0 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61 72  times they.** ar
2ebc0 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61  e not possible a
2ebd0 6e 64 20 69 6e 20 74 68 6f 73 65 20 63 61 73 65  nd in those case
2ebe0 73 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 73  s prior pointers
2ebf0 20 61 72 65 20 69 6e 76 61 6c 69 64 61 74 65 64   are invalidated
2ec00 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65  ..**.** The safe
2ec10 73 74 20 61 6e 64 20 65 61 73 69 65 73 74 20 74  st and easiest t
2ec20 6f 20 72 65 6d 65 6d 62 65 72 20 70 6f 6c 69 63  o remember polic
2ec30 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74  y is to invoke t
2ec40 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a  hese routines.**
2ec50 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 66   in one of the f
2ec60 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a  ollowing ways:.*
2ec70 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c  *.** <ul>.**  <l
2ec80 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  i>sqlite3_column
2ec90 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64  _text() followed
2eca0 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
2ecb0 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a  mn_bytes()</li>.
2ecc0 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f  **  <li>sqlite3_
2ecd0 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f  column_blob() fo
2ece0 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65  llowed by sqlite
2ecf0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
2ed00 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71  </li>.**  <li>sq
2ed10 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2ed20 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62  t16() followed b
2ed30 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
2ed40 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a  _bytes16()</li>.
2ed50 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49  ** </ul>.**.** I
2ed60 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 79  n other words, y
2ed70 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73  ou should call s
2ed80 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2ed90 78 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33  xt(),.** sqlite3
2eda0 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20  _column_blob(), 
2edb0 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  or sqlite3_colum
2edc0 6e 5f 74 65 78 74 31 36 28 29 20 66 69 72 73 74  n_text16() first
2edd0 20 74 6f 20 66 6f 72 63 65 20 74 68 65 20 72 65   to force the re
2ede0 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65  sult.** into the
2edf0 20 64 65 73 69 72 65 64 20 66 6f 72 6d 61 74 2c   desired format,
2ee00 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c   then invoke sql
2ee10 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2ee20 73 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  s() or.** sqlite
2ee30 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
2ee40 28 29 20 74 6f 20 66 69 6e 64 20 74 68 65 20 73  () to find the s
2ee50 69 7a 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c  ize of the resul
2ee60 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63  t.  Do not mix c
2ee70 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74  alls.** to sqlit
2ee80 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
2ee90 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   or sqlite3_colu
2eea0 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68 20 63  mn_blob() with c
2eeb0 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  alls to.** sqlit
2eec0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
2eed0 36 28 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20  6(), and do not 
2eee0 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  mix calls to sql
2eef0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2ef00 31 36 28 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c  16().** with cal
2ef10 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ls to sqlite3_co
2ef20 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a  lumn_bytes()..**
2ef30 0a 2a 2a 20 5e 54 68 65 20 70 6f 69 6e 74 65 72  .** ^The pointer
2ef40 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 76  s returned are v
2ef50 61 6c 69 64 20 75 6e 74 69 6c 20 61 20 74 79 70  alid until a typ
2ef60 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63  e conversion occ
2ef70 75 72 73 20 61 73 0a 2a 2a 20 64 65 73 63 72 69  urs as.** descri
2ef80 62 65 64 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e  bed above, or un
2ef90 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  til [sqlite3_ste
2efa0 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  p()] or [sqlite3
2efb0 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20  _reset()] or.** 
2efc0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
2efd0 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20  e()] is called. 
2efe0 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 73 70 61   ^The memory spa
2eff0 63 65 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20  ce used to hold 
2f000 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42  strings.** and B
2f010 4c 4f 42 73 20 69 73 20 66 72 65 65 64 20 61 75  LOBs is freed au
2f020 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f  tomatically.  Do
2f030 20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73 73   <b>not</b> pass
2f040 20 74 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65   the pointers re
2f050 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  turned.** from [
2f060 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2f070 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  lob()], [sqlite3
2f080 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c  _column_text()],
2f090 20 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73   etc. into.** [s
2f0a0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a  qlite3_free()]..
2f0b0 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 20 6d 65 6d  **.** ^(If a mem
2f0c0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65  ory allocation e
2f0d0 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69  rror occurs duri
2f0e0 6e 67 20 74 68 65 20 65 76 61 6c 75 61 74 69 6f  ng the evaluatio
2f0f0 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74  n of any.** of t
2f100 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 61  hese routines, a
2f110 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 69   default value i
2f120 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65  s returned.  The
2f130 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a   default value.*
2f140 2a 20 69 73 20 65 69 74 68 65 72 20 74 68 65 20  * is either the 
2f150 69 6e 74 65 67 65 72 20 30 2c 20 74 68 65 20 66  integer 0, the f
2f160 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75  loating point nu
2f170 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e  mber 0.0, or a N
2f180 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20  ULL.** pointer. 
2f190 20 53 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   Subsequent call
2f1a0 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72  s to [sqlite3_er
2f1b0 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72 65  rcode()] will re
2f1c0 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  turn.** [SQLITE_
2f1d0 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a 53 51 4c  NOMEM].)^.*/.SQL
2f1e0 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f  ITE_API const vo
2f1f0 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
2f200 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  mn_blob(sqlite3_
2f210 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
2f220 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
2f230 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2f240 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 73 74  bytes(sqlite3_st
2f250 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
2f260 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
2f270 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2f280 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f 73 74  tes16(sqlite3_st
2f290 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
2f2a0 53 51 4c 49 54 45 5f 41 50 49 20 64 6f 75 62 6c  SQLITE_API doubl
2f2b0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
2f2c0 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f  _double(sqlite3_
2f2d0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
2f2e0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
2f2f0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2f300 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  int(sqlite3_stmt
2f310 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51  *, int iCol);.SQ
2f320 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33  LITE_API sqlite3
2f330 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 63  _int64 sqlite3_c
2f340 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c 69  olumn_int64(sqli
2f350 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
2f360 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  Col);.SQLITE_API
2f370 20 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20   const unsigned 
2f380 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
2f390 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 65  lumn_text(sqlite
2f3a0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
2f3b0 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  l);.SQLITE_API c
2f3c0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
2f3d0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
2f3e0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2f3f0 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54  int iCol);.SQLIT
2f400 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
2f410 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71  3_column_type(sq
2f420 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2f430 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41   iCol);.SQLITE_A
2f440 50 49 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  PI sqlite3_value
2f450 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2f460 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73  _value(sqlite3_s
2f470 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
2f480 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2f490 3a 20 44 65 73 74 72 6f 79 20 41 20 50 72 65 70  : Destroy A Prep
2f4a0 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f  ared Statement O
2f4b0 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  bject.**.** ^The
2f4c0 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
2f4d0 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  e() function is 
2f4e0 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74 65  called to delete
2f4f0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
2f500 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20  tement]..** ^If 
2f510 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
2f520 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 74 68  evaluation of th
2f530 65 20 73 74 61 74 65 6d 65 6e 74 20 65 6e 63 6f  e statement enco
2f540 75 6e 74 65 72 65 64 20 6e 6f 20 65 72 72 6f 72  untered no error
2f550 73 0a 2a 2a 20 6f 72 20 69 66 20 74 68 65 20 73  s.** or if the s
2f560 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 65 76 65  tatement is neve
2f570 72 20 62 65 65 6e 20 65 76 61 6c 75 61 74 65 64  r been evaluated
2f580 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 66  , then sqlite3_f
2f590 69 6e 61 6c 69 7a 65 28 29 20 72 65 74 75 72 6e  inalize() return
2f5a0 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 2e 20  s.** SQLITE_OK. 
2f5b0 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65   ^If the most re
2f5c0 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20  cent evaluation 
2f5d0 6f 66 20 73 74 61 74 65 6d 65 6e 74 20 53 20 66  of statement S f
2f5e0 61 69 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 73  ailed, then.** s
2f5f0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2f600 53 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 61  S) returns the a
2f610 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f  ppropriate [erro
2f620 72 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65  r code] or.** [e
2f630 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f  xtended error co
2f640 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  de]..**.** ^The 
2f650 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2f660 28 53 29 20 72 6f 75 74 69 6e 65 20 63 61 6e 20  (S) routine can 
2f670 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61 6e 79  be called at any
2f680 20 70 6f 69 6e 74 20 64 75 72 69 6e 67 0a 2a 2a   point during.**
2f690 20 74 68 65 20 6c 69 66 65 20 63 79 63 6c 65 20   the life cycle 
2f6a0 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  of [prepared sta
2f6b0 74 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20 62 65  tement] S:.** be
2f6c0 66 6f 72 65 20 73 74 61 74 65 6d 65 6e 74 20 53  fore statement S
2f6d0 20 69 73 20 65 76 65 72 20 65 76 61 6c 75 61 74   is ever evaluat
2f6e0 65 64 2c 20 61 66 74 65 72 0a 2a 2a 20 6f 6e 65  ed, after.** one
2f6f0 20 6f 72 20 6d 6f 72 65 20 63 61 6c 6c 73 20 74   or more calls t
2f700 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  o [sqlite3_reset
2f710 28 29 5d 2c 20 6f 72 20 61 66 74 65 72 20 61 6e  ()], or after an
2f720 79 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71  y call.** to [sq
2f730 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65  lite3_step()] re
2f740 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74  gardless of whet
2f750 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 73  her or not the s
2f760 74 61 74 65 6d 65 6e 74 20 68 61 73 0a 2a 2a 20  tatement has.** 
2f770 63 6f 6d 70 6c 65 74 65 64 20 65 78 65 63 75 74  completed execut
2f780 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f  ion..**.** ^Invo
2f790 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 69 6e  king sqlite3_fin
2f7a0 61 6c 69 7a 65 28 29 20 6f 6e 20 61 20 4e 55 4c  alize() on a NUL
2f7b0 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 61 20 68  L pointer is a h
2f7c0 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a  armless no-op..*
2f7d0 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  *.** The applica
2f7e0 74 69 6f 6e 20 6d 75 73 74 20 66 69 6e 61 6c 69  tion must finali
2f7f0 7a 65 20 65 76 65 72 79 20 5b 70 72 65 70 61 72  ze every [prepar
2f800 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e  ed statement] in
2f810 20 6f 72 64 65 72 20 74 6f 20 61 76 6f 69 64 0a   order to avoid.
2f820 2a 2a 20 72 65 73 6f 75 72 63 65 20 6c 65 61 6b  ** resource leak
2f830 73 2e 20 20 49 74 20 69 73 20 61 20 67 72 69 65  s.  It is a grie
2f840 76 6f 75 73 20 65 72 72 6f 72 20 66 6f 72 20 74  vous error for t
2f850 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74  he application t
2f860 6f 20 74 72 79 20 74 6f 20 75 73 65 0a 2a 2a 20  o try to use.** 
2f870 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  a prepared state
2f880 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20 68 61  ment after it ha
2f890 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64  s been finalized
2f8a0 2e 20 20 41 6e 79 20 75 73 65 20 6f 66 20 61 20  .  Any use of a 
2f8b0 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74  prepared.** stat
2f8c0 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20 68  ement after it h
2f8d0 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65  as been finalize
2f8e0 64 20 63 61 6e 20 72 65 73 75 6c 74 20 69 6e 20  d can result in 
2f8f0 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 0a 2a 2a  undefined and.**
2f900 20 75 6e 64 65 73 69 72 61 62 6c 65 20 62 65 68   undesirable beh
2f910 61 76 69 6f 72 20 73 75 63 68 20 61 73 20 73 65  avior such as se
2f920 67 66 61 75 6c 74 73 20 61 6e 64 20 68 65 61 70  gfaults and heap
2f930 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a   corruption..*/.
2f940 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
2f950 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2f960 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
2f970 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
2f980 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 20 50  I3REF: Reset A P
2f990 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
2f9a0 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54  t Object.**.** T
2f9b0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74  he sqlite3_reset
2f9c0 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63  () function is c
2f9d0 61 6c 6c 65 64 20 74 6f 20 72 65 73 65 74 20 61  alled to reset a
2f9e0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2f9f0 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20  ment].** object 
2fa00 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74  back to its init
2fa10 69 61 6c 20 73 74 61 74 65 2c 20 72 65 61 64 79  ial state, ready
2fa20 20 74 6f 20 62 65 20 72 65 2d 65 78 65 63 75 74   to be re-execut
2fa30 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c 20  ed..** ^Any SQL 
2fa40 73 74 61 74 65 6d 65 6e 74 20 76 61 72 69 61 62  statement variab
2fa50 6c 65 73 20 74 68 61 74 20 68 61 64 20 76 61 6c  les that had val
2fa60 75 65 73 20 62 6f 75 6e 64 20 74 6f 20 74 68 65  ues bound to the
2fa70 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b  m using.** the [
2fa80 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
2fa90 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  b | sqlite3_bind
2faa0 5f 2a 28 29 20 41 50 49 5d 20 72 65 74 61 69 6e  _*() API] retain
2fab0 20 74 68 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a   their values..*
2fac0 2a 20 55 73 65 20 5b 73 71 6c 69 74 65 33 5f 63  * Use [sqlite3_c
2fad0 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d  lear_bindings()]
2fae0 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 62 69   to reset the bi
2faf0 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ndings..**.** ^T
2fb00 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  he [sqlite3_rese
2fb10 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20  t(S)] interface 
2fb20 72 65 73 65 74 73 20 74 68 65 20 5b 70 72 65 70  resets the [prep
2fb30 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2fb40 53 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 74 68 65  S.** back to the
2fb50 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74   beginning of it
2fb60 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a  s program..**.**
2fb70 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65   ^If the most re
2fb80 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  cent call to [sq
2fb90 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66  lite3_step(S)] f
2fba0 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  or the.** [prepa
2fbb0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
2fbc0 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54   returned [SQLIT
2fbd0 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54  E_ROW] or [SQLIT
2fbe0 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20 69  E_DONE],.** or i
2fbf0 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  f [sqlite3_step(
2fc00 53 29 5d 20 68 61 73 20 6e 65 76 65 72 20 62 65  S)] has never be
2fc10 66 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c 65 64  fore been called
2fc20 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e 20 5b   on S,.** then [
2fc30 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
2fc40 5d 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  ] returns [SQLIT
2fc50 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  E_OK]..**.** ^If
2fc60 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
2fc70 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
2fc80 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74  3_step(S)] for t
2fc90 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
2fca0 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64  statement] S ind
2fcb0 69 63 61 74 65 64 20 61 6e 20 65 72 72 6f 72 2c  icated an error,
2fcc0 20 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65   then.** [sqlite
2fcd0 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75  3_reset(S)] retu
2fce0 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 72 69 61  rns an appropria
2fcf0 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e  te [error code].
2fd00 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c  .**.** ^The [sql
2fd10 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69  ite3_reset(S)] i
2fd20 6e 74 65 72 66 61 63 65 20 64 6f 65 73 20 6e 6f  nterface does no
2fd30 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c  t change the val
2fd40 75 65 73 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b 73  ues.** of any [s
2fd50 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
2fd60 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68  |bindings] on th
2fd70 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
2fd80 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 53 51 4c  ement] S..*/.SQL
2fd90 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
2fda0 74 65 33 5f 72 65 73 65 74 28 73 71 6c 69 74 65  te3_reset(sqlite
2fdb0 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
2fdc0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2fdd0 20 43 72 65 61 74 65 20 4f 72 20 52 65 64 65 66   Create Or Redef
2fde0 69 6e 65 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e  ine SQL Function
2fdf0 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
2fe00 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f  function creatio
2fe10 6e 20 72 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b  n routines}.** K
2fe20 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63  EYWORDS: {applic
2fe30 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
2fe40 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b  L function}.** K
2fe50 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63  EYWORDS: {applic
2fe60 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
2fe70 4c 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a  L functions}.**.
2fe80 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69  ** ^These functi
2fe90 6f 6e 73 20 28 63 6f 6c 6c 65 63 74 69 76 65 6c  ons (collectivel
2fea0 79 20 6b 6e 6f 77 6e 20 61 73 20 22 66 75 6e 63  y known as "func
2feb0 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f  tion creation ro
2fec0 75 74 69 6e 65 73 22 29 0a 2a 2a 20 61 72 65 20  utines").** are 
2fed0 75 73 65 64 20 74 6f 20 61 64 64 20 53 51 4c 20  used to add SQL 
2fee0 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67  functions or agg
2fef0 72 65 67 61 74 65 73 20 6f 72 20 74 6f 20 72 65  regates or to re
2ff00 64 65 66 69 6e 65 20 74 68 65 20 62 65 68 61 76  define the behav
2ff10 69 6f 72 0a 2a 2a 20 6f 66 20 65 78 69 73 74 69  ior.** of existi
2ff20 6e 67 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ng SQL functions
2ff30 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 2e 20   or aggregates. 
2ff40 20 54 68 65 20 6f 6e 6c 79 20 64 69 66 66 65 72   The only differ
2ff50 65 6e 63 65 73 20 62 65 74 77 65 65 6e 0a 2a 2a  ences between.**
2ff60 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
2ff70 61 72 65 20 74 68 65 20 74 65 78 74 20 65 6e 63  are the text enc
2ff80 6f 64 69 6e 67 20 65 78 70 65 63 74 65 64 20 66  oding expected f
2ff90 6f 72 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64  or.** the second
2ffa0 20 70 61 72 61 6d 65 74 65 72 20 28 74 68 65 20   parameter (the 
2ffb0 6e 61 6d 65 20 6f 66 20 74 68 65 20 66 75 6e 63  name of the func
2ffc0 74 69 6f 6e 20 62 65 69 6e 67 20 63 72 65 61 74  tion being creat
2ffd0 65 64 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 70  ed).** and the p
2ffe0 72 65 73 65 6e 63 65 20 6f 72 20 61 62 73 65 6e  resence or absen
2fff0 63 65 20 6f 66 20 61 20 64 65 73 74 72 75 63 74  ce of a destruct
30000 6f 72 20 63 61 6c 6c 62 61 63 6b 20 66 6f 72 0a  or callback for.
30010 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
30020 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e  on data pointer.
30030 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
30040 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  t parameter is t
30050 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
30060 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77 68 69 63  nection] to whic
30070 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e  h the SQL.** fun
30080 63 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 20 61  ction is to be a
30090 64 64 65 64 2e 20 20 5e 49 66 20 61 6e 20 61 70  dded.  ^If an ap
300a0 70 6c 69 63 61 74 69 6f 6e 20 75 73 65 73 20 6d  plication uses m
300b0 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 64 61 74  ore than one dat
300c0 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
300d0 69 6f 6e 20 74 68 65 6e 20 61 70 70 6c 69 63 61  ion then applica
300e0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
300f0 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75 73 74 20   functions must 
30100 62 65 20 61 64 64 65 64 0a 2a 2a 20 74 6f 20 65  be added.** to e
30110 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ach database con
30120 6e 65 63 74 69 6f 6e 20 73 65 70 61 72 61 74 65  nection separate
30130 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ly..**.** ^The s
30140 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
30150 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
30160 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
30170 74 6f 20 62 65 20 63 72 65 61 74 65 64 20 6f 72  to be created or
30180 0a 2a 2a 20 72 65 64 65 66 69 6e 65 64 2e 20 20  .** redefined.  
30190 5e 54 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74  ^The length of t
301a0 68 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74  he name is limit
301b0 65 64 20 74 6f 20 32 35 35 20 62 79 74 65 73 20  ed to 255 bytes 
301c0 69 6e 20 61 20 55 54 46 2d 38 0a 2a 2a 20 72 65  in a UTF-8.** re
301d0 70 72 65 73 65 6e 74 61 74 69 6f 6e 2c 20 65 78  presentation, ex
301e0 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65 20 7a  clusive of the z
301f0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 20  ero-terminator. 
30200 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20   ^Note that the 
30210 6e 61 6d 65 0a 2a 2a 20 6c 65 6e 67 74 68 20 6c  name.** length l
30220 69 6d 69 74 20 69 73 20 69 6e 20 55 54 46 2d 38  imit is in UTF-8
30230 20 62 79 74 65 73 2c 20 6e 6f 74 20 63 68 61 72   bytes, not char
30240 61 63 74 65 72 73 20 6e 6f 72 20 55 54 46 2d 31  acters nor UTF-1
30250 36 20 62 79 74 65 73 2e 20 20 0a 2a 2a 20 5e 41  6 bytes.  .** ^A
30260 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63 72  ny attempt to cr
30270 65 61 74 65 20 61 20 66 75 6e 63 74 69 6f 6e 20  eate a function 
30280 77 69 74 68 20 61 20 6c 6f 6e 67 65 72 20 6e 61  with a longer na
30290 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 73 75 6c  me.** will resul
302a0 74 20 69 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53  t in [SQLITE_MIS
302b0 55 53 45 5d 20 62 65 69 6e 67 20 72 65 74 75 72  USE] being retur
302c0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ned..**.** ^The 
302d0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
302e0 28 6e 41 72 67 29 0a 2a 2a 20 69 73 20 74 68 65  (nArg).** is the
302f0 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d   number of argum
30300 65 6e 74 73 20 74 68 61 74 20 74 68 65 20 53 51  ents that the SQ
30310 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a  L function or.**
30320 20 61 67 67 72 65 67 61 74 65 20 74 61 6b 65 73   aggregate takes
30330 2e 20 5e 49 66 20 74 68 69 73 20 70 61 72 61 6d  . ^If this param
30340 65 74 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e  eter is -1, then
30350 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
30360 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74  n or.** aggregat
30370 65 20 6d 61 79 20 74 61 6b 65 20 61 6e 79 20 6e  e may take any n
30380 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e  umber of argumen
30390 74 73 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64  ts between 0 and
303a0 20 74 68 65 20 6c 69 6d 69 74 0a 2a 2a 20 73 65   the limit.** se
303b0 74 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69  t by [sqlite3_li
303c0 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d  mit]([SQLITE_LIM
303d0 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d  IT_FUNCTION_ARG]
303e0 29 2e 20 20 49 66 20 74 68 65 20 74 68 69 72 64  ).  If the third
303f0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69 73  .** parameter is
30400 20 6c 65 73 73 20 74 68 61 6e 20 2d 31 20 6f 72   less than -1 or
30410 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 31 32   greater than 12
30420 37 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  7 then the behav
30430 69 6f 72 20 69 73 0a 2a 2a 20 75 6e 64 65 66 69  ior is.** undefi
30440 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ned..**.** ^The 
30450 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
30460 2c 20 65 54 65 78 74 52 65 70 2c 20 73 70 65 63  , eTextRep, spec
30470 69 66 69 65 73 20 77 68 61 74 0a 2a 2a 20 5b 53  ifies what.** [S
30480 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 74 65 78  QLITE_UTF8 | tex
30490 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74 68 69 73  t encoding] this
304a0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 70 72   SQL function pr
304b0 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20 69 74 73  efers for.** its
304c0 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 45 76   parameters.  Ev
304d0 65 72 79 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ery SQL function
304e0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
304f0 6d 75 73 74 20 62 65 20 61 62 6c 65 20 74 6f 20  must be able to 
30500 77 6f 72 6b 0a 2a 2a 20 77 69 74 68 20 55 54 46  work.** with UTF
30510 2d 38 2c 20 55 54 46 2d 31 36 6c 65 2c 20 6f 72  -8, UTF-16le, or
30520 20 55 54 46 2d 31 36 62 65 2e 20 20 42 75 74 20   UTF-16be.  But 
30530 73 6f 6d 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  some implementat
30540 69 6f 6e 73 20 6d 61 79 20 62 65 0a 2a 2a 20 6d  ions may be.** m
30550 6f 72 65 20 65 66 66 69 63 69 65 6e 74 20 77 69  ore efficient wi
30560 74 68 20 6f 6e 65 20 65 6e 63 6f 64 69 6e 67 20  th one encoding 
30570 74 68 61 6e 20 61 6e 6f 74 68 65 72 2e 20 20 5e  than another.  ^
30580 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  An application m
30590 61 79 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c  ay.** invoke sql
305a0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
305b0 74 69 6f 6e 28 29 20 6f 72 20 73 71 6c 69 74 65  tion() or sqlite
305c0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
305d0 6e 31 36 28 29 20 6d 75 6c 74 69 70 6c 65 0a 2a  n16() multiple.*
305e0 2a 20 74 69 6d 65 73 20 77 69 74 68 20 74 68 65  * times with the
305f0 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 62   same function b
30600 75 74 20 77 69 74 68 20 64 69 66 66 65 72 65 6e  ut with differen
30610 74 20 76 61 6c 75 65 73 20 6f 66 20 65 54 65 78  t values of eTex
30620 74 52 65 70 2e 0a 2a 2a 20 5e 57 68 65 6e 20 6d  tRep..** ^When m
30630 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e  ultiple implemen
30640 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  tations of the s
30650 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 61 72 65  ame function are
30660 20 61 76 61 69 6c 61 62 6c 65 2c 20 53 51 4c 69   available, SQLi
30670 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 63 6b 20  te.** will pick 
30680 74 68 65 20 6f 6e 65 20 74 68 61 74 20 69 6e 76  the one that inv
30690 6f 6c 76 65 73 20 74 68 65 20 6c 65 61 73 74 20  olves the least 
306a0 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20 63  amount of data c
306b0 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20 49 66  onversion..** If
306c0 20 74 68 65 72 65 20 69 73 20 6f 6e 6c 79 20 61   there is only a
306d0 20 73 69 6e 67 6c 65 20 69 6d 70 6c 65 6d 65 6e   single implemen
306e0 74 61 74 69 6f 6e 20 77 68 69 63 68 20 64 6f 65  tation which doe
306f0 73 20 6e 6f 74 20 63 61 72 65 20 77 68 61 74 20  s not care what 
30700 74 65 78 74 0a 2a 2a 20 65 6e 63 6f 64 69 6e 67  text.** encoding
30710 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20 74   is used, then t
30720 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  he fourth argume
30730 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 5b 53 51  nt should be [SQ
30740 4c 49 54 45 5f 41 4e 59 5d 2e 0a 2a 2a 0a 2a 2a  LITE_ANY]..**.**
30750 20 5e 28 54 68 65 20 66 69 66 74 68 20 70 61 72   ^(The fifth par
30760 61 6d 65 74 65 72 20 69 73 20 61 6e 20 61 72 62  ameter is an arb
30770 69 74 72 61 72 79 20 70 6f 69 6e 74 65 72 2e 20  itrary pointer. 
30780 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   The implementat
30790 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 66 75  ion of the.** fu
307a0 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20  nction can gain 
307b0 61 63 63 65 73 73 20 74 6f 20 74 68 69 73 20 70  access to this p
307c0 6f 69 6e 74 65 72 20 75 73 69 6e 67 20 5b 73 71  ointer using [sq
307d0 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28  lite3_user_data(
307e0 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  )].)^.**.** ^The
307f0 20 73 69 78 74 68 2c 20 73 65 76 65 6e 74 68 20   sixth, seventh 
30800 61 6e 64 20 65 69 67 68 74 68 20 70 61 72 61 6d  and eighth param
30810 65 74 65 72 73 2c 20 78 46 75 6e 63 2c 20 78 53  eters, xFunc, xS
30820 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20  tep and xFinal, 
30830 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20  are.** pointers 
30840 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65 20 66 75  to C-language fu
30850 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 69 6d 70  nctions that imp
30860 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66  lement the SQL f
30870 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67  unction or.** ag
30880 67 72 65 67 61 74 65 2e 20 5e 41 20 73 63 61 6c  gregate. ^A scal
30890 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ar SQL function 
308a0 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c  requires an impl
308b0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68  ementation of th
308c0 65 20 78 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62  e xFunc.** callb
308d0 61 63 6b 20 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70  ack only; NULL p
308e0 6f 69 6e 74 65 72 73 20 6d 75 73 74 20 62 65 20  ointers must be 
308f0 70 61 73 73 65 64 20 61 73 20 74 68 65 20 78 53  passed as the xS
30900 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 0a 2a  tep and xFinal.*
30910 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20 5e 41  * parameters. ^A
30920 6e 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20  n aggregate SQL 
30930 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65  function require
30940 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  s an implementat
30950 69 6f 6e 20 6f 66 20 78 53 74 65 70 0a 2a 2a 20  ion of xStep.** 
30960 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e  and xFinal and N
30970 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6d 75 73 74  ULL pointer must
30980 20 62 65 20 70 61 73 73 65 64 20 66 6f 72 20 78   be passed for x
30990 46 75 6e 63 2e 20 5e 54 6f 20 64 65 6c 65 74 65  Func. ^To delete
309a0 20 61 6e 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20   an existing.** 
309b0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20  SQL function or 
309c0 61 67 67 72 65 67 61 74 65 2c 20 70 61 73 73 20  aggregate, pass 
309d0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 66 6f  NULL pointers fo
309e0 72 20 61 6c 6c 20 74 68 72 65 65 20 66 75 6e 63  r all three func
309f0 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  tion.** callback
30a00 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68  s..**.** ^(If th
30a10 65 20 6e 69 6e 74 68 20 70 61 72 61 6d 65 74 65  e ninth paramete
30a20 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65  r to sqlite3_cre
30a30 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28  ate_function_v2(
30a40 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a  ) is not NULL,.*
30a50 2a 20 74 68 65 6e 20 69 74 20 69 73 20 64 65 73  * then it is des
30a60 74 72 75 63 74 6f 72 20 66 6f 72 20 74 68 65 20  tructor for the 
30a70 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61  application data
30a80 20 70 6f 69 6e 74 65 72 2e 20 0a 2a 2a 20 54 68   pointer. .** Th
30a90 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20  e destructor is 
30aa0 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74 68 65  invoked when the
30ab0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c   function is del
30ac0 65 74 65 64 2c 20 65 69 74 68 65 72 20 62 79 20  eted, either by 
30ad0 62 65 69 6e 67 0a 2a 2a 20 6f 76 65 72 6c 6f 61  being.** overloa
30ae0 64 65 64 20 6f 72 20 77 68 65 6e 20 74 68 65 20  ded or when the 
30af0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
30b00 69 6f 6e 20 63 6c 6f 73 65 73 2e 29 5e 0a 2a 2a  ion closes.)^.**
30b10 20 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f 72   ^The destructor
30b20 20 69 73 20 61 6c 73 6f 20 69 6e 76 6f 6b 65 64   is also invoked
30b30 20 69 66 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a   if the call to.
30b40 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  ** sqlite3_creat
30b50 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20  e_function_v2() 
30b60 66 61 69 6c 73 2e 0a 2a 2a 20 5e 57 68 65 6e 20  fails..** ^When 
30b70 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 63  the destructor c
30b80 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 74  allback of the t
30b90 65 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  enth parameter i
30ba0 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74 0a 2a 2a  s invoked, it.**
30bb0 20 69 73 20 70 61 73 73 65 64 20 61 20 73 69 6e   is passed a sin
30bc0 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
30bd0 63 68 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  ch is a copy of 
30be0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
30bf0 64 61 74 61 20 0a 2a 2a 20 70 6f 69 6e 74 65 72  data .** pointer
30c00 20 77 68 69 63 68 20 77 61 73 20 74 68 65 20 66   which was the f
30c10 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  ifth parameter t
30c20 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  o sqlite3_create
30c30 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 2e 0a  _function_v2()..
30c40 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 70 65 72  **.** ^It is per
30c50 6d 69 74 74 65 64 20 74 6f 20 72 65 67 69 73 74  mitted to regist
30c60 65 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c  er multiple impl
30c70 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74  ementations of t
30c80 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74  he same.** funct
30c90 69 6f 6e 73 20 77 69 74 68 20 74 68 65 20 73 61  ions with the sa
30ca0 6d 65 20 6e 61 6d 65 20 62 75 74 20 77 69 74 68  me name but with
30cb0 20 65 69 74 68 65 72 20 64 69 66 66 65 72 69 6e   either differin
30cc0 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20  g numbers of.** 
30cd0 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 64 69 66  arguments or dif
30ce0 66 65 72 69 6e 67 20 70 72 65 66 65 72 72 65 64  fering preferred
30cf0 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e   text encodings.
30d00 20 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75    ^SQLite will u
30d10 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d  se.** the implem
30d20 65 6e 74 61 74 69 6f 6e 20 74 68 61 74 20 6d 6f  entation that mo
30d30 73 74 20 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68  st closely match
30d40 65 73 20 74 68 65 20 77 61 79 20 69 6e 20 77 68  es the way in wh
30d50 69 63 68 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66  ich the.** SQL f
30d60 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64 2e  unction is used.
30d70 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 69 6d    ^A function im
30d80 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74  plementation wit
30d90 68 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65  h a non-negative
30da0 0a 2a 2a 20 6e 41 72 67 20 70 61 72 61 6d 65 74  .** nArg paramet
30db0 65 72 20 69 73 20 61 20 62 65 74 74 65 72 20 6d  er is a better m
30dc0 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63  atch than a func
30dd0 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  tion implementat
30de0 69 6f 6e 20 77 69 74 68 0a 2a 2a 20 61 20 6e 65  ion with.** a ne
30df0 67 61 74 69 76 65 20 6e 41 72 67 2e 20 20 5e 41  gative nArg.  ^A
30e00 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20   function where 
30e10 74 68 65 20 70 72 65 66 65 72 72 65 64 20 74 65  the preferred te
30e20 78 74 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d  xt encoding.** m
30e30 61 74 63 68 65 73 20 74 68 65 20 64 61 74 61 62  atches the datab
30e40 61 73 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  ase encoding is 
30e50 61 20 62 65 74 74 65 72 0a 2a 2a 20 6d 61 74 63  a better.** matc
30e60 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f  h than a functio
30e70 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f  n where the enco
30e80 64 69 6e 67 20 69 73 20 64 69 66 66 65 72 65 6e  ding is differen
30e90 74 2e 20 20 0a 2a 2a 20 5e 41 20 66 75 6e 63 74  t.  .** ^A funct
30ea0 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e  ion where the en
30eb0 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63  coding differenc
30ec0 65 20 69 73 20 62 65 74 77 65 65 6e 20 55 54 46  e is between UTF
30ed0 31 36 6c 65 20 61 6e 64 20 55 54 46 31 36 62 65  16le and UTF16be
30ee0 0a 2a 2a 20 69 73 20 61 20 63 6c 6f 73 65 72 20  .** is a closer 
30ef0 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e  match than a fun
30f00 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20  ction where the 
30f10 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65  encoding differe
30f20 6e 63 65 20 69 73 0a 2a 2a 20 62 65 74 77 65 65  nce is.** betwee
30f30 6e 20 55 54 46 38 20 61 6e 64 20 55 54 46 31 36  n UTF8 and UTF16
30f40 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75 69 6c 74 2d 69  ..**.** ^Built-i
30f50 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20  n functions may 
30f60 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 20 62 79  be overloaded by
30f70 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e   new application
30f80 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
30f90 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 70  ns..**.** ^An ap
30fa0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
30fb0 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 65  d function is pe
30fc0 72 6d 69 74 74 65 64 20 74 6f 20 63 61 6c 6c 20  rmitted to call 
30fd0 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20  other.** SQLite 
30fe0 69 6e 74 65 72 66 61 63 65 73 2e 20 20 48 6f 77  interfaces.  How
30ff0 65 76 65 72 2c 20 73 75 63 68 20 63 61 6c 6c 73  ever, such calls
31000 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f   must not.** clo
31010 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  se the database 
31020 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e 6f 72 20 66  connection nor f
31030 69 6e 61 6c 69 7a 65 20 6f 72 20 72 65 73 65 74  inalize or reset
31040 20 74 68 65 20 70 72 65 70 61 72 65 64 0a 2a 2a   the prepared.**
31050 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 77 68   statement in wh
31060 69 63 68 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  ich the function
31070 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a   is running..*/.
31080 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
31090 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
310a0 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65  nction(.  sqlite
310b0 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63  3 *db,.  const c
310c0 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61  har *zFunctionNa
310d0 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a  me,.  int nArg,.
310e0 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a    int eTextRep,.
310f0 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20    void *pApp,.  
31100 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71  void (*xFunc)(sq
31110 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
31120 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
31130 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53  **),.  void (*xS
31140 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  tep)(sqlite3_con
31150 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
31160 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
31170 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c  id (*xFinal)(sql
31180 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29  ite3_context*).)
31190 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
311a0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
311b0 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20 73 71  function16(.  sq
311c0 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e  lite3 *db,.  con
311d0 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63 74 69  st void *zFuncti
311e0 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41  onName,.  int nA
311f0 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52  rg,.  int eTextR
31200 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70  ep,.  void *pApp
31210 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63  ,.  void (*xFunc
31220 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
31230 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
31240 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
31250 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33  (*xStep)(sqlite3
31260 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
31270 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
31280 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29    void (*xFinal)
31290 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
312a0 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  *).);.SQLITE_API
312b0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65   int sqlite3_cre
312c0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28  ate_function_v2(
312d0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a  .  sqlite3 *db,.
312e0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46    const char *zF
312f0 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69  unctionName,.  i
31300 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65  nt nArg,.  int e
31310 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20  TextRep,.  void 
31320 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a  *pApp,.  void (*
31330 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63  xFunc)(sqlite3_c
31340 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
31350 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
31360 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71  void (*xStep)(sq
31370 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
31380 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
31390 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  **),.  void (*xF
313a0 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f  inal)(sqlite3_co
313b0 6e 74 65 78 74 2a 29 2c 0a 20 20 76 6f 69 64 28  ntext*),.  void(
313c0 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a  *xDestroy)(void*
313d0 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ).);../*.** CAPI
313e0 33 52 45 46 3a 20 54 65 78 74 20 45 6e 63 6f 64  3REF: Text Encod
313f0 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ings.**.** These
31400 20 63 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 65   constant define
31410 20 69 6e 74 65 67 65 72 20 63 6f 64 65 73 20 74   integer codes t
31420 68 61 74 20 72 65 70 72 65 73 65 6e 74 20 74 68  hat represent th
31430 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20 74 65 78  e various.** tex
31440 74 20 65 6e 63 6f 64 69 6e 67 73 20 73 75 70 70  t encodings supp
31450 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2e  orted by SQLite.
31460 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
31470 54 45 5f 55 54 46 38 20 20 20 20 20 20 20 20 20  TE_UTF8         
31480 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
31490 54 45 5f 55 54 46 31 36 4c 45 20 20 20 20 20 20  TE_UTF16LE      
314a0 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
314b0 54 45 5f 55 54 46 31 36 42 45 20 20 20 20 20 20  TE_UTF16BE      
314c0 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    3.#define SQLI
314d0 54 45 5f 55 54 46 31 36 20 20 20 20 20 20 20 20  TE_UTF16        
314e0 20 20 34 20 20 20 20 2f 2a 20 55 73 65 20 6e 61    4    /* Use na
314f0 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20  tive byte order 
31500 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
31510 45 5f 41 4e 59 20 20 20 20 20 20 20 20 20 20 20  E_ANY           
31520 20 35 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33   5    /* sqlite3
31530 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
31540 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
31550 20 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c   SQLITE_UTF16_AL
31560 49 47 4e 45 44 20 20 38 20 20 20 20 2f 2a 20 73  IGNED  8    /* s
31570 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
31580 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a  llation only */.
31590 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
315a0 20 44 65 70 72 65 63 61 74 65 64 20 46 75 6e 63   Deprecated Func
315b0 74 69 6f 6e 73 0a 2a 2a 20 44 45 50 52 45 43 41  tions.** DEPRECA
315c0 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  TED.**.** These 
315d0 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 5b 64  functions are [d
315e0 65 70 72 65 63 61 74 65 64 5d 2e 20 20 49 6e 20  eprecated].  In 
315f0 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e 74 61 69  order to maintai
31600 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63  n.** backwards c
31610 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 77 69 74  ompatibility wit
31620 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20 74 68  h older code, th
31630 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 63 6f  ese functions co
31640 6e 74 69 6e 75 65 20 0a 2a 2a 20 74 6f 20 62 65  ntinue .** to be
31650 20 73 75 70 70 6f 72 74 65 64 2e 20 20 48 6f 77   supported.  How
31660 65 76 65 72 2c 20 6e 65 77 20 61 70 70 6c 69 63  ever, new applic
31670 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 61 76  ations should av
31680 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f  oid.** the use o
31690 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  f these function
316a0 73 2e 20 20 54 6f 20 68 65 6c 70 20 65 6e 63 6f  s.  To help enco
316b0 75 72 61 67 65 20 70 65 6f 70 6c 65 20 74 6f 20  urage people to 
316c0 61 76 6f 69 64 0a 2a 2a 20 75 73 69 6e 67 20 74  avoid.** using t
316d0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2c 20  hese functions, 
316e0 77 65 20 61 72 65 20 6e 6f 74 20 67 6f 69 6e 67  we are not going
316f0 20 74 6f 20 74 65 6c 6c 20 79 6f 75 20 77 68 61   to tell you wha
31700 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a 23 69  t they do..*/.#i
31710 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49  fndef SQLITE_OMI
31720 54 5f 44 45 50 52 45 43 41 54 45 44 0a 53 51 4c  T_DEPRECATED.SQL
31730 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44  ITE_API SQLITE_D
31740 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71  EPRECATED int sq
31750 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
31760 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f  count(sqlite3_co
31770 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f  ntext*);.SQLITE_
31780 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45  API SQLITE_DEPRE
31790 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65  CATED int sqlite
317a0 33 5f 65 78 70 69 72 65 64 28 73 71 6c 69 74 65  3_expired(sqlite
317b0 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45  3_stmt*);.SQLITE
317c0 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52  _API SQLITE_DEPR
317d0 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74  ECATED int sqlit
317e0 65 33 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e 64  e3_transfer_bind
317f0 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d  ings(sqlite3_stm
31800 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  t*, sqlite3_stmt
31810 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53  *);.SQLITE_API S
31820 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
31830 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 6c 6f   int sqlite3_glo
31840 62 61 6c 5f 72 65 63 6f 76 65 72 28 76 6f 69 64  bal_recover(void
31850 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51  );.SQLITE_API SQ
31860 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
31870 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 74 68 72  void sqlite3_thr
31880 65 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64  ead_cleanup(void
31890 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51  );.SQLITE_API SQ
318a0 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
318b0 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  int sqlite3_memo
318c0 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64 28 2a 29  ry_alarm(void(*)
318d0 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69  (void*,sqlite3_i
318e0 6e 74 36 34 2c 69 6e 74 29 2c 0a 20 20 20 20 20  nt64,int),.     
318f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
31900 20 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69   void*,sqlite3_i
31910 6e 74 36 34 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f  nt64);.#endif../
31920 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
31930 62 74 61 69 6e 69 6e 67 20 53 51 4c 20 46 75 6e  btaining SQL Fun
31940 63 74 69 6f 6e 20 50 61 72 61 6d 65 74 65 72 20  ction Parameter 
31950 56 61 6c 75 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65  Values.**.** The
31960 20 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c   C-language impl
31970 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51  ementation of SQ
31980 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20  L functions and 
31990 61 67 67 72 65 67 61 74 65 73 20 75 73 65 73 0a  aggregates uses.
319a0 2a 2a 20 74 68 69 73 20 73 65 74 20 6f 66 20 69  ** this set of i
319b0 6e 74 65 72 66 61 63 65 20 72 6f 75 74 69 6e 65  nterface routine
319c0 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20  s to access the 
319d0 70 61 72 61 6d 65 74 65 72 20 76 61 6c 75 65 73  parameter values
319e0 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74   on.** the funct
319f0 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65  ion or aggregate
31a00 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e  ..**.** The xFun
31a10 63 20 28 66 6f 72 20 73 63 61 6c 61 72 20 66 75  c (for scalar fu
31a20 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78 53 74 65  nctions) or xSte
31a30 70 20 28 66 6f 72 20 61 67 67 72 65 67 61 74 65  p (for aggregate
31a40 73 29 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a  s) parameters.**
31a50 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65   to [sqlite3_cre
31a60 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20  ate_function()] 
31a70 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  and [sqlite3_cre
31a80 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
31a90 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c  ].** define call
31aa0 62 61 63 6b 73 20 74 68 61 74 20 69 6d 70 6c 65  backs that imple
31ab0 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e  ment the SQL fun
31ac0 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65  ctions and aggre
31ad0 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20 33 72  gates..** The 3r
31ae0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
31af0 68 65 73 65 20 63 61 6c 6c 62 61 63 6b 73 20 69  hese callbacks i
31b00 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f  s an array of po
31b10 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72  inters to.** [pr
31b20 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
31b30 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20  value] objects. 
31b40 20 54 68 65 72 65 20 69 73 20 6f 6e 65 20 5b 73   There is one [s
31b50 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
31b60 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68  ject for.** each
31b70 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
31b80 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20  e SQL function. 
31b90 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
31ba0 61 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65  are used to.** e
31bb0 78 74 72 61 63 74 20 76 61 6c 75 65 73 20 66 72  xtract values fr
31bc0 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  om the [sqlite3_
31bd0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a  value] objects..
31be0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
31bf0 69 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77  ines work only w
31c00 69 74 68 20 5b 70 72 6f 74 65 63 74 65 64 20 73  ith [protected s
31c10 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
31c20 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74  jects..** Any at
31c30 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65  tempt to use the
31c40 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61  se routines on a
31c50 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  n [unprotected s
31c60 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a  qlite3_value].**
31c70 20 6f 62 6a 65 63 74 20 72 65 73 75 6c 74 73 20   object results 
31c80 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68  in undefined beh
31c90 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  avior..**.** ^Th
31ca0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72  ese routines wor
31cb0 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74 68 65 20  k just like the 
31cc0 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63  corresponding [c
31cd0 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e  olumn access fun
31ce0 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70  ctions].** excep
31cf0 74 20 74 68 61 74 20 20 74 68 65 73 65 20 72 6f  t that  these ro
31d00 75 74 69 6e 65 73 20 74 61 6b 65 20 61 20 73 69  utines take a si
31d10 6e 67 6c 65 20 5b 70 72 6f 74 65 63 74 65 64 20  ngle [protected 
31d20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
31d30 62 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 72  bject.** pointer
31d40 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 5b 73   instead of a [s
31d50 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f  qlite3_stmt*] po
31d60 69 6e 74 65 72 20 61 6e 64 20 61 6e 20 69 6e 74  inter and an int
31d70 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62  eger column numb
31d80 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  er..**.** ^The s
31d90 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
31da0 74 31 36 28 29 20 69 6e 74 65 72 66 61 63 65 20  t16() interface 
31db0 65 78 74 72 61 63 74 73 20 61 20 55 54 46 2d 31  extracts a UTF-1
31dc0 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74  6 string.** in t
31dd0 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 2d 6f  he native byte-o
31de0 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f 73 74  rder of the host
31df0 20 6d 61 63 68 69 6e 65 2e 20 20 5e 54 68 65 0a   machine.  ^The.
31e00 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
31e10 5f 74 65 78 74 31 36 62 65 28 29 20 61 6e 64 20  _text16be() and 
31e20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
31e30 78 74 31 36 6c 65 28 29 20 69 6e 74 65 72 66 61  xt16le() interfa
31e40 63 65 73 0a 2a 2a 20 65 78 74 72 61 63 74 20 55  ces.** extract U
31e50 54 46 2d 31 36 20 73 74 72 69 6e 67 73 20 61 73  TF-16 strings as
31e60 20 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20   big-endian and 
31e70 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65  little-endian re
31e80 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a  spectively..**.*
31e90 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f  * ^(The sqlite3_
31ea0 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79  value_numeric_ty
31eb0 70 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 61  pe() interface a
31ec0 74 74 65 6d 70 74 73 20 74 6f 20 61 70 70 6c 79  ttempts to apply
31ed0 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66 66 69  .** numeric affi
31ee0 6e 69 74 79 20 74 6f 20 74 68 65 20 76 61 6c 75  nity to the valu
31ef0 65 2e 20 20 54 68 69 73 20 6d 65 61 6e 73 20 74  e.  This means t
31f00 68 61 74 20 61 6e 20 61 74 74 65 6d 70 74 20 69  hat an attempt i
31f10 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e  s.** made to con
31f20 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 74  vert the value t
31f30 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 20  o an integer or 
31f40 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20  floating point. 
31f50 20 49 66 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f   If.** such a co
31f60 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 6f 73 73  nversion is poss
31f70 69 62 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f 73  ible without los
31f80 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  s of information
31f90 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f   (in other.** wo
31fa0 72 64 73 2c 20 69 66 20 74 68 65 20 76 61 6c 75  rds, if the valu
31fb0 65 20 69 73 20 61 20 73 74 72 69 6e 67 20 74 68  e is a string th
31fc0 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20  at looks like a 
31fd0 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20  number).** then 
31fe0 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69  the conversion i
31ff0 73 20 70 65 72 66 6f 72 6d 65 64 2e 20 20 4f 74  s performed.  Ot
32000 68 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65  herwise no conve
32010 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a  rsion occurs..**
32020 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 4e 54   The [SQLITE_INT
32030 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 5d  EGER | datatype]
32040 20 61 66 74 65 72 20 63 6f 6e 76 65 72 73 69 6f   after conversio
32050 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e  n is returned.)^
32060 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61  .**.** Please pa
32070 79 20 70 61 72 74 69 63 75 6c 61 72 20 61 74 74  y particular att
32080 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20 66 61  ention to the fa
32090 63 74 20 74 68 61 74 20 74 68 65 20 70 6f 69 6e  ct that the poin
320a0 74 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  ter returned.** 
320b0 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61  from [sqlite3_va
320c0 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71  lue_blob()], [sq
320d0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
320e0 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  ()], or.** [sqli
320f0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
32100 28 29 5d 20 63 61 6e 20 62 65 20 69 6e 76 61 6c  ()] can be inval
32110 69 64 61 74 65 64 20 62 79 20 61 20 73 75 62 73  idated by a subs
32120 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a  equent call to.*
32130 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  * [sqlite3_value
32140 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69  _bytes()], [sqli
32150 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31  te3_value_bytes1
32160 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76  6()], [sqlite3_v
32170 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a  alue_text()],.**
32180 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c   or [sqlite3_val
32190 75 65 5f 74 65 78 74 31 36 28 29 5d 2e 0a 2a 2a  ue_text16()]..**
321a0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
321b0 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  es must be calle
321c0 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20  d from the same 
321d0 74 68 72 65 61 64 20 61 73 0a 2a 2a 20 74 68 65  thread as.** the
321e0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68   SQL function th
321f0 61 74 20 73 75 70 70 6c 69 65 64 20 74 68 65 20  at supplied the 
32200 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 5d  [sqlite3_value*]
32210 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a   parameters..*/.
32220 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
32230 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76   void *sqlite3_v
32240 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65  alue_blob(sqlite
32250 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54  3_value*);.SQLIT
32260 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
32270 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 73 71  3_value_bytes(sq
32280 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53  lite3_value*);.S
32290 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
322a0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
322b0 73 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  s16(sqlite3_valu
322c0 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  e*);.SQLITE_API 
322d0 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 76  double sqlite3_v
322e0 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69  alue_double(sqli
322f0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c  te3_value*);.SQL
32300 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
32310 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 73 71  te3_value_int(sq
32320 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53  lite3_value*);.S
32330 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65  QLITE_API sqlite
32340 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
32350 76 61 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c 69  value_int64(sqli
32360 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c  te3_value*);.SQL
32370 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 75 6e  ITE_API const un
32380 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c  signed char *sql
32390 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28  ite3_value_text(
323a0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
323b0 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
323c0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
323d0 76 61 6c 75 65 5f 74 65 78 74 31 36 28 73 71 6c  value_text16(sql
323e0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51  ite3_value*);.SQ
323f0 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76  LITE_API const v
32400 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c  oid *sqlite3_val
32410 75 65 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69  ue_text16le(sqli
32420 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c  te3_value*);.SQL
32430 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f  ITE_API const vo
32440 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75  id *sqlite3_valu
32450 65 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 74  e_text16be(sqlit
32460 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49  e3_value*);.SQLI
32470 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
32480 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 73 71  e3_value_type(sq
32490 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53  lite3_value*);.S
324a0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
324b0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65  lite3_value_nume
324c0 72 69 63 5f 74 79 70 65 28 73 71 6c 69 74 65 33  ric_type(sqlite3
324d0 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  _value*);../*.**
324e0 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69   CAPI3REF: Obtai
324f0 6e 20 41 67 67 72 65 67 61 74 65 20 46 75 6e 63  n Aggregate Func
32500 74 69 6f 6e 20 43 6f 6e 74 65 78 74 0a 2a 2a 0a  tion Context.**.
32510 2a 2a 20 49 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** Implementatio
32520 6e 73 20 6f 66 20 61 67 67 72 65 67 61 74 65 20  ns of aggregate 
32530 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 75 73  SQL functions us
32540 65 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e  e this.** routin
32550 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65  e to allocate me
32560 6d 6f 72 79 20 66 6f 72 20 73 74 6f 72 69 6e 67  mory for storing
32570 20 74 68 65 69 72 20 73 74 61 74 65 2e 0a 2a 2a   their state..**
32580 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 74  .** ^The first t
32590 69 6d 65 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ime the sqlite3_
325a0 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
325b0 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20 69  t(C,N) routine i
325c0 73 20 63 61 6c 6c 65 64 20 0a 2a 2a 20 66 6f 72  s called .** for
325d0 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 61 67   a particular ag
325e0 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e  gregate function
325f0 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6c 6c 6f  , SQLite.** allo
32600 63 61 74 65 73 20 4e 20 6f 66 20 6d 65 6d 6f 72  cates N of memor
32610 79 2c 20 7a 65 72 6f 65 73 20 6f 75 74 20 74 68  y, zeroes out th
32620 61 74 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 72  at memory, and r
32630 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
32640 0a 2a 2a 20 74 6f 20 74 68 65 20 6e 65 77 20 6d  .** to the new m
32650 65 6d 6f 72 79 2e 20 5e 4f 6e 20 73 65 63 6f 6e  emory. ^On secon
32660 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74  d and subsequent
32670 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c   calls to.** sql
32680 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
32690 6f 6e 74 65 78 74 28 29 20 66 6f 72 20 74 68 65  ontext() for the
326a0 20 73 61 6d 65 20 61 67 67 72 65 67 61 74 65 20   same aggregate 
326b0 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63  function instanc
326c0 65 2c 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 62  e,.** the same b
326d0 75 66 66 65 72 20 69 73 20 72 65 74 75 72 6e 65  uffer is returne
326e0 64 2e 20 20 53 71 6c 69 74 65 33 5f 61 67 67 72  d.  Sqlite3_aggr
326f0 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20  egate_context() 
32700 69 73 20 6e 6f 72 6d 61 6c 6c 79 0a 2a 2a 20 63  is normally.** c
32710 61 6c 6c 65 64 20 6f 6e 63 65 20 66 6f 72 20 65  alled once for e
32720 61 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f  ach invocation o
32730 66 20 74 68 65 20 78 53 74 65 70 20 63 61 6c 6c  f the xStep call
32740 62 61 63 6b 20 61 6e 64 20 74 68 65 6e 20 6f 6e  back and then on
32750 65 0a 2a 2a 20 6c 61 73 74 20 74 69 6d 65 20 77  e.** last time w
32760 68 65 6e 20 74 68 65 20 78 46 69 6e 61 6c 20 63  hen the xFinal c
32770 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
32780 65 64 2e 20 20 5e 28 57 68 65 6e 20 6e 6f 20 72  ed.  ^(When no r
32790 6f 77 73 20 6d 61 74 63 68 0a 2a 2a 20 61 6e 20  ows match.** an 
327a0 61 67 67 72 65 67 61 74 65 20 71 75 65 72 79 2c  aggregate query,
327b0 20 74 68 65 20 78 53 74 65 70 28 29 20 63 61 6c   the xStep() cal
327c0 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 61 67 67  lback of the agg
327d0 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 0a  regate function.
327e0 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
327f0 6e 20 69 73 20 6e 65 76 65 72 20 63 61 6c 6c 65  n is never calle
32800 64 20 61 6e 64 20 78 46 69 6e 61 6c 28 29 20 69  d and xFinal() i
32810 73 20 63 61 6c 6c 65 64 20 65 78 61 63 74 6c 79  s called exactly
32820 20 6f 6e 63 65 2e 0a 2a 2a 20 49 6e 20 74 68 6f   once..** In tho
32830 73 65 20 63 61 73 65 73 2c 20 73 71 6c 69 74 65  se cases, sqlite
32840 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
32850 65 78 74 28 29 20 6d 69 67 68 74 20 62 65 20 63  ext() might be c
32860 61 6c 6c 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a  alled for the.**
32870 20 66 69 72 73 74 20 74 69 6d 65 20 66 72 6f 6d   first time from
32880 20 77 69 74 68 69 6e 20 78 46 69 6e 61 6c 28 29   within xFinal()
32890 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  .)^.**.** ^The s
328a0 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
328b0 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f  _context(C,N) ro
328c0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20  utine returns a 
328d0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 0a 2a 2a  NULL pointer .**
328e0 20 77 68 65 6e 20 66 69 72 73 74 20 63 61 6c 6c   when first call
328f0 65 64 20 69 66 20 4e 20 69 73 20 6c 65 73 73 20  ed if N is less 
32900 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f  than or equal to
32910 20 7a 65 72 6f 20 6f 72 20 69 66 20 61 20 6d 65   zero or if a me
32920 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65  mory.** allocate
32930 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a 2a   error occurs..*
32940 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 6d 6f 75 6e  *.** ^(The amoun
32950 74 20 6f 66 20 73 70 61 63 65 20 61 6c 6c 6f 63  t of space alloc
32960 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  ated by sqlite3_
32970 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
32980 74 28 43 2c 4e 29 20 69 73 0a 2a 2a 20 64 65 74  t(C,N) is.** det
32990 65 72 6d 69 6e 65 64 20 62 79 20 74 68 65 20 4e  ermined by the N
329a0 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 66 69   parameter on fi
329b0 72 73 74 20 73 75 63 63 65 73 73 66 75 6c 20 63  rst successful c
329c0 61 6c 6c 2e 20 20 43 68 61 6e 67 69 6e 67 20 74  all.  Changing t
329d0 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 4e  he.** value of N
329e0 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63   in subsequent c
329f0 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 61  all to sqlite3_a
32a00 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
32a10 28 29 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65  () within.** the
32a20 20 73 61 6d 65 20 61 67 67 72 65 67 61 74 65 20   same aggregate 
32a30 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63  function instanc
32a40 65 20 77 69 6c 6c 20 6e 6f 74 20 72 65 73 69 7a  e will not resiz
32a50 65 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20  e the memory.** 
32a60 61 6c 6c 6f 63 61 74 69 6f 6e 2e 29 5e 20 20 57  allocation.)^  W
32a70 69 74 68 69 6e 20 74 68 65 20 78 46 69 6e 61 6c  ithin the xFinal
32a80 20 63 61 6c 6c 62 61 63 6b 2c 20 69 74 20 69 73   callback, it is
32a90 20 63 75 73 74 6f 6d 61 72 79 20 74 6f 20 73 65   customary to se
32aa0 74 0a 2a 2a 20 4e 3d 30 20 69 6e 20 63 61 6c 6c  t.** N=0 in call
32ab0 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 61 67 67  s to sqlite3_agg
32ac0 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43  regate_context(C
32ad0 2c 4e 29 20 73 6f 20 74 68 61 74 20 6e 6f 20 0a  ,N) so that no .
32ae0 2a 2a 20 70 6f 69 6e 74 6c 65 73 73 20 6d 65 6d  ** pointless mem
32af0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20  ory allocations 
32b00 6f 63 63 75 72 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51  occur..**.** ^SQ
32b10 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c  Lite automatical
32b20 6c 79 20 66 72 65 65 73 20 74 68 65 20 6d 65 6d  ly frees the mem
32b30 6f 72 79 20 61 6c 6c 6f 63 61 74 65 64 20 62 79  ory allocated by
32b40 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67   .** sqlite3_agg
32b50 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
32b60 20 77 68 65 6e 20 74 68 65 20 61 67 67 72 65 67   when the aggreg
32b70 61 74 65 20 71 75 65 72 79 20 63 6f 6e 63 6c 75  ate query conclu
32b80 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  des..**.** The f
32b90 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 6d  irst parameter m
32ba0 75 73 74 20 62 65 20 61 20 63 6f 70 79 20 6f 66  ust be a copy of
32bb0 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
32bc0 5f 63 6f 6e 74 65 78 74 20 7c 20 53 51 4c 20 66  _context | SQL f
32bd0 75 6e 63 74 69 6f 6e 20 63 6f 6e 74 65 78 74 5d  unction context]
32be0 20 74 68 61 74 20 69 73 20 74 68 65 20 66 69 72   that is the fir
32bf0 73 74 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  st parameter.** 
32c00 74 6f 20 74 68 65 20 78 53 74 65 70 20 6f 72 20  to the xStep or 
32c10 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20  xFinal callback 
32c20 72 6f 75 74 69 6e 65 20 74 68 61 74 20 69 6d 70  routine that imp
32c30 6c 65 6d 65 6e 74 73 20 74 68 65 20 61 67 67 72  lements the aggr
32c40 65 67 61 74 65 0a 2a 2a 20 66 75 6e 63 74 69 6f  egate.** functio
32c50 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  n..**.** This ro
32c60 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61  utine must be ca
32c70 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61  lled from the sa
32c80 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69  me thread in whi
32c90 63 68 0a 2a 2a 20 74 68 65 20 61 67 67 72 65 67  ch.** the aggreg
32ca0 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ate SQL function
32cb0 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a   is running..*/.
32cc0 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
32cd0 2a 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61  *sqlite3_aggrega
32ce0 74 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69 74  te_context(sqlit
32cf0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
32d00 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a   nBytes);../*.**
32d10 20 43 41 50 49 33 52 45 46 3a 20 55 73 65 72 20   CAPI3REF: User 
32d20 44 61 74 61 20 46 6f 72 20 46 75 6e 63 74 69 6f  Data For Functio
32d30 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ns.**.** ^The sq
32d40 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28  lite3_user_data(
32d50 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
32d60 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a  rns a copy of.**
32d70 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 68 61   the pointer tha
32d80 74 20 77 61 73 20 74 68 65 20 70 55 73 65 72 44  t was the pUserD
32d90 61 74 61 20 70 61 72 61 6d 65 74 65 72 20 28 74  ata parameter (t
32da0 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
32db0 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c  ).** of the [sql
32dc0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
32dd0 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b  tion()].** and [
32de0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
32df0 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75  unction16()] rou
32e00 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69  tines that origi
32e10 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65  nally.** registe
32e20 72 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 74  red the applicat
32e30 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63  ion defined func
32e40 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  tion..**.** This
32e50 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65   routine must be
32e60 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
32e70 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20   same thread in 
32e80 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 70 70  which.** the app
32e90 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
32ea0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
32eb0 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  ning..*/.SQLITE_
32ec0 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  API void *sqlite
32ed0 33 5f 75 73 65 72 5f 64 61 74 61 28 73 71 6c 69  3_user_data(sqli
32ee0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a  te3_context*);..
32ef0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
32f00 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
32f10 69 6f 6e 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e  ion For Function
32f20 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
32f30 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f  ite3_context_db_
32f40 68 61 6e 64 6c 65 28 29 20 69 6e 74 65 72 66 61  handle() interfa
32f50 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70  ce returns a cop
32f60 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e  y of.** the poin
32f70 74 65 72 20 74 6f 20 74 68 65 20 5b 64 61 74 61  ter to the [data
32f80 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
32f90 20 28 74 68 65 20 31 73 74 20 70 61 72 61 6d 65   (the 1st parame
32fa0 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  ter).** of the [
32fb0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
32fc0 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e  unction()].** an
32fd0 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  d [sqlite3_creat
32fe0 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20  e_function16()] 
32ff0 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72  routines that or
33000 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69  iginally.** regi
33010 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c 69  stered the appli
33020 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66  cation defined f
33030 75 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49  unction..*/.SQLI
33040 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 20 2a  TE_API sqlite3 *
33050 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f  sqlite3_context_
33060 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65  db_handle(sqlite
33070 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a  3_context*);../*
33080 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75  .** CAPI3REF: Fu
33090 6e 63 74 69 6f 6e 20 41 75 78 69 6c 69 61 72 79  nction Auxiliary
330a0 20 44 61 74 61 0a 2a 2a 0a 2a 2a 20 54 68 65 73   Data.**.** Thes
330b0 65 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20  e functions may 
330c0 62 65 20 75 73 65 64 20 62 79 20 28 6e 6f 6e 2d  be used by (non-
330d0 61 67 67 72 65 67 61 74 65 29 20 53 51 4c 20 66  aggregate) SQL f
330e0 75 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61  unctions to.** a
330f0 73 73 6f 63 69 61 74 65 20 6d 65 74 61 64 61 74  ssociate metadat
33100 61 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20  a with argument 
33110 76 61 6c 75 65 73 2e 20 49 66 20 74 68 65 20 73  values. If the s
33120 61 6d 65 20 76 61 6c 75 65 20 69 73 20 70 61 73  ame value is pas
33130 73 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70  sed to.** multip
33140 6c 65 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f  le invocations o
33150 66 20 74 68 65 20 73 61 6d 65 20 53 51 4c 20 66  f the same SQL f
33160 75 6e 63 74 69 6f 6e 20 64 75 72 69 6e 67 20 71  unction during q
33170 75 65 72 79 20 65 78 65 63 75 74 69 6f 6e 2c 20  uery execution, 
33180 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 69  under.** some ci
33190 72 63 75 6d 73 74 61 6e 63 65 73 20 74 68 65 20  rcumstances the 
331a0 61 73 73 6f 63 69 61 74 65 64 20 6d 65 74 61 64  associated metad
331b0 61 74 61 20 6d 61 79 20 62 65 20 70 72 65 73 65  ata may be prese
331c0 72 76 65 64 2e 20 20 41 6e 20 65 78 61 6d 70 6c  rved.  An exampl
331d0 65 0a 2a 2a 20 6f 66 20 77 68 65 72 65 20 74 68  e.** of where th
331e0 69 73 20 6d 69 67 68 74 20 62 65 20 75 73 65 66  is might be usef
331f0 75 6c 20 69 73 20 69 6e 20 61 20 72 65 67 75 6c  ul is in a regul
33200 61 72 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d 61  ar-expression ma
33210 74 63 68 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69  tching.** functi
33220 6f 6e 2e 20 54 68 65 20 63 6f 6d 70 69 6c 65 64  on. The compiled
33230 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20   version of the 
33240 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69  regular expressi
33250 6f 6e 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64  on can be stored
33260 20 61 73 0a 2a 2a 20 6d 65 74 61 64 61 74 61 20   as.** metadata 
33270 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
33280 74 68 65 20 70 61 74 74 65 72 6e 20 73 74 72 69  the pattern stri
33290 6e 67 2e 20 20 0a 2a 2a 20 54 68 65 6e 20 61 73  ng.  .** Then as
332a0 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 70 61 74   long as the pat
332b0 74 65 72 6e 20 73 74 72 69 6e 67 20 72 65 6d 61  tern string rema
332c0 69 6e 73 20 74 68 65 20 73 61 6d 65 2c 0a 2a 2a  ins the same,.**
332d0 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 20 72 65   the compiled re
332e0 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e  gular expression
332f0 20 63 61 6e 20 62 65 20 72 65 75 73 65 64 20 6f   can be reused o
33300 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e  n multiple.** in
33310 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  vocations of the
33320 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 2e 0a   same function..
33330 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
33340 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29  e3_get_auxdata()
33350 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
33360 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
33370 74 68 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20  the metadata.** 
33380 61 73 73 6f 63 69 61 74 65 64 20 62 79 20 74 68  associated by th
33390 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  e sqlite3_set_au
333a0 78 64 61 74 61 28 29 20 66 75 6e 63 74 69 6f 6e  xdata() function
333b0 20 77 69 74 68 20 74 68 65 20 4e 74 68 20 61 72   with the Nth ar
333c0 67 75 6d 65 6e 74 0a 2a 2a 20 76 61 6c 75 65 20  gument.** value 
333d0 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  to the applicati
333e0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
333f0 69 6f 6e 2e 20 5e 49 66 20 74 68 65 72 65 20 69  ion. ^If there i
33400 73 20 6e 6f 20 6d 65 74 61 64 61 74 61 0a 2a 2a  s no metadata.**
33410 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
33420 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 61 72   the function ar
33430 67 75 6d 65 6e 74 2c 20 74 68 69 73 20 73 71 6c  gument, this sql
33440 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
33450 28 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  () interface.** 
33460 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70  returns a NULL p
33470 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ointer..**.** ^T
33480 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  he sqlite3_set_a
33490 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20  uxdata(C,N,P,X) 
334a0 69 6e 74 65 72 66 61 63 65 20 73 61 76 65 73 20  interface saves 
334b0 50 20 61 73 20 6d 65 74 61 64 61 74 61 20 66 6f  P as metadata fo
334c0 72 20 74 68 65 20 4e 2d 74 68 0a 2a 2a 20 61 72  r the N-th.** ar
334d0 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 70  gument of the ap
334e0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
334f0 64 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 53 75  d function.  ^Su
33500 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c  bsequent.** call
33510 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 67 65 74  s to sqlite3_get
33520 5f 61 75 78 64 61 74 61 28 43 2c 4e 29 20 72 65  _auxdata(C,N) re
33530 74 75 72 6e 20 50 20 66 72 6f 6d 20 74 68 65 20  turn P from the 
33540 6d 6f 73 74 20 72 65 63 65 6e 74 0a 2a 2a 20 73  most recent.** s
33550 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
33560 74 61 28 43 2c 4e 2c 50 2c 58 29 20 63 61 6c 6c  ta(C,N,P,X) call
33570 20 69 66 20 74 68 65 20 6d 65 74 61 64 61 74 61   if the metadata
33580 20 69 73 20 73 74 69 6c 6c 20 76 61 6c 69 64 20   is still valid 
33590 6f 72 0a 2a 2a 20 4e 55 4c 4c 20 69 66 20 74 68  or.** NULL if th
335a0 65 20 6d 65 74 61 64 61 74 61 20 68 61 73 20 62  e metadata has b
335b0 65 65 6e 20 64 69 73 63 61 72 64 65 64 2e 0a 2a  een discarded..*
335c0 2a 20 5e 41 66 74 65 72 20 65 61 63 68 20 63 61  * ^After each ca
335d0 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65  ll to sqlite3_se
335e0 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c  t_auxdata(C,N,P,
335f0 58 29 20 77 68 65 72 65 20 58 20 69 73 20 6e 6f  X) where X is no
33600 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 53 51 4c 69 74  t NULL,.** SQLit
33610 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68  e will invoke th
33620 65 20 64 65 73 74 72 75 63 74 6f 72 20 66 75 6e  e destructor fun
33630 63 74 69 6f 6e 20 58 20 77 69 74 68 20 70 61 72  ction X with par
33640 61 6d 65 74 65 72 20 50 20 65 78 61 63 74 6c 79  ameter P exactly
33650 0a 2a 2a 20 6f 6e 63 65 2c 20 77 68 65 6e 20 74  .** once, when t
33660 68 65 20 6d 65 74 61 64 61 74 61 20 69 73 20 64  he metadata is d
33670 69 73 63 61 72 64 65 64 2e 0a 2a 2a 20 53 51 4c  iscarded..** SQL
33680 69 74 65 20 69 73 20 66 72 65 65 20 74 6f 20 64  ite is free to d
33690 69 73 63 61 72 64 20 74 68 65 20 6d 65 74 61 64  iscard the metad
336a0 61 74 61 20 61 74 20 61 6e 79 20 74 69 6d 65 2c  ata at any time,
336b0 20 69 6e 63 6c 75 64 69 6e 67 3a 20 3c 75 6c 3e   including: <ul>
336c0 0a 2a 2a 20 3c 6c 69 3e 20 77 68 65 6e 20 74 68  .** <li> when th
336d0 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
336e0 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74  function paramet
336f0 65 72 20 63 68 61 6e 67 65 73 2c 20 6f 72 0a 2a  er changes, or.*
33700 2a 20 3c 6c 69 3e 20 77 68 65 6e 20 5b 73 71 6c  * <li> when [sql
33710 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
33720 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
33730 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20  ze()] is called 
33740 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  for the.**      
33750 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 6f  SQL statement, o
33760 72 0a 2a 2a 20 3c 6c 69 3e 20 77 68 65 6e 20 73  r.** <li> when s
33770 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
33780 74 61 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20  ta() is invoked 
33790 61 67 61 69 6e 20 6f 6e 20 74 68 65 20 73 61 6d  again on the sam
337a0 65 20 70 61 72 61 6d 65 74 65 72 2c 20 6f 72 0a  e parameter, or.
337b0 2a 2a 20 3c 6c 69 3e 20 64 75 72 69 6e 67 20 74  ** <li> during t
337c0 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 71 6c 69  he original sqli
337d0 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
337e0 29 20 63 61 6c 6c 20 77 68 65 6e 20 61 20 6d 65  ) call when a me
337f0 6d 6f 72 79 20 0a 2a 2a 20 20 20 20 20 20 61 6c  mory .**      al
33800 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f  location error o
33810 63 63 75 72 73 2e 20 3c 2f 75 6c 3e 29 5e 0a 2a  ccurs. </ul>)^.*
33820 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 65 20 6c 61  *.** Note the la
33830 73 74 20 62 75 6c 6c 65 74 20 69 6e 20 70 61 72  st bullet in par
33840 74 69 63 75 6c 61 72 2e 20 20 54 68 65 20 64 65  ticular.  The de
33850 73 74 72 75 63 74 6f 72 20 58 20 69 6e 20 0a 2a  structor X in .*
33860 2a 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  * sqlite3_set_au
33870 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20 6d  xdata(C,N,P,X) m
33880 69 67 68 74 20 62 65 20 63 61 6c 6c 65 64 20 69  ight be called i
33890 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 66 6f  mmediately, befo
338a0 72 65 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65  re the.** sqlite
338b0 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_set_auxdata() 
338c0 69 6e 74 65 72 66 61 63 65 20 65 76 65 6e 20 72  interface even r
338d0 65 74 75 72 6e 73 2e 20 20 48 65 6e 63 65 20 73  eturns.  Hence s
338e0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
338f0 74 61 28 29 0a 2a 2a 20 73 68 6f 75 6c 64 20 62  ta().** should b
33900 65 20 63 61 6c 6c 65 64 20 6e 65 61 72 20 74 68  e called near th
33910 65 20 65 6e 64 20 6f 66 20 74 68 65 20 66 75 6e  e end of the fun
33920 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
33930 74 69 6f 6e 20 61 6e 64 20 74 68 65 0a 2a 2a 20  tion and the.** 
33940 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65  function impleme
33950 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e  ntation should n
33960 6f 74 20 6d 61 6b 65 20 61 6e 79 20 75 73 65 20  ot make any use 
33970 6f 66 20 50 20 61 66 74 65 72 0a 2a 2a 20 73 71  of P after.** sq
33980 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
33990 61 28 29 20 68 61 73 20 62 65 65 6e 20 63 61 6c  a() has been cal
339a0 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20  led..**.** ^(In 
339b0 70 72 61 63 74 69 63 65 2c 20 6d 65 74 61 64 61  practice, metada
339c0 74 61 20 69 73 20 70 72 65 73 65 72 76 65 64 20  ta is preserved 
339d0 62 65 74 77 65 65 6e 20 66 75 6e 63 74 69 6f 6e  between function
339e0 20 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20 66 75   calls for.** fu
339f0 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72  nction parameter
33a00 73 20 74 68 61 74 20 61 72 65 20 63 6f 6d 70 69  s that are compi
33a10 6c 65 2d 74 69 6d 65 20 63 6f 6e 73 74 61 6e 74  le-time constant
33a20 73 2c 20 69 6e 63 6c 75 64 69 6e 67 20 6c 69 74  s, including lit
33a30 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73 20 61  eral.** values a
33a40 6e 64 20 5b 70 61 72 61 6d 65 74 65 72 73 5d 20  nd [parameters] 
33a50 61 6e 64 20 65 78 70 72 65 73 73 69 6f 6e 73 20  and expressions 
33a60 63 6f 6d 70 6f 73 65 64 20 66 72 6f 6d 20 74 68  composed from th
33a70 65 20 73 61 6d 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20  e same.)^.**.** 
33a80 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d  These routines m
33a90 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72  ust be called fr
33aa0 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65  om the same thre
33ab0 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74  ad in which.** t
33ac0 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
33ad0 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53  is running..*/.S
33ae0 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a  QLITE_API void *
33af0 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
33b00 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ata(sqlite3_cont
33b10 65 78 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 53 51  ext*, int N);.SQ
33b20 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71  LITE_API void sq
33b30 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
33b40 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  a(sqlite3_contex
33b50 74 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f 69 64 2a  t*, int N, void*
33b60 2c 20 76 6f 69 64 20 28 2a 29 28 76 6f 69 64 2a  , void (*)(void*
33b70 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ));.../*.** CAPI
33b80 33 52 45 46 3a 20 43 6f 6e 73 74 61 6e 74 73 20  3REF: Constants 
33b90 44 65 66 69 6e 69 6e 67 20 53 70 65 63 69 61 6c  Defining Special
33ba0 20 44 65 73 74 72 75 63 74 6f 72 20 42 65 68 61   Destructor Beha
33bb0 76 69 6f 72 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  vior.**.** These
33bc0 20 61 72 65 20 73 70 65 63 69 61 6c 20 76 61 6c   are special val
33bd0 75 65 73 20 66 6f 72 20 74 68 65 20 64 65 73 74  ues for the dest
33be0 72 75 63 74 6f 72 20 74 68 61 74 20 69 73 20 70  ructor that is p
33bf0 61 73 73 65 64 20 69 6e 20 61 73 20 74 68 65 0a  assed in as the.
33c00 2a 2a 20 66 69 6e 61 6c 20 61 72 67 75 6d 65 6e  ** final argumen
33c10 74 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69  t to routines li
33c20 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  ke [sqlite3_resu
33c30 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20 20 5e 49 66  lt_blob()].  ^If
33c40 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 0a   the destructor.
33c50 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20 53  ** argument is S
33c60 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 69 74  QLITE_STATIC, it
33c70 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
33c80 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65 72 20  content pointer 
33c90 69 73 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20 61  is constant.** a
33ca0 6e 64 20 77 69 6c 6c 20 6e 65 76 65 72 20 63 68  nd will never ch
33cb0 61 6e 67 65 2e 20 20 49 74 20 64 6f 65 73 20 6e  ange.  It does n
33cc0 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 64 65  ot need to be de
33cd0 73 74 72 6f 79 65 64 2e 20 20 5e 54 68 65 0a 2a  stroyed.  ^The.*
33ce0 2a 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45  * SQLITE_TRANSIE
33cf0 4e 54 20 76 61 6c 75 65 20 6d 65 61 6e 73 20 74  NT value means t
33d00 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  hat the content 
33d10 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 63 68 61 6e  will likely chan
33d20 67 65 20 69 6e 0a 2a 2a 20 74 68 65 20 6e 65 61  ge in.** the nea
33d30 72 20 66 75 74 75 72 65 20 61 6e 64 20 74 68 61  r future and tha
33d40 74 20 53 51 4c 69 74 65 20 73 68 6f 75 6c 64 20  t SQLite should 
33d50 6d 61 6b 65 20 69 74 73 20 6f 77 6e 20 70 72 69  make its own pri
33d60 76 61 74 65 20 63 6f 70 79 20 6f 66 0a 2a 2a 20  vate copy of.** 
33d70 74 68 65 20 63 6f 6e 74 65 6e 74 20 62 65 66 6f  the content befo
33d80 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a  re returning..**
33d90 0a 2a 2a 20 54 68 65 20 74 79 70 65 64 65 66 20  .** The typedef 
33da0 69 73 20 6e 65 63 65 73 73 61 72 79 20 74 6f 20  is necessary to 
33db0 77 6f 72 6b 20 61 72 6f 75 6e 64 20 70 72 6f 62  work around prob
33dc0 6c 65 6d 73 20 69 6e 20 63 65 72 74 61 69 6e 0a  lems in certain.
33dd0 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c 65 72 73  ** C++ compilers
33de0 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 76 6f 69  ..*/.typedef voi
33df0 64 20 28 2a 73 71 6c 69 74 65 33 5f 64 65 73 74  d (*sqlite3_dest
33e00 72 75 63 74 6f 72 5f 74 79 70 65 29 28 76 6f 69  ructor_type)(voi
33e10 64 2a 29 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c  d*);.#define SQL
33e20 49 54 45 5f 53 54 41 54 49 43 20 20 20 20 20 20  ITE_STATIC      
33e30 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75  ((sqlite3_destru
33e40 63 74 6f 72 5f 74 79 70 65 29 30 29 0a 23 64 65  ctor_type)0).#de
33e50 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e  fine SQLITE_TRAN
33e60 53 49 45 4e 54 20 20 20 28 28 73 71 6c 69 74 65  SIENT   ((sqlite
33e70 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70  3_destructor_typ
33e80 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e)-1)../*.** CAP
33e90 49 33 52 45 46 3a 20 53 65 74 74 69 6e 67 20 54  I3REF: Setting T
33ea0 68 65 20 52 65 73 75 6c 74 20 4f 66 20 41 6e 20  he Result Of An 
33eb0 53 51 4c 20 46 75 6e 63 74 69 6f 6e 0a 2a 2a 0a  SQL Function.**.
33ec0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
33ed0 73 20 61 72 65 20 75 73 65 64 20 62 79 20 74 68  s are used by th
33ee0 65 20 78 46 75 6e 63 20 6f 72 20 78 46 69 6e 61  e xFunc or xFina
33ef0 6c 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74  l callbacks that
33f00 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51  .** implement SQ
33f10 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20  L functions and 
33f20 61 67 67 72 65 67 61 74 65 73 2e 20 20 53 65 65  aggregates.  See
33f30 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  .** [sqlite3_cre
33f40 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20  ate_function()] 
33f50 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  and [sqlite3_cre
33f60 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
33f70 5d 0a 2a 2a 20 66 6f 72 20 61 64 64 69 74 69 6f  ].** for additio
33f80 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  nal information.
33f90 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e  .**.** These fun
33fa0 63 74 69 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79  ctions work very
33fb0 20 6d 75 63 68 20 6c 69 6b 65 20 74 68 65 20 5b   much like the [
33fc0 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e  parameter bindin
33fd0 67 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20  g] family of.** 
33fe0 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 64 20 74  functions used t
33ff0 6f 20 62 69 6e 64 20 76 61 6c 75 65 73 20 74 6f  o bind values to
34000 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73   host parameters
34010 20 69 6e 20 70 72 65 70 61 72 65 64 20 73 74 61   in prepared sta
34020 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65 66 65  tements..** Refe
34030 72 20 74 6f 20 74 68 65 20 5b 53 51 4c 20 70 61  r to the [SQL pa
34040 72 61 6d 65 74 65 72 5d 20 64 6f 63 75 6d 65 6e  rameter] documen
34050 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74  tation for addit
34060 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f  ional informatio
34070 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  n..**.** ^The sq
34080 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
34090 62 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65  b() interface se
340a0 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 66 72  ts the result fr
340b0 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61  om.** an applica
340c0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
340d0 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20  ction to be the 
340e0 42 4c 4f 42 20 77 68 6f 73 65 20 63 6f 6e 74 65  BLOB whose conte
340f0 6e 74 20 69 73 20 70 6f 69 6e 74 65 64 0a 2a 2a  nt is pointed.**
34100 20 74 6f 20 62 79 20 74 68 65 20 73 65 63 6f 6e   to by the secon
34110 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20  d parameter and 
34120 77 68 69 63 68 20 69 73 20 4e 20 62 79 74 65 73  which is N bytes
34130 20 6c 6f 6e 67 20 77 68 65 72 65 20 4e 20 69 73   long where N is
34140 20 74 68 65 0a 2a 2a 20 74 68 69 72 64 20 70 61   the.** third pa
34150 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  rameter..**.** ^
34160 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
34170 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 69 6e  lt_zeroblob() in
34180 74 65 72 66 61 63 65 73 20 73 65 74 20 74 68 65  terfaces set the
34190 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68   result of.** th
341a0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
341b0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
341c0 6f 20 62 65 20 61 20 42 4c 4f 42 20 63 6f 6e 74  o be a BLOB cont
341d0 61 69 6e 69 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a  aining all zero.
341e0 2a 2a 20 62 79 74 65 73 20 61 6e 64 20 4e 20 62  ** bytes and N b
341f0 79 74 65 73 20 69 6e 20 73 69 7a 65 2c 20 77 68  ytes in size, wh
34200 65 72 65 20 4e 20 69 73 20 74 68 65 20 76 61 6c  ere N is the val
34210 75 65 20 6f 66 20 74 68 65 20 32 6e 64 20 70 61  ue of the 2nd pa
34220 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  rameter..**.** ^
34230 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
34240 6c 74 5f 64 6f 75 62 6c 65 28 29 20 69 6e 74 65  lt_double() inte
34250 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
34260 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e  esult from.** an
34270 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
34280 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
34290 20 62 65 20 61 20 66 6c 6f 61 74 69 6e 67 20 70   be a floating p
342a0 6f 69 6e 74 20 76 61 6c 75 65 20 73 70 65 63 69  oint value speci
342b0 66 69 65 64 0a 2a 2a 20 62 79 20 69 74 73 20 32  fied.** by its 2
342c0 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  nd argument..**.
342d0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
342e0 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61  result_error() a
342f0 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  nd sqlite3_resul
34300 74 5f 65 72 72 6f 72 31 36 28 29 20 66 75 6e 63  t_error16() func
34310 74 69 6f 6e 73 0a 2a 2a 20 63 61 75 73 65 20 74  tions.** cause t
34320 68 65 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 53  he implemented S
34330 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 74  QL function to t
34340 68 72 6f 77 20 61 6e 20 65 78 63 65 70 74 69 6f  hrow an exceptio
34350 6e 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73  n..** ^SQLite us
34360 65 73 20 74 68 65 20 73 74 72 69 6e 67 20 70 6f  es the string po
34370 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 0a  inted to by the.
34380 2a 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  ** 2nd parameter
34390 20 6f 66 20 73 71 6c 69 74 65 33 5f 72 65 73 75   of sqlite3_resu
343a0 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 20 73 71  lt_error() or sq
343b0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
343c0 6f 72 31 36 28 29 0a 2a 2a 20 61 73 20 74 68 65  or16().** as the
343d0 20 74 65 78 74 20 6f 66 20 61 6e 20 65 72 72 6f   text of an erro
343e0 72 20 6d 65 73 73 61 67 65 2e 20 20 5e 53 51 4c  r message.  ^SQL
343f0 69 74 65 20 69 6e 74 65 72 70 72 65 74 73 20 74  ite interprets t
34400 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73  he error.** mess
34410 61 67 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20  age string from 
34420 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
34430 72 72 6f 72 28 29 20 61 73 20 55 54 46 2d 38 2e  rror() as UTF-8.
34440 20 5e 53 51 4c 69 74 65 0a 2a 2a 20 69 6e 74 65   ^SQLite.** inte
34450 72 70 72 65 74 73 20 74 68 65 20 73 74 72 69 6e  rprets the strin
34460 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72  g from sqlite3_r
34470 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20  esult_error16() 
34480 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6e 61 74  as UTF-16 in nat
34490 69 76 65 0a 2a 2a 20 62 79 74 65 20 6f 72 64 65  ive.** byte orde
344a0 72 2e 20 20 5e 49 66 20 74 68 65 20 74 68 69 72  r.  ^If the thir
344b0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
344c0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
344d0 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69  ror().** or sqli
344e0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
344f0 31 36 28 29 20 69 73 20 6e 65 67 61 74 69 76 65  16() is negative
34500 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b   then SQLite tak
34510 65 73 20 61 73 20 74 68 65 20 65 72 72 6f 72 0a  es as the error.
34520 2a 2a 20 6d 65 73 73 61 67 65 20 61 6c 6c 20 74  ** message all t
34530 65 78 74 20 75 70 20 74 68 72 6f 75 67 68 20 74  ext up through t
34540 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68  he first zero ch
34550 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20  aracter..** ^If 
34560 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
34570 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
34580 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72  esult_error() or
34590 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75  .** sqlite3_resu
345a0 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20  lt_error16() is 
345b0 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 74 68 65  non-negative the
345c0 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74  n SQLite takes t
345d0 68 61 74 20 6d 61 6e 79 0a 2a 2a 20 62 79 74 65  hat many.** byte
345e0 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72  s (not character
345f0 73 29 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20  s) from the 2nd 
34600 70 61 72 61 6d 65 74 65 72 20 61 73 20 74 68 65  parameter as the
34610 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a   error message..
34620 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
34630 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61  result_error() a
34640 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  nd sqlite3_resul
34650 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 72  t_error16().** r
34660 6f 75 74 69 6e 65 73 20 6d 61 6b 65 20 61 20 70  outines make a p
34670 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74  rivate copy of t
34680 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
34690 20 74 65 78 74 20 62 65 66 6f 72 65 0a 2a 2a 20   text before.** 
346a0 74 68 65 79 20 72 65 74 75 72 6e 2e 20 20 48 65  they return.  He
346b0 6e 63 65 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67  nce, the calling
346c0 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 64 65   function can de
346d0 61 6c 6c 6f 63 61 74 65 20 6f 72 0a 2a 2a 20 6d  allocate or.** m
346e0 6f 64 69 66 79 20 74 68 65 20 74 65 78 74 20 61  odify the text a
346f0 66 74 65 72 20 74 68 65 79 20 72 65 74 75 72 6e  fter they return
34700 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a   without harm..*
34710 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
34720 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65  esult_error_code
34730 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 68 61 6e  () function chan
34740 67 65 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f  ges the error co
34750 64 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62  de.** returned b
34760 79 20 53 51 4c 69 74 65 20 61 73 20 61 20 72 65  y SQLite as a re
34770 73 75 6c 74 20 6f 66 20 61 6e 20 65 72 72 6f 72  sult of an error
34780 20 69 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 20   in a function. 
34790 20 5e 42 79 20 64 65 66 61 75 6c 74 2c 0a 2a 2a   ^By default,.**
347a0 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20   the error code 
347b0 69 73 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e  is SQLITE_ERROR.
347c0 20 20 5e 41 20 73 75 62 73 65 71 75 65 6e 74 20    ^A subsequent 
347d0 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
347e0 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a  result_error().*
347f0 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73  * or sqlite3_res
34800 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 72 65  ult_error16() re
34810 73 65 74 73 20 74 68 65 20 65 72 72 6f 72 20 63  sets the error c
34820 6f 64 65 20 74 6f 20 53 51 4c 49 54 45 5f 45 52  ode to SQLITE_ER
34830 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ROR..**.** ^The 
34840 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
34850 72 72 6f 72 5f 74 6f 6f 62 69 67 28 29 20 69 6e  rror_toobig() in
34860 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20 53  terface causes S
34870 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61  QLite to throw a
34880 6e 0a 2a 2a 20 65 72 72 6f 72 20 69 6e 64 69 63  n.** error indic
34890 61 74 69 6e 67 20 74 68 61 74 20 61 20 73 74 72  ating that a str
348a0 69 6e 67 20 6f 72 20 42 4c 4f 42 20 69 73 20 74  ing or BLOB is t
348b0 6f 6f 20 6c 6f 6e 67 20 74 6f 20 72 65 70 72 65  oo long to repre
348c0 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  sent..**.** ^The
348d0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
348e0 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 29 20 69 6e  error_nomem() in
348f0 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20 53  terface causes S
34900 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61  QLite to throw a
34910 6e 0a 2a 2a 20 65 72 72 6f 72 20 69 6e 64 69 63  n.** error indic
34920 61 74 69 6e 67 20 74 68 61 74 20 61 20 6d 65 6d  ating that a mem
34930 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
34940 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ailed..**.** ^Th
34950 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
34960 5f 69 6e 74 28 29 20 69 6e 74 65 72 66 61 63 65  _int() interface
34970 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e   sets the return
34980 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65   value.** of the
34990 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
349a0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
349b0 20 62 65 20 74 68 65 20 33 32 2d 62 69 74 20 73   be the 32-bit s
349c0 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a  igned integer.**
349d0 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20   value given in 
349e0 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74  the 2nd argument
349f0 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
34a00 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 29  3_result_int64()
34a10 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
34a20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
34a30 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69  .** of the appli
34a40 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
34a50 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68  unction to be th
34a60 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20  e 64-bit signed 
34a70 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65  integer.** value
34a80 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e   given in the 2n
34a90 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  d argument..**.*
34aa0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
34ab0 65 73 75 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e 74  esult_null() int
34ac0 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
34ad0 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20  return value.** 
34ae0 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
34af0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
34b00 69 6f 6e 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a  ion to be NULL..
34b10 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
34b20 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 29  e3_result_text()
34b30 2c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  , sqlite3_result
34b40 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 73 71  _text16(),.** sq
34b50 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
34b60 74 31 36 6c 65 28 29 2c 20 61 6e 64 20 73 71 6c  t16le(), and sql
34b70 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
34b80 31 36 62 65 28 29 20 69 6e 74 65 72 66 61 63 65  16be() interface
34b90 73 0a 2a 2a 20 73 65 74 20 74 68 65 20 72 65 74  s.** set the ret
34ba0 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65  urn value of the
34bb0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
34bc0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
34bd0 20 62 65 0a 2a 2a 20 61 20 74 65 78 74 20 73 74   be.** a text st
34be0 72 69 6e 67 20 77 68 69 63 68 20 69 73 20 72 65  ring which is re
34bf0 70 72 65 73 65 6e 74 65 64 20 61 73 20 55 54 46  presented as UTF
34c00 2d 38 2c 20 55 54 46 2d 31 36 20 6e 61 74 69 76  -8, UTF-16 nativ
34c10 65 20 62 79 74 65 20 6f 72 64 65 72 2c 0a 2a 2a  e byte order,.**
34c20 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 20 65   UTF-16 little e
34c30 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36  ndian, or UTF-16
34c40 20 62 69 67 20 65 6e 64 69 61 6e 2c 20 72 65 73   big endian, res
34c50 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 53  pectively..** ^S
34c60 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68 65 20  QLite takes the 
34c70 74 65 78 74 20 72 65 73 75 6c 74 20 66 72 6f 6d  text result from
34c80 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
34c90 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e 64   from.** the 2nd
34ca0 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68   parameter of th
34cb0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
34cc0 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
34cd0 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33 72  s..** ^If the 3r
34ce0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
34cf0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
34d00 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
34d10 65 73 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76  es.** is negativ
34d20 65 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74  e, then SQLite t
34d30 61 6b 65 73 20 72 65 73 75 6c 74 20 74 65 78 74  akes result text
34d40 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61   from the 2nd pa
34d50 72 61 6d 65 74 65 72 0a 2a 2a 20 74 68 72 6f 75  rameter.** throu
34d60 67 68 20 74 68 65 20 66 69 72 73 74 20 7a 65 72  gh the first zer
34d70 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20  o character..** 
34d80 5e 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61  ^If the 3rd para
34d90 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
34da0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
34db0 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  * interfaces.** 
34dc0 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c  is non-negative,
34dd0 20 74 68 65 6e 20 61 73 20 6d 61 6e 79 20 62 79   then as many by
34de0 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74  tes (not charact
34df0 65 72 73 29 20 6f 66 20 74 68 65 20 74 65 78 74  ers) of the text
34e00 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62  .** pointed to b
34e10 79 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  y the 2nd parame
34e20 74 65 72 20 61 72 65 20 74 61 6b 65 6e 20 61 73  ter are taken as
34e30 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
34e40 2d 64 65 66 69 6e 65 64 0a 2a 2a 20 66 75 6e 63  -defined.** func
34e50 74 69 6f 6e 20 72 65 73 75 6c 74 2e 20 20 49 66  tion result.  If
34e60 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74   the 3rd paramet
34e70 65 72 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69  er is non-negati
34e80 76 65 2c 20 74 68 65 6e 20 69 74 0a 2a 2a 20 6d  ve, then it.** m
34e90 75 73 74 20 62 65 20 74 68 65 20 62 79 74 65 20  ust be the byte 
34ea0 6f 66 66 73 65 74 20 69 6e 74 6f 20 74 68 65 20  offset into the 
34eb0 73 74 72 69 6e 67 20 77 68 65 72 65 20 74 68 65  string where the
34ec0 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20   NUL terminator 
34ed0 77 6f 75 6c 64 0a 2a 2a 20 61 70 70 65 61 72 20  would.** appear 
34ee0 69 66 20 74 68 65 20 73 74 72 69 6e 67 20 77 68  if the string wh
34ef0 65 72 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74  ere NUL terminat
34f00 65 64 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c 20  ed.  If any NUL 
34f10 63 68 61 72 61 63 74 65 72 73 20 6f 63 63 75 72  characters occur
34f20 0a 2a 2a 20 69 6e 20 74 68 65 20 73 74 72 69 6e  .** in the strin
34f30 67 20 61 74 20 61 20 62 79 74 65 20 6f 66 66 73  g at a byte offs
34f40 65 74 20 74 68 61 74 20 69 73 20 6c 65 73 73 20  et that is less 
34f50 74 68 61 6e 20 74 68 65 20 76 61 6c 75 65 20 6f  than the value o
34f60 66 20 74 68 65 20 33 72 64 0a 2a 2a 20 70 61 72  f the 3rd.** par
34f70 61 6d 65 74 65 72 2c 20 74 68 65 6e 20 74 68 65  ameter, then the
34f80 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e   resulting strin
34f90 67 20 77 69 6c 6c 20 63 6f 6e 74 61 69 6e 20 65  g will contain e
34fa0 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 61 6e 64  mbedded NULs and
34fb0 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 6f   the.** result o
34fc0 66 20 65 78 70 72 65 73 73 69 6f 6e 73 20 6f 70  f expressions op
34fd0 65 72 61 74 69 6e 67 20 6f 6e 20 73 74 72 69 6e  erating on strin
34fe0 67 73 20 77 69 74 68 20 65 6d 62 65 64 64 65 64  gs with embedded
34ff0 20 4e 55 4c 73 20 69 73 20 75 6e 64 65 66 69 6e   NULs is undefin
35000 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34  ed..** ^If the 4
35010 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
35020 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
35030 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
35040 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  ces.** or sqlite
35050 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73  3_result_blob is
35060 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e   a non-NULL poin
35070 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  ter, then SQLite
35080 20 63 61 6c 6c 73 20 74 68 61 74 0a 2a 2a 20 66   calls that.** f
35090 75 6e 63 74 69 6f 6e 20 61 73 20 74 68 65 20 64  unction as the d
350a0 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65  estructor on the
350b0 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65   text or BLOB re
350c0 73 75 6c 74 20 77 68 65 6e 20 69 74 20 68 61 73  sult when it has
350d0 0a 2a 2a 20 66 69 6e 69 73 68 65 64 20 75 73 69  .** finished usi
350e0 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a  ng that result..
350f0 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20 70  ** ^If the 4th p
35100 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
35110 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
35120 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 20  ext* interfaces 
35130 6f 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  or to.** sqlite3
35140 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20  _result_blob is 
35150 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73  the special cons
35160 74 61 6e 74 20 53 51 4c 49 54 45 5f 53 54 41 54  tant SQLITE_STAT
35170 49 43 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 0a  IC, then SQLite.
35180 2a 2a 20 61 73 73 75 6d 65 73 20 74 68 61 74 20  ** assumes that 
35190 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42  the text or BLOB
351a0 20 72 65 73 75 6c 74 20 69 73 20 69 6e 20 63 6f   result is in co
351b0 6e 73 74 61 6e 74 20 73 70 61 63 65 20 61 6e 64  nstant space and
351c0 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f 70   does not.** cop
351d0 79 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66  y the content of
351e0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 6e   the parameter n
351f0 6f 72 20 63 61 6c 6c 20 61 20 64 65 73 74 72 75  or call a destru
35200 63 74 6f 72 20 6f 6e 20 74 68 65 20 63 6f 6e 74  ctor on the cont
35210 65 6e 74 0a 2a 2a 20 77 68 65 6e 20 69 74 20 68  ent.** when it h
35220 61 73 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e  as finished usin
35230 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a  g that result..*
35240 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 61  * ^If the 4th pa
35250 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
35260 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
35270 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  xt* interfaces.*
35280 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73  * or sqlite3_res
35290 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20  ult_blob is the 
352a0 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74  special constant
352b0 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e   SQLITE_TRANSIEN
352c0 54 0a 2a 2a 20 74 68 65 6e 20 53 51 4c 69 74 65  T.** then SQLite
352d0 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66   makes a copy of
352e0 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e 74 6f   the result into
352f0 20 73 70 61 63 65 20 6f 62 74 61 69 6e 65 64 20   space obtained 
35300 66 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71  from.** from [sq
35310 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
35320 62 65 66 6f 72 65 20 69 74 20 72 65 74 75 72 6e  before it return
35330 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  s..**.** ^The sq
35340 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
35350 75 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  ue() interface s
35360 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 6f  ets the result o
35370 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61  f.** the applica
35380 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
35390 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 63 6f  ction to be a co
353a0 70 79 20 74 68 65 0a 2a 2a 20 5b 75 6e 70 72 6f  py the.** [unpro
353b0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
353c0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 73 70 65  alue] object spe
353d0 63 69 66 69 65 64 20 62 79 20 74 68 65 20 32 6e  cified by the 2n
353e0 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 54  d parameter.  ^T
353f0 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65  he.** sqlite3_re
35400 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74  sult_value() int
35410 65 72 66 61 63 65 20 6d 61 6b 65 73 20 61 20 63  erface makes a c
35420 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  opy of the [sqli
35430 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 73 6f  te3_value].** so
35440 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74   that the [sqlit
35450 65 33 5f 76 61 6c 75 65 5d 20 73 70 65 63 69 66  e3_value] specif
35460 69 65 64 20 69 6e 20 74 68 65 20 70 61 72 61 6d  ied in the param
35470 65 74 65 72 20 6d 61 79 20 63 68 61 6e 67 65 20  eter may change 
35480 6f 72 0a 2a 2a 20 62 65 20 64 65 61 6c 6c 6f 63  or.** be dealloc
35490 61 74 65 64 20 61 66 74 65 72 20 73 71 6c 69 74  ated after sqlit
354a0 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
354b0 29 20 72 65 74 75 72 6e 73 20 77 69 74 68 6f 75  ) returns withou
354c0 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 41 20 5b 70  t harm..** ^A [p
354d0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
354e0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 6d  _value] object m
354f0 61 79 20 61 6c 77 61 79 73 20 62 65 20 75 73 65  ay always be use
35500 64 20 77 68 65 72 65 20 61 6e 0a 2a 2a 20 5b 75  d where an.** [u
35510 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
35520 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
35530 20 69 73 20 72 65 71 75 69 72 65 64 2c 20 73 6f   is required, so
35540 20 65 69 74 68 65 72 0a 2a 2a 20 6b 69 6e 64 20   either.** kind 
35550 6f 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  of [sqlite3_valu
35560 65 5d 20 6f 62 6a 65 63 74 20 63 61 6e 20 62 65  e] object can be
35570 20 75 73 65 64 20 77 69 74 68 20 74 68 69 73 20   used with this 
35580 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
35590 20 49 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   If these routin
355a0 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72  es are called fr
355b0 6f 6d 20 77 69 74 68 69 6e 20 74 68 65 20 64 69  om within the di
355c0 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 0a 2a  fferent thread.*
355d0 2a 20 74 68 61 6e 20 74 68 65 20 6f 6e 65 20 63  * than the one c
355e0 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 61 70  ontaining the ap
355f0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
35600 64 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20  d function that 
35610 72 65 63 65 69 76 65 64 0a 2a 2a 20 74 68 65 20  received.** the 
35620 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  [sqlite3_context
35630 5d 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 20 72  ] pointer, the r
35640 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66  esults are undef
35650 69 6e 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  ined..*/.SQLITE_
35660 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33  API void sqlite3
35670 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 73 71 6c  _result_blob(sql
35680 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
35690 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c  onst void*, int,
356a0 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
356b0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  ;.SQLITE_API voi
356c0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
356d0 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f  _double(sqlite3_
356e0 63 6f 6e 74 65 78 74 2a 2c 20 64 6f 75 62 6c 65  context*, double
356f0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  );.SQLITE_API vo
35700 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
35710 74 5f 65 72 72 6f 72 28 73 71 6c 69 74 65 33 5f  t_error(sqlite3_
35720 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
35730 63 68 61 72 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c  char*, int);.SQL
35740 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c  ITE_API void sql
35750 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
35760 72 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  r16(sqlite3_cont
35770 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ext*, const void
35780 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f  *, int);.SQLITE_
35790 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33  API void sqlite3
357a0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f  _result_error_to
357b0 6f 62 69 67 28 73 71 6c 69 74 65 33 5f 63 6f 6e  obig(sqlite3_con
357c0 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41  text*);.SQLITE_A
357d0 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  PI void sqlite3_
357e0 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d  result_error_nom
357f0 65 6d 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  em(sqlite3_conte
35800 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  xt*);.SQLITE_API
35810 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65   void sqlite3_re
35820 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28  sult_error_code(
35830 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
35840 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41  , int);.SQLITE_A
35850 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  PI void sqlite3_
35860 72 65 73 75 6c 74 5f 69 6e 74 28 73 71 6c 69 74  result_int(sqlit
35870 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
35880 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  );.SQLITE_API vo
35890 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
358a0 74 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f  t_int64(sqlite3_
358b0 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65  context*, sqlite
358c0 33 5f 69 6e 74 36 34 29 3b 0a 53 51 4c 49 54 45  3_int64);.SQLITE
358d0 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65  _API void sqlite
358e0 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 73 71  3_result_null(sq
358f0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
35900 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
35910 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
35920 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e  text(sqlite3_con
35930 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61  text*, const cha
35940 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29  r*, int, void(*)
35950 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45  (void*));.SQLITE
35960 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65  _API void sqlite
35970 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28  3_result_text16(
35980 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
35990 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
359a0 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  nt, void(*)(void
359b0 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  *));.SQLITE_API 
359c0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
359d0 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 73 71 6c  ult_text16le(sql
359e0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
359f0 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c  onst void*, int,
35a00 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
35a10 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
35a20 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
35a30 74 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 33  text16be(sqlite3
35a40 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
35a50 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64   void*, int,void
35a60 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c  (*)(void*));.SQL
35a70 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c  ITE_API void sql
35a80 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
35a90 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
35aa0 74 2a 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  t*, sqlite3_valu
35ab0 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  e*);.SQLITE_API 
35ac0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
35ad0 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c  ult_zeroblob(sql
35ae0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
35af0 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  nt n);../*.** CA
35b00 50 49 33 52 45 46 3a 20 44 65 66 69 6e 65 20 4e  PI3REF: Define N
35b10 65 77 20 43 6f 6c 6c 61 74 69 6e 67 20 53 65 71  ew Collating Seq
35b20 75 65 6e 63 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  uences.**.** ^Th
35b30 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 64  ese functions ad
35b40 64 2c 20 72 65 6d 6f 76 65 2c 20 6f 72 20 6d 6f  d, remove, or mo
35b50 64 69 66 79 20 61 20 5b 63 6f 6c 6c 61 74 69 6f  dify a [collatio
35b60 6e 5d 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a  n] associated.**
35b70 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62   with the [datab
35b80 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
35b90 73 70 65 63 69 66 69 65 64 20 61 73 20 74 68 65  specified as the
35ba0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e   first argument.
35bb0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65  .**.** ^The name
35bc0 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f   of the collatio
35bd0 6e 20 69 73 20 61 20 55 54 46 2d 38 20 73 74 72  n is a UTF-8 str
35be0 69 6e 67 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74  ing.** for sqlit
35bf0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
35c00 69 6f 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ion() and sqlite
35c10 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
35c20 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61 6e 64 20 61  on_v2().** and a
35c30 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69   UTF-16 string i
35c40 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  n native byte or
35c50 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f  der for sqlite3_
35c60 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
35c70 31 36 28 29 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74  16()..** ^Collat
35c80 69 6f 6e 20 6e 61 6d 65 73 20 74 68 61 74 20 63  ion names that c
35c90 6f 6d 70 61 72 65 20 65 71 75 61 6c 20 61 63 63  ompare equal acc
35ca0 6f 72 64 69 6e 67 20 74 6f 20 5b 73 71 6c 69 74  ording to [sqlit
35cb0 65 33 5f 73 74 72 6e 69 63 6d 70 28 29 5d 20 61  e3_strnicmp()] a
35cc0 72 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65 64  re.** considered
35cd0 20 74 6f 20 62 65 20 74 68 65 20 73 61 6d 65 20   to be the same 
35ce0 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  name..**.** ^(Th
35cf0 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
35d00 20 28 65 54 65 78 74 52 65 70 29 20 6d 75 73 74   (eTextRep) must
35d10 20 62 65 20 6f 6e 65 20 6f 66 20 74 68 65 20 63   be one of the c
35d20 6f 6e 73 74 61 6e 74 73 3a 0a 2a 2a 20 3c 75 6c  onstants:.** <ul
35d30 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  >.** <li> [SQLIT
35d40 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20 3c 6c 69 3e  E_UTF8],.** <li>
35d50 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45   [SQLITE_UTF16LE
35d60 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  ],.** <li> [SQLI
35d70 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20  TE_UTF16BE],.** 
35d80 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46  <li> [SQLITE_UTF
35d90 31 36 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20  16], or.** <li> 
35da0 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c  [SQLITE_UTF16_AL
35db0 49 47 4e 45 44 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e  IGNED]..** </ul>
35dc0 29 5e 0a 2a 2a 20 5e 54 68 65 20 65 54 65 78 74  )^.** ^The eText
35dd0 52 65 70 20 61 72 67 75 6d 65 6e 74 20 64 65 74  Rep argument det
35de0 65 72 6d 69 6e 65 73 20 74 68 65 20 65 6e 63 6f  ermines the enco
35df0 64 69 6e 67 20 6f 66 20 73 74 72 69 6e 67 73 20  ding of strings 
35e00 70 61 73 73 65 64 0a 2a 2a 20 74 6f 20 74 68 65  passed.** to the
35e10 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
35e20 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2c 20 78 43  ion callback, xC
35e30 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 54 68 65  allback..** ^The
35e40 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 20   [SQLITE_UTF16] 
35e50 61 6e 64 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  and [SQLITE_UTF1
35e60 36 5f 41 4c 49 47 4e 45 44 5d 20 76 61 6c 75 65  6_ALIGNED] value
35e70 73 20 66 6f 72 20 65 54 65 78 74 52 65 70 0a 2a  s for eTextRep.*
35e80 2a 20 66 6f 72 63 65 20 73 74 72 69 6e 67 73 20  * force strings 
35e90 74 6f 20 62 65 20 55 54 46 31 36 20 77 69 74 68  to be UTF16 with
35ea0 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
35eb0 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  er..** ^The [SQL
35ec0 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45  ITE_UTF16_ALIGNE
35ed0 44 5d 20 76 61 6c 75 65 20 66 6f 72 20 65 54 65  D] value for eTe
35ee0 78 74 52 65 70 20 66 6f 72 63 65 73 20 73 74 72  xtRep forces str
35ef0 69 6e 67 73 20 74 6f 20 62 65 67 69 6e 0a 2a 2a  ings to begin.**
35f00 20 6f 6e 20 61 6e 20 65 76 65 6e 20 62 79 74 65   on an even byte
35f10 20 61 64 64 72 65 73 73 2e 0a 2a 2a 0a 2a 2a 20   address..**.** 
35f20 5e 54 68 65 20 66 6f 75 72 74 68 20 61 72 67 75  ^The fourth argu
35f30 6d 65 6e 74 2c 20 70 41 72 67 2c 20 69 73 20 61  ment, pArg, is a
35f40 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61  n application da
35f50 74 61 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20  ta pointer that 
35f60 69 73 20 70 61 73 73 65 64 0a 2a 2a 20 74 68 72  is passed.** thr
35f70 6f 75 67 68 20 61 73 20 74 68 65 20 66 69 72 73  ough as the firs
35f80 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
35f90 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  e collating func
35fa0 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a  tion callback..*
35fb0 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 20  *.** ^The fifth 
35fc0 61 72 67 75 6d 65 6e 74 2c 20 78 43 61 6c 6c 62  argument, xCallb
35fd0 61 63 6b 2c 20 69 73 20 61 20 70 6f 69 6e 74 65  ack, is a pointe
35fe0 72 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69  r to the collati
35ff0 6e 67 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20  ng function..** 
36000 5e 4d 75 6c 74 69 70 6c 65 20 63 6f 6c 6c 61 74  ^Multiple collat
36010 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 63 61  ing functions ca
36020 6e 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20  n be registered 
36030 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65 20 6e  using the same n
36040 61 6d 65 20 62 75 74 0a 2a 2a 20 77 69 74 68 20  ame but.** with 
36050 64 69 66 66 65 72 65 6e 74 20 65 54 65 78 74 52  different eTextR
36060 65 70 20 70 61 72 61 6d 65 74 65 72 73 20 61 6e  ep parameters an
36070 64 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73  d SQLite will us
36080 65 20 77 68 69 63 68 65 76 65 72 0a 2a 2a 20 66  e whichever.** f
36090 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73  unction requires
360a0 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e   the least amoun
360b0 74 20 6f 66 20 64 61 74 61 20 74 72 61 6e 73 66  t of data transf
360c0 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66  ormation..** ^If
360d0 20 74 68 65 20 78 43 61 6c 6c 62 61 63 6b 20 61   the xCallback a
360e0 72 67 75 6d 65 6e 74 20 69 73 20 4e 55 4c 4c 20  rgument is NULL 
360f0 74 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69  then the collati
36100 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a  ng function is.*
36110 2a 20 64 65 6c 65 74 65 64 2e 20 20 5e 57 68 65  * deleted.  ^Whe
36120 6e 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6e 67 20  n all collating 
36130 66 75 6e 63 74 69 6f 6e 73 20 68 61 76 69 6e 67  functions having
36140 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 61   the same name a
36150 72 65 20 64 65 6c 65 74 65 64 2c 0a 2a 2a 20 74  re deleted,.** t
36160 68 61 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73  hat collation is
36170 20 6e 6f 20 6c 6f 6e 67 65 72 20 75 73 61 62 6c   no longer usabl
36180 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 6f  e..**.** ^The co
36190 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
361a0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
361b0 6f 6b 65 64 20 77 69 74 68 20 61 20 63 6f 70 79  oked with a copy
361c0 20 6f 66 20 74 68 65 20 70 41 72 67 20 0a 2a 2a   of the pArg .**
361d0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74   application dat
361e0 61 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 77 69  a pointer and wi
361f0 74 68 20 74 77 6f 20 73 74 72 69 6e 67 73 20 69  th two strings i
36200 6e 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 73  n the encoding s
36210 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74  pecified.** by t
36220 68 65 20 65 54 65 78 74 52 65 70 20 61 72 67 75  he eTextRep argu
36230 6d 65 6e 74 2e 20 20 54 68 65 20 63 6f 6c 6c 61  ment.  The colla
36240 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75  ting function mu
36250 73 74 20 72 65 74 75 72 6e 20 61 6e 0a 2a 2a 20  st return an.** 
36260 69 6e 74 65 67 65 72 20 74 68 61 74 20 69 73 20  integer that is 
36270 6e 65 67 61 74 69 76 65 2c 20 7a 65 72 6f 2c 20  negative, zero, 
36280 6f 72 20 70 6f 73 69 74 69 76 65 0a 2a 2a 20 69  or positive.** i
36290 66 20 74 68 65 20 66 69 72 73 74 20 73 74 72 69  f the first stri
362a0 6e 67 20 69 73 20 6c 65 73 73 20 74 68 61 6e 2c  ng is less than,
362b0 20 65 71 75 61 6c 20 74 6f 2c 20 6f 72 20 67 72   equal to, or gr
362c0 65 61 74 65 72 20 74 68 61 6e 20 74 68 65 20 73  eater than the s
362d0 65 63 6f 6e 64 2c 0a 2a 2a 20 72 65 73 70 65 63  econd,.** respec
362e0 74 69 76 65 6c 79 2e 20 20 41 20 63 6f 6c 6c 61  tively.  A colla
362f0 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75  ting function mu
36300 73 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  st always return
36310 20 74 68 65 20 73 61 6d 65 20 61 6e 73 77 65 72   the same answer
36320 0a 2a 2a 20 67 69 76 65 6e 20 74 68 65 20 73 61  .** given the sa
36330 6d 65 20 69 6e 70 75 74 73 2e 20 20 49 66 20 74  me inputs.  If t
36340 77 6f 20 6f 72 20 6d 6f 72 65 20 63 6f 6c 6c 61  wo or more colla
36350 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 61  ting functions a
36360 72 65 20 72 65 67 69 73 74 65 72 65 64 0a 2a 2a  re registered.**
36370 20 74 6f 20 74 68 65 20 73 61 6d 65 20 63 6f 6c   to the same col
36380 6c 61 74 69 6f 6e 20 6e 61 6d 65 20 28 75 73 69  lation name (usi
36390 6e 67 20 64 69 66 66 65 72 65 6e 74 20 65 54 65  ng different eTe
363a0 78 74 52 65 70 20 76 61 6c 75 65 73 29 20 74 68  xtRep values) th
363b0 65 6e 20 61 6c 6c 0a 2a 2a 20 6d 75 73 74 20 67  en all.** must g
363c0 69 76 65 20 61 6e 20 65 71 75 69 76 61 6c 65 6e  ive an equivalen
363d0 74 20 61 6e 73 77 65 72 20 77 68 65 6e 20 69 6e  t answer when in
363e0 76 6f 6b 65 64 20 77 69 74 68 20 65 71 75 69 76  voked with equiv
363f0 61 6c 65 6e 74 20 73 74 72 69 6e 67 73 2e 0a 2a  alent strings..*
36400 2a 20 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20  * The collating 
36410 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6f 62  function must ob
36420 65 79 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  ey the following
36430 20 70 72 6f 70 65 72 74 69 65 73 20 66 6f 72 20   properties for 
36440 61 6c 6c 0a 2a 2a 20 73 74 72 69 6e 67 73 20 41  all.** strings A
36450 2c 20 42 2c 20 61 6e 64 20 43 3a 0a 2a 2a 0a 2a  , B, and C:.**.*
36460 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 49  * <ol>.** <li> I
36470 66 20 41 3d 3d 42 20 74 68 65 6e 20 42 3d 3d 41  f A==B then B==A
36480 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 3d 3d  ..** <li> If A==
36490 42 20 61 6e 64 20 42 3d 3d 43 20 74 68 65 6e 20  B and B==C then 
364a0 41 3d 3d 43 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66  A==C..** <li> If
364b0 20 41 26 6c 74 3b 42 20 54 48 45 4e 20 42 26 67   A&lt;B THEN B&g
364c0 74 3b 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20  t;A..** <li> If 
364d0 41 26 6c 74 3b 42 20 61 6e 64 20 42 26 6c 74 3b  A&lt;B and B&lt;
364e0 43 20 74 68 65 6e 20 41 26 6c 74 3b 43 2e 0a 2a  C then A&lt;C..*
364f0 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66  * </ol>.**.** If
36500 20 61 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e   a collating fun
36510 63 74 69 6f 6e 20 66 61 69 6c 73 20 61 6e 79 20  ction fails any 
36520 6f 66 20 74 68 65 20 61 62 6f 76 65 20 63 6f 6e  of the above con
36530 73 74 72 61 69 6e 74 73 20 61 6e 64 20 74 68 61  straints and tha
36540 74 0a 2a 2a 20 63 6f 6c 6c 61 74 69 6e 67 20 66  t.** collating f
36550 75 6e 63 74 69 6f 6e 20 69 73 20 20 72 65 67 69  unction is  regi
36560 73 74 65 72 65 64 20 61 6e 64 20 75 73 65 64 2c  stered and used,
36570 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
36580 6f 72 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20  or of SQLite.** 
36590 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
365a0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
365b0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
365c0 6e 5f 76 32 28 29 20 77 6f 72 6b 73 20 6c 69 6b  n_v2() works lik
365d0 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  e sqlite3_create
365e0 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 0a 2a 2a 20  _collation().** 
365f0 77 69 74 68 20 74 68 65 20 61 64 64 69 74 69 6f  with the additio
36600 6e 20 74 68 61 74 20 74 68 65 20 78 44 65 73 74  n that the xDest
36610 72 6f 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  roy callback is 
36620 69 6e 76 6f 6b 65 64 20 6f 6e 20 70 41 72 67 20  invoked on pArg 
36630 77 68 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c  when.** the coll
36640 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69  ating function i
36650 73 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e 43  s deleted..** ^C
36660 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
36670 6e 73 20 61 72 65 20 64 65 6c 65 74 65 64 20 77  ns are deleted w
36680 68 65 6e 20 74 68 65 79 20 61 72 65 20 6f 76 65  hen they are ove
36690 72 72 69 64 64 65 6e 20 62 79 20 6c 61 74 65 72  rridden by later
366a0 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 74 68 65  .** calls to the
366b0 20 63 6f 6c 6c 61 74 69 6f 6e 20 63 72 65 61 74   collation creat
366c0 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72  ion functions or
366d0 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 64 61   when the.** [da
366e0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
366f0 6e 5d 20 69 73 20 63 6c 6f 73 65 64 20 75 73 69  n] is closed usi
36700 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73  ng [sqlite3_clos
36710 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  e()]..**.** ^The
36720 20 78 44 65 73 74 72 6f 79 20 63 61 6c 6c 62 61   xDestroy callba
36730 63 6b 20 69 73 20 3c 75 3e 6e 6f 74 3c 2f 75 3e  ck is <u>not</u>
36740 20 63 61 6c 6c 65 64 20 69 66 20 74 68 65 20 0a   called if the .
36750 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  ** sqlite3_creat
36760 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29  e_collation_v2()
36770 20 66 75 6e 63 74 69 6f 6e 20 66 61 69 6c 73 2e   function fails.
36780 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74    Applications t
36790 68 61 74 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71  hat invoke.** sq
367a0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
367b0 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77 69 74 68  lation_v2() with
367c0 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 78 44 65 73   a non-NULL xDes
367d0 74 72 6f 79 20 61 72 67 75 6d 65 6e 74 20 73 68  troy argument sh
367e0 6f 75 6c 64 20 0a 2a 2a 20 63 68 65 63 6b 20 74  ould .** check t
367f0 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 61  he return code a
36800 6e 64 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68  nd dispose of th
36810 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61  e application da
36820 74 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 68  ta pointer.** th
36830 65 6d 73 65 6c 76 65 73 20 72 61 74 68 65 72 20  emselves rather 
36840 74 68 61 6e 20 65 78 70 65 63 74 69 6e 67 20 53  than expecting S
36850 51 4c 69 74 65 20 74 6f 20 64 65 61 6c 20 77 69  QLite to deal wi
36860 74 68 20 69 74 20 66 6f 72 20 74 68 65 6d 2e 0a  th it for them..
36870 2a 2a 20 54 68 69 73 20 69 73 20 64 69 66 66 65  ** This is diffe
36880 72 65 6e 74 20 66 72 6f 6d 20 65 76 65 72 79 20  rent from every 
36890 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74  other SQLite int
368a0 65 72 66 61 63 65 2e 20 20 54 68 65 20 69 6e 63  erface.  The inc
368b0 6f 6e 73 69 73 74 65 6e 63 79 20 0a 2a 2a 20 69  onsistency .** i
368c0 73 20 75 6e 66 6f 72 74 75 6e 61 74 65 20 62 75  s unfortunate bu
368d0 74 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e  t cannot be chan
368e0 67 65 64 20 77 69 74 68 6f 75 74 20 62 72 65 61  ged without brea
368f0 6b 69 6e 67 20 62 61 63 6b 77 61 72 64 73 20 0a  king backwards .
36900 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ** compatibility
36910 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
36920 3a 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  :  [sqlite3_coll
36930 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 5d 20  ation_needed()] 
36940 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  and [sqlite3_col
36950 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28  lation_needed16(
36960 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  )]..*/.SQLITE_AP
36970 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  I int sqlite3_cr
36980 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 0a  eate_collation(.
36990 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63    sqlite3*, .  c
369a0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
369b0 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  , .  int eTextRe
369c0 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41 72 67  p, .  void *pArg
369d0 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72  ,.  int(*xCompar
369e0 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  e)(void*,int,con
369f0 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  st void*,int,con
36a00 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 53 51 4c  st void*).);.SQL
36a10 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
36a20 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
36a30 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74  tion_v2(.  sqlit
36a40 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68  e3*, .  const ch
36a50 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e  ar *zName, .  in
36a60 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76  t eTextRep, .  v
36a70 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74  oid *pArg,.  int
36a80 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64  (*xCompare)(void
36a90 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64  *,int,const void
36aa0 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64  *,int,const void
36ab0 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73  *),.  void(*xDes
36ac0 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a  troy)(void*).);.
36ad0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
36ae0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
36af0 6c 6c 61 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c  llation16(.  sql
36b00 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20  ite3*, .  const 
36b10 76 6f 69 64 20 2a 7a 4e 61 6d 65 2c 0a 20 20 69  void *zName,.  i
36b20 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20  nt eTextRep, .  
36b30 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e  void *pArg,.  in
36b40 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69  t(*xCompare)(voi
36b50 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69  d*,int,const voi
36b60 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69  d*,int,const voi
36b70 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  d*).);../*.** CA
36b80 50 49 33 52 45 46 3a 20 43 6f 6c 6c 61 74 69 6f  PI3REF: Collatio
36b90 6e 20 4e 65 65 64 65 64 20 43 61 6c 6c 62 61 63  n Needed Callbac
36ba0 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 6f 20 61 76 6f  ks.**.** ^To avo
36bb0 69 64 20 68 61 76 69 6e 67 20 74 6f 20 72 65 67  id having to reg
36bc0 69 73 74 65 72 20 61 6c 6c 20 63 6f 6c 6c 61 74  ister all collat
36bd0 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 62 65  ion sequences be
36be0 66 6f 72 65 20 61 20 64 61 74 61 62 61 73 65 0a  fore a database.
36bf0 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64 2c 20  ** can be used, 
36c00 61 20 73 69 6e 67 6c 65 20 63 61 6c 6c 62 61 63  a single callbac
36c10 6b 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62  k function may b
36c20 65 20 72 65 67 69 73 74 65 72 65 64 20 77 69 74  e registered wit
36c30 68 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61  h the.** [databa
36c40 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74  se connection] t
36c50 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65  o be invoked whe
36c60 6e 65 76 65 72 20 61 6e 20 75 6e 64 65 66 69 6e  never an undefin
36c70 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20  ed collation.** 
36c80 73 65 71 75 65 6e 63 65 20 69 73 20 72 65 71 75  sequence is requ
36c90 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ired..**.** ^If 
36ca0 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  the function is 
36cb0 72 65 67 69 73 74 65 72 65 64 20 75 73 69 6e 67  registered using
36cc0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c   the sqlite3_col
36cd0 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20  lation_needed() 
36ce0 41 50 49 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20  API,.** then it 
36cf0 69 73 20 70 61 73 73 65 64 20 74 68 65 20 6e 61  is passed the na
36d00 6d 65 73 20 6f 66 20 75 6e 64 65 66 69 6e 65 64  mes of undefined
36d10 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   collation seque
36d20 6e 63 65 73 20 61 73 20 73 74 72 69 6e 67 73 0a  nces as strings.
36d30 2a 2a 20 65 6e 63 6f 64 65 64 20 69 6e 20 55 54  ** encoded in UT
36d40 46 2d 38 2e 20 5e 49 66 20 73 71 6c 69 74 65 33  F-8. ^If sqlite3
36d50 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
36d60 64 31 36 28 29 20 69 73 20 75 73 65 64 2c 0a 2a  d16() is used,.*
36d70 2a 20 74 68 65 20 6e 61 6d 65 73 20 61 72 65 20  * the names are 
36d80 70 61 73 73 65 64 20 61 73 20 55 54 46 2d 31 36  passed as UTF-16
36d90 20 69 6e 20 6d 61 63 68 69 6e 65 20 6e 61 74 69   in machine nati
36da0 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a  ve byte order..*
36db0 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 65 69 74  * ^A call to eit
36dc0 68 65 72 20 66 75 6e 63 74 69 6f 6e 20 72 65 70  her function rep
36dd0 6c 61 63 65 73 20 74 68 65 20 65 78 69 73 74 69  laces the existi
36de0 6e 67 20 63 6f 6c 6c 61 74 69 6f 6e 2d 6e 65 65  ng collation-nee
36df0 64 65 64 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  ded callback..**
36e00 0a 2a 2a 20 5e 28 57 68 65 6e 20 74 68 65 20 63  .** ^(When the c
36e10 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
36e20 65 64 2c 20 74 68 65 20 66 69 72 73 74 20 61 72  ed, the first ar
36e30 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 69 73  gument passed is
36e40 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68   a copy.** of th
36e50 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
36e60 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  t to sqlite3_col
36e70 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20  lation_needed() 
36e80 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  or.** sqlite3_co
36e90 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36  llation_needed16
36ea0 28 29 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ().  The second 
36eb0 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
36ec0 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
36ed0 65 63 74 69 6f 6e 2e 20 20 54 68 65 20 74 68 69  ection.  The thi
36ee0 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f  rd argument is o
36ef0 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 55 54  ne of [SQLITE_UT
36f00 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46  F8], [SQLITE_UTF
36f10 31 36 42 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51  16BE],.** or [SQ
36f20 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 20 69  LITE_UTF16LE], i
36f30 6e 64 69 63 61 74 69 6e 67 20 74 68 65 20 6d 6f  ndicating the mo
36f40 73 74 20 64 65 73 69 72 61 62 6c 65 20 66 6f 72  st desirable for
36f50 6d 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74 69  m of the collati
36f60 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 66  on.** sequence f
36f70 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 64  unction required
36f80 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20 70 61  .  The fourth pa
36f90 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e  rameter is the n
36fa0 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65  ame of the.** re
36fb0 71 75 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e  quired collation
36fc0 20 73 65 71 75 65 6e 63 65 2e 29 5e 0a 2a 2a 0a   sequence.)^.**.
36fd0 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20  ** The callback 
36fe0 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20  function should 
36ff0 72 65 67 69 73 74 65 72 20 74 68 65 20 64 65 73  register the des
37000 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 75  ired collation u
37010 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
37020 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
37030 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63  n()], [sqlite3_c
37040 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31  reate_collation1
37050 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c  6()], or.** [sql
37060 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
37070 61 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a  ation_v2()]..*/.
37080 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
37090 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
370a0 5f 6e 65 65 64 65 64 28 0a 20 20 73 71 6c 69 74  _needed(.  sqlit
370b0 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 20 0a  e3*, .  void*, .
370c0 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c    void(*)(void*,
370d0 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65  sqlite3*,int eTe
370e0 78 74 52 65 70 2c 63 6f 6e 73 74 20 63 68 61 72  xtRep,const char
370f0 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  *).);.SQLITE_API
37100 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c   int sqlite3_col
37110 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28  lation_needed16(
37120 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
37130 76 6f 69 64 2a 2c 0a 20 20 76 6f 69 64 28 2a 29  void*,.  void(*)
37140 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c  (void*,sqlite3*,
37150 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e  int eTextRep,con
37160 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 23 69  st void*).);..#i
37170 66 64 65 66 20 53 51 4c 49 54 45 5f 48 41 53 5f  fdef SQLITE_HAS_
37180 43 4f 44 45 43 0a 2f 2a 0a 2a 2a 20 53 70 65 63  CODEC./*.** Spec
37190 69 66 79 20 74 68 65 20 6b 65 79 20 66 6f 72 20  ify the key for 
371a0 61 6e 20 65 6e 63 72 79 70 74 65 64 20 64 61 74  an encrypted dat
371b0 61 62 61 73 65 2e 20 20 54 68 69 73 20 72 6f 75  abase.  This rou
371c0 74 69 6e 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a  tine should be.*
371d0 2a 20 63 61 6c 6c 65 64 20 72 69 67 68 74 20 61  * called right a
371e0 66 74 65 72 20 73 71 6c 69 74 65 33 5f 6f 70 65  fter sqlite3_ope
371f0 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  n()..**.** The c
37200 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  ode to implement
37210 20 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74   this API is not
37220 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68   available in th
37230 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65  e public release
37240 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  .** of SQLite..*
37250 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
37260 20 73 71 6c 69 74 65 33 5f 6b 65 79 28 0a 20 20   sqlite3_key(.  
37270 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
37280 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
37290 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 62 65  * Database to be
372a0 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f   rekeyed */.  co
372b0 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20  nst void *pKey, 
372c0 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20  int nKey     /* 
372d0 54 68 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a 53 51  The key */.);.SQ
372e0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
372f0 69 74 65 33 5f 6b 65 79 5f 76 32 28 0a 20 20 73  ite3_key_v2(.  s
37300 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
37310 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
37320 20 44 61 74 61 62 61 73 65 20 74 6f 20 62 65 20   Database to be 
37330 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e  rekeyed */.  con
37340 73 74 20 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65  st char *zDbName
37350 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e  ,           /* N
37360 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ame of the datab
37370 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  ase */.  const v
37380 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e  oid *pKey, int n
37390 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6b  Key     /* The k
373a0 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ey */.);../*.** 
373b0 43 68 61 6e 67 65 20 74 68 65 20 6b 65 79 20 6f  Change the key o
373c0 6e 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61  n an open databa
373d0 73 65 2e 20 20 49 66 20 74 68 65 20 63 75 72 72  se.  If the curr
373e0 65 6e 74 20 64 61 74 61 62 61 73 65 20 69 73 20  ent database is 
373f0 6e 6f 74 0a 2a 2a 20 65 6e 63 72 79 70 74 65 64  not.** encrypted
37400 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  , this routine w
37410 69 6c 6c 20 65 6e 63 72 79 70 74 20 69 74 2e 20  ill encrypt it. 
37420 20 49 66 20 70 4e 65 77 3d 3d 30 20 6f 72 20 6e   If pNew==0 or n
37430 4e 65 77 3d 3d 30 2c 20 74 68 65 0a 2a 2a 20 64  New==0, the.** d
37440 61 74 61 62 61 73 65 20 69 73 20 64 65 63 72 79  atabase is decry
37450 70 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  pted..**.** The 
37460 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  code to implemen
37470 74 20 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f  t this API is no
37480 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74  t available in t
37490 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73  he public releas
374a0 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a  e.** of SQLite..
374b0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
374c0 74 20 73 71 6c 69 74 65 33 5f 72 65 6b 65 79 28  t sqlite3_rekey(
374d0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
374e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
374f0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f    /* Database to
37500 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20   be rekeyed */. 
37510 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65   const void *pKe
37520 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20  y, int nKey     
37530 2f 2a 20 54 68 65 20 6e 65 77 20 6b 65 79 20 2a  /* The new key *
37540 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  /.);.SQLITE_API 
37550 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6b 65  int sqlite3_reke
37560 79 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20  y_v2(.  sqlite3 
37570 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
37580 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
37590 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64  se to be rekeyed
375a0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
375b0 20 2a 7a 44 62 4e 61 6d 65 2c 20 20 20 20 20 20   *zDbName,      
375c0 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20       /* Name of 
375d0 74 68 65 20 64 61 74 61 62 61 73 65 20 2a 2f 0a  the database */.
375e0 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b    const void *pK
375f0 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20  ey, int nKey    
37600 20 2f 2a 20 54 68 65 20 6e 65 77 20 6b 65 79 20   /* The new key 
37610 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 65  */.);../*.** Spe
37620 63 69 66 79 20 74 68 65 20 61 63 74 69 76 61 74  cify the activat
37630 69 6f 6e 20 6b 65 79 20 66 6f 72 20 61 20 53 45  ion key for a SE
37640 45 20 64 61 74 61 62 61 73 65 2e 20 20 55 6e 6c  E database.  Unl
37650 65 73 73 20 0a 2a 2a 20 61 63 74 69 76 61 74 65  ess .** activate
37660 64 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20 53  d, none of the S
37670 45 45 20 72 6f 75 74 69 6e 65 73 20 77 69 6c 6c  EE routines will
37680 20 77 6f 72 6b 2e 0a 2a 2f 0a 53 51 4c 49 54 45   work..*/.SQLITE
37690 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65  _API void sqlite
376a0 33 5f 61 63 74 69 76 61 74 65 5f 73 65 65 28 0a  3_activate_see(.
376b0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50    const char *zP
376c0 61 73 73 50 68 72 61 73 65 20 20 20 20 20 20 20  assPhrase       
376d0 20 2f 2a 20 41 63 74 69 76 61 74 69 6f 6e 20 70   /* Activation p
376e0 68 72 61 73 65 20 2a 2f 0a 29 3b 0a 23 65 6e 64  hrase */.);.#end
376f0 69 66 0a 0a 23 69 66 64 65 66 20 53 51 4c 49 54  if..#ifdef SQLIT
37700 45 5f 45 4e 41 42 4c 45 5f 43 45 52 4f 44 0a 2f  E_ENABLE_CEROD./
37710 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65  *.** Specify the
37720 20 61 63 74 69 76 61 74 69 6f 6e 20 6b 65 79 20   activation key 
37730 66 6f 72 20 61 20 43 45 52 4f 44 20 64 61 74 61  for a CEROD data
37740 62 61 73 65 2e 20 20 55 6e 6c 65 73 73 20 0a 2a  base.  Unless .*
37750 2a 20 61 63 74 69 76 61 74 65 64 2c 20 6e 6f 6e  * activated, non
37760 65 20 6f 66 20 74 68 65 20 43 45 52 4f 44 20 72  e of the CEROD r
37770 6f 75 74 69 6e 65 73 20 77 69 6c 6c 20 77 6f 72  outines will wor
37780 6b 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  k..*/.SQLITE_API
37790 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 61 63   void sqlite3_ac
377a0 74 69 76 61 74 65 5f 63 65 72 6f 64 28 0a 20 20  tivate_cerod(.  
377b0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 73  const char *zPas
377c0 73 50 68 72 61 73 65 20 20 20 20 20 20 20 20 2f  sPhrase        /
377d0 2a 20 41 63 74 69 76 61 74 69 6f 6e 20 70 68 72  * Activation phr
377e0 61 73 65 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69 66  ase */.);.#endif
377f0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
37800 3a 20 53 75 73 70 65 6e 64 20 45 78 65 63 75 74  : Suspend Execut
37810 69 6f 6e 20 46 6f 72 20 41 20 53 68 6f 72 74 20  ion For A Short 
37820 54 69 6d 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  Time.**.** The s
37830 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 29 20 66  qlite3_sleep() f
37840 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20 74  unction causes t
37850 68 65 20 63 75 72 72 65 6e 74 20 74 68 72 65 61  he current threa
37860 64 20 74 6f 20 73 75 73 70 65 6e 64 20 65 78 65  d to suspend exe
37870 63 75 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 61 74  cution.** for at
37880 20 6c 65 61 73 74 20 61 20 6e 75 6d 62 65 72 20   least a number 
37890 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  of milliseconds 
378a0 73 70 65 63 69 66 69 65 64 20 69 6e 20 69 74 73  specified in its
378b0 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
378c0 2a 20 49 66 20 74 68 65 20 6f 70 65 72 61 74 69  * If the operati
378d0 6e 67 20 73 79 73 74 65 6d 20 64 6f 65 73 20 6e  ng system does n
378e0 6f 74 20 73 75 70 70 6f 72 74 20 73 6c 65 65 70  ot support sleep
378f0 20 72 65 71 75 65 73 74 73 20 77 69 74 68 0a 2a   requests with.*
37900 2a 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 74 69  * millisecond ti
37910 6d 65 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 20 74  me resolution, t
37920 68 65 6e 20 74 68 65 20 74 69 6d 65 20 77 69 6c  hen the time wil
37930 6c 20 62 65 20 72 6f 75 6e 64 65 64 20 75 70 20  l be rounded up 
37940 74 6f 0a 2a 2a 20 74 68 65 20 6e 65 61 72 65 73  to.** the neares
37950 74 20 73 65 63 6f 6e 64 2e 20 54 68 65 20 6e 75  t second. The nu
37960 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63  mber of millisec
37970 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 20 61 63  onds of sleep ac
37980 74 75 61 6c 6c 79 0a 2a 2a 20 72 65 71 75 65 73  tually.** reques
37990 74 65 64 20 66 72 6f 6d 20 74 68 65 20 6f 70 65  ted from the ope
379a0 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 73  rating system is
379b0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
379c0 20 5e 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65   ^SQLite impleme
379d0 6e 74 73 20 74 68 69 73 20 69 6e 74 65 72 66 61  nts this interfa
379e0 63 65 20 62 79 20 63 61 6c 6c 69 6e 67 20 74 68  ce by calling th
379f0 65 20 78 53 6c 65 65 70 28 29 0a 2a 2a 20 6d 65  e xSleep().** me
37a00 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61  thod of the defa
37a10 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  ult [sqlite3_vfs
37a20 5d 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 74 68  ] object.  If th
37a30 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f  e xSleep() metho
37a40 64 0a 2a 2a 20 6f 66 20 74 68 65 20 64 65 66 61  d.** of the defa
37a50 75 6c 74 20 56 46 53 20 69 73 20 6e 6f 74 20 69  ult VFS is not i
37a60 6d 70 6c 65 6d 65 6e 74 65 64 20 63 6f 72 72 65  mplemented corre
37a70 63 74 6c 79 2c 20 6f 72 20 6e 6f 74 20 69 6d 70  ctly, or not imp
37a80 6c 65 6d 65 6e 74 65 64 20 61 74 0a 2a 2a 20 61  lemented at.** a
37a90 6c 6c 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68  ll, then the beh
37aa0 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33  avior of sqlite3
37ab0 5f 73 6c 65 65 70 28 29 20 6d 61 79 20 64 65 76  _sleep() may dev
37ac0 69 61 74 65 20 66 72 6f 6d 20 74 68 65 20 64 65  iate from the de
37ad0 73 63 72 69 70 74 69 6f 6e 0a 2a 2a 20 69 6e 20  scription.** in 
37ae0 74 68 65 20 70 72 65 76 69 6f 75 73 20 70 61 72  the previous par
37af0 61 67 72 61 70 68 73 2e 0a 2a 2f 0a 53 51 4c 49  agraphs..*/.SQLI
37b00 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
37b10 65 33 5f 73 6c 65 65 70 28 69 6e 74 29 3b 0a 0a  e3_sleep(int);..
37b20 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
37b30 4e 61 6d 65 20 4f 66 20 54 68 65 20 46 6f 6c 64  Name Of The Fold
37b40 65 72 20 48 6f 6c 64 69 6e 67 20 54 65 6d 70 6f  er Holding Tempo
37b50 72 61 72 79 20 46 69 6c 65 73 0a 2a 2a 0a 2a 2a  rary Files.**.**
37b60 20 5e 28 49 66 20 74 68 69 73 20 67 6c 6f 62 61   ^(If this globa
37b70 6c 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d 61  l variable is ma
37b80 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 61  de to point to a
37b90 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 73   string which is
37ba0 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  .** the name of 
37bb0 61 20 66 6f 6c 64 65 72 20 28 61 2e 6b 2e 61 2e  a folder (a.k.a.
37bc0 20 64 69 72 65 63 74 6f 72 79 29 2c 20 74 68 65   directory), the
37bd0 6e 20 61 6c 6c 20 74 65 6d 70 6f 72 61 72 79 20  n all temporary 
37be0 66 69 6c 65 73 0a 2a 2a 20 63 72 65 61 74 65 64  files.** created
37bf0 20 62 79 20 53 51 4c 69 74 65 20 77 68 65 6e 20   by SQLite when 
37c00 75 73 69 6e 67 20 61 20 62 75 69 6c 74 2d 69 6e  using a built-in
37c10 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20   [sqlite3_vfs | 
37c20 56 46 53 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20  VFS].** will be 
37c30 70 6c 61 63 65 64 20 69 6e 20 74 68 61 74 20 64  placed in that d
37c40 69 72 65 63 74 6f 72 79 2e 29 5e 20 20 5e 49 66  irectory.)^  ^If
37c50 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a   this variable.*
37c60 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  * is a NULL poin
37c70 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  ter, then SQLite
37c80 20 70 65 72 66 6f 72 6d 73 20 61 20 73 65 61 72   performs a sear
37c90 63 68 20 66 6f 72 20 61 6e 20 61 70 70 72 6f 70  ch for an approp
37ca0 72 69 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61  riate.** tempora
37cb0 72 79 20 66 69 6c 65 20 64 69 72 65 63 74 6f 72  ry file director
37cc0 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 6e  y..**.** It is n
37cd0 6f 74 20 73 61 66 65 20 74 6f 20 72 65 61 64 20  ot safe to read 
37ce0 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76  or modify this v
37cf0 61 72 69 61 62 6c 65 20 69 6e 20 6d 6f 72 65 20  ariable in more 
37d00 74 68 61 6e 20 6f 6e 65 0a 2a 2a 20 74 68 72 65  than one.** thre
37d10 61 64 20 61 74 20 61 20 74 69 6d 65 2e 20 20 49  ad at a time.  I
37d20 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f  t is not safe to
37d30 20 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79 20   read or modify 
37d40 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a  this variable.**
37d50 20 69 66 20 61 20 5b 64 61 74 61 62 61 73 65 20   if a [database 
37d60 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62  connection] is b
37d70 65 69 6e 67 20 75 73 65 64 20 61 74 20 74 68 65  eing used at the
37d80 20 73 61 6d 65 20 74 69 6d 65 20 69 6e 20 61 20   same time in a 
37d90 73 65 70 61 72 61 74 65 0a 2a 2a 20 74 68 72 65  separate.** thre
37da0 61 64 2e 0a 2a 2a 20 49 74 20 69 73 20 69 6e 74  ad..** It is int
37db0 65 6e 64 65 64 20 74 68 61 74 20 74 68 69 73 20  ended that this 
37dc0 76 61 72 69 61 62 6c 65 20 62 65 20 73 65 74 20  variable be set 
37dd0 6f 6e 63 65 0a 2a 2a 20 61 73 20 70 61 72 74 20  once.** as part 
37de0 6f 66 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69  of process initi
37df0 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 20 62 65  alization and be
37e00 66 6f 72 65 20 61 6e 79 20 53 51 4c 69 74 65 20  fore any SQLite 
37e10 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 6f 75  interface.** rou
37e20 74 69 6e 65 73 20 68 61 76 65 20 62 65 65 6e 20  tines have been 
37e30 63 61 6c 6c 65 64 20 61 6e 64 20 74 68 61 74 20  called and that 
37e40 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 72 65  this variable re
37e50 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65 64 0a 2a  main unchanged.*
37e60 2a 20 74 68 65 72 65 61 66 74 65 72 2e 0a 2a 2a  * thereafter..**
37e70 0a 2a 2a 20 5e 54 68 65 20 5b 74 65 6d 70 5f 73  .** ^The [temp_s
37e80 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70  tore_directory p
37e90 72 61 67 6d 61 5d 20 6d 61 79 20 6d 6f 64 69 66  ragma] may modif
37ea0 79 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20  y this variable 
37eb0 61 6e 64 20 63 61 75 73 65 0a 2a 2a 20 69 74 20  and cause.** it 
37ec0 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f  to point to memo
37ed0 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ry obtained from
37ee0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
37ef0 5d 2e 20 20 5e 46 75 72 74 68 65 72 6d 6f 72 65  ].  ^Furthermore
37f00 2c 0a 2a 2a 20 74 68 65 20 5b 74 65 6d 70 5f 73  ,.** the [temp_s
37f10 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70  tore_directory p
37f20 72 61 67 6d 61 5d 20 61 6c 77 61 79 73 20 61 73  ragma] always as
37f30 73 75 6d 65 73 20 74 68 61 74 20 61 6e 79 20 73  sumes that any s
37f40 74 72 69 6e 67 0a 2a 2a 20 74 68 61 74 20 74 68  tring.** that th
37f50 69 73 20 76 61 72 69 61 62 6c 65 20 70 6f 69 6e  is variable poin
37f60 74 73 20 74 6f 20 69 73 20 68 65 6c 64 20 69 6e  ts to is held in
37f70 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
37f80 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74   from .** [sqlit
37f90 65 33 5f 6d 61 6c 6c 6f 63 5d 20 61 6e 64 20 74  e3_malloc] and t
37fa0 68 65 20 70 72 61 67 6d 61 20 6d 61 79 20 61 74  he pragma may at
37fb0 74 65 6d 70 74 20 74 6f 20 66 72 65 65 20 74 68  tempt to free th
37fc0 61 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 75 73 69  at memory.** usi
37fd0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ng [sqlite3_free
37fe0 5d 2e 0a 2a 2a 20 48 65 6e 63 65 2c 20 69 66 20  ]..** Hence, if 
37ff0 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 69 73  this variable is
38000 20 6d 6f 64 69 66 69 65 64 20 64 69 72 65 63 74   modified direct
38010 6c 79 2c 20 65 69 74 68 65 72 20 69 74 20 73 68  ly, either it sh
38020 6f 75 6c 64 20 62 65 0a 2a 2a 20 6d 61 64 65 20  ould be.** made 
38030 4e 55 4c 4c 20 6f 72 20 6d 61 64 65 20 74 6f 20  NULL or made to 
38040 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20  point to memory 
38050 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
38060 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 0a 2a  qlite3_malloc].*
38070 2a 20 6f 72 20 65 6c 73 65 20 74 68 65 20 75 73  * or else the us
38080 65 20 6f 66 20 74 68 65 20 5b 74 65 6d 70 5f 73  e of the [temp_s
38090 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70  tore_directory p
380a0 72 61 67 6d 61 5d 20 73 68 6f 75 6c 64 20 62 65  ragma] should be
380b0 20 61 76 6f 69 64 65 64 2e 0a 2a 2a 0a 2a 2a 20   avoided..**.** 
380c0 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f  <b>Note to Windo
380d0 77 73 20 52 75 6e 74 69 6d 65 20 75 73 65 72 73  ws Runtime users
380e0 3a 3c 2f 62 3e 20 20 54 68 65 20 74 65 6d 70 6f  :</b>  The tempo
380f0 72 61 72 79 20 64 69 72 65 63 74 6f 72 79 20 6d  rary directory m
38100 75 73 74 20 62 65 20 73 65 74 0a 2a 2a 20 70 72  ust be set.** pr
38110 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20 5b  ior to calling [
38120 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5d 20 6f 72  sqlite3_open] or
38130 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
38140 32 5d 2e 20 20 4f 74 68 65 72 77 69 73 65 2c 20  2].  Otherwise, 
38150 76 61 72 69 6f 75 73 0a 2a 2a 20 66 65 61 74 75  various.** featu
38160 72 65 73 20 74 68 61 74 20 72 65 71 75 69 72 65  res that require
38170 20 74 68 65 20 75 73 65 20 6f 66 20 74 65 6d 70   the use of temp
38180 6f 72 61 72 79 20 66 69 6c 65 73 20 6d 61 79 20  orary files may 
38190 66 61 69 6c 2e 20 20 48 65 72 65 20 69 73 20 61  fail.  Here is a
381a0 6e 0a 2a 2a 20 65 78 61 6d 70 6c 65 20 6f 66 20  n.** example of 
381b0 68 6f 77 20 74 6f 20 64 6f 20 74 68 69 73 20 75  how to do this u
381c0 73 69 6e 67 20 43 2b 2b 20 77 69 74 68 20 74 68  sing C++ with th
381d0 65 20 57 69 6e 64 6f 77 73 20 52 75 6e 74 69 6d  e Windows Runtim
381e0 65 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  e:.**.** <blockq
381f0 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 4c 50  uote><pre>.** LP
38200 43 57 53 54 52 20 7a 50 61 74 68 20 3d 20 57 69  CWSTR zPath = Wi
38210 6e 64 6f 77 73 3a 3a 53 74 6f 72 61 67 65 3a 3a  ndows::Storage::
38220 41 70 70 6c 69 63 61 74 69 6f 6e 44 61 74 61 3a  ApplicationData:
38230 3a 43 75 72 72 65 6e 74 2d 3e 0a 2a 2a 20 26 6e  :Current->.** &n
38240 62 73 70 3b 20 20 20 20 20 54 65 6d 70 6f 72 61  bsp;     Tempora
38250 72 79 46 6f 6c 64 65 72 2d 3e 50 61 74 68 2d 3e  ryFolder->Path->
38260 44 61 74 61 28 29 3b 0a 2a 2a 20 63 68 61 72 20  Data();.** char 
38270 7a 50 61 74 68 42 75 66 26 23 39 31 3b 4d 41 58  zPathBuf&#91;MAX
38280 5f 50 41 54 48 20 2b 20 31 26 23 39 33 3b 3b 0a  _PATH + 1&#93;;.
38290 2a 2a 20 6d 65 6d 73 65 74 28 7a 50 61 74 68 42  ** memset(zPathB
382a0 75 66 2c 20 30 2c 20 73 69 7a 65 6f 66 28 7a 50  uf, 0, sizeof(zP
382b0 61 74 68 42 75 66 29 29 3b 0a 2a 2a 20 57 69 64  athBuf));.** Wid
382c0 65 43 68 61 72 54 6f 4d 75 6c 74 69 42 79 74 65  eCharToMultiByte
382d0 28 43 50 5f 55 54 46 38 2c 20 30 2c 20 7a 50 61  (CP_UTF8, 0, zPa
382e0 74 68 2c 20 2d 31 2c 20 7a 50 61 74 68 42 75 66  th, -1, zPathBuf
382f0 2c 20 73 69 7a 65 6f 66 28 7a 50 61 74 68 42 75  , sizeof(zPathBu
38300 66 29 2c 0a 2a 2a 20 26 6e 62 73 70 3b 20 20 20  f),.** &nbsp;   
38310 20 20 4e 55 4c 4c 2c 20 4e 55 4c 4c 29 3b 0a 2a    NULL, NULL);.*
38320 2a 20 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64  * sqlite3_temp_d
38330 69 72 65 63 74 6f 72 79 20 3d 20 73 71 6c 69 74  irectory = sqlit
38340 65 33 5f 6d 70 72 69 6e 74 66 28 22 25 73 22 2c  e3_mprintf("%s",
38350 20 7a 50 61 74 68 42 75 66 29 3b 0a 2a 2a 20 3c   zPathBuf);.** <
38360 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
38370 65 3e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  e>.*/.SQLITE_API
38380 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 74   char *sqlite3_t
38390 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 3b 0a 0a  emp_directory;..
383a0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
383b0 4e 61 6d 65 20 4f 66 20 54 68 65 20 46 6f 6c 64  Name Of The Fold
383c0 65 72 20 48 6f 6c 64 69 6e 67 20 44 61 74 61 62  er Holding Datab
383d0 61 73 65 20 46 69 6c 65 73 0a 2a 2a 0a 2a 2a 20  ase Files.**.** 
383e0 5e 28 49 66 20 74 68 69 73 20 67 6c 6f 62 61 6c  ^(If this global
383f0 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d 61 64   variable is mad
38400 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 61 20  e to point to a 
38410 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 73 0a  string which is.
38420 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61  ** the name of a
38430 20 66 6f 6c 64 65 72 20 28 61 2e 6b 2e 61 2e 20   folder (a.k.a. 
38440 64 69 72 65 63 74 6f 72 79 29 2c 20 74 68 65 6e  directory), then
38450 20 61 6c 6c 20 64 61 74 61 62 61 73 65 20 66 69   all database fi
38460 6c 65 73 0a 2a 2a 20 73 70 65 63 69 66 69 65 64  les.** specified
38470 20 77 69 74 68 20 61 20 72 65 6c 61 74 69 76 65   with a relative
38480 20 70 61 74 68 6e 61 6d 65 20 61 6e 64 20 63 72   pathname and cr
38490 65 61 74 65 64 20 6f 72 20 61 63 63 65 73 73 65  eated or accesse
384a0 64 20 62 79 0a 2a 2a 20 53 51 4c 69 74 65 20 77  d by.** SQLite w
384b0 68 65 6e 20 75 73 69 6e 67 20 61 20 62 75 69 6c  hen using a buil
384c0 74 2d 69 6e 20 77 69 6e 64 6f 77 73 20 5b 73 71  t-in windows [sq
384d0 6c 69 74 65 33 5f 76 66 73 20 7c 20 56 46 53 5d  lite3_vfs | VFS]
384e0 20 77 69 6c 6c 20 62 65 20 61 73 73 75 6d 65 64   will be assumed
384f0 0a 2a 2a 20 74 6f 20 62 65 20 72 65 6c 61 74 69  .** to be relati
38500 76 65 20 74 6f 20 74 68 61 74 20 64 69 72 65 63  ve to that direc
38510 74 6f 72 79 2e 29 5e 20 5e 49 66 20 74 68 69 73  tory.)^ ^If this
38520 20 76 61 72 69 61 62 6c 65 20 69 73 20 61 20 4e   variable is a N
38530 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2c 20  ULL.** pointer, 
38540 74 68 65 6e 20 53 51 4c 69 74 65 20 61 73 73 75  then SQLite assu
38550 6d 65 73 20 74 68 61 74 20 61 6c 6c 20 64 61 74  mes that all dat
38560 61 62 61 73 65 20 66 69 6c 65 73 20 73 70 65 63  abase files spec
38570 69 66 69 65 64 0a 2a 2a 20 77 69 74 68 20 61 20  ified.** with a 
38580 72 65 6c 61 74 69 76 65 20 70 61 74 68 6e 61 6d  relative pathnam
38590 65 20 61 72 65 20 72 65 6c 61 74 69 76 65 20 74  e are relative t
385a0 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 69  o the current di
385b0 72 65 63 74 6f 72 79 0a 2a 2a 20 66 6f 72 20 74  rectory.** for t
385c0 68 65 20 70 72 6f 63 65 73 73 2e 20 20 4f 6e 6c  he process.  Onl
385d0 79 20 74 68 65 20 77 69 6e 64 6f 77 73 20 56 46  y the windows VF
385e0 53 20 6d 61 6b 65 73 20 75 73 65 20 6f 66 20 74  S makes use of t
385f0 68 69 73 20 67 6c 6f 62 61 6c 0a 2a 2a 20 76 61  his global.** va
38600 72 69 61 62 6c 65 3b 20 69 74 20 69 73 20 69 67  riable; it is ig
38610 6e 6f 72 65 64 20 62 79 20 74 68 65 20 75 6e 69  nored by the uni
38620 78 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 43 68 61  x VFS..**.** Cha
38630 6e 67 69 6e 67 20 74 68 65 20 76 61 6c 75 65 20  nging the value 
38640 6f 66 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  of this variable
38650 20 77 68 69 6c 65 20 61 20 64 61 74 61 62 61 73   while a databas
38660 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 0a  e connection is.
38670 2a 2a 20 6f 70 65 6e 20 63 61 6e 20 72 65 73 75  ** open can resu
38680 6c 74 20 69 6e 20 61 20 63 6f 72 72 75 70 74 20  lt in a corrupt 
38690 64 61 74 61 62 61 73 65 2e 0a 2a 2a 0a 2a 2a 20  database..**.** 
386a0 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74  It is not safe t
386b0 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79  o read or modify
386c0 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 69   this variable i
386d0 6e 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 0a  n more than one.
386e0 2a 2a 20 74 68 72 65 61 64 20 61 74 20 61 20 74  ** thread at a t
386f0 69 6d 65 2e 20 20 49 74 20 69 73 20 6e 6f 74 20  ime.  It is not 
38700 73 61 66 65 20 74 6f 20 72 65 61 64 20 6f 72 20  safe to read or 
38710 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69  modify this vari
38720 61 62 6c 65 0a 2a 2a 20 69 66 20 61 20 5b 64 61  able.** if a [da
38730 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
38740 6e 5d 20 69 73 20 62 65 69 6e 67 20 75 73 65 64  n] is being used
38750 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d   at the same tim
38760 65 20 69 6e 20 61 20 73 65 70 61 72 61 74 65 0a  e in a separate.
38770 2a 2a 20 74 68 72 65 61 64 2e 0a 2a 2a 20 49 74  ** thread..** It
38780 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 68 61   is intended tha
38790 7