System.Data.SQLite
Hex Artifact Content
Not logged in

Artifact f58313b8e06e367acf7724b2a6f6eb02143a2bfe:


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 31 2d 30        "2013-11-0
1630: 39 20 32 32 3a 30 38 3a 31 30 20 64 30 36 64 39  9 22:08:10 d06d9
1640: 66 64 62 36 65 36 61 63 33 36 39 30 33 35 63 38  fdb6e6ac369035c8
1650: 32 35 64 39 63 33 30 39 37 30 31 31 35 62 33 62  25d9c30970115b3b
1660: 61 37 31 22 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  a71"../*.** 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 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
4510: 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64  ction] specified
4520: 20 62 79 0a 2a 2a 20 20 20 20 20 20 74 68 65 20   by.**      the 
4530: 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  1st parameter to
4540: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
4550: 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78  while sqlite3_ex
4560: 65 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e  ec() is running.
4570: 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70  .** <li> The app
4580: 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  lication must no
4590: 74 20 6d 6f 64 69 66 79 20 74 68 65 20 53 51 4c  t modify the SQL
45a0: 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20   statement text 
45b0: 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 20  passed into.**  
45c0: 20 20 20 20 74 68 65 20 32 6e 64 20 70 61 72 61      the 2nd para
45d0: 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33  meter of sqlite3
45e0: 5f 65 78 65 63 28 29 20 77 68 69 6c 65 20 73 71  _exec() while sq
45f0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
4600: 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c  running..** </ul
4610: 3e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  >.*/.SQLITE_API 
4620: 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 65 63  int sqlite3_exec
4630: 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 20  (.  sqlite3*,   
4640: 20 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 2f                 /
4660: 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61  * An open databa
4670: 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  se */.  const ch
4680: 61 72 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 20  ar *sql,        
4690: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
46a0: 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20     /* SQL to be 
46b0: 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69  evaluated */.  i
46c0: 6e 74 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76  nt (*callback)(v
46d0: 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c  oid*,int,char**,
46e0: 63 68 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c  char**),  /* Cal
46f0: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a  lback function *
4700: 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20  /.  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 2f                 /
4730: 2a 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 74  * 1st argument t
4740: 6f 20 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20  o callback */.  
4750: 63 68 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20  char **errmsg   
4760: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4770: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72             /* Er
4780: 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20  ror msg written 
4790: 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a  here */.);../*.*
47a0: 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75  * CAPI3REF: Resu
47b0: 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57  lt Codes.** KEYW
47c0: 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 4f 4b 20  ORDS: SQLITE_OK 
47d0: 7b 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 72  {error code} {er
47e0: 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45  ror codes}.** KE
47f0: 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74 20  YWORDS: {result 
4800: 63 6f 64 65 7d 20 7b 72 65 73 75 6c 74 20 63 6f  code} {result co
4810: 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20  des}.**.** Many 
4820: 53 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73  SQLite functions
4830: 20 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67   return an integ
4840: 65 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66  er result code f
4850: 72 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77  rom the set show
4860: 6e 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64  n.** here in ord
4870: 65 72 20 74 6f 20 69 6e 64 69 63 61 74 65 20 73  er to indicate s
4880: 75 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72  uccess or failur
4890: 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72  e..**.** New err
48a0: 6f 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20  or codes may be 
48b0: 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
48c0: 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
48d0: 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  te..**.** See al
48e0: 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52  so: [SQLITE_IOER
48f0: 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65  R_READ | extende
4900: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 2c  d result codes],
4910: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 74 61  .** [sqlite3_vta
4920: 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d  b_on_conflict()]
4930: 20 5b 53 51 4c 49 54 45 5f 52 4f 4c 4c 42 41 43   [SQLITE_ROLLBAC
4940: 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 73  K | result codes
4950: 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ]..*/.#define SQ
4960: 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20 20 20 20  LITE_OK         
4970: 20 20 30 20 20 20 2f 2a 20 53 75 63 63 65 73 73    0   /* Success
4980: 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a  ful result */./*
4990: 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72   beginning-of-er
49a0: 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23 64 65  ror-codes */.#de
49b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 52 52 4f  fine SQLITE_ERRO
49c0: 52 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20  R        1   /* 
49d0: 53 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d 69 73  SQL error or mis
49e0: 73 69 6e 67 20 64 61 74 61 62 61 73 65 20 2a 2f  sing database */
49f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4a00: 49 4e 54 45 52 4e 41 4c 20 20 20 20 20 32 20 20  INTERNAL     2  
4a10: 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c 6f 67   /* Internal log
4a20: 69 63 20 65 72 72 6f 72 20 69 6e 20 53 51 4c 69  ic error in SQLi
4a30: 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  te */.#define SQ
4a40: 4c 49 54 45 5f 50 45 52 4d 20 20 20 20 20 20 20  LITE_PERM       
4a50: 20 20 33 20 20 20 2f 2a 20 41 63 63 65 73 73 20    3   /* Access 
4a60: 70 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e 69 65  permission denie
4a70: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4a80: 49 54 45 5f 41 42 4f 52 54 20 20 20 20 20 20 20  ITE_ABORT       
4a90: 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b   4   /* Callback
4aa0: 20 72 6f 75 74 69 6e 65 20 72 65 71 75 65 73 74   routine request
4ab0: 65 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f 0a 23  ed an abort */.#
4ac0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55  define SQLITE_BU
4ad0: 53 59 20 20 20 20 20 20 20 20 20 35 20 20 20 2f  SY         5   /
4ae0: 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20 66  * The database f
4af0: 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f  ile is locked */
4b00: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4b10: 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 36 20 20  LOCKED       6  
4b20: 20 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e 20 74   /* A table in t
4b30: 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6c  he database is l
4b40: 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  ocked */.#define
4b50: 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 20 20   SQLITE_NOMEM   
4b60: 20 20 20 20 20 37 20 20 20 2f 2a 20 41 20 6d 61       7   /* A ma
4b70: 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64 20 2a 2f  lloc() failed */
4b80: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4b90: 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 38 20 20  READONLY     8  
4ba0: 20 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f 20 77   /* Attempt to w
4bb0: 72 69 74 65 20 61 20 72 65 61 64 6f 6e 6c 79 20  rite a readonly 
4bc0: 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66  database */.#def
4bd0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52  ine SQLITE_INTER
4be0: 52 55 50 54 20 20 20 20 39 20 20 20 2f 2a 20 4f  RUPT    9   /* O
4bf0: 70 65 72 61 74 69 6f 6e 20 74 65 72 6d 69 6e 61  peration termina
4c00: 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69  ted by sqlite3_i
4c10: 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a 23 64 65  nterrupt()*/.#de
4c20: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4c30: 52 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20  R       10   /* 
4c40: 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64 69 73  Some kind of dis
4c50: 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63 63 75  k I/O error occu
4c60: 72 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rred */.#define 
4c70: 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 20  SQLITE_CORRUPT  
4c80: 20 20 20 31 31 20 20 20 2f 2a 20 54 68 65 20 64     11   /* The d
4c90: 61 74 61 62 61 73 65 20 64 69 73 6b 20 69 6d 61  atabase disk ima
4ca0: 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65 64 20  ge is malformed 
4cb0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4cc0: 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20 31 32  E_NOTFOUND    12
4cd0: 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e 20 6f 70     /* Unknown op
4ce0: 63 6f 64 65 20 69 6e 20 73 71 6c 69 74 65 33 5f  code in sqlite3_
4cf0: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 20 2a  file_control() *
4d00: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4d10: 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 31 33 20  _FULL        13 
4d20: 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 20 66    /* Insertion f
4d30: 61 69 6c 65 64 20 62 65 63 61 75 73 65 20 64 61  ailed because da
4d40: 74 61 62 61 73 65 20 69 73 20 66 75 6c 6c 20 2a  tabase is full *
4d50: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4d60: 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20 31 34 20  _CANTOPEN    14 
4d70: 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 20 6f    /* Unable to o
4d80: 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  pen the database
4d90: 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65   file */.#define
4da0: 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43 4f 4c   SQLITE_PROTOCOL
4db0: 20 20 20 20 31 35 20 20 20 2f 2a 20 44 61 74 61      15   /* Data
4dc0: 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74 6f 63  base lock protoc
4dd0: 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66  ol error */.#def
4de0: 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50 54 59  ine SQLITE_EMPTY
4df0: 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 44         16   /* D
4e00: 61 74 61 62 61 73 65 20 69 73 20 65 6d 70 74 79  atabase is empty
4e10: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4e20: 54 45 5f 53 43 48 45 4d 41 20 20 20 20 20 20 31  TE_SCHEMA      1
4e30: 37 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62  7   /* The datab
4e40: 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67  ase schema chang
4e50: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
4e60: 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20 20 20 20  LITE_TOOBIG     
4e70: 20 31 38 20 20 20 2f 2a 20 53 74 72 69 6e 67 20   18   /* String 
4e80: 6f 72 20 42 4c 4f 42 20 65 78 63 65 65 64 73 20  or BLOB exceeds 
4e90: 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a 23 64  size limit */.#d
4ea0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
4eb0: 53 54 52 41 49 4e 54 20 20 31 39 20 20 20 2f 2a  STRAINT  19   /*
4ec0: 20 41 62 6f 72 74 20 64 75 65 20 74 6f 20 63 6f   Abort due to co
4ed0: 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69  nstraint violati
4ee0: 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  on */.#define SQ
4ef0: 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48 20 20 20  LITE_MISMATCH   
4f00: 20 32 30 20 20 20 2f 2a 20 44 61 74 61 20 74 79   20   /* Data ty
4f10: 70 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f 0a 23  pe mismatch */.#
4f20: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49  define SQLITE_MI
4f30: 53 55 53 45 20 20 20 20 20 20 32 31 20 20 20 2f  SUSE      21   /
4f40: 2a 20 4c 69 62 72 61 72 79 20 75 73 65 64 20 69  * Library used i
4f50: 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a 23 64  ncorrectly */.#d
4f60: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4c  efine SQLITE_NOL
4f70: 46 53 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a  FS       22   /*
4f80: 20 55 73 65 73 20 4f 53 20 66 65 61 74 75 72 65   Uses OS feature
4f90: 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 65 64 20  s not supported 
4fa0: 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65 66 69  on host */.#defi
4fb0: 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48 20 20  ne SQLITE_AUTH  
4fc0: 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 41 75        23   /* Au
4fd0: 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65 6e 69  thorization deni
4fe0: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
4ff0: 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20 20 20 20  LITE_FORMAT     
5000: 20 32 34 20 20 20 2f 2a 20 41 75 78 69 6c 69 61   24   /* Auxilia
5010: 72 79 20 64 61 74 61 62 61 73 65 20 66 6f 72 6d  ry database form
5020: 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66  at error */.#def
5030: 69 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e 47 45  ine SQLITE_RANGE
5040: 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 32         25   /* 2
5050: 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  nd parameter to 
5060: 73 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f 75 74  sqlite3_bind out
5070: 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23 64 65   of range */.#de
5080: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 41  fine SQLITE_NOTA
5090: 44 42 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20  DB      26   /* 
50a0: 46 69 6c 65 20 6f 70 65 6e 65 64 20 74 68 61 74  File opened that
50b0: 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61   is not a databa
50c0: 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69  se file */.#defi
50d0: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45  ne SQLITE_NOTICE
50e0: 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20 4e 6f        27   /* No
50f0: 74 69 66 69 63 61 74 69 6f 6e 73 20 66 72 6f 6d  tifications from
5100: 20 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 20 2a   sqlite3_log() *
5110: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5120: 5f 57 41 52 4e 49 4e 47 20 20 20 20 20 32 38 20  _WARNING     28 
5130: 20 20 2f 2a 20 57 61 72 6e 69 6e 67 73 20 66 72    /* Warnings fr
5140: 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29  om sqlite3_log()
5150: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5160: 54 45 5f 52 4f 57 20 20 20 20 20 20 20 20 20 31  TE_ROW         1
5170: 30 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73  00  /* sqlite3_s
5180: 74 65 70 28 29 20 68 61 73 20 61 6e 6f 74 68 65  tep() has anothe
5190: 72 20 72 6f 77 20 72 65 61 64 79 20 2a 2f 0a 23  r row ready */.#
51a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 4f  define SQLITE_DO
51b0: 4e 45 20 20 20 20 20 20 20 20 31 30 31 20 20 2f  NE        101  /
51c0: 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  * sqlite3_step()
51d0: 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 65 78   has finished ex
51e0: 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e  ecuting */./* en
51f0: 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73  d-of-error-codes
5200: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
5210: 52 45 46 3a 20 45 78 74 65 6e 64 65 64 20 52 65  REF: Extended Re
5220: 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45  sult Codes.** KE
5230: 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64 65  YWORDS: {extende
5240: 64 20 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65  d error code} {e
5250: 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f  xtended error co
5260: 64 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  des}.** KEYWORDS
5270: 3a 20 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75  : {extended resu
5280: 6c 74 20 63 6f 64 65 7d 20 7b 65 78 74 65 6e 64  lt code} {extend
5290: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 7d  ed result codes}
52a0: 0a 2a 2a 0a 2a 2a 20 49 6e 20 69 74 73 20 64 65  .**.** In its de
52b0: 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74  fault configurat
52c0: 69 6f 6e 2c 20 53 51 4c 69 74 65 20 41 50 49 20  ion, SQLite API 
52d0: 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
52e0: 6f 6e 65 20 6f 66 20 32 36 20 69 6e 74 65 67 65  one of 26 intege
52f0: 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 20  r.** [SQLITE_OK 
5300: 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 2e  | result codes].
5310: 20 20 48 6f 77 65 76 65 72 2c 20 65 78 70 65 72    However, exper
5320: 69 65 6e 63 65 20 68 61 73 20 73 68 6f 77 6e 20  ience has shown 
5330: 74 68 61 74 20 6d 61 6e 79 20 6f 66 0a 2a 2a 20  that many of.** 
5340: 74 68 65 73 65 20 72 65 73 75 6c 74 20 63 6f 64  these result cod
5350: 65 73 20 61 72 65 20 74 6f 6f 20 63 6f 61 72 73  es are too coars
5360: 65 2d 67 72 61 69 6e 65 64 2e 20 20 54 68 65 79  e-grained.  They
5370: 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69 64 65 20   do not provide 
5380: 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e 66 6f 72  as.** much infor
5390: 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 70 72 6f  mation about pro
53a0: 62 6c 65 6d 73 20 61 73 20 70 72 6f 67 72 61 6d  blems as program
53b0: 6d 65 72 73 20 6d 69 67 68 74 20 6c 69 6b 65 2e  mers might like.
53c0: 20 20 49 6e 20 61 6e 20 65 66 66 6f 72 74 20 74    In an effort t
53d0: 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20 74 68 69  o.** address thi
53e0: 73 2c 20 6e 65 77 65 72 20 76 65 72 73 69 6f 6e  s, newer version
53f0: 73 20 6f 66 20 53 51 4c 69 74 65 20 28 76 65 72  s of SQLite (ver
5400: 73 69 6f 6e 20 33 2e 33 2e 38 20 61 6e 64 20 6c  sion 3.3.8 and l
5410: 61 74 65 72 29 20 69 6e 63 6c 75 64 65 0a 2a 2a  ater) include.**
5420: 20 73 75 70 70 6f 72 74 20 66 6f 72 20 61 64 64   support for add
5430: 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c 74 20 63  itional result c
5440: 6f 64 65 73 20 74 68 61 74 20 70 72 6f 76 69 64  odes that provid
5450: 65 20 6d 6f 72 65 20 64 65 74 61 69 6c 65 64 20  e more detailed 
5460: 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61  information.** a
5470: 62 6f 75 74 20 65 72 72 6f 72 73 2e 20 54 68 65  bout errors. The
5480: 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
5490: 20 63 6f 64 65 73 20 61 72 65 20 65 6e 61 62 6c   codes are enabl
54a0: 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a  ed or disabled.*
54b0: 2a 20 6f 6e 20 61 20 70 65 72 20 64 61 74 61 62  * on a per datab
54c0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62  ase connection b
54d0: 61 73 69 73 20 75 73 69 6e 67 20 74 68 65 0a 2a  asis using the.*
54e0: 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  * [sqlite3_exten
54f0: 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73  ded_result_codes
5500: 28 29 5d 20 41 50 49 2e 0a 2a 2a 0a 2a 2a 20 53  ()] API..**.** S
5510: 6f 6d 65 20 6f 66 20 74 68 65 20 61 76 61 69 6c  ome of the avail
5520: 61 62 6c 65 20 65 78 74 65 6e 64 65 64 20 72 65  able extended re
5530: 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 6c  sult codes are l
5540: 69 73 74 65 64 20 68 65 72 65 2e 0a 2a 2a 20 4f  isted here..** O
5550: 6e 65 20 6d 61 79 20 65 78 70 65 63 74 20 74 68  ne may expect th
5560: 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 65  e number of exte
5570: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
5580: 73 20 77 69 6c 6c 20 62 65 20 65 78 70 61 6e 64  s will be expand
5590: 0a 2a 2a 20 6f 76 65 72 20 74 69 6d 65 2e 20 20  .** over time.  
55a0: 53 6f 66 74 77 61 72 65 20 74 68 61 74 20 75 73  Software that us
55b0: 65 73 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  es extended resu
55c0: 6c 74 20 63 6f 64 65 73 20 73 68 6f 75 6c 64 20  lt codes should 
55d0: 65 78 70 65 63 74 0a 2a 2a 20 74 6f 20 73 65 65  expect.** to see
55e0: 20 6e 65 77 20 72 65 73 75 6c 74 20 63 6f 64 65   new result code
55f0: 73 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  s in future rele
5600: 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ases of SQLite..
5610: 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  **.** The SQLITE
5620: 5f 4f 4b 20 72 65 73 75 6c 74 20 63 6f 64 65 20  _OK result code 
5630: 77 69 6c 6c 20 6e 65 76 65 72 20 62 65 20 65 78  will never be ex
5640: 74 65 6e 64 65 64 2e 20 20 49 74 20 77 69 6c 6c  tended.  It will
5650: 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20 65 78   always.** be ex
5660: 61 63 74 6c 79 20 7a 65 72 6f 2e 0a 2a 2f 0a 23  actly zero..*/.#
5670: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5680: 45 52 52 5f 52 45 41 44 20 20 20 20 20 20 20 20  ERR_READ        
5690: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
56a0: 45 52 52 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64  ERR | (1<<8)).#d
56b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
56c0: 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 20 20  RR_SHORT_READ   
56d0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
56e0: 52 52 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65  RR | (2<<8)).#de
56f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5700: 52 5f 57 52 49 54 45 20 20 20 20 20 20 20 20 20  R_WRITE         
5710: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5720: 52 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66  R | (3<<8)).#def
5730: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5740: 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20 20 20  _FSYNC          
5750: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5760: 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69   | (4<<8)).#defi
5770: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5780: 44 49 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20  DIR_FSYNC       
5790: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
57a0: 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (5<<8)).#defin
57b0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 54  e SQLITE_IOERR_T
57c0: 52 55 4e 43 41 54 45 20 20 20 20 20 20 20 20 20  RUNCATE         
57d0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
57e0: 20 28 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (6<<8)).#define
57f0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53   SQLITE_IOERR_FS
5800: 54 41 54 20 20 20 20 20 20 20 20 20 20 20 20 20  TAT             
5810: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
5820: 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (7<<8)).#define 
5830: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 55 4e 4c  SQLITE_IOERR_UNL
5840: 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 28  OCK            (
5850: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5860: 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  8<<8)).#define S
5870: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 44 4c 4f  QLITE_IOERR_RDLO
5880: 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 28 53  CK            (S
5890: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 39  QLITE_IOERR | (9
58a0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
58b0: 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54  LITE_IOERR_DELET
58c0: 45 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51  E            (SQ
58d0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 30  LITE_IOERR | (10
58e0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
58f0: 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
5900: 45 44 20 20 20 20 20 20 20 20 20 20 20 28 53 51  ED           (SQ
5910: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 31  LITE_IOERR | (11
5920: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5930: 4c 49 54 45 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d  LITE_IOERR_NOMEM
5940: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
5950: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 32  LITE_IOERR | (12
5960: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5970: 4c 49 54 45 5f 49 4f 45 52 52 5f 41 43 43 45 53  LITE_IOERR_ACCES
5980: 53 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51  S            (SQ
5990: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 33  LITE_IOERR | (13
59a0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
59b0: 4c 49 54 45 5f 49 4f 45 52 52 5f 43 48 45 43 4b  LITE_IOERR_CHECK
59c0: 52 45 53 45 52 56 45 44 4c 4f 43 4b 20 28 53 51  RESERVEDLOCK (SQ
59d0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 34  LITE_IOERR | (14
59e0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
59f0: 4c 49 54 45 5f 49 4f 45 52 52 5f 4c 4f 43 4b 20  LITE_IOERR_LOCK 
5a00: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
5a10: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 35  LITE_IOERR | (15
5a20: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5a30: 4c 49 54 45 5f 49 4f 45 52 52 5f 43 4c 4f 53 45  LITE_IOERR_CLOSE
5a40: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
5a50: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 36  LITE_IOERR | (16
5a60: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5a70: 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 43  LITE_IOERR_DIR_C
5a80: 4c 4f 53 45 20 20 20 20 20 20 20 20 20 28 53 51  LOSE         (SQ
5a90: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 37  LITE_IOERR | (17
5aa0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5ab0: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4f 50  LITE_IOERR_SHMOP
5ac0: 45 4e 20 20 20 20 20 20 20 20 20 20 20 28 53 51  EN           (SQ
5ad0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 38  LITE_IOERR | (18
5ae0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5af0: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 53 49  LITE_IOERR_SHMSI
5b00: 5a 45 20 20 20 20 20 20 20 20 20 20 20 28 53 51  ZE           (SQ
5b10: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 39  LITE_IOERR | (19
5b20: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5b30: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4c 4f  LITE_IOERR_SHMLO
5b40: 43 4b 20 20 20 20 20 20 20 20 20 20 20 28 53 51  CK           (SQ
5b50: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 30  LITE_IOERR | (20
5b60: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5b70: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4d 41  LITE_IOERR_SHMMA
5b80: 50 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51  P            (SQ
5b90: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 31  LITE_IOERR | (21
5ba0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5bb0: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 45 45 4b 20  LITE_IOERR_SEEK 
5bc0: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
5bd0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 32  LITE_IOERR | (22
5be0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5bf0: 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54  LITE_IOERR_DELET
5c00: 45 5f 4e 4f 45 4e 54 20 20 20 20 20 20 28 53 51  E_NOENT      (SQ
5c10: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 33  LITE_IOERR | (23
5c20: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5c30: 4c 49 54 45 5f 49 4f 45 52 52 5f 4d 4d 41 50 20  LITE_IOERR_MMAP 
5c40: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
5c50: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 34  LITE_IOERR | (24
5c60: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5c70: 4c 49 54 45 5f 49 4f 45 52 52 5f 47 45 54 54 45  LITE_IOERR_GETTE
5c80: 4d 50 50 41 54 48 20 20 20 20 20 20 20 28 53 51  MPPATH       (SQ
5c90: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 35  LITE_IOERR | (25
5ca0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5cb0: 4c 49 54 45 5f 49 4f 45 52 52 5f 43 4f 4e 56 50  LITE_IOERR_CONVP
5cc0: 41 54 48 20 20 20 20 20 20 20 20 20 20 28 53 51  ATH          (SQ
5cd0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 36  LITE_IOERR | (26
5ce0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5cf0: 4c 49 54 45 5f 4c 4f 43 4b 45 44 5f 53 48 41 52  LITE_LOCKED_SHAR
5d00: 45 44 43 41 43 48 45 20 20 20 20 20 20 28 53 51  EDCACHE      (SQ
5d10: 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 7c 20 20 28  LITE_LOCKED |  (
5d20: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
5d30: 51 4c 49 54 45 5f 42 55 53 59 5f 52 45 43 4f 56  QLITE_BUSY_RECOV
5d40: 45 52 59 20 20 20 20 20 20 20 20 20 20 20 28 53  ERY           (S
5d50: 51 4c 49 54 45 5f 42 55 53 59 20 20 20 7c 20 20  QLITE_BUSY   |  
5d60: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
5d70: 53 51 4c 49 54 45 5f 42 55 53 59 5f 53 4e 41 50  SQLITE_BUSY_SNAP
5d80: 53 48 4f 54 20 20 20 20 20 20 20 20 20 20 20 28  SHOT           (
5d90: 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20 7c 20  SQLITE_BUSY   | 
5da0: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (2<<8)).#define
5db0: 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e   SQLITE_CANTOPEN
5dc0: 5f 4e 4f 54 45 4d 50 44 49 52 20 20 20 20 20 20  _NOTEMPDIR      
5dd0: 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e  (SQLITE_CANTOPEN
5de0: 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69   | (1<<8)).#defi
5df0: 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  ne SQLITE_CANTOP
5e00: 45 4e 5f 49 53 44 49 52 20 20 20 20 20 20 20 20  EN_ISDIR        
5e10: 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50    (SQLITE_CANTOP
5e20: 45 4e 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65  EN | (2<<8)).#de
5e30: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54  fine SQLITE_CANT
5e40: 4f 50 45 4e 5f 46 55 4c 4c 50 41 54 48 20 20 20  OPEN_FULLPATH   
5e50: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54      (SQLITE_CANT
5e60: 4f 50 45 4e 20 7c 20 28 33 3c 3c 38 29 29 0a 23  OPEN | (3<<8)).#
5e70: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41  define SQLITE_CA
5e80: 4e 54 4f 50 45 4e 5f 43 4f 4e 56 50 41 54 48 20  NTOPEN_CONVPATH 
5e90: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41        (SQLITE_CA
5ea0: 4e 54 4f 50 45 4e 20 7c 20 28 34 3c 3c 38 29 29  NTOPEN | (4<<8))
5eb0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5ec0: 43 4f 52 52 55 50 54 5f 56 54 41 42 20 20 20 20  CORRUPT_VTAB    
5ed0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5ee0: 43 4f 52 52 55 50 54 20 7c 20 28 31 3c 3c 38 29  CORRUPT | (1<<8)
5ef0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5f00: 5f 52 45 41 44 4f 4e 4c 59 5f 52 45 43 4f 56 45  _READONLY_RECOVE
5f10: 52 59 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  RY       (SQLITE
5f20: 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 31 3c 3c  _READONLY | (1<<
5f30: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5f40: 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 43 41 4e 54  TE_READONLY_CANT
5f50: 4c 4f 43 4b 20 20 20 20 20 20 20 28 53 51 4c 49  LOCK       (SQLI
5f60: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 32  TE_READONLY | (2
5f70: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5f80: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 4f  LITE_READONLY_RO
5f90: 4c 4c 42 41 43 4b 20 20 20 20 20 20 20 28 53 51  LLBACK       (SQ
5fa0: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20  LITE_READONLY | 
5fb0: 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (3<<8)).#define 
5fc0: 53 51 4c 49 54 45 5f 41 42 4f 52 54 5f 52 4f 4c  SQLITE_ABORT_ROL
5fd0: 4c 42 41 43 4b 20 20 20 20 20 20 20 20 20 20 28  LBACK          (
5fe0: 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 7c 20 28  SQLITE_ABORT | (
5ff0: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  2<<8)).#define S
6000: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
6010: 5f 43 48 45 43 4b 20 20 20 20 20 20 20 20 28 53  _CHECK        (S
6020: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
6030: 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69   | (1<<8)).#defi
6040: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
6050: 41 49 4e 54 5f 43 4f 4d 4d 49 54 48 4f 4f 4b 20  AINT_COMMITHOOK 
6060: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52    (SQLITE_CONSTR
6070: 41 49 4e 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23  AINT | (2<<8)).#
6080: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
6090: 4e 53 54 52 41 49 4e 54 5f 46 4f 52 45 49 47 4e  NSTRAINT_FOREIGN
60a0: 4b 45 59 20 20 20 28 53 51 4c 49 54 45 5f 43 4f  KEY   (SQLITE_CO
60b0: 4e 53 54 52 41 49 4e 54 20 7c 20 28 33 3c 3c 38  NSTRAINT | (3<<8
60c0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
60d0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46 55 4e  E_CONSTRAINT_FUN
60e0: 43 54 49 4f 4e 20 20 20 20 20 28 53 51 4c 49 54  CTION     (SQLIT
60f0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28  E_CONSTRAINT | (
6100: 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  4<<8)).#define S
6110: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
6120: 5f 4e 4f 54 4e 55 4c 4c 20 20 20 20 20 20 28 53  _NOTNULL      (S
6130: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
6140: 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69   | (5<<8)).#defi
6150: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
6160: 41 49 4e 54 5f 50 52 49 4d 41 52 59 4b 45 59 20  AINT_PRIMARYKEY 
6170: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52    (SQLITE_CONSTR
6180: 41 49 4e 54 20 7c 20 28 36 3c 3c 38 29 29 0a 23  AINT | (6<<8)).#
6190: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
61a0: 4e 53 54 52 41 49 4e 54 5f 54 52 49 47 47 45 52  NSTRAINT_TRIGGER
61b0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f        (SQLITE_CO
61c0: 4e 53 54 52 41 49 4e 54 20 7c 20 28 37 3c 3c 38  NSTRAINT | (7<<8
61d0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
61e0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 55 4e 49  E_CONSTRAINT_UNI
61f0: 51 55 45 20 20 20 20 20 20 20 28 53 51 4c 49 54  QUE       (SQLIT
6200: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28  E_CONSTRAINT | (
6210: 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  8<<8)).#define S
6220: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
6230: 5f 56 54 41 42 20 20 20 20 20 20 20 20 20 28 53  _VTAB         (S
6240: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
6250: 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69   | (9<<8)).#defi
6260: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
6270: 41 49 4e 54 5f 52 4f 57 49 44 20 20 20 20 20 20  AINT_ROWID      
6280: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52    (SQLITE_CONSTR
6290: 41 49 4e 54 20 7c 28 31 30 3c 3c 38 29 29 0a 23  AINT |(10<<8)).#
62a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
62b0: 54 49 43 45 5f 52 45 43 4f 56 45 52 5f 57 41 4c  TICE_RECOVER_WAL
62c0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4e 4f        (SQLITE_NO
62d0: 54 49 43 45 20 7c 20 28 31 3c 3c 38 29 29 0a 23  TICE | (1<<8)).#
62e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
62f0: 54 49 43 45 5f 52 45 43 4f 56 45 52 5f 52 4f 4c  TICE_RECOVER_ROL
6300: 4c 42 41 43 4b 20 28 53 51 4c 49 54 45 5f 4e 4f  LBACK (SQLITE_NO
6310: 54 49 43 45 20 7c 20 28 32 3c 3c 38 29 29 0a 23  TICE | (2<<8)).#
6320: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 41  define SQLITE_WA
6330: 52 4e 49 4e 47 5f 41 55 54 4f 49 4e 44 45 58 20  RNING_AUTOINDEX 
6340: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 57 41        (SQLITE_WA
6350: 52 4e 49 4e 47 20 7c 20 28 31 3c 3c 38 29 29 0a  RNING | (1<<8)).
6360: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
6370: 20 46 6c 61 67 73 20 46 6f 72 20 46 69 6c 65 20   Flags For File 
6380: 4f 70 65 6e 20 4f 70 65 72 61 74 69 6f 6e 73 0a  Open Operations.
6390: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 62 69 74 20  **.** These bit 
63a0: 76 61 6c 75 65 73 20 61 72 65 20 69 6e 74 65 6e  values are inten
63b0: 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 74  ded for use in t
63c0: 68 65 0a 2a 2a 20 33 72 64 20 70 61 72 61 6d 65  he.** 3rd parame
63d0: 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ter to the [sqli
63e0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69  te3_open_v2()] i
63f0: 6e 74 65 72 66 61 63 65 20 61 6e 64 0a 2a 2a 20  nterface and.** 
6400: 69 6e 20 74 68 65 20 34 74 68 20 70 61 72 61 6d  in the 4th param
6410: 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c  eter to the [sql
6420: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20  ite3_vfs.xOpen] 
6430: 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 23 64 65 66 69  method..*/.#defi
6440: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  ne SQLITE_OPEN_R
6450: 45 41 44 4f 4e 4c 59 20 20 20 20 20 20 20 20 20  EADONLY         
6460: 30 78 30 30 30 30 30 30 30 31 20 20 2f 2a 20 4f  0x00000001  /* O
6470: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
6480: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
6490: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  ne SQLITE_OPEN_R
64a0: 45 41 44 57 52 49 54 45 20 20 20 20 20 20 20 20  EADWRITE        
64b0: 30 78 30 30 30 30 30 30 30 32 20 20 2f 2a 20 4f  0x00000002  /* O
64c0: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
64d0: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
64e0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  ne SQLITE_OPEN_C
64f0: 52 45 41 54 45 20 20 20 20 20 20 20 20 20 20 20  REATE           
6500: 30 78 30 30 30 30 30 30 30 34 20 20 2f 2a 20 4f  0x00000004  /* O
6510: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
6520: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
6530: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44  ne SQLITE_OPEN_D
6540: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 20 20 20 20  ELETEONCLOSE    
6550: 30 78 30 30 30 30 30 30 30 38 20 20 2f 2a 20 56  0x00000008  /* V
6560: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
6570: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45  ne SQLITE_OPEN_E
6580: 58 43 4c 55 53 49 56 45 20 20 20 20 20 20 20 20  XCLUSIVE        
6590: 30 78 30 30 30 30 30 30 31 30 20 20 2f 2a 20 56  0x00000010  /* V
65a0: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
65b0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 41  ne SQLITE_OPEN_A
65c0: 55 54 4f 50 52 4f 58 59 20 20 20 20 20 20 20 20  UTOPROXY        
65d0: 30 78 30 30 30 30 30 30 32 30 20 20 2f 2a 20 56  0x00000020  /* V
65e0: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
65f0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55  ne SQLITE_OPEN_U
6600: 52 49 20 20 20 20 20 20 20 20 20 20 20 20 20 20  RI              
6610: 30 78 30 30 30 30 30 30 34 30 20 20 2f 2a 20 4f  0x00000040  /* O
6620: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
6630: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
6640: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d  ne SQLITE_OPEN_M
6650: 45 4d 4f 52 59 20 20 20 20 20 20 20 20 20 20 20  EMORY           
6660: 30 78 30 30 30 30 30 30 38 30 20 20 2f 2a 20 4f  0x00000080  /* O
6670: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
6680: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
6690: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d  ne SQLITE_OPEN_M
66a0: 41 49 4e 5f 44 42 20 20 20 20 20 20 20 20 20 20  AIN_DB          
66b0: 30 78 30 30 30 30 30 31 30 30 20 20 2f 2a 20 56  0x00000100  /* V
66c0: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
66d0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54  ne SQLITE_OPEN_T
66e0: 45 4d 50 5f 44 42 20 20 20 20 20 20 20 20 20 20  EMP_DB          
66f0: 30 78 30 30 30 30 30 32 30 30 20 20 2f 2a 20 56  0x00000200  /* V
6700: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
6710: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54  ne SQLITE_OPEN_T
6720: 52 41 4e 53 49 45 4e 54 5f 44 42 20 20 20 20 20  RANSIENT_DB     
6730: 30 78 30 30 30 30 30 34 30 30 20 20 2f 2a 20 56  0x00000400  /* V
6740: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
6750: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d  ne SQLITE_OPEN_M
6760: 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20  AIN_JOURNAL     
6770: 30 78 30 30 30 30 30 38 30 30 20 20 2f 2a 20 56  0x00000800  /* V
6780: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
6790: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54  ne SQLITE_OPEN_T
67a0: 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20  EMP_JOURNAL     
67b0: 30 78 30 30 30 30 31 30 30 30 20 20 2f 2a 20 56  0x00001000  /* V
67c0: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
67d0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53  ne SQLITE_OPEN_S
67e0: 55 42 4a 4f 55 52 4e 41 4c 20 20 20 20 20 20 20  UBJOURNAL       
67f0: 30 78 30 30 30 30 32 30 30 30 20 20 2f 2a 20 56  0x00002000  /* V
6800: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
6810: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d  ne SQLITE_OPEN_M
6820: 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 20 20 20  ASTER_JOURNAL   
6830: 30 78 30 30 30 30 34 30 30 30 20 20 2f 2a 20 56  0x00004000  /* V
6840: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
6850: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e  ne SQLITE_OPEN_N
6860: 4f 4d 55 54 45 58 20 20 20 20 20 20 20 20 20 20  OMUTEX          
6870: 30 78 30 30 30 30 38 30 30 30 20 20 2f 2a 20 4f  0x00008000  /* O
6880: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
6890: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
68a0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46  ne SQLITE_OPEN_F
68b0: 55 4c 4c 4d 55 54 45 58 20 20 20 20 20 20 20 20  ULLMUTEX        
68c0: 30 78 30 30 30 31 30 30 30 30 20 20 2f 2a 20 4f  0x00010000  /* O
68d0: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
68e0: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
68f0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53  ne SQLITE_OPEN_S
6900: 48 41 52 45 44 43 41 43 48 45 20 20 20 20 20 20  HAREDCACHE      
6910: 30 78 30 30 30 32 30 30 30 30 20 20 2f 2a 20 4f  0x00020000  /* O
6920: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
6930: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
6940: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50  ne SQLITE_OPEN_P
6950: 52 49 56 41 54 45 43 41 43 48 45 20 20 20 20 20  RIVATECACHE     
6960: 30 78 30 30 30 34 30 30 30 30 20 20 2f 2a 20 4f  0x00040000  /* O
6970: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
6980: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
6990: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 57  ne SQLITE_OPEN_W
69a0: 41 4c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  AL              
69b0: 30 78 30 30 30 38 30 30 30 30 20 20 2f 2a 20 56  0x00080000  /* V
69c0: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 20 52  FS only */../* R
69d0: 65 73 65 72 76 65 64 3a 20 20 20 20 20 20 20 20  eserved:        
69e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
69f0: 20 30 78 30 30 46 30 30 30 30 30 20 2a 2f 0a 0a   0x00F00000 */..
6a00: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
6a10: 44 65 76 69 63 65 20 43 68 61 72 61 63 74 65 72  Device Character
6a20: 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 54 68 65  istics.**.** The
6a30: 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65   xDeviceCharacte
6a40: 72 69 73 74 69 63 73 20 6d 65 74 68 6f 64 20 6f  ristics method o
6a50: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69  f the [sqlite3_i
6a60: 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62  o_methods].** ob
6a70: 6a 65 63 74 20 72 65 74 75 72 6e 73 20 61 6e 20  ject returns an 
6a80: 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73  integer which is
6a90: 20 61 20 76 65 63 74 6f 72 20 6f 66 20 74 68 65   a vector of the
6aa0: 73 65 0a 2a 2a 20 62 69 74 20 76 61 6c 75 65 73  se.** bit values
6ab0: 20 65 78 70 72 65 73 73 69 6e 67 20 49 2f 4f 20   expressing I/O 
6ac0: 63 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20  characteristics 
6ad0: 6f 66 20 74 68 65 20 6d 61 73 73 20 73 74 6f 72  of the mass stor
6ae0: 61 67 65 0a 2a 2a 20 64 65 76 69 63 65 20 74 68  age.** device th
6af0: 61 74 20 68 6f 6c 64 73 20 74 68 65 20 66 69 6c  at holds the fil
6b00: 65 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69  e that the [sqli
6b10: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a  te3_io_methods].
6b20: 2a 2a 20 72 65 66 65 72 73 20 74 6f 2e 0a 2a 2a  ** refers to..**
6b30: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 49  .** The SQLITE_I
6b40: 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70  OCAP_ATOMIC prop
6b50: 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20  erty means that 
6b60: 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a  all writes of.**
6b70: 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61 74   any size are at
6b80: 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54  omic.  The SQLIT
6b90: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e  E_IOCAP_ATOMICnn
6ba0: 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e  n values.** mean
6bb0: 20 74 68 61 74 20 77 72 69 74 65 73 20 6f 66 20   that writes of 
6bc0: 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65 20  blocks that are 
6bd0: 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69 7a  nnn bytes in siz
6be0: 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69  e and.** are ali
6bf0: 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72 65  gned to an addre
6c00: 73 73 20 77 68 69 63 68 20 69 73 20 61 6e 20 69  ss which is an i
6c10: 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 20  nteger multiple 
6c20: 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74  of.** nnn are at
6c30: 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54  omic.  The SQLIT
6c40: 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50  E_IOCAP_SAFE_APP
6c50: 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a  END value means.
6c60: 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61 74  ** that when dat
6c70: 61 20 69 73 20 61 70 70 65 6e 64 65 64 20 74 6f  a is appended to
6c80: 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74   a file, the dat
6c90: 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a  a is appended.**
6ca0: 20 66 69 72 73 74 20 74 68 65 6e 20 74 68 65 20   first then the 
6cb0: 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c 65  size of the file
6cc0: 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e 65   is extended, ne
6cd0: 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a  ver the other.**
6ce0: 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 68   way around.  Th
6cf0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
6d00: 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 72  EQUENTIAL proper
6d10: 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a  ty means that.**
6d20: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20   information is 
6d30: 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 20  written to disk 
6d40: 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64 65  in the same orde
6d50: 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f  r as calls.** to
6d60: 20 78 57 72 69 74 65 28 29 2e 20 20 54 68 65 20   xWrite().  The 
6d70: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57  SQLITE_IOCAP_POW
6d80: 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45  ERSAFE_OVERWRITE
6d90: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20   property means 
6da0: 74 68 61 74 0a 2a 2a 20 61 66 74 65 72 20 72 65  that.** after re
6db0: 62 6f 6f 74 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  boot following a
6dc0: 20 63 72 61 73 68 20 6f 72 20 70 6f 77 65 72 20   crash or power 
6dd0: 6c 6f 73 73 2c 20 74 68 65 20 6f 6e 6c 79 20 62  loss, the only b
6de0: 79 74 65 73 20 69 6e 20 61 0a 2a 2a 20 66 69 6c  ytes in a.** fil
6df0: 65 20 74 68 61 74 20 77 65 72 65 20 77 72 69 74  e that were writ
6e00: 74 65 6e 20 61 74 20 74 68 65 20 61 70 70 6c 69  ten at the appli
6e10: 63 61 74 69 6f 6e 20 6c 65 76 65 6c 20 6d 69 67  cation level mig
6e20: 68 74 20 68 61 76 65 20 63 68 61 6e 67 65 64 0a  ht have changed.
6e30: 2a 2a 20 61 6e 64 20 74 68 61 74 20 61 64 6a 61  ** and that adja
6e40: 63 65 6e 74 20 62 79 74 65 73 2c 20 65 76 65 6e  cent bytes, even
6e50: 20 62 79 74 65 73 20 77 69 74 68 69 6e 20 74 68   bytes within th
6e60: 65 20 73 61 6d 65 20 73 65 63 74 6f 72 20 61 72  e same sector ar
6e70: 65 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 64 20  e.** guaranteed 
6e80: 74 6f 20 62 65 20 75 6e 63 68 61 6e 67 65 64 2e  to be unchanged.
6e90: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
6ea0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20  TE_IOCAP_ATOMIC 
6eb0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6ec0: 30 78 30 30 30 30 30 30 30 31 0a 23 64 65 66 69  0x00000001.#defi
6ed0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6ee0: 41 54 4f 4d 49 43 35 31 32 20 20 20 20 20 20 20  ATOMIC512       
6ef0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
6f00: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
6f10: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 20  _IOCAP_ATOMIC1K 
6f20: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
6f30: 30 30 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65  00000004.#define
6f40: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
6f50: 4f 4d 49 43 32 4b 20 20 20 20 20 20 20 20 20 20  OMIC2K          
6f60: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 38 0a       0x00000008.
6f70: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6f80: 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 20 20 20  OCAP_ATOMIC4K   
6f90: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6fa0: 30 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53  000010.#define S
6fb0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
6fc0: 49 43 38 4b 20 20 20 20 20 20 20 20 20 20 20 20  IC8K            
6fd0: 20 20 20 30 78 30 30 30 30 30 30 32 30 0a 23 64     0x00000020.#d
6fe0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
6ff0: 41 50 5f 41 54 4f 4d 49 43 31 36 4b 20 20 20 20  AP_ATOMIC16K    
7000: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
7010: 30 30 34 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0040.#define SQL
7020: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
7030: 33 32 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  32K             
7040: 20 30 78 30 30 30 30 30 30 38 30 0a 23 64 65 66   0x00000080.#def
7050: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
7060: 5f 41 54 4f 4d 49 43 36 34 4b 20 20 20 20 20 20  _ATOMIC64K      
7070: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31          0x000001
7080: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  00.#define SQLIT
7090: 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50  E_IOCAP_SAFE_APP
70a0: 45 4e 44 20 20 20 20 20 20 20 20 20 20 20 20 30  END            0
70b0: 78 30 30 30 30 30 32 30 30 0a 23 64 65 66 69 6e  x00000200.#defin
70c0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
70d0: 45 51 55 45 4e 54 49 41 4c 20 20 20 20 20 20 20  EQUENTIAL       
70e0: 20 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30        0x00000400
70f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
7100: 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c  IOCAP_UNDELETABL
7110: 45 5f 57 48 45 4e 5f 4f 50 45 4e 20 20 30 78 30  E_WHEN_OPEN  0x0
7120: 30 30 30 30 38 30 30 0a 23 64 65 66 69 6e 65 20  0000800.#define 
7130: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57  SQLITE_IOCAP_POW
7140: 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45  ERSAFE_OVERWRITE
7150: 20 20 20 20 30 78 30 30 30 30 31 30 30 30 0a 0a      0x00001000..
7160: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
7170: 46 69 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 76  File Locking Lev
7180: 65 6c 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  els.**.** SQLite
7190: 20 75 73 65 73 20 6f 6e 65 20 6f 66 20 74 68 65   uses one of the
71a0: 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65  se integer value
71b0: 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a  s as the second.
71c0: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63  ** argument to c
71d0: 61 6c 6c 73 20 69 74 20 6d 61 6b 65 73 20 74 6f  alls it makes to
71e0: 20 74 68 65 20 78 4c 6f 63 6b 28 29 20 61 6e 64   the xLock() and
71f0: 20 78 55 6e 6c 6f 63 6b 28 29 20 6d 65 74 68 6f   xUnlock() metho
7200: 64 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73 71 6c  ds.** of an [sql
7210: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
7220: 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66   object..*/.#def
7230: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
7240: 4e 4f 4e 45 20 20 20 20 20 20 20 20 20 20 30 0a  NONE          0.
7250: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
7260: 4f 43 4b 5f 53 48 41 52 45 44 20 20 20 20 20 20  OCK_SHARED      
7270: 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
7280: 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44  TE_LOCK_RESERVED
7290: 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
72a0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44  SQLITE_LOCK_PEND
72b0: 49 4e 47 20 20 20 20 20 20 20 33 0a 23 64 65 66  ING       3.#def
72c0: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
72d0: 45 58 43 4c 55 53 49 56 45 20 20 20 20 20 34 0a  EXCLUSIVE     4.
72e0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
72f0: 20 53 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e   Synchronization
7300: 20 54 79 70 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a   Type Flags.**.*
7310: 2a 20 57 68 65 6e 20 53 51 4c 69 74 65 20 69 6e  * When SQLite in
7320: 76 6f 6b 65 73 20 74 68 65 20 78 53 79 6e 63 28  vokes the xSync(
7330: 29 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 0a 2a  ) method of an.*
7340: 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  * [sqlite3_io_me
7350: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 69 74  thods] object it
7360: 20 75 73 65 73 20 61 20 63 6f 6d 62 69 6e 61 74   uses a combinat
7370: 69 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20  ion of.** these 
7380: 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61  integer values a
7390: 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  s the second arg
73a0: 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65  ument..**.** Whe
73b0: 6e 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e  n the SQLITE_SYN
73c0: 43 5f 44 41 54 41 4f 4e 4c 59 20 66 6c 61 67 20  C_DATAONLY flag 
73d0: 69 73 20 75 73 65 64 2c 20 69 74 20 6d 65 61 6e  is used, it mean
73e0: 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 73 79  s that the.** sy
73f0: 6e 63 20 6f 70 65 72 61 74 69 6f 6e 20 6f 6e 6c  nc operation onl
7400: 79 20 6e 65 65 64 73 20 74 6f 20 66 6c 75 73 68  y needs to flush
7410: 20 64 61 74 61 20 74 6f 20 6d 61 73 73 20 73 74   data to mass st
7420: 6f 72 61 67 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a  orage.  Inode.**
7430: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6e 65 65   information nee
7440: 64 20 6e 6f 74 20 62 65 20 66 6c 75 73 68 65 64  d not be flushed
7450: 2e 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66  . If the lower f
7460: 6f 75 72 20 62 69 74 73 20 6f 66 20 74 68 65 20  our bits of the 
7470: 66 6c 61 67 0a 2a 2a 20 65 71 75 61 6c 20 53 51  flag.** equal SQ
7480: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
7490: 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 6f 20  , that means to 
74a0: 75 73 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63  use normal fsync
74b0: 28 29 20 73 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a  () semantics..**
74c0: 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f   If the lower fo
74d0: 75 72 20 62 69 74 73 20 65 71 75 61 6c 20 53 51  ur bits equal SQ
74e0: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20  LITE_SYNC_FULL, 
74f0: 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f  that means.** to
7500: 20 75 73 65 20 4d 61 63 20 4f 53 20 58 20 73 74   use Mac OS X st
7510: 79 6c 65 20 66 75 6c 6c 73 79 6e 63 20 69 6e 73  yle fullsync ins
7520: 74 65 61 64 20 6f 66 20 66 73 79 6e 63 28 29 2e  tead of fsync().
7530: 0a 2a 2a 0a 2a 2a 20 44 6f 20 6e 6f 74 20 63 6f  .**.** Do not co
7540: 6e 66 75 73 65 20 74 68 65 20 53 51 4c 49 54 45  nfuse the SQLITE
7550: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64  _SYNC_NORMAL and
7560: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c   SQLITE_SYNC_FUL
7570: 4c 20 66 6c 61 67 73 0a 2a 2a 20 77 69 74 68 20  L flags.** with 
7580: 74 68 65 20 5b 50 52 41 47 4d 41 20 73 79 6e 63  the [PRAGMA sync
7590: 68 72 6f 6e 6f 75 73 5d 3d 4e 4f 52 4d 41 4c 20  hronous]=NORMAL 
75a0: 61 6e 64 20 5b 50 52 41 47 4d 41 20 73 79 6e 63  and [PRAGMA sync
75b0: 68 72 6f 6e 6f 75 73 5d 3d 46 55 4c 4c 0a 2a 2a  hronous]=FULL.**
75c0: 20 73 65 74 74 69 6e 67 73 2e 20 20 54 68 65 20   settings.  The 
75d0: 5b 73 79 6e 63 68 72 6f 6e 6f 75 73 20 70 72 61  [synchronous pra
75e0: 67 6d 61 5d 20 64 65 74 65 72 6d 69 6e 65 73 20  gma] determines 
75f0: 77 68 65 6e 20 63 61 6c 6c 73 20 74 6f 20 74 68  when calls to th
7600: 65 0a 2a 2a 20 78 53 79 6e 63 20 56 46 53 20 6d  e.** xSync VFS m
7610: 65 74 68 6f 64 20 6f 63 63 75 72 20 61 6e 64 20  ethod occur and 
7620: 61 70 70 6c 69 65 73 20 75 6e 69 66 6f 72 6d 6c  applies uniforml
7630: 79 20 61 63 72 6f 73 73 20 61 6c 6c 20 70 6c 61  y across all pla
7640: 74 66 6f 72 6d 73 2e 0a 2a 2a 20 54 68 65 20 53  tforms..** The S
7650: 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41  QLITE_SYNC_NORMA
7660: 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e  L and SQLITE_SYN
7670: 43 5f 46 55 4c 4c 20 66 6c 61 67 73 20 64 65 74  C_FULL flags det
7680: 65 72 6d 69 6e 65 20 68 6f 77 0a 2a 2a 20 65 6e  ermine how.** en
7690: 65 72 67 65 74 69 63 20 6f 72 20 72 69 67 6f 72  ergetic or rigor
76a0: 6f 75 73 20 6f 72 20 66 6f 72 63 65 66 75 6c 20  ous or forceful 
76b0: 74 68 65 20 73 79 6e 63 20 6f 70 65 72 61 74 69  the sync operati
76c0: 6f 6e 73 20 61 72 65 20 61 6e 64 0a 2a 2a 20 6f  ons are and.** o
76d0: 6e 6c 79 20 6d 61 6b 65 20 61 20 64 69 66 66 65  nly make a diffe
76e0: 72 65 6e 63 65 20 6f 6e 20 4d 61 63 20 4f 53 58  rence on Mac OSX
76f0: 20 66 6f 72 20 74 68 65 20 64 65 66 61 75 6c 74   for the default
7700: 20 53 51 4c 69 74 65 20 63 6f 64 65 2e 0a 2a 2a   SQLite code..**
7710: 20 28 54 68 69 72 64 2d 70 61 72 74 79 20 56 46   (Third-party VF
7720: 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
7730: 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 6d 61 6b  s might also mak
7740: 65 20 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f  e the distinctio
7750: 6e 0a 2a 2a 20 62 65 74 77 65 65 6e 20 53 51 4c  n.** between SQL
7760: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20  ITE_SYNC_NORMAL 
7770: 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  and SQLITE_SYNC_
7780: 46 55 4c 4c 2c 20 62 75 74 20 61 6d 6f 6e 67 20  FULL, but among 
7790: 74 68 65 0a 2a 2a 20 6f 70 65 72 61 74 69 6e 67  the.** operating
77a0: 20 73 79 73 74 65 6d 73 20 6e 61 74 69 76 65 6c   systems nativel
77b0: 79 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53  y supported by S
77c0: 51 4c 69 74 65 2c 20 6f 6e 6c 79 20 4d 61 63 20  QLite, only Mac 
77d0: 4f 53 58 0a 2a 2a 20 63 61 72 65 73 20 61 62 6f  OSX.** cares abo
77e0: 75 74 20 74 68 65 20 64 69 66 66 65 72 65 6e 63  ut the differenc
77f0: 65 2e 29 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  e.).*/.#define S
7800: 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41  QLITE_SYNC_NORMA
7810: 4c 20 20 20 20 20 20 20 20 30 78 30 30 30 30 32  L        0x00002
7820: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
7830: 53 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20 20  SYNC_FULL       
7840: 20 20 20 30 78 30 30 30 30 33 0a 23 64 65 66 69     0x00003.#defi
7850: 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44  ne SQLITE_SYNC_D
7860: 41 54 41 4f 4e 4c 59 20 20 20 20 20 20 30 78 30  ATAONLY      0x0
7870: 30 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  0010../*.** CAPI
7880: 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61  3REF: OS Interfa
7890: 63 65 20 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e  ce Open File Han
78a0: 64 6c 65 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71  dle.**.** An [sq
78b0: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
78c0: 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e  ct represents an
78d0: 20 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20 74 68   open file in th
78e0: 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  e .** [sqlite3_v
78f0: 66 73 20 7c 20 4f 53 20 69 6e 74 65 72 66 61 63  fs | OS interfac
7900: 65 20 6c 61 79 65 72 5d 2e 20 20 49 6e 64 69 76  e layer].  Indiv
7910: 69 64 75 61 6c 20 4f 53 20 69 6e 74 65 72 66 61  idual OS interfa
7920: 63 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  ce.** implementa
7930: 74 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61  tions will.** wa
7940: 6e 74 20 74 6f 20 73 75 62 63 6c 61 73 73 20 74  nt to subclass t
7950: 68 69 73 20 6f 62 6a 65 63 74 20 62 79 20 61 70  his object by ap
7960: 70 65 6e 64 69 6e 67 20 61 64 64 69 74 69 6f 6e  pending addition
7970: 61 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72  al fields.** for
7980: 20 74 68 65 69 72 20 6f 77 6e 20 75 73 65 2e 20   their own use. 
7990: 20 54 68 65 20 70 4d 65 74 68 6f 64 73 20 65 6e   The pMethods en
79a0: 74 72 79 20 69 73 20 61 20 70 6f 69 6e 74 65 72  try is a pointer
79b0: 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74   to an.** [sqlit
79c0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f  e3_io_methods] o
79d0: 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e  bject that defin
79e0: 65 73 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 70  es methods for p
79f0: 65 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f  erforming.** I/O
7a00: 20 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74   operations on t
7a10: 68 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f  he open file..*/
7a20: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
7a30: 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 73 71 6c  sqlite3_file sql
7a40: 69 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63  ite3_file;.struc
7a50: 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b  t sqlite3_file {
7a60: 0a 20 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20  .  const struct 
7a70: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
7a80: 64 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f  ds *pMethods;  /
7a90: 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 61 6e  * Methods for an
7aa0: 20 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b   open file */.};
7ab0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
7ac0: 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 46  : OS Interface F
7ad0: 69 6c 65 20 56 69 72 74 75 61 6c 20 4d 65 74 68  ile Virtual Meth
7ae0: 6f 64 73 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a  ods Object.**.**
7af0: 20 45 76 65 72 79 20 66 69 6c 65 20 6f 70 65 6e   Every file open
7b00: 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74  ed by the [sqlit
7b10: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65  e3_vfs.xOpen] me
7b20: 74 68 6f 64 20 70 6f 70 75 6c 61 74 65 73 20 61  thod populates a
7b30: 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  n.** [sqlite3_fi
7b40: 6c 65 5d 20 6f 62 6a 65 63 74 20 28 6f 72 2c 20  le] object (or, 
7b50: 6d 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61  more commonly, a
7b60: 20 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65   subclass of the
7b70: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
7b80: 65 5d 20 6f 62 6a 65 63 74 29 20 77 69 74 68 20  e] object) with 
7b90: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
7ba0: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
7bb0: 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 73   object..** This
7bc0: 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20   object defines 
7bd0: 74 68 65 20 6d 65 74 68 6f 64 73 20 75 73 65 64  the methods used
7be0: 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69   to perform vari
7bf0: 6f 75 73 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a  ous operations.*
7c00: 2a 20 61 67 61 69 6e 73 74 20 74 68 65 20 6f 70  * against the op
7c10: 65 6e 20 66 69 6c 65 20 72 65 70 72 65 73 65 6e  en file represen
7c20: 74 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69  ted by the [sqli
7c30: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74  te3_file] object
7c40: 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b  ..**.** If the [
7c50: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65  sqlite3_vfs.xOpe
7c60: 6e 5d 20 6d 65 74 68 6f 64 20 73 65 74 73 20 74  n] method sets t
7c70: 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e  he sqlite3_file.
7c80: 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74  pMethods element
7c90: 20 0a 2a 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55   .** to a non-NU
7ca0: 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e  LL pointer, then
7cb0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6f 5f   the sqlite3_io_
7cc0: 6d 65 74 68 6f 64 73 2e 78 43 6c 6f 73 65 20 6d  methods.xClose m
7cd0: 65 74 68 6f 64 0a 2a 2a 20 6d 61 79 20 62 65 20  ethod.** may be 
7ce0: 69 6e 76 6f 6b 65 64 20 65 76 65 6e 20 69 66 20  invoked even if 
7cf0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
7d00: 2e 78 4f 70 65 6e 5d 20 72 65 70 6f 72 74 65 64  .xOpen] reported
7d10: 20 74 68 61 74 20 69 74 20 66 61 69 6c 65 64 2e   that it failed.
7d20: 20 20 54 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61    The.** only wa
7d30: 79 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 63  y to prevent a c
7d40: 61 6c 6c 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f  all to xClose fo
7d50: 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 65 64  llowing a failed
7d60: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f   [sqlite3_vfs.xO
7d70: 70 65 6e 5d 0a 2a 2a 20 69 73 20 66 6f 72 20 74  pen].** is for t
7d80: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  he [sqlite3_vfs.
7d90: 78 4f 70 65 6e 5d 20 74 6f 20 73 65 74 20 74 68  xOpen] to set th
7da0: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70  e sqlite3_file.p
7db0: 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 0a  Methods element.
7dc0: 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  ** to NULL..**.*
7dd0: 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75  * The flags argu
7de0: 6d 65 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d 61  ment to xSync ma
7df0: 79 20 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c  y be one of [SQL
7e00: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d  ITE_SYNC_NORMAL]
7e10: 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53   or.** [SQLITE_S
7e20: 59 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20  YNC_FULL].  The 
7e30: 66 69 72 73 74 20 63 68 6f 69 63 65 20 69 73 20  first choice is 
7e40: 74 68 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63  the normal fsync
7e50: 28 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  ()..** The secon
7e60: 64 20 63 68 6f 69 63 65 20 69 73 20 61 20 4d 61  d choice is a Ma
7e70: 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c  c OS X style ful
7e80: 6c 73 79 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c  lsync.  The [SQL
7e90: 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c  ITE_SYNC_DATAONL
7ea0: 59 5d 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62  Y].** flag may b
7eb0: 65 20 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e 64  e ORed in to ind
7ec0: 69 63 61 74 65 20 74 68 61 74 20 6f 6e 6c 79 20  icate that only 
7ed0: 74 68 65 20 64 61 74 61 20 6f 66 20 74 68 65 20  the data of the 
7ee0: 66 69 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20  file.** and not 
7ef0: 69 74 73 20 69 6e 6f 64 65 20 6e 65 65 64 73 20  its inode needs 
7f00: 74 6f 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a  to be synced..**
7f10: 0a 2a 2a 20 54 68 65 20 69 6e 74 65 67 65 72 20  .** The integer 
7f20: 76 61 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28  values to xLock(
7f30: 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20  ) and xUnlock() 
7f40: 61 72 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75  are one of.** <u
7f50: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  l>.** <li> [SQLI
7f60: 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a  TE_LOCK_NONE],.*
7f70: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c  * <li> [SQLITE_L
7f80: 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20  OCK_SHARED],.** 
7f90: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
7fa0: 4b 5f 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20  K_RESERVED],.** 
7fb0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
7fc0: 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a  K_PENDING], or.*
7fd0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c  * <li> [SQLITE_L
7fe0: 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a  OCK_EXCLUSIVE]..
7ff0: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63  ** </ul>.** xLoc
8000: 6b 28 29 20 69 6e 63 72 65 61 73 65 73 20 74 68  k() increases th
8010: 65 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28  e lock. xUnlock(
8020: 29 20 64 65 63 72 65 61 73 65 73 20 74 68 65 20  ) decreases the 
8030: 6c 6f 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68  lock..** The xCh
8040: 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 28  eckReservedLock(
8050: 29 20 6d 65 74 68 6f 64 20 63 68 65 63 6b 73 20  ) method checks 
8060: 77 68 65 74 68 65 72 20 61 6e 79 20 64 61 74 61  whether any data
8070: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c  base connection,
8080: 0a 2a 2a 20 65 69 74 68 65 72 20 69 6e 20 74 68  .** either in th
8090: 69 73 20 70 72 6f 63 65 73 73 20 6f 72 20 69 6e  is process or in
80a0: 20 73 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f 63   some other proc
80b0: 65 73 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20  ess, is holding 
80c0: 61 20 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50  a RESERVED,.** P
80d0: 45 4e 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55  ENDING, or EXCLU
80e0: 53 49 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65  SIVE lock on the
80f0: 20 66 69 6c 65 2e 20 20 49 74 20 72 65 74 75 72   file.  It retur
8100: 6e 73 20 74 72 75 65 0a 2a 2a 20 69 66 20 73 75  ns true.** if su
8110: 63 68 20 61 20 6c 6f 63 6b 20 65 78 69 73 74 73  ch a lock exists
8120: 20 61 6e 64 20 66 61 6c 73 65 20 6f 74 68 65 72   and false other
8130: 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  wise..**.** The 
8140: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d  xFileControl() m
8150: 65 74 68 6f 64 20 69 73 20 61 20 67 65 6e 65 72  ethod is a gener
8160: 69 63 20 69 6e 74 65 72 66 61 63 65 20 74 68 61  ic interface tha
8170: 74 20 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a  t allows custom.
8180: 2a 2a 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  ** VFS implement
8190: 61 74 69 6f 6e 73 20 74 6f 20 64 69 72 65 63 74  ations to direct
81a0: 6c 79 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70  ly control an op
81b0: 65 6e 20 66 69 6c 65 20 75 73 69 6e 67 20 74 68  en file using th
81c0: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  e.** [sqlite3_fi
81d0: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e  le_control()] in
81e0: 74 65 72 66 61 63 65 2e 20 20 54 68 65 20 73 65  terface.  The se
81f0: 63 6f 6e 64 20 22 6f 70 22 20 61 72 67 75 6d 65  cond "op" argume
8200: 6e 74 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65  nt is an.** inte
8210: 67 65 72 20 6f 70 63 6f 64 65 2e 20 20 54 68 65  ger opcode.  The
8220: 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
8230: 69 73 20 61 20 67 65 6e 65 72 69 63 20 70 6f 69  is a generic poi
8240: 6e 74 65 72 20 69 6e 74 65 6e 64 65 64 20 74 6f  nter intended to
8250: 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20 73  .** point to a s
8260: 74 72 75 63 74 75 72 65 20 74 68 61 74 20 6d 61  tructure that ma
8270: 79 20 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65  y contain argume
8280: 6e 74 73 20 6f 72 20 73 70 61 63 65 20 69 6e 20  nts or space in 
8290: 77 68 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74  which to.** writ
82a0: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 73 2e  e return values.
82b0: 20 20 50 6f 74 65 6e 74 69 61 6c 20 75 73 65 73    Potential uses
82c0: 20 66 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f   for xFileContro
82d0: 6c 28 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20  l() might be.** 
82e0: 66 75 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61  functions to ena
82f0: 62 6c 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63  ble blocking loc
8300: 6b 73 20 77 69 74 68 20 74 69 6d 65 6f 75 74 73  ks with timeouts
8310: 2c 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 0a  , to change the.
8320: 2a 2a 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74  ** locking strat
8330: 65 67 79 20 28 66 6f 72 20 65 78 61 6d 70 6c 65  egy (for example
8340: 20 74 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c 65   to use dot-file
8350: 20 6c 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75   locks), to inqu
8360: 69 72 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65  ire.** about the
8370: 20 73 74 61 74 75 73 20 6f 66 20 61 20 6c 6f 63   status of a loc
8380: 6b 2c 20 6f 72 20 74 6f 20 62 72 65 61 6b 20 73  k, or to break s
8390: 74 61 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65  tale locks.  The
83a0: 20 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20   SQLite.** core 
83b0: 72 65 73 65 72 76 65 73 20 61 6c 6c 20 6f 70 63  reserves all opc
83c0: 6f 64 65 73 20 6c 65 73 73 20 74 68 61 6e 20 31  odes less than 1
83d0: 30 30 20 66 6f 72 20 69 74 73 20 6f 77 6e 20 75  00 for its own u
83e0: 73 65 2e 0a 2a 2a 20 41 20 5b 53 51 4c 49 54 45  se..** A [SQLITE
83f0: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45  _FCNTL_LOCKSTATE
8400: 20 7c 20 6c 69 73 74 20 6f 66 20 6f 70 63 6f 64   | list of opcod
8410: 65 73 5d 20 6c 65 73 73 20 74 68 61 6e 20 31 30  es] less than 10
8420: 30 20 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a  0 is available..
8430: 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** Applications 
8440: 74 68 61 74 20 64 65 66 69 6e 65 20 61 20 63 75  that define a cu
8450: 73 74 6f 6d 20 78 46 69 6c 65 43 6f 6e 74 72 6f  stom xFileContro
8460: 6c 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 20  l method should 
8470: 75 73 65 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 67  use opcodes.** g
8480: 72 65 61 74 65 72 20 74 68 61 6e 20 31 30 30 20  reater than 100 
8490: 74 6f 20 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63  to avoid conflic
84a0: 74 73 2e 20 20 56 46 53 20 69 6d 70 6c 65 6d 65  ts.  VFS impleme
84b0: 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 0a  ntations should.
84c0: 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ** return [SQLIT
84d0: 45 5f 4e 4f 54 46 4f 55 4e 44 5d 20 66 6f 72 20  E_NOTFOUND] for 
84e0: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63  file control opc
84f0: 6f 64 65 73 20 74 68 61 74 20 74 68 65 79 20 64  odes that they d
8500: 6f 20 6e 6f 74 0a 2a 2a 20 72 65 63 6f 67 6e 69  o not.** recogni
8510: 7a 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53  ze..**.** The xS
8520: 65 63 74 6f 72 53 69 7a 65 28 29 20 6d 65 74 68  ectorSize() meth
8530: 6f 64 20 72 65 74 75 72 6e 73 20 74 68 65 20 73  od returns the s
8540: 65 63 74 6f 72 20 73 69 7a 65 20 6f 66 20 74 68  ector size of th
8550: 65 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74  e.** device that
8560: 20 75 6e 64 65 72 6c 69 65 73 20 74 68 65 20 66   underlies the f
8570: 69 6c 65 2e 20 20 54 68 65 20 73 65 63 74 6f 72  ile.  The sector
8580: 20 73 69 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20   size is the.** 
8590: 6d 69 6e 69 6d 75 6d 20 77 72 69 74 65 20 74 68  minimum write th
85a0: 61 74 20 63 61 6e 20 62 65 20 70 65 72 66 6f 72  at can be perfor
85b0: 6d 65 64 20 77 69 74 68 6f 75 74 20 64 69 73 74  med without dist
85c0: 75 72 62 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20  urbing.** other 
85d0: 62 79 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c  bytes in the fil
85e0: 65 2e 20 20 54 68 65 20 78 44 65 76 69 63 65 43  e.  The xDeviceC
85f0: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 28 29  haracteristics()
8600: 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72  .** method retur
8610: 6e 73 20 61 20 62 69 74 20 76 65 63 74 6f 72 20  ns a bit vector 
8620: 64 65 73 63 72 69 62 69 6e 67 20 62 65 68 61 76  describing behav
8630: 69 6f 72 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75  iors of the.** u
8640: 6e 64 65 72 6c 79 69 6e 67 20 64 65 76 69 63 65  nderlying device
8650: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
8660: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
8670: 41 50 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c  AP_ATOMIC].** <l
8680: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
8690: 5f 41 54 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c  _ATOMIC512].** <
86a0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
86b0: 50 5f 41 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c  P_ATOMIC1K].** <
86c0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
86d0: 50 5f 41 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c  P_ATOMIC2K].** <
86e0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
86f0: 50 5f 41 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c  P_ATOMIC4K].** <
8700: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
8710: 50 5f 41 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c  P_ATOMIC8K].** <
8720: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
8730: 50 5f 41 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20  P_ATOMIC16K].** 
8740: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
8750: 41 50 5f 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a  AP_ATOMIC32K].**
8760: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
8770: 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a  CAP_ATOMIC64K].*
8780: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
8790: 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44  OCAP_SAFE_APPEND
87a0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
87b0: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
87c0: 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  AL].** </ul>.**.
87d0: 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  ** The SQLITE_IO
87e0: 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65  CAP_ATOMIC prope
87f0: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61  rty means that a
8800: 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20  ll writes of.** 
8810: 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f  any size are ato
8820: 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45  mic.  The SQLITE
8830: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e  _IOCAP_ATOMICnnn
8840: 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20   values.** mean 
8850: 74 68 61 74 20 77 72 69 74 65 73 20 6f 66 20 62  that writes of b
8860: 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e  locks that are n
8870: 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65  nn bytes in size
8880: 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67   and.** are alig
8890: 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73  ned to an addres
88a0: 73 20 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e  s which is an in
88b0: 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f  teger multiple o
88c0: 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f  f.** nnn are ato
88d0: 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45  mic.  The SQLITE
88e0: 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45  _IOCAP_SAFE_APPE
88f0: 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a  ND value means.*
8900: 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61 74 61  * that when data
8910: 20 69 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20   is appended to 
8920: 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61  a file, the data
8930: 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20   is appended.** 
8940: 66 69 72 73 74 20 74 68 65 6e 20 74 68 65 20 73  first then the s
8950: 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20  ize of the file 
8960: 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76  is extended, nev
8970: 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20  er the other.** 
8980: 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65  way around.  The
8990: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45   SQLITE_IOCAP_SE
89a0: 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74  QUENTIAL propert
89b0: 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20  y means that.** 
89c0: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77  information is w
89d0: 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69  ritten to disk i
89e0: 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72  n the same order
89f0: 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20   as calls.** to 
8a00: 78 57 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20  xWrite()..**.** 
8a10: 49 66 20 78 52 65 61 64 28 29 20 72 65 74 75 72  If xRead() retur
8a20: 6e 73 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ns SQLITE_IOERR_
8a30: 53 48 4f 52 54 5f 52 45 41 44 20 69 74 20 6d 75  SHORT_READ it mu
8a40: 73 74 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20  st also fill.** 
8a50: 69 6e 20 74 68 65 20 75 6e 72 65 61 64 20 70 6f  in the unread po
8a60: 72 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 62 75  rtions of the bu
8a70: 66 66 65 72 20 77 69 74 68 20 7a 65 72 6f 73 2e  ffer with zeros.
8a80: 20 20 41 20 56 46 53 20 74 68 61 74 0a 2a 2a 20    A VFS that.** 
8a90: 66 61 69 6c 73 20 74 6f 20 7a 65 72 6f 2d 66 69  fails to zero-fi
8aa0: 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 6d  ll short reads m
8ab0: 69 67 68 74 20 73 65 65 6d 20 74 6f 20 77 6f 72  ight seem to wor
8ac0: 6b 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20  k.  However,.** 
8ad0: 66 61 69 6c 75 72 65 20 74 6f 20 7a 65 72 6f 2d  failure to zero-
8ae0: 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73  fill short reads
8af0: 20 77 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79   will eventually
8b00: 20 6c 65 61 64 20 74 6f 0a 2a 2a 20 64 61 74 61   lead to.** data
8b10: 62 61 73 65 20 63 6f 72 72 75 70 74 69 6f 6e 2e  base corruption.
8b20: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
8b30: 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  ct sqlite3_io_me
8b40: 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 69 6f  thods sqlite3_io
8b50: 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74  _methods;.struct
8b60: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68   sqlite3_io_meth
8b70: 6f 64 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72  ods {.  int iVer
8b80: 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43  sion;.  int (*xC
8b90: 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 66 69  lose)(sqlite3_fi
8ba0: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52  le*);.  int (*xR
8bb0: 65 61 64 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ead)(sqlite3_fil
8bc0: 65 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69  e*, void*, int i
8bd0: 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  Amt, sqlite3_int
8be0: 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74  64 iOfst);.  int
8bf0: 20 28 2a 78 57 72 69 74 65 29 28 73 71 6c 69 74   (*xWrite)(sqlit
8c00: 65 33 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20  e3_file*, const 
8c10: 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c  void*, int iAmt,
8c20: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69   sqlite3_int64 i
8c30: 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  Ofst);.  int (*x
8c40: 54 72 75 6e 63 61 74 65 29 28 73 71 6c 69 74 65  Truncate)(sqlite
8c50: 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33  3_file*, sqlite3
8c60: 5f 69 6e 74 36 34 20 73 69 7a 65 29 3b 0a 20 20  _int64 size);.  
8c70: 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c  int (*xSync)(sql
8c80: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
8c90: 66 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a  flags);.  int (*
8ca0: 78 46 69 6c 65 53 69 7a 65 29 28 73 71 6c 69 74  xFileSize)(sqlit
8cb0: 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65  e3_file*, sqlite
8cc0: 33 5f 69 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b  3_int64 *pSize);
8cd0: 0a 20 20 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28  .  int (*xLock)(
8ce0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
8cf0: 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e  nt);.  int (*xUn
8d00: 6c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69  lock)(sqlite3_fi
8d10: 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74  le*, int);.  int
8d20: 20 28 2a 78 43 68 65 63 6b 52 65 73 65 72 76 65   (*xCheckReserve
8d30: 64 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66  dLock)(sqlite3_f
8d40: 69 6c 65 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f  ile*, int *pResO
8d50: 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69  ut);.  int (*xFi
8d60: 6c 65 43 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74  leControl)(sqlit
8d70: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70  e3_file*, int op
8d80: 2c 20 76 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20  , void *pArg);. 
8d90: 20 69 6e 74 20 28 2a 78 53 65 63 74 6f 72 53 69   int (*xSectorSi
8da0: 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ze)(sqlite3_file
8db0: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 76  *);.  int (*xDev
8dc0: 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69  iceCharacteristi
8dd0: 63 73 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  cs)(sqlite3_file
8de0: 2a 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73  *);.  /* Methods
8df0: 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64   above are valid
8e00: 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 31 20 2a   for version 1 *
8e10: 2f 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4d 61  /.  int (*xShmMa
8e20: 70 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  p)(sqlite3_file*
8e30: 2c 20 69 6e 74 20 69 50 67 2c 20 69 6e 74 20 70  , int iPg, int p
8e40: 67 73 7a 2c 20 69 6e 74 2c 20 76 6f 69 64 20 76  gsz, int, void v
8e50: 6f 6c 61 74 69 6c 65 2a 2a 29 3b 0a 20 20 69 6e  olatile**);.  in
8e60: 74 20 28 2a 78 53 68 6d 4c 6f 63 6b 29 28 73 71  t (*xShmLock)(sq
8e70: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
8e80: 20 6f 66 66 73 65 74 2c 20 69 6e 74 20 6e 2c 20   offset, int n, 
8e90: 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 76 6f  int flags);.  vo
8ea0: 69 64 20 28 2a 78 53 68 6d 42 61 72 72 69 65 72  id (*xShmBarrier
8eb0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
8ec0: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 55 6e  ;.  int (*xShmUn
8ed0: 6d 61 70 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  map)(sqlite3_fil
8ee0: 65 2a 2c 20 69 6e 74 20 64 65 6c 65 74 65 46 6c  e*, int deleteFl
8ef0: 61 67 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64  ag);.  /* Method
8f00: 73 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69  s above are vali
8f10: 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 32 20  d for version 2 
8f20: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 46 65 74 63  */.  int (*xFetc
8f30: 68 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  h)(sqlite3_file*
8f40: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
8f50: 69 4f 66 73 74 2c 20 69 6e 74 20 69 41 6d 74 2c  iOfst, int iAmt,
8f60: 20 76 6f 69 64 20 2a 2a 70 70 29 3b 0a 20 20 69   void **pp);.  i
8f70: 6e 74 20 28 2a 78 55 6e 66 65 74 63 68 29 28 73  nt (*xUnfetch)(s
8f80: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71  qlite3_file*, sq
8f90: 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73  lite3_int64 iOfs
8fa0: 74 2c 20 76 6f 69 64 20 2a 70 29 3b 0a 20 20 2f  t, void *p);.  /
8fb0: 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  * Methods above 
8fc0: 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65  are valid for ve
8fd0: 72 73 69 6f 6e 20 33 20 2a 2f 0a 20 20 2f 2a 20  rsion 3 */.  /* 
8fe0: 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f  Additional metho
8ff0: 64 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  ds may be added 
9000: 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
9010: 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  es */.};../*.** 
9020: 43 41 50 49 33 52 45 46 3a 20 53 74 61 6e 64 61  CAPI3REF: Standa
9030: 72 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20  rd File Control 
9040: 4f 70 63 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68  Opcodes.**.** Th
9050: 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73  ese integer cons
9060: 74 61 6e 74 73 20 61 72 65 20 6f 70 63 6f 64 65  tants are opcode
9070: 73 20 66 6f 72 20 74 68 65 20 78 46 69 6c 65 43  s for the xFileC
9080: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a  ontrol method.**
9090: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
90a0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
90b0: 65 63 74 20 61 6e 64 20 66 6f 72 20 74 68 65 20  ect and for the 
90c0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
90d0: 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65  ntrol()].** inte
90e0: 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rface..**.** The
90f0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c   [SQLITE_FCNTL_L
9100: 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64 65  OCKSTATE] opcode
9110: 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65 62   is used for deb
9120: 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a  ugging.  This.**
9130: 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20 74   opcode causes t
9140: 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  he xFileControl 
9150: 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74 65 20  method to write 
9160: 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61 74  the current stat
9170: 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b  e of.** the lock
9180: 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45   (one of [SQLITE
9190: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51  _LOCK_NONE], [SQ
91a0: 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44  LITE_LOCK_SHARED
91b0: 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f  ],.** [SQLITE_LO
91c0: 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b 53  CK_RESERVED], [S
91d0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49  QLITE_LOCK_PENDI
91e0: 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  NG], or [SQLITE_
91f0: 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 29  LOCK_EXCLUSIVE])
9200: 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74 65  .** into an inte
9210: 67 65 72 20 74 68 61 74 20 74 68 65 20 70 41 72  ger that the pAr
9220: 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74  g argument point
9230: 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70 61 62  s to. This capab
9240: 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73 65 64  ility.** is used
9250: 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20   during testing 
9260: 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74  and only needs t
9270: 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 20 77  o be supported w
9280: 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 54 0a  hen SQLITE_TEST.
9290: 2a 2a 20 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a  ** is defined..*
92a0: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 5b 5b  * <ul>.** <li>[[
92b0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a  SQLITE_FCNTL_SIZ
92c0: 45 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 54 68 65 20  E_HINT]].** The 
92d0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49  [SQLITE_FCNTL_SI
92e0: 5a 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65 20  ZE_HINT] opcode 
92f0: 69 73 20 75 73 65 64 20 62 79 20 53 51 4c 69 74  is used by SQLit
9300: 65 20 74 6f 20 67 69 76 65 20 74 68 65 20 56 46  e to give the VF
9310: 53 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68 69 6e  S.** layer a hin
9320: 74 20 6f 66 20 68 6f 77 20 6c 61 72 67 65 20 74  t of how large t
9330: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
9340: 20 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62 65   will grow to be
9350: 20 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20 63   during the.** c
9360: 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74 69  urrent transacti
9370: 6f 6e 2e 20 20 54 68 69 73 20 68 69 6e 74 20 69  on.  This hint i
9380: 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 64  s not guaranteed
9390: 20 74 6f 20 62 65 20 61 63 63 75 72 61 74 65 20   to be accurate 
93a0: 62 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66 74  but it.** is oft
93b0: 65 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65 20 75  en close.  The u
93c0: 6e 64 65 72 6c 79 69 6e 67 20 56 46 53 20 6d 69  nderlying VFS mi
93d0: 67 68 74 20 63 68 6f 6f 73 65 20 74 6f 20 70 72  ght choose to pr
93e0: 65 61 6c 6c 6f 63 61 74 65 20 64 61 74 61 62 61  eallocate databa
93f0: 73 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63 65  se.** file space
9400: 20 62 61 73 65 64 20 6f 6e 20 74 68 69 73 20 68   based on this h
9410: 69 6e 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  int in order to 
9420: 68 65 6c 70 20 77 72 69 74 65 73 20 74 6f 20 74  help writes to t
9430: 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66  he database.** f
9440: 69 6c 65 20 72 75 6e 20 66 61 73 74 65 72 2e 0a  ile run faster..
9450: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
9460: 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53  TE_FCNTL_CHUNK_S
9470: 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  IZE]].** The [SQ
9480: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b  LITE_FCNTL_CHUNK
9490: 5f 53 49 5a 45 5d 20 6f 70 63 6f 64 65 20 69 73  _SIZE] opcode is
94a0: 20 75 73 65 64 20 74 6f 20 72 65 71 75 65 73 74   used to request
94b0: 20 74 68 61 74 20 74 68 65 20 56 46 53 0a 2a 2a   that the VFS.**
94c0: 20 65 78 74 65 6e 64 73 20 61 6e 64 20 74 72 75   extends and tru
94d0: 6e 63 61 74 65 73 20 74 68 65 20 64 61 74 61 62  ncates the datab
94e0: 61 73 65 20 66 69 6c 65 20 69 6e 20 63 68 75 6e  ase file in chun
94f0: 6b 73 20 6f 66 20 61 20 73 69 7a 65 20 73 70 65  ks of a size spe
9500: 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65  cified.** by the
9510: 20 75 73 65 72 2e 20 54 68 65 20 66 6f 75 72 74   user. The fourt
9520: 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73  h argument to [s
9530: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
9540: 72 6f 6c 28 29 5d 20 73 68 6f 75 6c 64 20 0a 2a  rol()] should .*
9550: 2a 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 69 6e  * point to an in
9560: 74 65 67 65 72 20 28 74 79 70 65 20 69 6e 74 29  teger (type int)
9570: 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
9580: 6e 65 77 20 63 68 75 6e 6b 2d 73 69 7a 65 20 74  new chunk-size t
9590: 6f 20 75 73 65 0a 2a 2a 20 66 6f 72 20 74 68 65  o use.** for the
95a0: 20 6e 6f 6d 69 6e 61 74 65 64 20 64 61 74 61 62   nominated datab
95b0: 61 73 65 2e 20 41 6c 6c 6f 63 61 74 69 6e 67 20  ase. Allocating 
95c0: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 73 70  database file sp
95d0: 61 63 65 20 69 6e 20 6c 61 72 67 65 0a 2a 2a 20  ace in large.** 
95e0: 63 68 75 6e 6b 73 20 28 73 61 79 20 31 4d 42 20  chunks (say 1MB 
95f0: 61 74 20 61 20 74 69 6d 65 29 2c 20 6d 61 79 20  at a time), may 
9600: 72 65 64 75 63 65 20 66 69 6c 65 2d 73 79 73 74  reduce file-syst
9610: 65 6d 20 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e  em fragmentation
9620: 20 61 6e 64 0a 2a 2a 20 69 6d 70 72 6f 76 65 20   and.** improve 
9630: 70 65 72 66 6f 72 6d 61 6e 63 65 20 6f 6e 20 73  performance on s
9640: 6f 6d 65 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 0a  ome systems..**.
9650: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
9660: 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54  FCNTL_FILE_POINT
9670: 45 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ER]].** The [SQL
9680: 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50  ITE_FCNTL_FILE_P
9690: 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 69  OINTER] opcode i
96a0: 73 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e  s used to obtain
96b0: 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f   a pointer.** to
96c0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   the [sqlite3_fi
96d0: 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f 63  le] object assoc
96e0: 69 61 74 65 64 20 77 69 74 68 20 61 20 70 61 72  iated with a par
96f0: 74 69 63 75 6c 61 72 20 64 61 74 61 62 61 73 65  ticular database
9700: 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  .** connection. 
9710: 20 53 65 65 20 74 68 65 20 5b 73 71 6c 69 74 65   See the [sqlite
9720: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
9730: 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20  ] documentation 
9740: 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61  for.** additiona
9750: 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  l information..*
9760: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
9770: 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49  E_FCNTL_SYNC_OMI
9780: 54 54 45 44 5d 5d 0a 2a 2a 20 5e 28 54 68 65 20  TTED]].** ^(The 
9790: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59  [SQLITE_FCNTL_SY
97a0: 4e 43 5f 4f 4d 49 54 54 45 44 5d 20 6f 70 63 6f  NC_OMITTED] opco
97b0: 64 65 20 69 73 20 67 65 6e 65 72 61 74 65 64 20  de is generated 
97c0: 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 0a 2a 2a  internally by.**
97d0: 20 53 51 4c 69 74 65 20 61 6e 64 20 73 65 6e 74   SQLite and sent
97e0: 20 74 6f 20 61 6c 6c 20 56 46 53 65 73 20 69 6e   to all VFSes in
97f0: 20 70 6c 61 63 65 20 6f 66 20 61 20 63 61 6c 6c   place of a call
9800: 20 74 6f 20 74 68 65 20 78 53 79 6e 63 20 6d 65   to the xSync me
9810: 74 68 6f 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65  thod.** when the
9820: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
9830: 74 69 6f 6e 20 68 61 73 20 5b 50 52 41 47 4d 41  tion has [PRAGMA
9840: 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 20 73 65   synchronous] se
9850: 74 20 74 6f 20 4f 46 46 2e 29 5e 0a 2a 2a 20 53  t to OFF.)^.** S
9860: 6f 6d 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20  ome specialized 
9870: 56 46 53 65 73 20 6e 65 65 64 20 74 68 69 73 20  VFSes need this 
9880: 73 69 67 6e 61 6c 20 69 6e 20 6f 72 64 65 72 20  signal in order 
9890: 74 6f 20 6f 70 65 72 61 74 65 20 63 6f 72 72 65  to operate corre
98a0: 63 74 6c 79 0a 2a 2a 20 77 68 65 6e 20 5b 50 52  ctly.** when [PR
98b0: 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73  AGMA synchronous
98c0: 20 7c 20 50 52 41 47 4d 41 20 73 79 6e 63 68 72   | PRAGMA synchr
98d0: 6f 6e 6f 75 73 3d 4f 46 46 5d 20 69 73 20 73 65  onous=OFF] is se
98e0: 74 2c 20 62 75 74 20 6d 6f 73 74 20 0a 2a 2a 20  t, but most .** 
98f0: 56 46 53 65 73 20 64 6f 20 6e 6f 74 20 6e 65 65  VFSes do not nee
9900: 64 20 74 68 69 73 20 73 69 67 6e 61 6c 20 61 6e  d this signal an
9910: 64 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c  d should silentl
9920: 79 20 69 67 6e 6f 72 65 20 74 68 69 73 20 6f 70  y ignore this op
9930: 63 6f 64 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61  code..** Applica
9940: 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74  tions should not
9950: 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66   call [sqlite3_f
9960: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77  ile_control()] w
9970: 69 74 68 20 74 68 69 73 0a 2a 2a 20 6f 70 63 6f  ith this.** opco
9980: 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d  de as doing so m
9990: 61 79 20 64 69 73 72 75 70 74 20 74 68 65 20 6f  ay disrupt the o
99a0: 70 65 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  peration of the 
99b0: 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65  specialized VFSe
99c0: 73 0a 2a 2a 20 74 68 61 74 20 64 6f 20 72 65 71  s.** that do req
99d0: 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a  uire it.  .**.**
99e0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
99f0: 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54  NTL_WIN32_AV_RET
9a00: 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  RY]].** ^The [SQ
9a10: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32  LITE_FCNTL_WIN32
9a20: 5f 41 56 5f 52 45 54 52 59 5d 20 6f 70 63 6f 64  _AV_RETRY] opcod
9a30: 65 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f 6e  e is used to con
9a40: 66 69 67 75 72 65 20 61 75 74 6f 6d 61 74 69 63  figure automatic
9a50: 0a 2a 2a 20 72 65 74 72 79 20 63 6f 75 6e 74 73  .** retry counts
9a60: 20 61 6e 64 20 69 6e 74 65 72 76 61 6c 73 20 66   and intervals f
9a70: 6f 72 20 63 65 72 74 61 69 6e 20 64 69 73 6b 20  or certain disk 
9a80: 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 66  I/O operations f
9a90: 6f 72 20 74 68 65 0a 2a 2a 20 77 69 6e 64 6f 77  or the.** window
9aa0: 73 20 5b 56 46 53 5d 20 69 6e 20 6f 72 64 65 72  s [VFS] in order
9ab0: 20 74 6f 20 70 72 6f 76 69 64 65 20 72 6f 62 75   to provide robu
9ac0: 73 74 6e 65 73 73 20 69 6e 20 74 68 65 20 70 72  stness in the pr
9ad0: 65 73 65 6e 63 65 20 6f 66 0a 2a 2a 20 61 6e 74  esence of.** ant
9ae0: 69 2d 76 69 72 75 73 20 70 72 6f 67 72 61 6d 73  i-virus programs
9af0: 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c 20 74  .  By default, t
9b00: 68 65 20 77 69 6e 64 6f 77 73 20 56 46 53 20 77  he windows VFS w
9b10: 69 6c 6c 20 72 65 74 72 79 20 66 69 6c 65 20 72  ill retry file r
9b20: 65 61 64 2c 0a 2a 2a 20 66 69 6c 65 20 77 72 69  ead,.** file wri
9b30: 74 65 2c 20 61 6e 64 20 66 69 6c 65 20 64 65 6c  te, and file del
9b40: 65 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20 75  ete operations u
9b50: 70 20 74 6f 20 31 30 20 74 69 6d 65 73 2c 20 77  p to 10 times, w
9b60: 69 74 68 20 61 20 64 65 6c 61 79 0a 2a 2a 20 6f  ith a delay.** o
9b70: 66 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  f 25 millisecond
9b80: 73 20 62 65 66 6f 72 65 20 74 68 65 20 66 69 72  s before the fir
9b90: 73 74 20 72 65 74 72 79 20 61 6e 64 20 77 69 74  st retry and wit
9ba0: 68 20 74 68 65 20 64 65 6c 61 79 20 69 6e 63 72  h the delay incr
9bb0: 65 61 73 69 6e 67 0a 2a 2a 20 62 79 20 61 6e 20  easing.** by an 
9bc0: 61 64 64 69 74 69 6f 6e 61 6c 20 32 35 20 6d 69  additional 25 mi
9bd0: 6c 6c 69 73 65 63 6f 6e 64 73 20 77 69 74 68 20  lliseconds with 
9be0: 65 61 63 68 20 73 75 62 73 65 71 75 65 6e 74 20  each subsequent 
9bf0: 72 65 74 72 79 2e 20 20 54 68 69 73 0a 2a 2a 20  retry.  This.** 
9c00: 6f 70 63 6f 64 65 20 61 6c 6c 6f 77 73 20 74 68  opcode allows th
9c10: 65 73 65 20 74 77 6f 20 76 61 6c 75 65 73 20 28  ese two values (
9c20: 31 30 20 72 65 74 72 69 65 73 20 61 6e 64 20 32  10 retries and 2
9c30: 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f  5 milliseconds o
9c40: 66 20 64 65 6c 61 79 29 0a 2a 2a 20 74 6f 20 62  f delay).** to b
9c50: 65 20 61 64 6a 75 73 74 65 64 2e 20 20 54 68 65  e adjusted.  The
9c60: 20 76 61 6c 75 65 73 20 61 72 65 20 63 68 61 6e   values are chan
9c70: 67 65 64 20 66 6f 72 20 61 6c 6c 20 64 61 74 61  ged for all data
9c80: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
9c90: 0a 2a 2a 20 77 69 74 68 69 6e 20 74 68 65 20 73  .** within the s
9ca0: 61 6d 65 20 70 72 6f 63 65 73 73 2e 20 20 54 68  ame process.  Th
9cb0: 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  e argument is a 
9cc0: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 61 72  pointer to an ar
9cd0: 72 61 79 20 6f 66 20 74 77 6f 0a 2a 2a 20 69 6e  ray of two.** in
9ce0: 74 65 67 65 72 73 20 77 68 65 72 65 20 74 68 65  tegers where the
9cf0: 20 66 69 72 73 74 20 69 6e 74 65 67 65 72 20 69   first integer i
9d00: 20 74 68 65 20 6e 65 77 20 72 65 74 72 79 20 63   the new retry c
9d10: 6f 75 6e 74 20 61 6e 64 20 74 68 65 20 73 65 63  ount and the sec
9d20: 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 69  ond.** integer i
9d30: 73 20 74 68 65 20 64 65 6c 61 79 2e 20 20 49 66  s the delay.  If
9d40: 20 65 69 74 68 65 72 20 69 6e 74 65 67 65 72 20   either integer 
9d50: 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65  is negative, the
9d60: 6e 20 74 68 65 20 73 65 74 74 69 6e 67 0a 2a 2a  n the setting.**
9d70: 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 20   is not changed 
9d80: 62 75 74 20 69 6e 73 74 65 61 64 20 74 68 65 20  but instead the 
9d90: 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 74  prior value of t
9da0: 68 61 74 20 73 65 74 74 69 6e 67 20 69 73 20 77  hat setting is w
9db0: 72 69 74 74 65 6e 0a 2a 2a 20 69 6e 74 6f 20 74  ritten.** into t
9dc0: 68 65 20 61 72 72 61 79 20 65 6e 74 72 79 2c 20  he array entry, 
9dd0: 61 6c 6c 6f 77 69 6e 67 20 74 68 65 20 63 75 72  allowing the cur
9de0: 72 65 6e 74 20 72 65 74 72 79 20 73 65 74 74 69  rent retry setti
9df0: 6e 67 73 20 74 6f 20 62 65 0a 2a 2a 20 69 6e 74  ngs to be.** int
9e00: 65 72 72 6f 67 61 74 65 64 2e 20 20 54 68 65 20  errogated.  The 
9e10: 7a 44 62 4e 61 6d 65 20 70 61 72 61 6d 65 74 65  zDbName paramete
9e20: 72 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a  r is ignored..**
9e30: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
9e40: 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57  _FCNTL_PERSIST_W
9e50: 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  AL]].** ^The [SQ
9e60: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49  LITE_FCNTL_PERSI
9e70: 53 54 5f 57 41 4c 5d 20 6f 70 63 6f 64 65 20 69  ST_WAL] opcode i
9e80: 73 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f 72  s used to set or
9e90: 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 70 65   query the.** pe
9ea0: 72 73 69 73 74 65 6e 74 20 5b 57 41 4c 20 7c 20  rsistent [WAL | 
9eb0: 57 72 69 74 65 20 41 68 65 61 64 20 4c 6f 67 5d  Write Ahead Log]
9ec0: 20 73 65 74 74 69 6e 67 2e 20 20 42 79 20 64 65   setting.  By de
9ed0: 66 61 75 6c 74 2c 20 74 68 65 20 61 75 78 69 6c  fault, the auxil
9ee0: 69 61 72 79 0a 2a 2a 20 77 72 69 74 65 20 61 68  iary.** write ah
9ef0: 65 61 64 20 6c 6f 67 20 61 6e 64 20 73 68 61 72  ead log and shar
9f00: 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20  ed memory files 
9f10: 75 73 65 64 20 66 6f 72 20 74 72 61 6e 73 61 63  used for transac
9f20: 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20  tion control.** 
9f30: 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  are automaticall
9f40: 79 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 74  y deleted when t
9f50: 68 65 20 6c 61 74 65 73 74 20 63 6f 6e 6e 65 63  he latest connec
9f60: 74 69 6f 6e 20 74 6f 20 74 68 65 20 64 61 74 61  tion to the data
9f70: 62 61 73 65 0a 2a 2a 20 63 6c 6f 73 65 73 2e 20  base.** closes. 
9f80: 20 53 65 74 74 69 6e 67 20 70 65 72 73 69 73 74   Setting persist
9f90: 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 63 61 75  ent WAL mode cau
9fa0: 73 65 73 20 74 68 6f 73 65 20 66 69 6c 65 73 20  ses those files 
9fb0: 74 6f 20 70 65 72 73 69 73 74 20 61 66 74 65 72  to persist after
9fc0: 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20 50 65 72 73  .** close.  Pers
9fd0: 69 73 74 69 6e 67 20 74 68 65 20 66 69 6c 65 73  isting the files
9fe0: 20 69 73 20 75 73 65 66 75 6c 20 77 68 65 6e 20   is useful when 
9ff0: 6f 74 68 65 72 20 70 72 6f 63 65 73 73 65 73 20  other processes 
a000: 74 68 61 74 20 64 6f 20 6e 6f 74 0a 2a 2a 20 68  that do not.** h
a010: 61 76 65 20 77 72 69 74 65 20 70 65 72 6d 69 73  ave write permis
a020: 73 69 6f 6e 20 6f 6e 20 74 68 65 20 64 69 72 65  sion on the dire
a030: 63 74 6f 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67  ctory containing
a040: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
a050: 6c 65 20 77 61 6e 74 0a 2a 2a 20 74 6f 20 72 65  le want.** to re
a060: 61 64 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ad the database 
a070: 66 69 6c 65 2c 20 61 73 20 74 68 65 20 57 41 4c  file, as the WAL
a080: 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d 6f   and shared memo
a090: 72 79 20 66 69 6c 65 73 20 6d 75 73 74 20 65 78  ry files must ex
a0a0: 69 73 74 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20  ist.** in order 
a0b0: 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 73 65  for the database
a0c0: 20 74 6f 20 62 65 20 72 65 61 64 61 62 6c 65 2e   to be readable.
a0d0: 20 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72    The fourth par
a0e0: 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71  ameter to.** [sq
a0f0: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
a100: 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20 6f  ol()] for this o
a110: 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65 20  pcode should be 
a120: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
a130: 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74  integer..** That
a140: 20 69 6e 74 65 67 65 72 20 69 73 20 30 20 74 6f   integer is 0 to
a150: 20 64 69 73 61 62 6c 65 20 70 65 72 73 69 73 74   disable persist
a160: 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 6f 72 20  ent WAL mode or 
a170: 31 20 74 6f 20 65 6e 61 62 6c 65 20 70 65 72 73  1 to enable pers
a180: 69 73 74 65 6e 74 0a 2a 2a 20 57 41 4c 20 6d 6f  istent.** WAL mo
a190: 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74 65  de.  If the inte
a1a0: 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20  ger is -1, then 
a1b0: 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 74 65  it is overwritte
a1c0: 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65  n with the curre
a1d0: 6e 74 0a 2a 2a 20 57 41 4c 20 70 65 72 73 69 73  nt.** WAL persis
a1e0: 74 65 6e 63 65 20 73 65 74 74 69 6e 67 2e 0a 2a  tence setting..*
a1f0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
a200: 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46  E_FCNTL_POWERSAF
a210: 45 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a  E_OVERWRITE]].**
a220: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43   ^The [SQLITE_FC
a230: 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56  NTL_POWERSAFE_OV
a240: 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20  ERWRITE] opcode 
a250: 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f  is used to set o
a260: 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 70  r query the.** p
a270: 65 72 73 69 73 74 65 6e 74 20 22 70 6f 77 65 72  ersistent "power
a280: 73 61 66 65 2d 6f 76 65 72 77 72 69 74 65 22 20  safe-overwrite" 
a290: 6f 72 20 22 50 53 4f 57 22 20 73 65 74 74 69 6e  or "PSOW" settin
a2a0: 67 2e 20 20 54 68 65 20 50 53 4f 57 20 73 65 74  g.  The PSOW set
a2b0: 74 69 6e 67 0a 2a 2a 20 64 65 74 65 72 6d 69 6e  ting.** determin
a2c0: 65 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 49  es the [SQLITE_I
a2d0: 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f  OCAP_POWERSAFE_O
a2e0: 56 45 52 57 52 49 54 45 5d 20 62 69 74 20 6f 66  VERWRITE] bit of
a2f0: 20 74 68 65 0a 2a 2a 20 78 44 65 76 69 63 65 43   the.** xDeviceC
a300: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6d  haracteristics m
a310: 65 74 68 6f 64 73 2e 20 54 68 65 20 66 6f 75 72  ethods. The four
a320: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  th parameter to.
a330: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
a340: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20  _control()] for 
a350: 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68 6f 75  this opcode shou
a360: 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20  ld be a pointer 
a370: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a  to an integer..*
a380: 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72 20 69  * That integer i
a390: 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 7a  s 0 to disable z
a3a0: 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20  ero-damage mode 
a3b0: 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 7a  or 1 to enable z
a3c0: 65 72 6f 2d 64 61 6d 61 67 65 0a 2a 2a 20 6d 6f  ero-damage.** mo
a3d0: 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74 65  de.  If the inte
a3e0: 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20  ger is -1, then 
a3f0: 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 74 65  it is overwritte
a400: 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65  n with the curre
a410: 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64 61 6d 61 67  nt.** zero-damag
a420: 65 20 6d 6f 64 65 20 73 65 74 74 69 6e 67 2e 0a  e mode setting..
a430: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
a440: 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49  TE_FCNTL_OVERWRI
a450: 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  TE]].** ^The [SQ
a460: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57  LITE_FCNTL_OVERW
a470: 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20  RITE] opcode is 
a480: 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c 69 74  invoked by SQLit
a490: 65 20 61 66 74 65 72 20 6f 70 65 6e 69 6e 67 0a  e after opening.
a4a0: 2a 2a 20 61 20 77 72 69 74 65 20 74 72 61 6e 73  ** a write trans
a4b0: 61 63 74 69 6f 6e 20 74 6f 20 69 6e 64 69 63 61  action to indica
a4c0: 74 65 20 74 68 61 74 2c 20 75 6e 6c 65 73 73 20  te that, unless 
a4d0: 69 74 20 69 73 20 72 6f 6c 6c 65 64 20 62 61 63  it is rolled bac
a4e0: 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a 2a 20 72 65  k for some.** re
a4f0: 61 73 6f 6e 2c 20 74 68 65 20 65 6e 74 69 72 65  ason, the entire
a500: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77   database file w
a510: 69 6c 6c 20 62 65 20 6f 76 65 72 77 72 69 74 74  ill be overwritt
a520: 65 6e 20 62 79 20 74 68 65 20 63 75 72 72 65 6e  en by the curren
a530: 74 20 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f  t .** transactio
a540: 6e 2e 20 54 68 69 73 20 69 73 20 75 73 65 64 20  n. This is used 
a550: 62 79 20 56 41 43 55 55 4d 20 6f 70 65 72 61 74  by VACUUM operat
a560: 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  ions..**.** <li>
a570: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56  [[SQLITE_FCNTL_V
a580: 46 53 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 54 68 65  FSNAME]].** ^The
a590: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56   [SQLITE_FCNTL_V
a5a0: 46 53 4e 41 4d 45 5d 20 6f 70 63 6f 64 65 20 63  FSNAME] opcode c
a5b0: 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62  an be used to ob
a5c0: 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f  tain the names o
a5d0: 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46 53 65 73 5d  f.** all [VFSes]
a5e0: 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 61 63   in the VFS stac
a5f0: 6b 2e 20 20 54 68 65 20 6e 61 6d 65 73 20 61 72  k.  The names ar
a600: 65 20 6f 66 20 61 6c 6c 20 56 46 53 20 73 68 69  e of all VFS shi
a610: 6d 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20 66 69  ms and the.** fi
a620: 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c 65 76 65 6c  nal bottom-level
a630: 20 56 46 53 20 61 72 65 20 77 72 69 74 74 65 6e   VFS are written
a640: 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74   into memory obt
a650: 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b  ained from .** [
a660: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
a670: 5d 20 61 6e 64 20 74 68 65 20 72 65 73 75 6c 74  ] and the result
a680: 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 74 68   is stored in th
a690: 65 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c 65  e char* variable
a6a0: 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 66 6f 75  .** that the fou
a6b0: 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f 66  rth parameter of
a6c0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
a6d0: 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f 69 6e 74 73  ontrol()] points
a6e0: 20 74 6f 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c   to..** The call
a6f0: 65 72 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c  er is responsibl
a700: 65 20 66 6f 72 20 66 72 65 65 69 6e 67 20 74 68  e for freeing th
a710: 65 20 6d 65 6d 6f 72 79 20 77 68 65 6e 20 64 6f  e memory when do
a720: 6e 65 2e 20 20 41 73 20 77 69 74 68 0a 2a 2a 20  ne.  As with.** 
a730: 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c  all file-control
a740: 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 72 65 20   actions, there 
a750: 69 73 20 6e 6f 20 67 75 61 72 61 6e 74 65 65 20  is no guarantee 
a760: 74 68 61 74 20 74 68 69 73 20 77 69 6c 6c 20 61  that this will a
a770: 63 74 75 61 6c 6c 79 0a 2a 2a 20 64 6f 20 61 6e  ctually.** do an
a780: 79 74 68 69 6e 67 2e 20 20 43 61 6c 6c 65 72 73  ything.  Callers
a790: 20 73 68 6f 75 6c 64 20 69 6e 69 74 69 61 6c 69   should initiali
a7a0: 7a 65 20 74 68 65 20 63 68 61 72 2a 20 76 61 72  ze the char* var
a7b0: 69 61 62 6c 65 20 74 6f 20 61 20 4e 55 4c 4c 0a  iable to a NULL.
a7c0: 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 20 63 61  ** pointer in ca
a7d0: 73 65 20 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e  se this file-con
a7e0: 74 72 6f 6c 20 69 73 20 6e 6f 74 20 69 6d 70 6c  trol is not impl
a7f0: 65 6d 65 6e 74 65 64 2e 20 20 54 68 69 73 20 66  emented.  This f
a800: 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 69  ile-control.** i
a810: 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 64  s intended for d
a820: 69 61 67 6e 6f 73 74 69 63 20 75 73 65 20 6f 6e  iagnostic use on
a830: 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ly..**.** <li>[[
a840: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
a850: 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68 65 6e 65 76  GMA]].** ^Whenev
a860: 65 72 20 61 20 5b 50 52 41 47 4d 41 5d 20 73 74  er a [PRAGMA] st
a870: 61 74 65 6d 65 6e 74 20 69 73 20 70 61 72 73 65  atement is parse
a880: 64 2c 20 61 6e 20 5b 53 51 4c 49 54 45 5f 46 43  d, an [SQLITE_FC
a890: 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 0a 2a 2a 20  NTL_PRAGMA] .** 
a8a0: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20  file control is 
a8b0: 73 65 6e 74 20 74 6f 20 74 68 65 20 6f 70 65 6e  sent to the open
a8c0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
a8d0: 6f 62 6a 65 63 74 20 63 6f 72 72 65 73 70 6f 6e  object correspon
a8e0: 64 69 6e 67 0a 2a 2a 20 74 6f 20 74 68 65 20 64  ding.** to the d
a8f0: 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 6f 20  atabase file to 
a900: 77 68 69 63 68 20 74 68 65 20 70 72 61 67 6d 61  which the pragma
a910: 20 73 74 61 74 65 6d 65 6e 74 20 72 65 66 65 72   statement refer
a920: 73 2e 20 5e 54 68 65 20 61 72 67 75 6d 65 6e 74  s. ^The argument
a930: 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 53 51 4c 49  .** to the [SQLI
a940: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
a950: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73   file control is
a960: 20 61 6e 20 61 72 72 61 79 20 6f 66 0a 2a 2a 20   an array of.** 
a970: 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69  pointers to stri
a980: 6e 67 73 20 28 63 68 61 72 2a 2a 29 20 69 6e 20  ngs (char**) in 
a990: 77 68 69 63 68 20 74 68 65 20 73 65 63 6f 6e 64  which the second
a9a0: 20 65 6c 65 6d 65 6e 74 20 6f 66 20 74 68 65 20   element of the 
a9b0: 61 72 72 61 79 0a 2a 2a 20 69 73 20 74 68 65 20  array.** is the 
a9c0: 6e 61 6d 65 20 6f 66 20 74 68 65 20 70 72 61 67  name of the prag
a9d0: 6d 61 20 61 6e 64 20 74 68 65 20 74 68 69 72 64  ma and the third
a9e0: 20 65 6c 65 6d 65 6e 74 20 69 73 20 74 68 65 20   element is the 
a9f0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 0a  argument to the.
aa00: 2a 2a 20 70 72 61 67 6d 61 20 6f 72 20 4e 55 4c  ** pragma or NUL
aa10: 4c 20 69 66 20 74 68 65 20 70 72 61 67 6d 61 20  L if the pragma 
aa20: 68 61 73 20 6e 6f 20 61 72 67 75 6d 65 6e 74 2e  has no argument.
aa30: 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 20 66    ^The handler f
aa40: 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45  or an.** [SQLITE
aa50: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66  _FCNTL_PRAGMA] f
aa60: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 63 61 6e 20  ile control can 
aa70: 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d 61 6b 65 20  optionally make 
aa80: 74 68 65 20 66 69 72 73 74 20 65 6c 65 6d 65 6e  the first elemen
aa90: 74 0a 2a 2a 20 6f 66 20 74 68 65 20 63 68 61 72  t.** of the char
aaa0: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e  ** argument poin
aab0: 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6f 62  t to a string ob
aac0: 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
aad0: 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d 0a  ite3_mprintf()].
aae0: 2a 2a 20 6f 72 20 74 68 65 20 65 71 75 69 76 61  ** or the equiva
aaf0: 6c 65 6e 74 20 61 6e 64 20 74 68 61 74 20 73 74  lent and that st
ab00: 72 69 6e 67 20 77 69 6c 6c 20 62 65 63 6f 6d 65  ring will become
ab10: 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20 74   the result of t
ab20: 68 65 20 70 72 61 67 6d 61 20 6f 72 0a 2a 2a 20  he pragma or.** 
ab30: 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
ab40: 65 20 69 66 20 74 68 65 20 70 72 61 67 6d 61 20  e if the pragma 
ab50: 66 61 69 6c 73 2e 20 5e 49 66 20 74 68 65 0a 2a  fails. ^If the.*
ab60: 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  * [SQLITE_FCNTL_
ab70: 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e  PRAGMA] file con
ab80: 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53 51  trol returns [SQ
ab90: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20  LITE_NOTFOUND], 
aba0: 74 68 65 6e 20 6e 6f 72 6d 61 6c 20 0a 2a 2a 20  then normal .** 
abb0: 5b 50 52 41 47 4d 41 5d 20 70 72 6f 63 65 73 73  [PRAGMA] process
abc0: 69 6e 67 20 63 6f 6e 74 69 6e 75 65 73 2e 20 20  ing continues.  
abd0: 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ^If the [SQLITE_
abe0: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a  FCNTL_PRAGMA].**
abf0: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65   file control re
ac00: 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
ac10: 5d 2c 20 74 68 65 6e 20 74 68 65 20 70 61 72 73  ], then the pars
ac20: 65 72 20 61 73 73 75 6d 65 73 20 74 68 61 74 20  er assumes that 
ac30: 74 68 65 0a 2a 2a 20 56 46 53 20 68 61 73 20 68  the.** VFS has h
ac40: 61 6e 64 6c 65 64 20 74 68 65 20 50 52 41 47 4d  andled the PRAGM
ac50: 41 20 69 74 73 65 6c 66 20 61 6e 64 20 74 68 65  A itself and the
ac60: 20 70 61 72 73 65 72 20 67 65 6e 65 72 61 74 65   parser generate
ac70: 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a 20 70 72 65  s a no-op.** pre
ac80: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 2e  pared statement.
ac90: 20 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54    ^If the [SQLIT
aca0: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20  E_FCNTL_PRAGMA] 
acb0: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74  file control ret
acc0: 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 72 65 73 75  urns.** any resu
acd0: 6c 74 20 63 6f 64 65 20 6f 74 68 65 72 20 74 68  lt code other th
ace0: 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  an [SQLITE_OK] o
acf0: 72 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55  r [SQLITE_NOTFOU
ad00: 4e 44 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a  ND], that means.
ad10: 2a 2a 20 74 68 61 74 20 74 68 65 20 56 46 53 20  ** that the VFS 
ad20: 65 6e 63 6f 75 6e 74 65 72 65 64 20 61 6e 20 65  encountered an e
ad30: 72 72 6f 72 20 77 68 69 6c 65 20 68 61 6e 64 6c  rror while handl
ad40: 69 6e 67 20 74 68 65 20 5b 50 52 41 47 4d 41 5d  ing the [PRAGMA]
ad50: 20 61 6e 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70   and the.** comp
ad60: 69 6c 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 50  ilation of the P
ad70: 52 41 47 4d 41 20 66 61 69 6c 73 20 77 69 74 68  RAGMA fails with
ad80: 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 54 68 65   an error.  ^The
ad90: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
ada0: 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63  RAGMA].** file c
adb0: 6f 6e 74 72 6f 6c 20 6f 63 63 75 72 73 20 61 74  ontrol occurs at
adc0: 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f   the beginning o
add0: 66 20 70 72 61 67 6d 61 20 73 74 61 74 65 6d 65  f pragma stateme
ade0: 6e 74 20 61 6e 61 6c 79 73 69 73 20 61 6e 64 20  nt analysis and 
adf0: 73 6f 0a 2a 2a 20 69 74 20 69 73 20 61 62 6c 65  so.** it is able
ae00: 20 74 6f 20 6f 76 65 72 72 69 64 65 20 62 75 69   to override bui
ae10: 6c 74 2d 69 6e 20 5b 50 52 41 47 4d 41 5d 20 73  lt-in [PRAGMA] s
ae20: 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  tatements..**.**
ae30: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
ae40: 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d  NTL_BUSYHANDLER]
ae50: 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ].** ^The [SQLIT
ae60: 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44  E_FCNTL_BUSYHAND
ae70: 4c 45 52 5d 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e  LER].** file-con
ae80: 74 72 6f 6c 20 6d 61 79 20 62 65 20 69 6e 76 6f  trol may be invo
ae90: 6b 65 64 20 62 79 20 53 51 4c 69 74 65 20 6f 6e  ked by SQLite on
aea0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
aeb0: 6c 65 20 68 61 6e 64 6c 65 0a 2a 2a 20 73 68 6f  le handle.** sho
aec0: 72 74 6c 79 20 61 66 74 65 72 20 69 74 20 69 73  rtly after it is
aed0: 20 6f 70 65 6e 65 64 20 69 6e 20 6f 72 64 65 72   opened in order
aee0: 20 74 6f 20 70 72 6f 76 69 64 65 20 61 20 63 75   to provide a cu
aef0: 73 74 6f 6d 20 56 46 53 20 77 69 74 68 20 61 63  stom VFS with ac
af00: 63 65 73 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63  cess.** to the c
af10: 6f 6e 6e 65 63 74 69 6f 6e 73 20 62 75 73 79 2d  onnections busy-
af20: 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b  handler callback
af30: 2e 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69  . The argument i
af40: 73 20 6f 66 20 74 79 70 65 20 28 76 6f 69 64 20  s of type (void 
af50: 2a 2a 29 0a 2a 2a 20 2d 20 61 6e 20 61 72 72 61  **).** - an arra
af60: 79 20 6f 66 20 74 77 6f 20 28 76 6f 69 64 20 2a  y of two (void *
af70: 29 20 76 61 6c 75 65 73 2e 20 54 68 65 20 66 69  ) values. The fi
af80: 72 73 74 20 28 76 6f 69 64 20 2a 29 20 61 63 74  rst (void *) act
af90: 75 61 6c 6c 79 20 70 6f 69 6e 74 73 0a 2a 2a 20  ually points.** 
afa0: 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66  to a function of
afb0: 20 74 79 70 65 20 28 69 6e 74 20 28 2a 29 28 76   type (int (*)(v
afc0: 6f 69 64 20 2a 29 29 2e 20 49 6e 20 6f 72 64 65  oid *)). In orde
afd0: 72 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 20  r to invoke the 
afe0: 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 62  connections.** b
aff0: 75 73 79 2d 68 61 6e 64 6c 65 72 2c 20 74 68 69  usy-handler, thi
b000: 73 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c  s function shoul
b010: 64 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74  d be invoked wit
b020: 68 20 74 68 65 20 73 65 63 6f 6e 64 20 28 76 6f  h the second (vo
b030: 69 64 20 2a 29 20 69 6e 0a 2a 2a 20 74 68 65 20  id *) in.** the 
b040: 61 72 72 61 79 20 61 73 20 74 68 65 20 6f 6e 6c  array as the onl
b050: 79 20 61 72 67 75 6d 65 6e 74 2e 20 49 66 20 69  y argument. If i
b060: 74 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65  t returns non-ze
b070: 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 6f 70 65  ro, then the ope
b080: 72 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64  ration.** should
b090: 20 62 65 20 72 65 74 72 69 65 64 2e 20 49 66 20   be retried. If 
b0a0: 69 74 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c  it returns zero,
b0b0: 20 74 68 65 20 63 75 73 74 6f 6d 20 56 46 53 20   the custom VFS 
b0c0: 73 68 6f 75 6c 64 20 61 62 61 6e 64 6f 6e 20 74  should abandon t
b0d0: 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 6f 70  he.** current op
b0e0: 65 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c  eration..**.** <
b0f0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
b100: 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 5d  L_TEMPFILENAME]]
b110: 0a 2a 2a 20 5e 41 70 70 6c 69 63 61 74 69 6f 6e  .** ^Application
b120: 20 63 61 6e 20 69 6e 76 6f 6b 65 20 74 68 65 20   can invoke the 
b130: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45  [SQLITE_FCNTL_TE
b140: 4d 50 46 49 4c 45 4e 41 4d 45 5d 20 66 69 6c 65  MPFILENAME] file
b150: 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 74 6f 20 68  -control.** to h
b160: 61 76 65 20 53 51 4c 69 74 65 20 67 65 6e 65 72  ave SQLite gener
b170: 61 74 65 20 61 0a 2a 2a 20 74 65 6d 70 6f 72 61  ate a.** tempora
b180: 72 79 20 66 69 6c 65 6e 61 6d 65 20 75 73 69 6e  ry filename usin
b190: 67 20 74 68 65 20 73 61 6d 65 20 61 6c 67 6f 72  g the same algor
b1a0: 69 74 68 6d 20 74 68 61 74 20 69 73 20 66 6f 6c  ithm that is fol
b1b0: 6c 6f 77 65 64 20 74 6f 20 67 65 6e 65 72 61 74  lowed to generat
b1c0: 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66  e.** temporary f
b1d0: 69 6c 65 6e 61 6d 65 73 20 66 6f 72 20 54 45 4d  ilenames for TEM
b1e0: 50 20 74 61 62 6c 65 73 20 61 6e 64 20 6f 74 68  P tables and oth
b1f0: 65 72 20 69 6e 74 65 72 6e 61 6c 20 75 73 65 73  er internal uses
b200: 2e 20 20 54 68 65 0a 2a 2a 20 61 72 67 75 6d 65  .  The.** argume
b210: 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 61 20 63  nt should be a c
b220: 68 61 72 2a 2a 20 77 68 69 63 68 20 77 69 6c 6c  har** which will
b230: 20 62 65 20 66 69 6c 6c 65 64 20 77 69 74 68 20   be filled with 
b240: 74 68 65 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20  the filename.** 
b250: 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d  written into mem
b260: 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
b270: 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
b280: 63 28 29 5d 2e 20 20 54 68 65 20 63 61 6c 6c 65  c()].  The calle
b290: 72 20 73 68 6f 75 6c 64 0a 2a 2a 20 69 6e 76 6f  r should.** invo
b2a0: 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ke [sqlite3_free
b2b0: 28 29 5d 20 6f 6e 20 74 68 65 20 72 65 73 75 6c  ()] on the resul
b2c0: 74 20 74 6f 20 61 76 6f 69 64 20 61 20 6d 65 6d  t to avoid a mem
b2d0: 6f 72 79 20 6c 65 61 6b 2e 0a 2a 2a 0a 2a 2a 20  ory leak..**.** 
b2e0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
b2f0: 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a  TL_MMAP_SIZE]].*
b300: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
b310: 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66  NTL_MMAP_SIZE] f
b320: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75  ile control is u
b330: 73 65 64 20 74 6f 20 71 75 65 72 79 20 6f 72 20  sed to query or 
b340: 73 65 74 20 74 68 65 0a 2a 2a 20 6d 61 78 69 6d  set the.** maxim
b350: 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  um number of byt
b360: 65 73 20 74 68 61 74 20 77 69 6c 6c 20 62 65 20  es that will be 
b370: 75 73 65 64 20 66 6f 72 20 6d 65 6d 6f 72 79 2d  used for memory-
b380: 6d 61 70 70 65 64 20 49 2f 4f 2e 0a 2a 2a 20 54  mapped I/O..** T
b390: 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  he argument is a
b3a0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 61   pointer to a va
b3b0: 6c 75 65 20 6f 66 20 74 79 70 65 20 73 71 6c 69  lue of type sqli
b3c0: 74 65 33 5f 69 6e 74 36 34 20 74 68 61 74 0a 2a  te3_int64 that.*
b3d0: 2a 20 69 73 20 61 6e 20 61 64 76 69 73 6f 72 79  * is an advisory
b3e0: 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
b3f0: 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  of bytes in the 
b400: 66 69 6c 65 20 74 6f 20 6d 65 6d 6f 72 79 20 6d  file to memory m
b410: 61 70 2e 20 20 54 68 65 0a 2a 2a 20 70 6f 69 6e  ap.  The.** poin
b420: 74 65 72 20 69 73 20 6f 76 65 72 77 72 69 74 74  ter is overwritt
b430: 65 6e 20 77 69 74 68 20 74 68 65 20 6f 6c 64 20  en with the old 
b440: 76 61 6c 75 65 2e 20 20 54 68 65 20 6c 69 6d 69  value.  The limi
b450: 74 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64  t is not changed
b460: 20 69 66 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65   if.** the value
b470: 20 6f 72 69 67 69 6e 61 6c 6c 79 20 70 6f 69 6e   originally poin
b480: 74 65 64 20 74 6f 20 69 73 20 6e 65 67 61 74 69  ted to is negati
b490: 76 65 2c 20 61 6e 64 20 73 6f 20 74 68 65 20 63  ve, and so the c
b4a0: 75 72 72 65 6e 74 20 6c 69 6d 69 74 20 0a 2a 2a  urrent limit .**
b4b0: 20 63 61 6e 20 62 65 20 71 75 65 72 69 65 64 20   can be queried 
b4c0: 62 79 20 70 61 73 73 69 6e 67 20 69 6e 20 61 20  by passing in a 
b4d0: 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e 65 67  pointer to a neg
b4e0: 61 74 69 76 65 20 6e 75 6d 62 65 72 2e 20 20 54  ative number.  T
b4f0: 68 69 73 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74  his.** file-cont
b500: 72 6f 6c 20 69 73 20 75 73 65 64 20 69 6e 74 65  rol is used inte
b510: 72 6e 61 6c 6c 79 20 74 6f 20 69 6d 70 6c 65 6d  rnally to implem
b520: 65 6e 74 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70  ent [PRAGMA mmap
b530: 5f 73 69 7a 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  _size]..**.** <l
b540: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
b550: 5f 54 52 41 43 45 5d 5d 0a 2a 2a 20 54 68 65 20  _TRACE]].** The 
b560: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52  [SQLITE_FCNTL_TR
b570: 41 43 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f  ACE] file contro
b580: 6c 20 70 72 6f 76 69 64 65 73 20 61 64 76 69 73  l provides advis
b590: 6f 72 79 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a  ory information.
b5a0: 2a 2a 20 74 6f 20 74 68 65 20 56 46 53 20 61 62  ** to the VFS ab
b5b0: 6f 75 74 20 77 68 61 74 20 74 68 65 20 68 69 67  out what the hig
b5c0: 68 65 72 20 6c 61 79 65 72 73 20 6f 66 20 74 68  her layers of th
b5d0: 65 20 53 51 4c 69 74 65 20 73 74 61 63 6b 20 61  e SQLite stack a
b5e0: 72 65 20 64 6f 69 6e 67 2e 0a 2a 2a 20 54 68 69  re doing..** Thi
b5f0: 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69  s file control i
b600: 73 20 75 73 65 64 20 62 79 20 73 6f 6d 65 20 56  s used by some V
b610: 46 53 20 61 63 74 69 76 69 74 79 20 74 72 61 63  FS activity trac
b620: 69 6e 67 20 5b 73 68 69 6d 73 5d 2e 0a 2a 2a 20  ing [shims]..** 
b630: 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  The argument is 
b640: 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
b650: 64 20 73 74 72 69 6e 67 2e 20 20 48 69 67 68 65  d string.  Highe
b660: 72 20 6c 61 79 65 72 73 20 69 6e 20 74 68 65 0a  r layers in the.
b670: 2a 2a 20 53 51 4c 69 74 65 20 73 74 61 63 6b 20  ** SQLite stack 
b680: 6d 61 79 20 67 65 6e 65 72 61 74 65 20 69 6e 73  may generate ins
b690: 74 61 6e 63 65 73 20 6f 66 20 74 68 69 73 20 66  tances of this f
b6a0: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 66 0a 2a  ile control if.*
b6b0: 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 55 53  * the [SQLITE_US
b6c0: 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 20 63  E_FCNTL_TRACE] c
b6d0: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
b6e0: 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a  on is enabled..*
b6f0: 2a 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64  *.** </ul>.*/.#d
b700: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
b710: 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20 20  TL_LOCKSTATE    
b720: 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65             1.#de
b730: 66 69 6e 65 20 53 51 4c 49 54 45 5f 47 45 54 5f  fine SQLITE_GET_
b740: 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20  LOCKPROXYFILE   
b750: 20 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66            2.#def
b760: 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c  ine SQLITE_SET_L
b770: 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20  OCKPROXYFILE    
b780: 20 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69           3.#defi
b790: 6e 65 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f 45  ne SQLITE_LAST_E
b7a0: 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20  RRNO            
b7b0: 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e          4.#defin
b7c0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53  e SQLITE_FCNTL_S
b7d0: 49 5a 45 5f 48 49 4e 54 20 20 20 20 20 20 20 20  IZE_HINT        
b7e0: 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65         5.#define
b7f0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48   SQLITE_FCNTL_CH
b800: 55 4e 4b 5f 53 49 5a 45 20 20 20 20 20 20 20 20  UNK_SIZE        
b810: 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20        6.#define 
b820: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c  SQLITE_FCNTL_FIL
b830: 45 5f 50 4f 49 4e 54 45 52 20 20 20 20 20 20 20  E_POINTER       
b840: 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53       7.#define S
b850: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43  QLITE_FCNTL_SYNC
b860: 5f 4f 4d 49 54 54 45 44 20 20 20 20 20 20 20 20  _OMITTED        
b870: 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51      8.#define SQ
b880: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32  LITE_FCNTL_WIN32
b890: 5f 41 56 5f 52 45 54 52 59 20 20 20 20 20 20 20  _AV_RETRY       
b8a0: 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c     9.#define SQL
b8b0: 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53  ITE_FCNTL_PERSIS
b8c0: 54 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20 20  T_WAL           
b8d0: 20 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   10.#define SQLI
b8e0: 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49  TE_FCNTL_OVERWRI
b8f0: 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TE              
b900: 31 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  11.#define SQLIT
b910: 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 20  E_FCNTL_VFSNAME 
b920: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
b930: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
b940: 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45  _FCNTL_POWERSAFE
b950: 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 31 33  _OVERWRITE    13
b960: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
b970: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 20 20 20 20  FCNTL_PRAGMA    
b980: 20 20 20 20 20 20 20 20 20 20 20 20 20 31 34 0a               14.
b990: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
b9a0: 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52  CNTL_BUSYHANDLER
b9b0: 20 20 20 20 20 20 20 20 20 20 20 20 31 35 0a 23              15.#
b9c0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
b9d0: 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45  NTL_TEMPFILENAME
b9e0: 20 20 20 20 20 20 20 20 20 20 20 31 36 0a 23 64             16.#d
b9f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
ba00: 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20  TL_MMAP_SIZE    
ba10: 20 20 20 20 20 20 20 20 20 20 31 38 0a 23 64 65            18.#de
ba20: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
ba30: 4c 5f 54 52 41 43 45 20 20 20 20 20 20 20 20 20  L_TRACE         
ba40: 20 20 20 20 20 20 20 20 20 31 39 0a 0a 2f 2a 0a           19../*.
ba50: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74  ** CAPI3REF: Mut
ba60: 65 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20  ex Handle.**.** 
ba70: 54 68 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65  The mutex module
ba80: 20 77 69 74 68 69 6e 20 53 51 4c 69 74 65 20 64   within SQLite d
ba90: 65 66 69 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f  efines [sqlite3_
baa0: 6d 75 74 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a  mutex] to be an.
bab0: 2a 2a 20 61 62 73 74 72 61 63 74 20 74 79 70 65  ** abstract type
bac0: 20 66 6f 72 20 61 20 6d 75 74 65 78 20 6f 62 6a   for a mutex obj
bad0: 65 63 74 2e 20 20 54 68 65 20 53 51 4c 69 74 65  ect.  The SQLite
bae0: 20 63 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b   core never look
baf0: 73 0a 2a 2a 20 61 74 20 74 68 65 20 69 6e 74 65  s.** at the inte
bb00: 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74  rnal representat
bb10: 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74  ion of an [sqlit
bb20: 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f  e3_mutex].  It o
bb30: 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74  nly.** deals wit
bb40: 68 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68  h pointers to th
bb50: 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e [sqlite3_mutex
bb60: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20  ] object..**.** 
bb70: 4d 75 74 65 78 65 73 20 61 72 65 20 63 72 65 61  Mutexes are crea
bb80: 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ted using [sqlit
bb90: 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29  e3_mutex_alloc()
bba0: 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  ]..*/.typedef st
bbb0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74  ruct sqlite3_mut
bbc0: 65 78 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ex sqlite3_mutex
bbd0: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
bbe0: 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20  F: OS Interface 
bbf0: 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20  Object.**.** An 
bc00: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
bc10: 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65  sqlite3_vfs obje
bc20: 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69  ct defines the i
bc30: 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e  nterface between
bc40: 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74 65 20 63  .** the SQLite c
bc50: 6f 72 65 20 61 6e 64 20 74 68 65 20 75 6e 64 65  ore and the unde
bc60: 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67  rlying operating
bc70: 20 73 79 73 74 65 6d 2e 20 20 54 68 65 20 22 76   system.  The "v
bc80: 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61  fs".** in the na
bc90: 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a 65 63 74  me of the object
bca0: 20 73 74 61 6e 64 73 20 66 6f 72 20 22 76 69 72   stands for "vir
bcb0: 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d  tual file system
bcc0: 22 2e 20 20 53 65 65 0a 2a 2a 20 74 68 65 20 5b  ".  See.** the [
bcd0: 56 46 53 20 7c 20 56 46 53 20 64 6f 63 75 6d 65  VFS | VFS docume
bce0: 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 66 75 72  ntation] for fur
bcf0: 74 68 65 72 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  ther information
bd00: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75  ..**.** The valu
bd10: 65 20 6f 66 20 74 68 65 20 69 56 65 72 73 69 6f  e of the iVersio
bd20: 6e 20 66 69 65 6c 64 20 69 73 20 69 6e 69 74 69  n field is initi
bd30: 61 6c 6c 79 20 31 20 62 75 74 20 6d 61 79 20 62  ally 1 but may b
bd40: 65 20 6c 61 72 67 65 72 20 69 6e 0a 2a 2a 20 66  e larger in.** f
bd50: 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
bd60: 66 20 53 51 4c 69 74 65 2e 20 20 41 64 64 69 74  f SQLite.  Addit
bd70: 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61 79  ional fields may
bd80: 20 62 65 20 61 70 70 65 6e 64 65 64 20 74 6f 20   be appended to 
bd90: 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77  this.** object w
bda0: 68 65 6e 20 74 68 65 20 69 56 65 72 73 69 6f 6e  hen the iVersion
bdb0: 20 76 61 6c 75 65 20 69 73 20 69 6e 63 72 65 61   value is increa
bdc0: 73 65 64 2e 20 20 4e 6f 74 65 20 74 68 61 74 20  sed.  Note that 
bdd0: 74 68 65 20 73 74 72 75 63 74 75 72 65 0a 2a 2a  the structure.**
bde0: 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
bdf0: 76 66 73 20 6f 62 6a 65 63 74 20 63 68 61 6e 67  vfs object chang
be00: 65 73 20 69 6e 20 74 68 65 20 74 72 61 6e 73 61  es in the transa
be10: 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a  ction between.**
be20: 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
be30: 33 2e 35 2e 39 20 61 6e 64 20 33 2e 36 2e 30 20  3.5.9 and 3.6.0 
be40: 61 6e 64 20 79 65 74 20 74 68 65 20 69 56 65 72  and yet the iVer
be50: 73 69 6f 6e 20 66 69 65 6c 64 20 77 61 73 20 6e  sion field was n
be60: 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 2e 0a  ot.** modified..
be70: 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69  **.** The szOsFi
be80: 6c 65 20 66 69 65 6c 64 20 69 73 20 74 68 65 20  le field is the 
be90: 73 69 7a 65 20 6f 66 20 74 68 65 20 73 75 62 63  size of the subc
bea0: 6c 61 73 73 65 64 20 5b 73 71 6c 69 74 65 33 5f  lassed [sqlite3_
beb0: 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75  file].** structu
bec0: 72 65 20 75 73 65 64 20 62 79 20 74 68 69 73 20  re used by this 
bed0: 56 46 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65  VFS.  mxPathname
bee0: 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20   is the maximum 
bef0: 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70  length of.** a p
bf00: 61 74 68 6e 61 6d 65 20 69 6e 20 74 68 69 73 20  athname in this 
bf10: 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73  VFS..**.** Regis
bf20: 74 65 72 65 64 20 73 71 6c 69 74 65 33 5f 76 66  tered sqlite3_vf
bf30: 73 20 6f 62 6a 65 63 74 73 20 61 72 65 20 6b 65  s objects are ke
bf40: 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c  pt on a linked l
bf50: 69 73 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a  ist formed by.**
bf60: 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74   the pNext point
bf70: 65 72 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65  er.  The [sqlite
bf80: 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28 29  3_vfs_register()
bf90: 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ].** and [sqlite
bfa0: 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72  3_vfs_unregister
bfb0: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 6d  ()] interfaces m
bfc0: 61 6e 61 67 65 20 74 68 69 73 20 6c 69 73 74 0a  anage this list.
bfd0: 2a 2a 20 69 6e 20 61 20 74 68 72 65 61 64 2d 73  ** in a thread-s
bfe0: 61 66 65 20 77 61 79 2e 20 20 54 68 65 20 5b 73  afe way.  The [s
bff0: 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28  qlite3_vfs_find(
c000: 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  )] interface.** 
c010: 73 65 61 72 63 68 65 73 20 74 68 65 20 6c 69 73  searches the lis
c020: 74 2e 20 20 4e 65 69 74 68 65 72 20 74 68 65 20  t.  Neither the 
c030: 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65  application code
c040: 20 6e 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a 20   nor the VFS.** 
c050: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73  implementation s
c060: 68 6f 75 6c 64 20 75 73 65 20 74 68 65 20 70 4e  hould use the pN
c070: 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ext pointer..**.
c080: 2a 2a 20 54 68 65 20 70 4e 65 78 74 20 66 69 65  ** The pNext fie
c090: 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c 79 20 66  ld is the only f
c0a0: 69 65 6c 64 20 69 6e 20 74 68 65 20 73 71 6c 69  ield in the sqli
c0b0: 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63  te3_vfs.** struc
c0c0: 74 75 72 65 20 74 68 61 74 20 53 51 4c 69 74 65  ture that SQLite
c0d0: 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66   will ever modif
c0e0: 79 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  y.  SQLite will 
c0f0: 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f  only access.** o
c100: 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 66 69  r modify this fi
c110: 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e  eld while holdin
c120: 67 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 73  g a particular s
c130: 74 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20  tatic mutex..** 
c140: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
c150: 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64  should never mod
c160: 69 66 79 20 61 6e 79 74 68 69 6e 67 20 77 69 74  ify anything wit
c170: 68 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hin the sqlite3_
c180: 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e  vfs.** object on
c190: 63 65 20 74 68 65 20 6f 62 6a 65 63 74 20 68 61  ce the object ha
c1a0: 73 20 62 65 65 6e 20 72 65 67 69 73 74 65 72 65  s been registere
c1b0: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61  d..**.** The zNa
c1c0: 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64 73 20 74  me field holds t
c1d0: 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 56  he name of the V
c1e0: 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20  FS module.  The 
c1f0: 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20  name must.** be 
c200: 75 6e 69 71 75 65 20 61 63 72 6f 73 73 20 61 6c  unique across al
c210: 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a  l VFS modules..*
c220: 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76  *.** [[sqlite3_v
c230: 66 73 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53  fs.xOpen]].** ^S
c240: 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65 73  QLite guarantees
c250: 20 74 68 61 74 20 74 68 65 20 7a 46 69 6c 65 6e   that the zFilen
c260: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ame parameter to
c270: 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74   xOpen.** is eit
c280: 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  her a NULL point
c290: 65 72 20 6f 72 20 73 74 72 69 6e 67 20 6f 62 74  er or string obt
c2a0: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46  ained.** from xF
c2b0: 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29 20 77 69  ullPathname() wi
c2c0: 74 68 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 73  th an optional s
c2d0: 75 66 66 69 78 20 61 64 64 65 64 2e 0a 2a 2a 20  uffix added..** 
c2e0: 5e 49 66 20 61 20 73 75 66 66 69 78 20 69 73 20  ^If a suffix is 
c2f0: 61 64 64 65 64 20 74 6f 20 74 68 65 20 7a 46 69  added to the zFi
c300: 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72  lename parameter
c310: 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e  , it will.** con
c320: 73 69 73 74 20 6f 66 20 61 20 73 69 6e 67 6c 65  sist of a single
c330: 20 22 2d 22 20 63 68 61 72 61 63 74 65 72 20 66   "-" character f
c340: 6f 6c 6c 6f 77 65 64 20 62 79 20 6e 6f 20 6d 6f  ollowed by no mo
c350: 72 65 20 74 68 61 6e 0a 2a 2a 20 31 31 20 61 6c  re than.** 11 al
c360: 70 68 61 6e 75 6d 65 72 69 63 20 61 6e 64 2f 6f  phanumeric and/o
c370: 72 20 22 2d 22 20 63 68 61 72 61 63 74 65 72 73  r "-" characters
c380: 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 66 75 72  ..** ^SQLite fur
c390: 74 68 65 72 20 67 75 61 72 61 6e 74 65 65 73 20  ther guarantees 
c3a0: 74 68 61 74 0a 2a 2a 20 74 68 65 20 73 74 72 69  that.** the stri
c3b0: 6e 67 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64  ng will be valid
c3c0: 20 61 6e 64 20 75 6e 63 68 61 6e 67 65 64 20 75   and unchanged u
c3d0: 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29 20 69 73  ntil xClose() is
c3e0: 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65 63 61  .** called. Beca
c3f0: 75 73 65 20 6f 66 20 74 68 65 20 70 72 65 76 69  use of the previ
c400: 6f 75 73 20 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a  ous sentence,.**
c410: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   the [sqlite3_fi
c420: 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c 79 20 73  le] can safely s
c430: 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 72 20 74  tore a pointer t
c440: 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d  o the.** filenam
c450: 65 20 69 66 20 69 74 20 6e 65 65 64 73 20 74 6f  e if it needs to
c460: 20 72 65 6d 65 6d 62 65 72 20 74 68 65 20 66 69   remember the fi
c470: 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20  lename for some 
c480: 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68  reason..** If th
c490: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  e zFilename para
c4a0: 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 20 69  meter to xOpen i
c4b0: 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
c4c0: 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d   then xOpen.** m
c4d0: 75 73 74 20 69 6e 76 65 6e 74 20 69 74 73 20 6f  ust invent its o
c4e0: 77 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e 61 6d  wn temporary nam
c4f0: 65 20 66 6f 72 20 74 68 65 20 66 69 6c 65 2e 20  e for the file. 
c500: 20 5e 57 68 65 6e 65 76 65 72 20 74 68 65 20 0a   ^Whenever the .
c510: 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70 61 72  ** xFilename par
c520: 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20 69  ameter is NULL i
c530: 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74  t will also be t
c540: 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65  he case that the
c550: 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72 61 6d 65  .** flags parame
c560: 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65  ter will include
c570: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45   [SQLITE_OPEN_DE
c580: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a  LETEONCLOSE]..**
c590: 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72  .** The flags ar
c5a0: 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28  gument to xOpen(
c5b0: 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62  ) includes all b
c5c0: 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68  its set in.** th
c5d0: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
c5e0: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   to [sqlite3_ope
c5f0: 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69 66 20  n_v2()].  Or if 
c600: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
c610: 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
c620: 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73 65  open16()] is use
c630: 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 69 6e  d, then flags in
c640: 63 6c 75 64 65 73 20 61 74 20 6c 65 61 73 74 0a  cludes at least.
c650: 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
c660: 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51  READWRITE] | [SQ
c670: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
c680: 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28  ]. .** If xOpen(
c690: 29 20 6f 70 65 6e 73 20 61 20 66 69 6c 65 20 72  ) opens a file r
c6a0: 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74  ead-only then it
c6b0: 20 73 65 74 73 20 2a 70 4f 75 74 46 6c 61 67 73   sets *pOutFlags
c6c0: 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b   to.** include [
c6d0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
c6e0: 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62 69  ONLY].  Other bi
c6f0: 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73  ts in *pOutFlags
c700: 20 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a   may be set..**.
c710: 2a 2a 20 5e 28 53 51 4c 69 74 65 20 77 69 6c 6c  ** ^(SQLite will
c720: 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66   also add one of
c730: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66   the following f
c740: 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65  lags to the xOpe
c750: 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70  n().** call, dep
c760: 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62  ending on the ob
c770: 6a 65 63 74 20 62 65 69 6e 67 20 6f 70 65 6e 65  ject being opene
c780: 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  d:.**.** <ul>.**
c790: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
c7a0: 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20  PEN_MAIN_DB].** 
c7b0: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
c7c0: 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d  EN_MAIN_JOURNAL]
c7d0: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
c7e0: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a  E_OPEN_TEMP_DB].
c7f0: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
c800: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e  _OPEN_TEMP_JOURN
c810: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  AL].** <li>  [SQ
c820: 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49  LITE_OPEN_TRANSI
c830: 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20  ENT_DB].** <li> 
c840: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55   [SQLITE_OPEN_SU
c850: 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69  BJOURNAL].** <li
c860: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
c870: 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a  MASTER_JOURNAL].
c880: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
c890: 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f  _OPEN_WAL].** </
c8a0: 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ul>)^.**.** The 
c8b0: 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65  file I/O impleme
c8c0: 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75 73 65 20  ntation can use 
c8d0: 74 68 65 20 6f 62 6a 65 63 74 20 74 79 70 65 20  the object type 
c8e0: 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e  flags to.** chan
c8f0: 67 65 20 74 68 65 20 77 61 79 20 69 74 20 64 65  ge the way it de
c900: 61 6c 73 20 77 69 74 68 20 66 69 6c 65 73 2e 20  als with files. 
c910: 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e   For example, an
c920: 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20   application.** 
c930: 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 63 61  that does not ca
c940: 72 65 20 61 62 6f 75 74 20 63 72 61 73 68 20 72  re about crash r
c950: 65 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62  ecovery or rollb
c960: 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a  ack might make.*
c970: 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 20 61 20  * the open of a 
c980: 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e  journal file a n
c990: 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 20 74 6f  o-op.  Writes to
c9a0: 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f   this journal wo
c9b0: 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e  uld.** also be n
c9c0: 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79 20 61  o-ops, and any a
c9d0: 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64 20 74  ttempt to read t
c9e0: 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64  he journal would
c9f0: 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54   return.** SQLIT
ca00: 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74 68 65  E_IOERR.  Or the
ca10: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
ca20: 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 7a 65 20  might recognize 
ca30: 74 68 61 74 20 61 20 64 61 74 61 62 61 73 65 0a  that a database.
ca40: 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20  ** file will be 
ca50: 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e  doing page-align
ca60: 65 64 20 73 65 63 74 6f 72 20 72 65 61 64 73 20  ed sector reads 
ca70: 61 6e 64 20 77 72 69 74 65 73 20 69 6e 20 61 20  and writes in a 
ca80: 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20  random.** order 
ca90: 61 6e 64 20 73 65 74 20 75 70 20 69 74 73 20 49  and set up its I
caa0: 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 61 63 63  /O subsystem acc
cab0: 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ordingly..**.** 
cac0: 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73  SQLite might als
cad0: 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65  o add one of the
cae0: 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73   following flags
caf0: 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65   to the xOpen me
cb00: 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  thod:.**.** <ul>
cb10: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
cb20: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
cb30: 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  OSE].** <li> [SQ
cb40: 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53  LITE_OPEN_EXCLUS
cb50: 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  IVE].** </ul>.**
cb60: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
cb70: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
cb80: 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74  SE] flag means t
cb90: 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62  he file should b
cba0: 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77 68 65  e.** deleted whe
cbb0: 6e 20 69 74 20 69 73 20 63 6c 6f 73 65 64 2e 20  n it is closed. 
cbc0: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50   ^The [SQLITE_OP
cbd0: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
cbe0: 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65 74  ].** will be set
cbf0: 20 66 6f 72 20 54 45 4d 50 20 64 61 74 61 62 61   for TEMP databa
cc00: 73 65 73 20 61 6e 64 20 74 68 65 69 72 20 6a 6f  ses and their jo
cc10: 75 72 6e 61 6c 73 2c 20 74 72 61 6e 73 69 65 6e  urnals, transien
cc20: 74 0a 2a 2a 20 64 61 74 61 62 61 73 65 73 2c 20  t.** databases, 
cc30: 61 6e 64 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e  and subjournals.
cc40: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  .**.** ^The [SQL
cc50: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49  ITE_OPEN_EXCLUSI
cc60: 56 45 5d 20 66 6c 61 67 20 69 73 20 61 6c 77 61  VE] flag is alwa
cc70: 79 73 20 75 73 65 64 20 69 6e 20 63 6f 6e 6a 75  ys used in conju
cc80: 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74  nction.** with t
cc90: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
cca0: 43 52 45 41 54 45 5d 20 66 6c 61 67 2c 20 77 68  CREATE] flag, wh
ccb0: 69 63 68 20 61 72 65 20 62 6f 74 68 20 64 69 72  ich are both dir
ccc0: 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f  ectly.** analogo
ccd0: 75 73 20 74 6f 20 74 68 65 20 4f 5f 45 58 43 4c  us to the O_EXCL
cce0: 20 61 6e 64 20 4f 5f 43 52 45 41 54 20 66 6c 61   and O_CREAT fla
ccf0: 67 73 20 6f 66 20 74 68 65 20 50 4f 53 49 58 20  gs of the POSIX 
cd00: 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 49 2e 20 20  open().** API.  
cd10: 54 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  The SQLITE_OPEN_
cd20: 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67 2c 20  EXCLUSIVE flag, 
cd30: 77 68 65 6e 20 70 61 69 72 65 64 20 77 69 74 68  when paired with
cd40: 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f   the .** SQLITE_
cd50: 4f 50 45 4e 5f 43 52 45 41 54 45 2c 20 69 73 20  OPEN_CREATE, is 
cd60: 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65  used to indicate
cd70: 20 74 68 61 74 20 66 69 6c 65 20 73 68 6f 75 6c   that file shoul
cd80: 64 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20 63  d always.** be c
cd90: 72 65 61 74 65 64 2c 20 61 6e 64 20 74 68 61 74  reated, and that
cda0: 20 69 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20   it is an error 
cdb0: 69 66 20 69 74 20 61 6c 72 65 61 64 79 20 65 78  if it already ex
cdc0: 69 73 74 73 2e 0a 2a 2a 20 49 74 20 69 73 20 3c  ists..** It is <
cdd0: 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65 64 20 74  i>not</i> used t
cde0: 6f 20 69 6e 64 69 63 61 74 65 20 74 68 65 20 66  o indicate the f
cdf0: 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 6f 70  ile should be op
ce00: 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 20 65 78 63  ened .** for exc
ce10: 6c 75 73 69 76 65 20 61 63 63 65 73 73 2e 0a 2a  lusive access..*
ce20: 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61 73 74 20 73  *.** ^At least s
ce30: 7a 4f 73 46 69 6c 65 20 62 79 74 65 73 20 6f 66  zOsFile bytes of
ce40: 20 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f   memory are allo
ce50: 63 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 0a  cated by SQLite.
ce60: 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 20  ** to hold the  
ce70: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73  [sqlite3_file] s
ce80: 74 72 75 63 74 75 72 65 20 70 61 73 73 65 64 20  tructure passed 
ce90: 61 73 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20  as the third.** 
cea0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65  argument to xOpe
ceb0: 6e 2e 20 20 54 68 65 20 78 4f 70 65 6e 20 6d 65  n.  The xOpen me
cec0: 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68 61  thod does not ha
ced0: 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74  ve to.** allocat
cee0: 65 20 74 68 65 20 73 74 72 75 63 74 75 72 65 3b  e the structure;
cef0: 20 69 74 20 73 68 6f 75 6c 64 20 6a 75 73 74 20   it should just 
cf00: 66 69 6c 6c 20 69 74 20 69 6e 2e 20 20 4e 6f 74  fill it in.  Not
cf10: 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 78 4f  e that.** the xO
cf20: 70 65 6e 20 6d 65 74 68 6f 64 20 6d 75 73 74 20  pen method must 
cf30: 73 65 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f  set the sqlite3_
cf40: 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 74 6f  file.pMethods to
cf50: 20 65 69 74 68 65 72 0a 2a 2a 20 61 20 76 61 6c   either.** a val
cf60: 69 64 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  id [sqlite3_io_m
cf70: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 6f  ethods] object o
cf80: 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70 65  r to NULL.  xOpe
cf90: 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a 20 74 68 69  n must do.** thi
cfa0: 73 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f 70  s even if the op
cfb0: 65 6e 20 66 61 69 6c 73 2e 20 20 53 51 4c 69 74  en fails.  SQLit
cfc0: 65 20 65 78 70 65 63 74 73 20 74 68 61 74 20 74  e expects that t
cfd0: 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e  he sqlite3_file.
cfe0: 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d  pMethods.** elem
cff0: 65 6e 74 20 77 69 6c 6c 20 62 65 20 76 61 6c 69  ent will be vali
d000: 64 20 61 66 74 65 72 20 78 4f 70 65 6e 20 72 65  d after xOpen re
d010: 74 75 72 6e 73 20 72 65 67 61 72 64 6c 65 73 73  turns regardless
d020: 20 6f 66 20 74 68 65 20 73 75 63 63 65 73 73 0a   of the success.
d030: 2a 2a 20 6f 72 20 66 61 69 6c 75 72 65 20 6f 66  ** or failure of
d040: 20 74 68 65 20 78 4f 70 65 6e 20 63 61 6c 6c 2e   the xOpen call.
d050: 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33  .**.** [[sqlite3
d060: 5f 76 66 73 2e 78 41 63 63 65 73 73 5d 5d 0a 2a  _vfs.xAccess]].*
d070: 2a 20 5e 54 68 65 20 66 6c 61 67 73 20 61 72 67  * ^The flags arg
d080: 75 6d 65 6e 74 20 74 6f 20 78 41 63 63 65 73 73  ument to xAccess
d090: 28 29 20 6d 61 79 20 62 65 20 5b 53 51 4c 49 54  () may be [SQLIT
d0a0: 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 5d  E_ACCESS_EXISTS]
d0b0: 0a 2a 2a 20 74 6f 20 74 65 73 74 20 66 6f 72 20  .** to test for 
d0c0: 74 68 65 20 65 78 69 73 74 65 6e 63 65 20 6f 66  the existence of
d0d0: 20 61 20 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c   a file, or [SQL
d0e0: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
d0f0: 52 49 54 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74  RITE] to.** test
d100: 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20   whether a file 
d110: 69 73 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20  is readable and 
d120: 77 72 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51  writable, or [SQ
d130: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
d140: 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 77 68 65  ].** to test whe
d150: 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 61  ther a file is a
d160: 74 20 6c 65 61 73 74 20 72 65 61 64 61 62 6c 65  t least readable
d170: 2e 20 20 20 54 68 65 20 66 69 6c 65 20 63 61 6e  .   The file can
d180: 20 62 65 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f   be a.** directo
d190: 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74  ry..**.** ^SQLit
d1a0: 65 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c  e will always al
d1b0: 6c 6f 63 61 74 65 20 61 74 20 6c 65 61 73 74 20  locate at least 
d1c0: 6d 78 50 61 74 68 6e 61 6d 65 2b 31 20 62 79 74  mxPathname+1 byt
d1d0: 65 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75  es for the.** ou
d1e0: 74 70 75 74 20 62 75 66 66 65 72 20 78 46 75 6c  tput buffer xFul
d1f0: 6c 50 61 74 68 6e 61 6d 65 2e 20 20 54 68 65 20  lPathname.  The 
d200: 65 78 61 63 74 20 73 69 7a 65 20 6f 66 20 74 68  exact size of th
d210: 65 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a  e output buffer.
d220: 2a 2a 20 69 73 20 61 6c 73 6f 20 70 61 73 73 65  ** is also passe
d230: 64 20 61 73 20 61 20 70 61 72 61 6d 65 74 65 72  d as a parameter
d240: 20 74 6f 20 62 6f 74 68 20 20 6d 65 74 68 6f 64   to both  method
d250: 73 2e 20 49 66 20 74 68 65 20 6f 75 74 70 75 74  s. If the output
d260: 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f   buffer.** is no
d270: 74 20 6c 61 72 67 65 20 65 6e 6f 75 67 68 2c 20  t large enough, 
d280: 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e  [SQLITE_CANTOPEN
d290: 5d 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75  ] should be retu
d2a0: 72 6e 65 64 2e 20 53 69 6e 63 65 20 74 68 69 73  rned. Since this
d2b0: 20 69 73 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61   is.** handled a
d2c0: 73 20 61 20 66 61 74 61 6c 20 65 72 72 6f 72 20  s a fatal error 
d2d0: 62 79 20 53 51 4c 69 74 65 2c 20 76 66 73 20 69  by SQLite, vfs i
d2e0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73  mplementations s
d2f0: 68 6f 75 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a  hould endeavor.*
d300: 2a 20 74 6f 20 70 72 65 76 65 6e 74 20 74 68 69  * to prevent thi
d310: 73 20 62 79 20 73 65 74 74 69 6e 67 20 6d 78 50  s by setting mxP
d320: 61 74 68 6e 61 6d 65 20 74 6f 20 61 20 73 75 66  athname to a suf
d330: 66 69 63 69 65 6e 74 6c 79 20 6c 61 72 67 65 20  ficiently large 
d340: 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  value..**.** The
d350: 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20   xRandomness(), 
d360: 78 53 6c 65 65 70 28 29 2c 20 78 43 75 72 72 65  xSleep(), xCurre
d370: 6e 74 54 69 6d 65 28 29 2c 20 61 6e 64 20 78 43  ntTime(), and xC
d380: 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28  urrentTimeInt64(
d390: 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  ).** interfaces 
d3a0: 61 72 65 20 6e 6f 74 20 73 74 72 69 63 74 6c 79  are not strictly
d3b0: 20 61 20 70 61 72 74 20 6f 66 20 74 68 65 20 66   a part of the f
d3c0: 69 6c 65 73 79 73 74 65 6d 2c 20 62 75 74 20 74  ilesystem, but t
d3d0: 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75  hey are.** inclu
d3e0: 64 65 64 20 69 6e 20 74 68 65 20 56 46 53 20 73  ded in the VFS s
d3f0: 74 72 75 63 74 75 72 65 20 66 6f 72 20 63 6f 6d  tructure for com
d400: 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68  pleteness..** Th
d410: 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20  e xRandomness() 
d420: 66 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70 74  function attempt
d430: 73 20 74 6f 20 72 65 74 75 72 6e 20 6e 42 79 74  s to return nByt
d440: 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67  es bytes.** of g
d450: 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72 61 6e 64  ood-quality rand
d460: 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74  omness into zOut
d470: 2e 20 20 54 68 65 20 72 65 74 75 72 6e 20 76 61  .  The return va
d480: 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65 20 61 63  lue is.** the ac
d490: 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62  tual number of b
d4a0: 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65  ytes of randomne
d4b0: 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20  ss obtained..** 
d4c0: 54 68 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74  The xSleep() met
d4d0: 68 6f 64 20 63 61 75 73 65 73 20 74 68 65 20 63  hod causes the c
d4e0: 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 74 6f  alling thread to
d4f0: 20 73 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a   sleep for at.**
d500: 20 6c 65 61 73 74 20 74 68 65 20 6e 75 6d 62 65   least the numbe
d510: 72 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64  r of microsecond
d520: 73 20 67 69 76 65 6e 2e 20 20 5e 54 68 65 20 78  s given.  ^The x
d530: 43 75 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a  CurrentTime().**
d540: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
d550: 61 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d  a Julian Day Num
d560: 62 65 72 20 66 6f 72 20 74 68 65 20 63 75 72 72  ber for the curr
d570: 65 6e 74 20 64 61 74 65 20 61 6e 64 20 74 69 6d  ent date and tim
d580: 65 20 61 73 0a 2a 2a 20 61 20 66 6c 6f 61 74 69  e as.** a floati
d590: 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 2e 0a  ng point value..
d5a0: 2a 2a 20 5e 54 68 65 20 78 43 75 72 72 65 6e 74  ** ^The xCurrent
d5b0: 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68  TimeInt64() meth
d5c0: 6f 64 20 72 65 74 75 72 6e 73 2c 20 61 73 20 61  od returns, as a
d5d0: 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 65 20 4a  n integer, the J
d5e0: 75 6c 69 61 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d  ulian.** Day Num
d5f0: 62 65 72 20 6d 75 6c 74 69 70 6c 69 65 64 20 62  ber multiplied b
d600: 79 20 38 36 34 30 30 30 30 30 20 28 74 68 65 20  y 86400000 (the 
d610: 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73  number of millis
d620: 65 63 6f 6e 64 73 20 69 6e 20 0a 2a 2a 20 61 20  econds in .** a 
d630: 32 34 2d 68 6f 75 72 20 64 61 79 29 2e 20 20 0a  24-hour day).  .
d640: 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20  ** ^SQLite will 
d650: 75 73 65 20 74 68 65 20 78 43 75 72 72 65 6e 74  use the xCurrent
d660: 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68  TimeInt64() meth
d670: 6f 64 20 74 6f 20 67 65 74 20 74 68 65 20 63 75  od to get the cu
d680: 72 72 65 6e 74 0a 2a 2a 20 64 61 74 65 20 61 6e  rrent.** date an
d690: 64 20 74 69 6d 65 20 69 66 20 74 68 61 74 20 6d  d time if that m
d6a0: 65 74 68 6f 64 20 69 73 20 61 76 61 69 6c 61 62  ethod is availab
d6b0: 6c 65 20 28 69 66 20 69 56 65 72 73 69 6f 6e 20  le (if iVersion 
d6c0: 69 73 20 32 20 6f 72 20 0a 2a 2a 20 67 72 65 61  is 2 or .** grea
d6d0: 74 65 72 20 61 6e 64 20 74 68 65 20 66 75 6e 63  ter and the func
d6e0: 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20  tion pointer is 
d6f0: 6e 6f 74 20 4e 55 4c 4c 29 20 61 6e 64 20 77 69  not NULL) and wi
d700: 6c 6c 20 66 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20  ll fall back.** 
d710: 74 6f 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28  to xCurrentTime(
d720: 29 20 69 66 20 78 43 75 72 72 65 6e 74 54 69 6d  ) if xCurrentTim
d730: 65 49 6e 74 36 34 28 29 20 69 73 20 75 6e 61 76  eInt64() is unav
d740: 61 69 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e  ailable..**.** ^
d750: 54 68 65 20 78 53 65 74 53 79 73 74 65 6d 43 61  The xSetSystemCa
d760: 6c 6c 28 29 2c 20 78 47 65 74 53 79 73 74 65 6d  ll(), xGetSystem
d770: 43 61 6c 6c 28 29 2c 20 61 6e 64 20 78 4e 65 73  Call(), and xNes
d780: 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 20 69 6e  tSystemCall() in
d790: 74 65 72 66 61 63 65 73 0a 2a 2a 20 61 72 65 20  terfaces.** are 
d7a0: 6e 6f 74 20 75 73 65 64 20 62 79 20 74 68 65 20  not used by the 
d7b0: 53 51 4c 69 74 65 20 63 6f 72 65 2e 20 20 54 68  SQLite core.  Th
d7c0: 65 73 65 20 6f 70 74 69 6f 6e 61 6c 20 69 6e 74  ese optional int
d7d0: 65 72 66 61 63 65 73 20 61 72 65 20 70 72 6f 76  erfaces are prov
d7e0: 69 64 65 64 0a 2a 2a 20 62 79 20 73 6f 6d 65 20  ided.** by some 
d7f0: 56 46 53 65 73 20 74 6f 20 66 61 63 69 6c 69 74  VFSes to facilit
d800: 61 74 65 20 74 65 73 74 69 6e 67 20 6f 66 20 74  ate testing of t
d810: 68 65 20 56 46 53 20 63 6f 64 65 2e 20 42 79 20  he VFS code. By 
d820: 6f 76 65 72 72 69 64 69 6e 67 20 0a 2a 2a 20 73  overriding .** s
d830: 79 73 74 65 6d 20 63 61 6c 6c 73 20 77 69 74 68  ystem calls with
d840: 20 66 75 6e 63 74 69 6f 6e 73 20 75 6e 64 65 72   functions under
d850: 20 69 74 73 20 63 6f 6e 74 72 6f 6c 2c 20 61 20   its control, a 
d860: 74 65 73 74 20 70 72 6f 67 72 61 6d 20 63 61 6e  test program can
d870: 0a 2a 2a 20 73 69 6d 75 6c 61 74 65 20 66 61 75  .** simulate fau
d880: 6c 74 73 20 61 6e 64 20 65 72 72 6f 72 20 63 6f  lts and error co
d890: 6e 64 69 74 69 6f 6e 73 20 74 68 61 74 20 77 6f  nditions that wo
d8a0: 75 6c 64 20 6f 74 68 65 72 77 69 73 65 20 62 65  uld otherwise be
d8b0: 20 64 69 66 66 69 63 75 6c 74 0a 2a 2a 20 6f 72   difficult.** or
d8c0: 20 69 6d 70 6f 73 73 69 62 6c 65 20 74 6f 20 69   impossible to i
d8d0: 6e 64 75 63 65 2e 20 20 54 68 65 20 73 65 74 20  nduce.  The set 
d8e0: 6f 66 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20  of system calls 
d8f0: 74 68 61 74 20 63 61 6e 20 62 65 20 6f 76 65 72  that can be over
d900: 72 69 64 64 65 6e 0a 2a 2a 20 76 61 72 69 65 73  ridden.** varies
d910: 20 66 72 6f 6d 20 6f 6e 65 20 56 46 53 20 74 6f   from one VFS to
d920: 20 61 6e 6f 74 68 65 72 2c 20 61 6e 64 20 66 72   another, and fr
d930: 6f 6d 20 6f 6e 65 20 76 65 72 73 69 6f 6e 20 6f  om one version o
d940: 66 20 74 68 65 20 73 61 6d 65 20 56 46 53 20 74  f the same VFS t
d950: 6f 20 74 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20  o the.** next.  
d960: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  Applications tha
d970: 74 20 75 73 65 20 74 68 65 73 65 20 69 6e 74 65  t use these inte
d980: 72 66 61 63 65 73 20 6d 75 73 74 20 62 65 20 70  rfaces must be p
d990: 72 65 70 61 72 65 64 20 66 6f 72 20 61 6e 79 0a  repared for any.
d9a0: 2a 2a 20 6f 72 20 61 6c 6c 20 6f 66 20 74 68 65  ** or all of the
d9b0: 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 74 6f  se interfaces to
d9c0: 20 62 65 20 4e 55 4c 4c 20 6f 72 20 66 6f 72 20   be NULL or for 
d9d0: 74 68 65 69 72 20 62 65 68 61 76 69 6f 72 20 74  their behavior t
d9e0: 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d  o change.** from
d9f0: 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 74 6f 20   one release to 
da00: 74 68 65 20 6e 65 78 74 2e 20 20 41 70 70 6c 69  the next.  Appli
da10: 63 61 74 69 6f 6e 73 20 6d 75 73 74 20 6e 6f 74  cations must not
da20: 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63 63 65   attempt to acce
da30: 73 73 0a 2a 2a 20 61 6e 79 20 6f 66 20 74 68 65  ss.** any of the
da40: 73 65 20 6d 65 74 68 6f 64 73 20 69 66 20 74 68  se methods if th
da50: 65 20 69 56 65 72 73 69 6f 6e 20 6f 66 20 74 68  e iVersion of th
da60: 65 20 56 46 53 20 69 73 20 6c 65 73 73 20 74 68  e VFS is less th
da70: 61 6e 20 33 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  an 3..*/.typedef
da80: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
da90: 76 66 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b  vfs sqlite3_vfs;
daa0: 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a  .typedef void (*
dab0: 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f  sqlite3_syscall_
dac0: 70 74 72 29 28 76 6f 69 64 29 3b 0a 73 74 72 75  ptr)(void);.stru
dad0: 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 7b  ct sqlite3_vfs {
dae0: 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b  .  int iVersion;
daf0: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53              /* S
db00: 74 72 75 63 74 75 72 65 20 76 65 72 73 69 6f 6e  tructure version
db10: 20 6e 75 6d 62 65 72 20 28 63 75 72 72 65 6e 74   number (current
db20: 6c 79 20 33 29 20 2a 2f 0a 20 20 69 6e 74 20 73  ly 3) */.  int s
db30: 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20 20 20 20  zOsFile;        
db40: 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73      /* Size of s
db50: 75 62 63 6c 61 73 73 65 64 20 73 71 6c 69 74 65  ubclassed sqlite
db60: 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20  3_file */.  int 
db70: 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20 20 20 20  mxPathname;     
db80: 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
db90: 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 6c 65  file pathname le
dba0: 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65  ngth */.  sqlite
dbb0: 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b 20 20 20  3_vfs *pNext;   
dbc0: 20 20 20 2f 2a 20 4e 65 78 74 20 72 65 67 69 73     /* Next regis
dbd0: 74 65 72 65 64 20 56 46 53 20 2a 2f 0a 20 20 63  tered VFS */.  c
dbe0: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
dbf0: 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20  ;       /* Name 
dc00: 6f 66 20 74 68 69 73 20 76 69 72 74 75 61 6c 20  of this virtual 
dc10: 66 69 6c 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20  file system */. 
dc20: 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b   void *pAppData;
dc30: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 50 6f 69            /* Poi
dc40: 6e 74 65 72 20 74 6f 20 61 70 70 6c 69 63 61 74  nter to applicat
dc50: 69 6f 6e 2d 73 70 65 63 69 66 69 63 20 64 61 74  ion-specific dat
dc60: 61 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70  a */.  int (*xOp
dc70: 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  en)(sqlite3_vfs*
dc80: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
dc90: 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c  ame, sqlite3_fil
dca0: 65 2a 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  e*,.            
dcb0: 20 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e     int flags, in
dcc0: 74 20 2a 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20  t *pOutFlags);. 
dcd0: 20 69 6e 74 20 28 2a 78 44 65 6c 65 74 65 29 28   int (*xDelete)(
dce0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
dcf0: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
dd00: 20 69 6e 74 20 73 79 6e 63 44 69 72 29 3b 0a 20   int syncDir);. 
dd10: 20 69 6e 74 20 28 2a 78 41 63 63 65 73 73 29 28   int (*xAccess)(
dd20: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
dd30: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
dd40: 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20   int flags, int 
dd50: 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74  *pResOut);.  int
dd60: 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65   (*xFullPathname
dd70: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
dd80: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
dd90: 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61  e, int nOut, cha
dda0: 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64  r *zOut);.  void
ddb0: 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c   *(*xDlOpen)(sql
ddc0: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
ddd0: 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65   char *zFilename
dde0: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 45  );.  void (*xDlE
ddf0: 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66  rror)(sqlite3_vf
de00: 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63  s*, int nByte, c
de10: 68 61 72 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20  har *zErrMsg);. 
de20: 20 76 6f 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d   void (*(*xDlSym
de30: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76  )(sqlite3_vfs*,v
de40: 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  oid*, const char
de50: 20 2a 7a 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64   *zSymbol))(void
de60: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 43  );.  void (*xDlC
de70: 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76 66  lose)(sqlite3_vf
de80: 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e  s*, void*);.  in
de90: 74 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29  t (*xRandomness)
dea0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
deb0: 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a  nt nByte, char *
dec0: 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  zOut);.  int (*x
ded0: 53 6c 65 65 70 29 28 73 71 6c 69 74 65 33 5f 76  Sleep)(sqlite3_v
dee0: 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65  fs*, int microse
def0: 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a  conds);.  int (*
df00: 78 43 75 72 72 65 6e 74 54 69 6d 65 29 28 73 71  xCurrentTime)(sq
df10: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62  lite3_vfs*, doub
df20: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47  le*);.  int (*xG
df30: 65 74 4c 61 73 74 45 72 72 6f 72 29 28 73 71 6c  etLastError)(sql
df40: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20  ite3_vfs*, int, 
df50: 63 68 61 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20  char *);.  /*.  
df60: 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61  ** The methods a
df70: 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72 73  bove are in vers
df80: 69 6f 6e 20 31 20 6f 66 20 74 68 65 20 73 71 6c  ion 1 of the sql
df90: 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 0a 20  ite_vfs object. 
dfa0: 20 2a 2a 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20   ** definition. 
dfb0: 20 54 68 6f 73 65 20 74 68 61 74 20 66 6f 6c 6c   Those that foll
dfc0: 6f 77 20 61 72 65 20 61 64 64 65 64 20 69 6e 20  ow are added in 
dfd0: 76 65 72 73 69 6f 6e 20 32 20 6f 72 20 6c 61 74  version 2 or lat
dfe0: 65 72 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  er.  */.  int (*
dff0: 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36  xCurrentTimeInt6
e000: 34 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  4)(sqlite3_vfs*,
e010: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2a 29   sqlite3_int64*)
e020: 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20  ;.  /*.  ** The 
e030: 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72  methods above ar
e040: 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20  e in versions 1 
e050: 61 6e 64 20 32 20 6f 66 20 74 68 65 20 73 71 6c  and 2 of the sql
e060: 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a  ite_vfs object..
e070: 20 20 2a 2a 20 54 68 6f 73 65 20 62 65 6c 6f 77    ** Those below
e080: 20 61 72 65 20 66 6f 72 20 76 65 72 73 69 6f 6e   are for version
e090: 20 33 20 61 6e 64 20 67 72 65 61 74 65 72 2e 0a   3 and greater..
e0a0: 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 65    */.  int (*xSe
e0b0: 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c  tSystemCall)(sql
e0c0: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
e0d0: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71   char *zName, sq
e0e0: 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74  lite3_syscall_pt
e0f0: 72 29 3b 0a 20 20 73 71 6c 69 74 65 33 5f 73 79  r);.  sqlite3_sy
e100: 73 63 61 6c 6c 5f 70 74 72 20 28 2a 78 47 65 74  scall_ptr (*xGet
e110: 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69  SystemCall)(sqli
e120: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
e130: 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20  char *zName);.  
e140: 63 6f 6e 73 74 20 63 68 61 72 20 2a 28 2a 78 4e  const char *(*xN
e150: 65 78 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73  extSystemCall)(s
e160: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
e170: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b  st char *zName);
e180: 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d  .  /*.  ** The m
e190: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
e1a0: 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 74   in versions 1 t
e1b0: 68 72 6f 75 67 68 20 33 20 6f 66 20 74 68 65 20  hrough 3 of the 
e1c0: 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63  sqlite_vfs objec
e1d0: 74 2e 0a 20 20 2a 2a 20 4e 65 77 20 66 69 65 6c  t..  ** New fiel
e1e0: 64 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64  ds may be append
e1f0: 65 64 20 69 6e 20 66 69 67 75 72 65 20 76 65 72  ed in figure ver
e200: 73 69 6f 6e 73 2e 20 20 54 68 65 20 69 56 65 72  sions.  The iVer
e210: 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20  sion.  ** value 
e220: 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77  will increment w
e230: 68 65 6e 65 76 65 72 20 74 68 69 73 20 68 61 70  henever this hap
e240: 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a  pens. .  */.};..
e250: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
e260: 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 41  Flags for the xA
e270: 63 63 65 73 73 20 56 46 53 20 6d 65 74 68 6f 64  ccess VFS method
e280: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74  .**.** These int
e290: 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 63  eger constants c
e2a0: 61 6e 20 62 65 20 75 73 65 64 20 61 73 20 74 68  an be used as th
e2b0: 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
e2c0: 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63  r to.** the xAcc
e2d0: 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e  ess method of an
e2e0: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
e2f0: 62 6a 65 63 74 2e 20 20 54 68 65 79 20 64 65 74  bject.  They det
e300: 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b  ermine.** what k
e310: 69 6e 64 20 6f 66 20 70 65 72 6d 69 73 73 69 6f  ind of permissio
e320: 6e 73 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  ns the xAccess m
e330: 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67  ethod is looking
e340: 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51   for..** With SQ
e350: 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53  LITE_ACCESS_EXIS
e360: 54 53 2c 20 74 68 65 20 78 41 63 63 65 73 73 20  TS, the xAccess 
e370: 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79  method.** simply
e380: 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20   checks whether 
e390: 74 68 65 20 66 69 6c 65 20 65 78 69 73 74 73 2e  the file exists.
e3a0: 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f  .** With SQLITE_
e3b0: 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45  ACCESS_READWRITE
e3c0: 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  , the xAccess me
e3d0: 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77  thod.** checks w
e3e0: 68 65 74 68 65 72 20 74 68 65 20 6e 61 6d 65 64  hether the named
e3f0: 20 64 69 72 65 63 74 6f 72 79 20 69 73 20 62 6f   directory is bo
e400: 74 68 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20  th readable and 
e410: 77 72 69 74 61 62 6c 65 0a 2a 2a 20 28 69 6e 20  writable.** (in 
e420: 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 66 20  other words, if 
e430: 66 69 6c 65 73 20 63 61 6e 20 62 65 20 61 64 64  files can be add
e440: 65 64 2c 20 72 65 6d 6f 76 65 64 2c 20 61 6e 64  ed, removed, and
e450: 20 72 65 6e 61 6d 65 64 20 77 69 74 68 69 6e 0a   renamed within.
e460: 2a 2a 20 74 68 65 20 64 69 72 65 63 74 6f 72 79  ** the directory
e470: 29 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  )..** The SQLITE
e480: 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
e490: 45 20 63 6f 6e 73 74 61 6e 74 20 69 73 20 63 75  E constant is cu
e4a0: 72 72 65 6e 74 6c 79 20 75 73 65 64 20 6f 6e 6c  rrently used onl
e4b0: 79 20 62 79 20 74 68 65 0a 2a 2a 20 5b 74 65 6d  y by the.** [tem
e4c0: 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72  p_store_director
e4d0: 79 20 70 72 61 67 6d 61 5d 2c 20 74 68 6f 75 67  y pragma], thoug
e4e0: 68 20 74 68 69 73 20 63 6f 75 6c 64 20 63 68 61  h this could cha
e4f0: 6e 67 65 20 69 6e 20 61 20 66 75 74 75 72 65 0a  nge in a future.
e500: 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51  ** release of SQ
e510: 4c 69 74 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51  Lite..** With SQ
e520: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
e530: 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  , the xAccess me
e540: 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77  thod.** checks w
e550: 68 65 74 68 65 72 20 74 68 65 20 66 69 6c 65 20  hether the file 
e560: 69 73 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68  is readable.  Th
e570: 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  e SQLITE_ACCESS_
e580: 52 45 41 44 20 63 6f 6e 73 74 61 6e 74 20 69 73  READ constant is
e590: 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 75 6e  .** currently un
e5a0: 75 73 65 64 2c 20 74 68 6f 75 67 68 20 69 74 20  used, though it 
e5b0: 6d 69 67 68 74 20 62 65 20 75 73 65 64 20 69 6e  might be used in
e5c0: 20 61 20 66 75 74 75 72 65 20 72 65 6c 65 61 73   a future releas
e5d0: 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a  e of.** SQLite..
e5e0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
e5f0: 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 20  E_ACCESS_EXISTS 
e600: 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c     0.#define SQL
e610: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
e620: 52 49 54 45 20 31 20 20 20 2f 2a 20 55 73 65 64  RITE 1   /* Used
e630: 20 62 79 20 50 52 41 47 4d 41 20 74 65 6d 70 5f   by PRAGMA temp_
e640: 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20  store_directory 
e650: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
e660: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20 20 20  E_ACCESS_READ   
e670: 20 20 20 32 20 20 20 2f 2a 20 55 6e 75 73 65 64     2   /* Unused
e680: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
e690: 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74  REF: Flags for t
e6a0: 68 65 20 78 53 68 6d 4c 6f 63 6b 20 56 46 53 20  he xShmLock VFS 
e6b0: 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65  method.**.** The
e6c0: 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74  se integer const
e6d0: 61 6e 74 73 20 64 65 66 69 6e 65 20 74 68 65 20  ants define the 
e6e0: 76 61 72 69 6f 75 73 20 6c 6f 63 6b 69 6e 67 20  various locking 
e6f0: 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c  operations.** al
e700: 6c 6f 77 65 64 20 62 79 20 74 68 65 20 78 53 68  lowed by the xSh
e710: 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 66 20  mLock method of 
e720: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
e730: 6f 64 73 5d 2e 20 20 54 68 65 0a 2a 2a 20 66 6f  ods].  The.** fo
e740: 6c 6c 6f 77 69 6e 67 20 61 72 65 20 74 68 65 20  llowing are the 
e750: 6f 6e 6c 79 20 6c 65 67 61 6c 20 63 6f 6d 62 69  only legal combi
e760: 6e 61 74 69 6f 6e 73 20 6f 66 20 66 6c 61 67 73  nations of flags
e770: 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 68 6d 4c   to the.** xShmL
e780: 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a  ock method:.**.*
e790: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20  * <ul>.** <li>  
e7a0: 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20  SQLITE_SHM_LOCK 
e7b0: 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41  | SQLITE_SHM_SHA
e7c0: 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  RED.** <li>  SQL
e7d0: 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53  ITE_SHM_LOCK | S
e7e0: 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53  QLITE_SHM_EXCLUS
e7f0: 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  IVE.** <li>  SQL
e800: 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c  ITE_SHM_UNLOCK |
e810: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52   SQLITE_SHM_SHAR
e820: 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  ED.** <li>  SQLI
e830: 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20  TE_SHM_UNLOCK | 
e840: 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55  SQLITE_SHM_EXCLU
e850: 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  SIVE.** </ul>.**
e860: 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c 6f 63 6b 69  .** When unlocki
e870: 6e 67 2c 20 74 68 65 20 73 61 6d 65 20 53 48 41  ng, the same SHA
e880: 52 45 44 20 6f 72 20 45 58 43 4c 55 53 49 56 45  RED or EXCLUSIVE
e890: 20 66 6c 61 67 20 6d 75 73 74 20 62 65 20 73 75   flag must be su
e8a0: 70 70 6c 69 65 64 20 61 73 0a 2a 2a 20 77 61 73  pplied as.** was
e8b0: 20 67 69 76 65 6e 20 6e 6f 20 74 68 65 20 63 6f   given no the co
e8c0: 72 72 65 73 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b  rresponding lock
e8d0: 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53  .  .**.** The xS
e8e0: 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 63 61  hmLock method ca
e8f0: 6e 20 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74  n transition bet
e900: 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e  ween unlocked an
e910: 64 20 53 48 41 52 45 44 20 6f 72 0a 2a 2a 20 62  d SHARED or.** b
e920: 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20  etween unlocked 
e930: 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e 20 20  and EXCLUSIVE.  
e940: 49 74 20 63 61 6e 6e 6f 74 20 74 72 61 6e 73 69  It cannot transi
e950: 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 53 48 41  tion between SHA
e960: 52 45 44 0a 2a 2a 20 61 6e 64 20 45 58 43 4c 55  RED.** and EXCLU
e970: 53 49 56 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  SIVE..*/.#define
e980: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f   SQLITE_SHM_UNLO
e990: 43 4b 20 20 20 20 20 20 20 31 0a 23 64 65 66 69  CK       1.#defi
e9a0: 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f  ne SQLITE_SHM_LO
e9b0: 43 4b 20 20 20 20 20 20 20 20 20 32 0a 23 64 65  CK         2.#de
e9c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f  fine SQLITE_SHM_
e9d0: 53 48 41 52 45 44 20 20 20 20 20 20 20 34 0a 23  SHARED       4.#
e9e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
e9f0: 4d 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 38  M_EXCLUSIVE    8
ea00: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
ea10: 3a 20 4d 61 78 69 6d 75 6d 20 78 53 68 6d 4c 6f  : Maximum xShmLo
ea20: 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54  ck index.**.** T
ea30: 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68  he xShmLock meth
ea40: 6f 64 20 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 69  od on [sqlite3_i
ea50: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d 61 79 20 75  o_methods] may u
ea60: 73 65 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74  se values.** bet
ea70: 77 65 65 6e 20 30 20 61 6e 64 20 74 68 69 73 20  ween 0 and this 
ea80: 75 70 70 65 72 20 62 6f 75 6e 64 20 61 73 20 69  upper bound as i
ea90: 74 73 20 22 6f 66 66 73 65 74 22 20 61 72 67 75  ts "offset" argu
eaa0: 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 53 51 4c  ment..** The SQL
eab0: 69 74 65 20 63 6f 72 65 20 77 69 6c 6c 20 6e 65  ite core will ne
eac0: 76 65 72 20 61 74 74 65 6d 70 74 20 74 6f 20 61  ver attempt to a
ead0: 63 71 75 69 72 65 20 6f 72 20 72 65 6c 65 61 73  cquire or releas
eae0: 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73  e a.** lock outs
eaf0: 69 64 65 20 6f 66 20 74 68 69 73 20 72 61 6e 67  ide of this rang
eb00: 65 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e.*/.#define SQL
eb10: 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20  ITE_SHM_NLOCK   
eb20: 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43       8.../*.** C
eb30: 41 50 49 33 52 45 46 3a 20 49 6e 69 74 69 61 6c  API3REF: Initial
eb40: 69 7a 65 20 54 68 65 20 53 51 4c 69 74 65 20 4c  ize The SQLite L
eb50: 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68  ibrary.**.** ^Th
eb60: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
eb70: 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69  lize() routine i
eb80: 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a  nitializes the.*
eb90: 2a 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  * SQLite library
eba0: 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
ebb0: 73 68 75 74 64 6f 77 6e 28 29 20 72 6f 75 74 69  shutdown() routi
ebc0: 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65  ne.** deallocate
ebd0: 73 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20  s any resources 
ebe0: 74 68 61 74 20 77 65 72 65 20 61 6c 6c 6f 63 61  that were alloca
ebf0: 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69  ted by sqlite3_i
ec00: 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20  nitialize()..** 
ec10: 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
ec20: 72 65 20 64 65 73 69 67 6e 65 64 20 74 6f 20 61  re designed to a
ec30: 69 64 20 69 6e 20 70 72 6f 63 65 73 73 20 69 6e  id in process in
ec40: 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64  itialization and
ec50: 0a 2a 2a 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20  .** shutdown on 
ec60: 65 6d 62 65 64 64 65 64 20 73 79 73 74 65 6d 73  embedded systems
ec70: 2e 20 20 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61  .  Workstation a
ec80: 70 70 6c 69 63 61 74 69 6f 6e 73 20 75 73 69 6e  pplications usin
ec90: 67 0a 2a 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d  g.** SQLite norm
eca0: 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64  ally do not need
ecb0: 20 74 6f 20 69 6e 76 6f 6b 65 20 65 69 74 68 65   to invoke eithe
ecc0: 72 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  r of these routi
ecd0: 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c  nes..**.** A cal
ece0: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69  l to sqlite3_ini
ecf0: 74 69 61 6c 69 7a 65 28 29 20 69 73 20 61 6e 20  tialize() is an 
ed00: 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c  "effective" call
ed10: 20 69 66 20 69 74 20 69 73 0a 2a 2a 20 74 68 65   if it is.** the
ed20: 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69   first time sqli
ed30: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
ed40: 20 69 73 20 69 6e 76 6f 6b 65 64 20 64 75 72 69   is invoked duri
ed50: 6e 67 20 74 68 65 20 6c 69 66 65 74 69 6d 65 20  ng the lifetime 
ed60: 6f 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63 65 73  of.** the proces
ed70: 73 2c 20 6f 72 20 69 66 20 69 74 20 69 73 20 74  s, or if it is t
ed80: 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71  he first time sq
ed90: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
eda0: 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a  () is invoked.**
edb0: 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c   following a cal
edc0: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75  l to sqlite3_shu
edd0: 74 64 6f 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79  tdown().  ^(Only
ede0: 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61   an effective ca
edf0: 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33  ll.** of sqlite3
ee00: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 6f  _initialize() do
ee10: 65 73 20 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a  es any initializ
ee20: 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65  ation.  All othe
ee30: 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68  r calls.** are h
ee40: 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29  armless no-ops.)
ee50: 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74  ^.**.** A call t
ee60: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
ee70: 77 6e 28 29 20 69 73 20 61 6e 20 22 65 66 66 65  wn() is an "effe
ee80: 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69  ctive" call if i
ee90: 74 20 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a  t is the first.*
eea0: 2a 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  * call to sqlite
eeb0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 73 69 6e  3_shutdown() sin
eec0: 63 65 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69  ce the last sqli
eed0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
eee0: 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20  .  ^(Only.** an 
eef0: 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 20 74  effective call t
ef00: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
ef10: 77 6e 28 29 20 64 6f 65 73 20 61 6e 79 20 64 65  wn() does any de
ef20: 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a  initialization..
ef30: 2a 2a 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c  ** All other val
ef40: 69 64 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  id calls to sqli
ef50: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 61  te3_shutdown() a
ef60: 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f  re harmless no-o
ef70: 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ps.)^.**.** The 
ef80: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
ef90: 7a 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  ze() interface i
efa0: 73 20 74 68 72 65 61 64 73 61 66 65 2c 20 62 75  s threadsafe, bu
efb0: 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  t sqlite3_shutdo
efc0: 77 6e 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20  wn().** is not. 
efd0: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75   The sqlite3_shu
efe0: 74 64 6f 77 6e 28 29 20 69 6e 74 65 72 66 61 63  tdown() interfac
eff0: 65 20 6d 75 73 74 20 6f 6e 6c 79 20 62 65 20 63  e must only be c
f000: 61 6c 6c 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20  alled from a.** 
f010: 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20  single thread.  
f020: 41 6c 6c 20 6f 70 65 6e 20 5b 64 61 74 61 62 61  All open [databa
f030: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20  se connections] 
f040: 6d 75 73 74 20 62 65 20 63 6c 6f 73 65 64 20 61  must be closed a
f050: 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20  nd all.** other 
f060: 53 51 4c 69 74 65 20 72 65 73 6f 75 72 63 65 73  SQLite resources
f070: 20 6d 75 73 74 20 62 65 20 64 65 61 6c 6c 6f 63   must be dealloc
f080: 61 74 65 64 20 70 72 69 6f 72 20 74 6f 20 69 6e  ated prior to in
f090: 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65  voking.** sqlite
f0a0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a  3_shutdown()..**
f0b0: 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20  .** Among other 
f0c0: 74 68 69 6e 67 73 2c 20 5e 73 71 6c 69 74 65 33  things, ^sqlite3
f0d0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 77 69  _initialize() wi
f0e0: 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c  ll invoke.** sql
f0f0: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20  ite3_os_init(). 
f100: 20 53 69 6d 69 6c 61 72 6c 79 2c 20 5e 73 71 6c   Similarly, ^sql
f110: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a  ite3_shutdown().
f120: 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 73  ** will invoke s
f130: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e  qlite3_os_end().
f140: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
f150: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
f160: 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
f170: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20   [SQLITE_OK] on 
f180: 73 75 63 63 65 73 73 2e 0a 2a 2a 20 5e 49 66 20  success..** ^If 
f190: 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c  for some reason,
f1a0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
f1b0: 69 7a 65 28 29 20 69 73 20 75 6e 61 62 6c 65 20  ize() is unable 
f1c0: 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a  to initialize.**
f1d0: 20 74 68 65 20 6c 69 62 72 61 72 79 20 28 70 65   the library (pe
f1e0: 72 68 61 70 73 20 69 74 20 69 73 20 75 6e 61 62  rhaps it is unab
f1f0: 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61  le to allocate a
f200: 20 6e 65 65 64 65 64 20 72 65 73 6f 75 72 63 65   needed resource
f210: 20 73 75 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75   such.** as a mu
f220: 74 65 78 29 20 69 74 20 72 65 74 75 72 6e 73 20  tex) it returns 
f230: 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  an [error code] 
f240: 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
f250: 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54  TE_OK]..**.** ^T
f260: 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  he sqlite3_initi
f270: 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20  alize() routine 
f280: 69 73 20 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e  is called intern
f290: 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f 74 68  ally by many oth
f2a0: 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74  er.** SQLite int
f2b0: 65 72 66 61 63 65 73 20 73 6f 20 74 68 61 74 20  erfaces so that 
f2c0: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75  an application u
f2d0: 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20  sually does not 
f2e0: 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b  need to.** invok
f2f0: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
f300: 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79 2e  lize() directly.
f310: 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b    For example, [
f320: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a  sqlite3_open()].
f330: 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74 65 33  ** calls sqlite3
f340: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 73 6f  _initialize() so
f350: 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72   the SQLite libr
f360: 61 72 79 20 77 69 6c 6c 20 62 65 20 61 75 74 6f  ary will be auto
f370: 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69  matically.** ini
f380: 74 69 61 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73  tialized when [s
f390: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69  qlite3_open()] i
f3a0: 73 20 63 61 6c 6c 65 64 20 69 66 20 69 74 20 68  s called if it h
f3b0: 61 73 20 6e 6f 74 20 62 65 20 69 6e 69 74 69 61  as not be initia
f3c0: 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79  lized.** already
f3d0: 2e 20 20 5e 48 6f 77 65 76 65 72 2c 20 69 66 20  .  ^However, if 
f3e0: 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
f3f0: 65 64 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c  ed with the [SQL
f400: 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49  ITE_OMIT_AUTOINI
f410: 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69  T].** compile-ti
f420: 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20  me option, then 
f430: 74 68 65 20 61 75 74 6f 6d 61 74 69 63 20 63 61  the automatic ca
f440: 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 69  lls to sqlite3_i
f450: 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61  nitialize().** a
f460: 72 65 20 6f 6d 69 74 74 65 64 20 61 6e 64 20 74  re omitted and t
f470: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
f480: 75 73 74 20 63 61 6c 6c 20 73 71 6c 69 74 65 33  ust call sqlite3
f490: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69  _initialize() di
f4a0: 72 65 63 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20  rectly.** prior 
f4b0: 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68  to using any oth
f4c0: 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
f4d0: 61 63 65 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75  ace.  For maximu
f4e0: 6d 20 70 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a  m portability,.*
f4f0: 2a 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e  * it is recommen
f500: 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61  ded that applica
f510: 74 69 6f 6e 73 20 61 6c 77 61 79 73 20 69 6e 76  tions always inv
f520: 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  oke sqlite3_init
f530: 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65  ialize().** dire
f540: 63 74 6c 79 20 70 72 69 6f 72 20 74 6f 20 75 73  ctly prior to us
f550: 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51  ing any other SQ
f560: 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20  Lite interface. 
f570: 20 46 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   Future releases
f580: 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20 6d 61  .** of SQLite ma
f590: 79 20 72 65 71 75 69 72 65 20 74 68 69 73 2e 20  y require this. 
f5a0: 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
f5b0: 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 65 78   the behavior ex
f5c0: 68 69 62 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20  hibited.** when 
f5d0: 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
f5e0: 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f  ed with [SQLITE_
f5f0: 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d  OMIT_AUTOINIT] m
f600: 69 67 68 74 20 62 65 63 6f 6d 65 20 74 68 65 0a  ight become the.
f610: 2a 2a 20 64 65 66 61 75 6c 74 20 62 65 68 61 76  ** default behav
f620: 69 6f 72 20 69 6e 20 73 6f 6d 65 20 66 75 74 75  ior in some futu
f630: 72 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51  re release of SQ
f640: 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  Lite..**.** The 
f650: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
f660: 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f  ) routine does o
f670: 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20  perating-system 
f680: 73 70 65 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74  specific.** init
f690: 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68  ialization of th
f6a0: 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  e SQLite library
f6b0: 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f  .  The sqlite3_o
f6c0: 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69  s_end().** routi
f6d0: 6e 65 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66  ne undoes the ef
f6e0: 66 65 63 74 20 6f 66 20 73 71 6c 69 74 65 33 5f  fect of sqlite3_
f6f0: 6f 73 5f 69 6e 69 74 28 29 2e 20 20 54 79 70 69  os_init().  Typi
f700: 63 61 6c 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72  cal tasks.** per
f710: 66 6f 72 6d 65 64 20 62 79 20 74 68 65 73 65 20  formed by these 
f720: 72 6f 75 74 69 6e 65 73 20 69 6e 63 6c 75 64 65  routines include
f730: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64   allocation or d
f740: 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f  eallocation.** o
f750: 66 20 73 74 61 74 69 63 20 72 65 73 6f 75 72 63  f static resourc
f760: 65 73 2c 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  es, initializati
f770: 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72  on of global var
f780: 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69  iables,.** setti
f790: 6e 67 20 75 70 20 61 20 64 65 66 61 75 6c 74 20  ng up a default 
f7a0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f  [sqlite3_vfs] mo
f7b0: 64 75 6c 65 2c 20 6f 72 20 73 65 74 74 69 6e 67  dule, or setting
f7c0: 20 75 70 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74   up.** a default
f7d0: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75   configuration u
f7e0: 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f  sing [sqlite3_co
f7f0: 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54  nfig()]..**.** T
f800: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73  he application s
f810: 68 6f 75 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f  hould never invo
f820: 6b 65 20 65 69 74 68 65 72 20 73 71 6c 69 74 65  ke either sqlite
f830: 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f  3_os_init().** o
f840: 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  r sqlite3_os_end
f850: 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 54 68  () directly.  Th
f860: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
f870: 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65  ould only invoke
f880: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  .** sqlite3_init
f890: 69 61 6c 69 7a 65 28 29 20 61 6e 64 20 73 71 6c  ialize() and sql
f8a0: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e  ite3_shutdown().
f8b0: 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73    The sqlite3_os
f8c0: 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72  _init().** inter
f8d0: 66 61 63 65 20 69 73 20 63 61 6c 6c 65 64 20 61  face is called a
f8e0: 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20  utomatically by 
f8f0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
f900: 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69  ze() and.** sqli
f910: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20  te3_os_end() is 
f920: 63 61 6c 6c 65 64 20 62 79 20 73 71 6c 69 74 65  called by sqlite
f930: 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 41  3_shutdown().  A
f940: 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d  ppropriate.** im
f950: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f  plementations fo
f960: 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  r sqlite3_os_ini
f970: 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  t() and sqlite3_
f980: 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20  os_end().** are 
f990: 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74  built into SQLit
f9a0: 65 20 77 68 65 6e 20 69 74 20 69 73 20 63 6f 6d  e when it is com
f9b0: 70 69 6c 65 64 20 66 6f 72 20 55 6e 69 78 2c 20  piled for Unix, 
f9c0: 57 69 6e 64 6f 77 73 2c 20 6f 72 20 4f 53 2f 32  Windows, or OS/2
f9d0: 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63 75 73 74 6f  ..** When [custo
f9e0: 6d 20 62 75 69 6c 64 73 20 7c 20 62 75 69 6c 74  m builds | built
f9f0: 20 66 6f 72 20 6f 74 68 65 72 20 70 6c 61 74 66   for other platf
fa00: 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 20  orms].** (using 
fa10: 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f  the [SQLITE_OS_O
fa20: 54 48 45 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d  THER=1] compile-
fa30: 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20  time.** option) 
fa40: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
fa50: 6d 75 73 74 20 73 75 70 70 6c 79 20 61 20 73 75  must supply a su
fa60: 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  itable implement
fa70: 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c  ation for.** sql
fa80: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61  ite3_os_init() a
fa90: 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  nd sqlite3_os_en
faa0: 64 28 29 2e 20 20 41 6e 20 61 70 70 6c 69 63 61  d().  An applica
fab0: 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a  tion-supplied.**
fac0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
fad0: 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  of sqlite3_os_in
fae0: 69 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  it() or sqlite3_
faf0: 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74  os_end().** must
fb00: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
fb10: 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61  OK] on success a
fb20: 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65  nd some other [e
fb30: 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a  rror code] upon.
fb40: 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 53  ** failure..*/.S
fb50: 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
fb60: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
fb70: 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41  (void);.SQLITE_A
fb80: 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  PI int sqlite3_s
fb90: 68 75 74 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 53  hutdown(void);.S
fba0: 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
fbb0: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f  lite3_os_init(vo
fbc0: 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  id);.SQLITE_API 
fbd0: 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  int sqlite3_os_e
fbe0: 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a  nd(void);../*.**
fbf0: 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69   CAPI3REF: Confi
fc00: 67 75 72 69 6e 67 20 54 68 65 20 53 51 4c 69 74  guring The SQLit
fc10: 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20  e Library.**.** 
fc20: 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  The sqlite3_conf
fc30: 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  ig() interface i
fc40: 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 67  s used to make g
fc50: 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72 61 74  lobal configurat
fc60: 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74  ion.** changes t
fc70: 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65  o SQLite in orde
fc80: 72 20 74 6f 20 74 75 6e 65 20 53 51 4c 69 74 65  r to tune SQLite
fc90: 20 74 6f 20 74 68 65 20 73 70 65 63 69 66 69 63   to the specific
fca0: 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65   needs of.** the
fcb0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54   application.  T
fcc0: 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69  he default confi
fcd0: 67 75 72 61 74 69 6f 6e 20 69 73 20 72 65 63 6f  guration is reco
fce0: 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74  mmended for most
fcf0: 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  .** applications
fd00: 20 61 6e 64 20 73 6f 20 74 68 69 73 20 72 6f 75   and so this rou
fd10: 74 69 6e 65 20 69 73 20 75 73 75 61 6c 6c 79 20  tine is usually 
fd20: 6e 6f 74 20 6e 65 63 65 73 73 61 72 79 2e 20 20  not necessary.  
fd30: 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65  It is.** provide
fd40: 64 20 74 6f 20 73 75 70 70 6f 72 74 20 72 61 72  d to support rar
fd50: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 77  e applications w
fd60: 69 74 68 20 75 6e 75 73 75 61 6c 20 6e 65 65 64  ith unusual need
fd70: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  s..**.** The sql
fd80: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e  ite3_config() in
fd90: 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 74  terface is not t
fda0: 68 72 65 61 64 73 61 66 65 2e 20 20 54 68 65 20  hreadsafe.  The 
fdb0: 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d  application.** m
fdc0: 75 73 74 20 69 6e 73 75 72 65 20 74 68 61 74 20  ust insure that 
fdd0: 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  no other SQLite 
fde0: 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69  interfaces are i
fdf0: 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68 65 72 0a  nvoked by other.
fe00: 2a 2a 20 74 68 72 65 61 64 73 20 77 68 69 6c 65  ** threads while
fe10: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
fe20: 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 20 46  ) is running.  F
fe30: 75 72 74 68 65 72 6d 6f 72 65 2c 20 73 71 6c 69  urthermore, sqli
fe40: 74 65 33 5f 63 6f 6e 66 69 67 28 29 0a 2a 2a 20  te3_config().** 
fe50: 6d 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f  may only be invo
fe60: 6b 65 64 20 70 72 69 6f 72 20 74 6f 20 6c 69 62  ked prior to lib
fe70: 72 61 72 79 20 69 6e 69 74 69 61 6c 69 7a 61 74  rary initializat
fe80: 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  ion using.** [sq
fe90: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
fea0: 28 29 5d 20 6f 72 20 61 66 74 65 72 20 73 68 75  ()] or after shu
feb0: 74 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74 65  tdown by [sqlite
fec0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a  3_shutdown()]..*
fed0: 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f  * ^If sqlite3_co
fee0: 6e 66 69 67 28 29 20 69 73 20 63 61 6c 6c 65 64  nfig() is called
fef0: 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f   after [sqlite3_
ff00: 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 61 6e  initialize()] an
ff10: 64 20 62 65 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c  d before.** [sql
ff20: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d  ite3_shutdown()]
ff30: 20 74 68 65 6e 20 69 74 20 77 69 6c 6c 20 72 65   then it will re
ff40: 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55  turn SQLITE_MISU
ff50: 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77  SE..** Note, how
ff60: 65 76 65 72 2c 20 74 68 61 74 20 5e 73 71 6c 69  ever, that ^sqli
ff70: 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 63 61 6e  te3_config() can
ff80: 20 62 65 20 63 61 6c 6c 65 64 20 61 73 20 70 61   be called as pa
ff90: 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6d 70  rt of the.** imp
ffa0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61  lementation of a
ffb0: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
ffc0: 66 69 6e 65 64 20 5b 73 71 6c 69 74 65 33 5f 6f  fined [sqlite3_o
ffd0: 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a  s_init()]..**.**
ffe0: 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
fff0: 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  ent to sqlite3_c
10000 6f 6e 66 69 67 28 29 20 69 73 20 61 6e 20 69 6e  onfig() is an in
10010 74 65 67 65 72 0a 2a 2a 20 5b 63 6f 6e 66 69 67  teger.** [config
10020 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20  uration option] 
10030 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 73 0a  that determines.
10040 2a 2a 20 77 68 61 74 20 70 72 6f 70 65 72 74 79  ** what property
10050 20 6f 66 20 53 51 4c 69 74 65 20 69 73 20 74 6f   of SQLite is to
10060 20 62 65 20 63 6f 6e 66 69 67 75 72 65 64 2e 20   be configured. 
10070 20 53 75 62 73 65 71 75 65 6e 74 20 61 72 67 75   Subsequent argu
10080 6d 65 6e 74 73 0a 2a 2a 20 76 61 72 79 20 64 65  ments.** vary de
10090 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 5b  pending on the [
100a0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
100b0 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20  tion].** in the 
100c0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a  first argument..
100d0 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 61 20 63 6f  **.** ^When a co
100e0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
100f0 6f 6e 20 69 73 20 73 65 74 2c 20 73 71 6c 69 74  on is set, sqlit
10100 65 33 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75  e3_config() retu
10110 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e  rns [SQLITE_OK].
10120 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6f 70 74 69  .** ^If the opti
10130 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72  on is unknown or
10140 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c   SQLite is unabl
10150 65 20 74 6f 20 73 65 74 20 74 68 65 20 6f 70 74  e to set the opt
10160 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73  ion.** then this
10170 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
10180 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72   a non-zero [err
10190 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 53 51 4c  or code]..*/.SQL
101a0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
101b0 74 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20  te3_config(int, 
101c0 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ...);../*.** CAP
101d0 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 65  I3REF: Configure
101e0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
101f0 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20  tions.**.** The 
10200 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
10210 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  g() interface is
10220 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 63 6f   used to make co
10230 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63  nfiguration.** c
10240 68 61 6e 67 65 73 20 74 6f 20 61 20 5b 64 61 74  hanges to a [dat
10250 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
10260 5d 2e 20 20 54 68 65 20 69 6e 74 65 72 66 61 63  ].  The interfac
10270 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 0a  e is similar to.
10280 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
10290 69 67 28 29 5d 20 65 78 63 65 70 74 20 74 68 61  ig()] except tha
102a0 74 20 74 68 65 20 63 68 61 6e 67 65 73 20 61 70  t the changes ap
102b0 70 6c 79 20 74 6f 20 61 20 73 69 6e 67 6c 65 0a  ply to a single.
102c0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
102d0 6e 65 63 74 69 6f 6e 5d 20 28 73 70 65 63 69 66  nection] (specif
102e0 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 74  ied in the first
102f0 20 61 72 67 75 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a   argument)..**.*
10300 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67  * The second arg
10310 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
10320 5f 64 62 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e  _db_config(D,V,.
10330 2e 2e 29 20 20 69 73 20 74 68 65 0a 2a 2a 20 5b  ..)  is the.** [
10340 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
10350 4c 4f 4f 4b 41 53 49 44 45 20 7c 20 63 6f 6e 66  LOOKASIDE | conf
10360 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62 5d 20  iguration verb] 
10370 2d 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64  - an integer cod
10380 65 20 0a 2a 2a 20 74 68 61 74 20 69 6e 64 69 63  e .** that indic
10390 61 74 65 73 20 77 68 61 74 20 61 73 70 65 63 74  ates what aspect
103a0 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73   of the [databas
103b0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73  e connection] is
103c0 20 62 65 69 6e 67 20 63 6f 6e 66 69 67 75 72 65   being configure
103d0 64 2e 0a 2a 2a 20 53 75 62 73 65 71 75 65 6e 74  d..** Subsequent
103e0 20 61 72 67 75 6d 65 6e 74 73 20 76 61 72 79 20   arguments vary 
103f0 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65  depending on the
10400 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76   configuration v
10410 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c  erb..**.** ^Call
10420 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f  s to sqlite3_db_
10430 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e 20  config() return 
10440 53 51 4c 49 54 45 5f 4f 4b 20 69 66 20 61 6e 64  SQLITE_OK if and
10450 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 74 68 65 20   only if.** the 
10460 63 61 6c 6c 20 69 73 20 63 6f 6e 73 69 64 65 72  call is consider
10470 65 64 20 73 75 63 63 65 73 73 66 75 6c 2e 0a 2a  ed successful..*
10480 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
10490 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66   sqlite3_db_conf
104a0 69 67 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  ig(sqlite3*, int
104b0 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a   op, ...);../*.*
104c0 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f  * CAPI3REF: Memo
104d0 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f  ry Allocation Ro
104e0 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20  utines.**.** An 
104f0 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
10500 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20   object defines 
10510 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65  the interface be
10520 74 77 65 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20  tween SQLite.** 
10530 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65  and low-level me
10540 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
10550 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20  routines..**.** 
10560 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 75  This object is u
10570 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20  sed in only one 
10580 70 6c 61 63 65 20 69 6e 20 74 68 65 20 53 51 4c  place in the SQL
10590 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ite interface..*
105a0 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  * A pointer to a
105b0 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
105c0 69 73 20 6f 62 6a 65 63 74 20 69 73 20 74 68 65  is object is the
105d0 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
105e0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
105f0 29 5d 20 77 68 65 6e 20 74 68 65 20 63 6f 6e 66  )] when the conf
10600 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
10610 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43   is.** [SQLITE_C
10620 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72  ONFIG_MALLOC] or
10630 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
10640 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a  GETMALLOC].  .**
10650 20 42 79 20 63 72 65 61 74 69 6e 67 20 61 6e 20   By creating an 
10660 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
10670 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 70   object.** and p
10680 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71  assing it to [sq
10690 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53  lite3_config]([S
106a0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
106b0 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 69 6e 67 20  LOC]).** during 
106c0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 61  configuration, a
106d0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 61  n application ca
106e0 6e 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74  n specify an alt
106f0 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f  ernative.** memo
10700 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75  ry allocation su
10710 62 73 79 73 74 65 6d 20 66 6f 72 20 53 51 4c 69  bsystem for SQLi
10720 74 65 20 74 6f 20 75 73 65 20 66 6f 72 20 61 6c  te to use for al
10730 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 64 79 6e 61  l of its.** dyna
10740 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73  mic memory needs
10750 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
10760 74 20 53 51 4c 69 74 65 20 63 6f 6d 65 73 20 77  t SQLite comes w
10770 69 74 68 20 73 65 76 65 72 61 6c 20 5b 62 75 69  ith several [bui
10780 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c  lt-in memory all
10790 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 74 68 61 74  ocators].** that
107a0 20 61 72 65 20 70 65 72 66 65 63 74 6c 79 20 61   are perfectly a
107b0 64 65 71 75 61 74 65 20 66 6f 72 20 74 68 65 20  dequate for the 
107c0 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20 6d 61 6a  overwhelming maj
107d0 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61  ority of applica
107e0 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74 68 61  tions.** and tha
107f0 74 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73  t this object is
10800 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20 74 6f 20   only useful to 
10810 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69 74 79 20  a tiny minority 
10820 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a  of applications.
10830 2a 2a 20 77 69 74 68 20 73 70 65 63 69 61 6c 69  ** with speciali
10840 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  zed memory alloc
10850 61 74 69 6f 6e 20 72 65 71 75 69 72 65 6d 65 6e  ation requiremen
10860 74 73 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74  ts.  This object
10870 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 73 65 64   is.** also used
10880 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20   during testing 
10890 6f 66 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64  of SQLite in ord
108a0 65 72 20 74 6f 20 73 70 65 63 69 66 79 20 61 6e  er to specify an
108b0 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20   alternative.** 
108c0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
108d0 20 74 68 61 74 20 73 69 6d 75 6c 61 74 65 73 20   that simulates 
108e0 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d 65  memory out-of-me
108f0 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f 6e 73 20  mory conditions 
10900 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 6f 20 76  in.** order to v
10910 65 72 69 66 79 20 74 68 61 74 20 53 51 4c 69 74  erify that SQLit
10920 65 20 72 65 63 6f 76 65 72 73 20 67 72 61 63 65  e recovers grace
10930 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75 63 68 0a  fully from such.
10940 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a  ** conditions..*
10950 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c 6c 6f 63  *.** The xMalloc
10960 2c 20 78 52 65 61 6c 6c 6f 63 2c 20 61 6e 64 20  , xRealloc, and 
10970 78 46 72 65 65 20 6d 65 74 68 6f 64 73 20 6d 75  xFree methods mu
10980 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20 74 68 65  st work like the
10990 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 2c 20 72 65  .** malloc(), re
109a0 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65  alloc() and free
109b0 28 29 20 66 75 6e 63 74 69 6f 6e 73 20 66 72 6f  () functions fro
109c0 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43  m the standard C
109d0 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 5e 53 51   library..** ^SQ
109e0 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65 73 20  Lite guarantees 
109f0 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e 64 20  that the second 
10a00 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78  argument to.** x
10a10 52 65 61 6c 6c 6f 63 20 69 73 20 61 6c 77 61 79  Realloc is alway
10a20 73 20 61 20 76 61 6c 75 65 20 72 65 74 75 72 6e  s a value return
10a30 65 64 20 62 79 20 61 20 70 72 69 6f 72 20 63 61  ed by a prior ca
10a40 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 75 70 2e 0a  ll to xRoundup..
10a50 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75  **.** xSize shou
10a60 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 61 6c  ld return the al
10a70 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 20  located size of 
10a80 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
10a90 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  ion.** previousl
10aa0 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
10ab0 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c  xMalloc or xReal
10ac0 6c 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61  loc.  The alloca
10ad0 74 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61  ted size.** is a
10ae0 6c 77 61 79 73 20 61 74 20 6c 65 61 73 74 20 61  lways at least a
10af0 73 20 62 69 67 20 61 73 20 74 68 65 20 72 65 71  s big as the req
10b00 75 65 73 74 65 64 20 73 69 7a 65 20 62 75 74 20  uested size but 
10b10 6d 61 79 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a  may be larger..*
10b20 2a 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e 64 75  *.** The xRoundu
10b30 70 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  p method returns
10b40 20 77 68 61 74 20 77 6f 75 6c 64 20 62 65 20 74   what would be t
10b50 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a  he allocated siz
10b60 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79  e of.** a memory
10b70 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65   allocation give
10b80 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72  n a particular r
10b90 65 71 75 65 73 74 65 64 20 73 69 7a 65 2e 20 20  equested size.  
10ba0 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61  Most memory.** a
10bb0 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20  llocators round 
10bc0 75 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  up memory alloca
10bd0 74 69 6f 6e 73 20 61 74 20 6c 65 61 73 74 20 74  tions at least t
10be0 6f 20 74 68 65 20 6e 65 78 74 20 6d 75 6c 74 69  o the next multi
10bf0 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f  ple.** of 8.  So
10c00 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f  me allocators ro
10c10 75 6e 64 20 75 70 20 74 6f 20 61 20 6c 61 72 67  und up to a larg
10c20 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74  er multiple or t
10c30 6f 20 61 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a  o a power of 2..
10c40 2a 2a 20 45 76 65 72 79 20 6d 65 6d 6f 72 79 20  ** Every memory 
10c50 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 65  allocation reque
10c60 73 74 20 63 6f 6d 69 6e 67 20 69 6e 20 74 68 72  st coming in thr
10c70 6f 75 67 68 20 5b 73 71 6c 69 74 65 33 5f 6d 61  ough [sqlite3_ma
10c80 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73  lloc()].** or [s
10c90 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
10ca0 5d 20 66 69 72 73 74 20 63 61 6c 6c 73 20 78 52  ] first calls xR
10cb0 6f 75 6e 64 75 70 2e 20 20 49 66 20 78 52 6f 75  oundup.  If xRou
10cc0 6e 64 75 70 20 72 65 74 75 72 6e 73 20 30 2c 20  ndup returns 0, 
10cd0 0a 2a 2a 20 74 68 61 74 20 63 61 75 73 65 73 20  .** that causes 
10ce0 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
10cf0 67 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  g memory allocat
10d00 69 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a  ion to fail..**.
10d10 2a 2a 20 54 68 65 20 78 49 6e 69 74 20 6d 65 74  ** The xInit met
10d20 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65 73 20  hod initializes 
10d30 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
10d40 61 74 6f 72 2e 20 20 28 46 6f 72 20 65 78 61 6d  ator.  (For exam
10d50 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 74  ple,.** it might
10d60 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65   allocate any re
10d70 71 75 69 72 65 20 6d 75 74 65 78 65 73 20 6f 72  quire mutexes or
10d80 20 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74 65   initialize inte
10d90 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74 72  rnal data.** str
10da0 75 63 74 75 72 65 73 2e 20 20 54 68 65 20 78 53  uctures.  The xS
10db0 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69  hutdown method i
10dc0 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69 72  s invoked (indir
10dd0 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 71  ectly) by.** [sq
10de0 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
10df0 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20 64 65 61  ] and should dea
10e00 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 73 6f  llocate any reso
10e10 75 72 63 65 73 20 61 63 71 75 69 72 65 64 0a 2a  urces acquired.*
10e20 2a 20 62 79 20 78 49 6e 69 74 2e 20 20 54 68 65  * by xInit.  The
10e30 20 70 41 70 70 44 61 74 61 20 70 6f 69 6e 74 65   pAppData pointe
10e40 72 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65  r is used as the
10e50 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20   only parameter 
10e60 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64 20  to.** xInit and 
10e70 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a  xShutdown..**.**
10e80 20 53 51 4c 69 74 65 20 68 6f 6c 64 73 20 74 68   SQLite holds th
10e90 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  e [SQLITE_MUTEX_
10ea0 53 54 41 54 49 43 5f 4d 41 53 54 45 52 5d 20 6d  STATIC_MASTER] m
10eb0 75 74 65 78 20 77 68 65 6e 20 69 74 20 69 6e 76  utex when it inv
10ec0 6f 6b 65 73 0a 2a 2a 20 74 68 65 20 78 49 6e 69  okes.** the xIni
10ed0 74 20 6d 65 74 68 6f 64 2c 20 73 6f 20 74 68 65  t method, so the
10ee0 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 6e 65   xInit method ne
10ef0 65 64 20 6e 6f 74 20 62 65 20 74 68 72 65 61 64  ed not be thread
10f00 73 61 66 65 2e 20 20 54 68 65 0a 2a 2a 20 78 53  safe.  The.** xS
10f10 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69  hutdown method i
10f20 73 20 6f 6e 6c 79 20 63 61 6c 6c 65 64 20 66 72  s only called fr
10f30 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74  om [sqlite3_shut
10f40 64 6f 77 6e 28 29 5d 20 73 6f 20 69 74 20 64 6f  down()] so it do
10f50 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64 20 74  es.** not need t
10f60 6f 20 62 65 20 74 68 72 65 61 64 73 61 66 65 20  o be threadsafe 
10f70 65 69 74 68 65 72 2e 20 20 46 6f 72 20 61 6c 6c  either.  For all
10f80 20 6f 74 68 65 72 20 6d 65 74 68 6f 64 73 2c 20   other methods, 
10f90 53 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64 73 20  SQLite.** holds 
10fa0 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45  the [SQLITE_MUTE
10fb0 58 5f 53 54 41 54 49 43 5f 4d 45 4d 5d 20 6d 75  X_STATIC_MEM] mu
10fc0 74 65 78 20 61 73 20 6c 6f 6e 67 20 61 73 20 74  tex as long as t
10fd0 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f  he.** [SQLITE_CO
10fe0 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20  NFIG_MEMSTATUS] 
10ff0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
11000 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f  tion is turned o
11010 6e 20 28 77 68 69 63 68 0a 2a 2a 20 69 74 20 69  n (which.** it i
11020 73 20 62 79 20 64 65 66 61 75 6c 74 29 20 61 6e  s by default) an
11030 64 20 73 6f 20 74 68 65 20 6d 65 74 68 6f 64 73  d so the methods
11040 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c   are automatical
11050 6c 79 20 73 65 72 69 61 6c 69 7a 65 64 2e 0a 2a  ly serialized..*
11060 2a 20 48 6f 77 65 76 65 72 2c 20 69 66 20 5b 53  * However, if [S
11070 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
11080 53 54 41 54 55 53 5d 20 69 73 20 64 69 73 61 62  STATUS] is disab
11090 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20 6f 74  led, then the ot
110a0 68 65 72 0a 2a 2a 20 6d 65 74 68 6f 64 73 20 6d  her.** methods m
110b0 75 73 74 20 62 65 20 74 68 72 65 61 64 73 61 66  ust be threadsaf
110c0 65 20 6f 72 20 65 6c 73 65 20 6d 61 6b 65 20 74  e or else make t
110d0 68 65 69 72 20 6f 77 6e 20 61 72 72 61 6e 67 65  heir own arrange
110e0 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a 20 73 65 72  ments for.** ser
110f0 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  ialization..**.*
11100 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65  * SQLite will ne
11110 76 65 72 20 69 6e 76 6f 6b 65 20 78 49 6e 69 74  ver invoke xInit
11120 28 29 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63  () more than onc
11130 65 20 77 69 74 68 6f 75 74 20 61 6e 20 69 6e 74  e without an int
11140 65 72 76 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c  ervening.** call
11150 20 74 6f 20 78 53 68 75 74 64 6f 77 6e 28 29 2e   to xShutdown().
11160 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
11170 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  ct sqlite3_mem_m
11180 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d  ethods sqlite3_m
11190 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75  em_methods;.stru
111a0 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  ct sqlite3_mem_m
111b0 65 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64 20  ethods {.  void 
111c0 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74 29  *(*xMalloc)(int)
111d0 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 65 6d  ;         /* Mem
111e0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
111f0 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69  unction */.  voi
11200 64 20 28 2a 78 46 72 65 65 29 28 76 6f 69 64 2a  d (*xFree)(void*
11210 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46  );          /* F
11220 72 65 65 20 61 20 70 72 69 6f 72 20 61 6c 6c 6f  ree a prior allo
11230 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64  cation */.  void
11240 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76 6f   *(*xRealloc)(vo
11250 69 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52 65  id*,int);  /* Re
11260 73 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74 69  size an allocati
11270 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53  on */.  int (*xS
11280 69 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20  ize)(void*);    
11290 20 20 20 20 20 20 20 2f 2a 20 52 65 74 75 72 6e         /* Return
112a0 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 6e 20   the size of an 
112b0 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20  allocation */.  
112c0 69 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70 29 28  int (*xRoundup)(
112d0 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 20 2f  int);          /
112e0 2a 20 52 6f 75 6e 64 20 75 70 20 72 65 71 75 65  * Round up reque
112f0 73 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f 63  st size to alloc
11300 61 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20 20  ation size */.  
11310 69 6e 74 20 28 2a 78 49 6e 69 74 29 28 76 6f 69  int (*xInit)(voi
11320 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f  d*);           /
11330 2a 20 49 6e 69 74 69 61 6c 69 7a 65 20 74 68 65  * Initialize the
11340 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
11350 72 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 53  r */.  void (*xS
11360 68 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29 3b  hutdown)(void*);
11370 20 20 20 20 20 20 2f 2a 20 44 65 69 6e 69 74 69        /* Deiniti
11380 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79  alize the memory
11390 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20   allocator */.  
113a0 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20  void *pAppData; 
113b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
113c0 2a 20 41 72 67 75 6d 65 6e 74 20 74 6f 20 78 49  * Argument to xI
113d0 6e 69 74 28 29 20 61 6e 64 20 78 53 68 75 74 64  nit() and xShutd
113e0 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a  own() */.};../*.
113f0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
11400 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f  figuration Optio
11410 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ns.** KEYWORDS: 
11420 7b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f  {configuration o
11430 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  ption}.**.** The
11440 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65  se constants are
11450 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69   the available i
11460 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61  nteger configura
11470 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61  tion options tha
11480 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73  t.** can be pass
11490 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20  ed as the first 
114a0 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
114b0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
114c0 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  )] interface..**
114d0 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72  .** New configur
114e0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61  ation options ma
114f0 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  y be added in fu
11500 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66  ture releases of
11510 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73   SQLite..** Exis
11520 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69  ting configurati
11530 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74  on options might
11540 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64   be discontinued
11550 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a  .  Applications.
11560 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20  ** should check 
11570 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20  the return code 
11580 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f  from [sqlite3_co
11590 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20  nfig()] to make 
115a0 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65  sure that.** the
115b0 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 54   call worked.  T
115c0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  he [sqlite3_conf
115d0 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  ig()] interface 
115e0 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a  will return a.**
115f0 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72   non-zero [error
11600 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63   code] if a disc
11610 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75  ontinued or unsu
11620 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72  pported configur
11630 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20  ation option.** 
11640 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a  is invoked..**.*
11650 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49  * <dl>.** [[SQLI
11660 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
11670 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c  THREAD]] <dt>SQL
11680 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
11690 45 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20  ETHREAD</dt>.** 
116a0 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f  <dd>There are no
116b0 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
116c0 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69  is option.  ^Thi
116d0 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68  s option sets th
116e0 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20  e.** [threading 
116f0 6d 6f 64 65 5d 20 74 6f 20 53 69 6e 67 6c 65 2d  mode] to Single-
11700 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65  thread.  In othe
11710 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61  r words, it disa
11720 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65  bles.** all mute
11730 78 69 6e 67 20 61 6e 64 20 70 75 74 73 20 53 51  xing and puts SQ
11740 4c 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64 65  Lite into a mode
11750 20 77 68 65 72 65 20 69 74 20 63 61 6e 20 6f 6e   where it can on
11760 6c 79 20 62 65 20 75 73 65 64 0a 2a 2a 20 62 79  ly be used.** by
11770 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64   a single thread
11780 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69  .   ^If SQLite i
11790 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
117a0 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
117b0 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49  HREADSAFE | SQLI
117c0 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
117d0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
117e0 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20  tion then.** it 
117f0 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  is not possible 
11800 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 5b 74  to change the [t
11810 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 66  hreading mode] f
11820 72 6f 6d 20 69 74 73 20 64 65 66 61 75 6c 74 0a  rom its default.
11830 2a 2a 20 76 61 6c 75 65 20 6f 66 20 53 69 6e 67  ** value of Sing
11840 6c 65 2d 74 68 72 65 61 64 20 61 6e 64 20 73 6f  le-thread and so
11850 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
11860 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ()] will return 
11870 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  .** [SQLITE_ERRO
11880 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74  R] if called wit
11890 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  h the SQLITE_CON
118a0 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
118b0 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  .** configuratio
118c0 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a  n option.</dd>.*
118d0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
118e0 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44  NFIG_MULTITHREAD
118f0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
11900 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44  NFIG_MULTITHREAD
11910 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
11920 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65  re are no argume
11930 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69  nts to this opti
11940 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f  on.  ^This optio
11950 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74  n sets the.** [t
11960 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74  hreading mode] t
11970 6f 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 2e 20  o Multi-thread. 
11980 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
11990 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20   it disables.** 
119a0 6d 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61 74  mutexing on [dat
119b0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
119c0 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20  ] and [prepared 
119d0 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63  statement] objec
119e0 74 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  ts..** The appli
119f0 63 61 74 69 6f 6e 20 69 73 20 72 65 73 70 6f 6e  cation is respon
11a00 73 69 62 6c 65 20 66 6f 72 20 73 65 72 69 61 6c  sible for serial
11a10 69 7a 69 6e 67 20 61 63 63 65 73 73 20 74 6f 0a  izing access to.
11a20 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
11a30 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70  nections] and [p
11a40 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
11a50 74 73 5d 2e 20 20 42 75 74 20 6f 74 68 65 72 20  ts].  But other 
11a60 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65  mutexes.** are e
11a70 6e 61 62 6c 65 64 20 73 6f 20 74 68 61 74 20 53  nabled so that S
11a80 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 73 61  QLite will be sa
11a90 66 65 20 74 6f 20 75 73 65 20 69 6e 20 61 20 6d  fe to use in a m
11aa0 75 6c 74 69 2d 74 68 72 65 61 64 65 64 0a 2a 2a  ulti-threaded.**
11ab0 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73 20   environment as 
11ac0 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20 74  long as no two t
11ad0 68 72 65 61 64 73 20 61 74 74 65 6d 70 74 20 74  hreads attempt t
11ae0 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 0a 2a  o use the same.*
11af0 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
11b00 65 63 74 69 6f 6e 5d 20 61 74 20 74 68 65 20 73  ection] at the s
11b10 61 6d 65 20 74 69 6d 65 2e 20 20 5e 49 66 20 53  ame time.  ^If S
11b20 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
11b30 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53  d with.** the [S
11b40 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
11b50 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44   | SQLITE_THREAD
11b60 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d  SAFE=0] compile-
11b70 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e  time option then
11b80 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f  .** it is not po
11b90 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68  ssible to set th
11ba0 65 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b  e Multi-thread [
11bb0 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
11bc0 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
11bd0 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72  config()] will r
11be0 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52  eturn [SQLITE_ER
11bf0 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77  ROR] if called w
11c00 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54  ith the.** SQLIT
11c10 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48  E_CONFIG_MULTITH
11c20 52 45 41 44 20 63 6f 6e 66 69 67 75 72 61 74 69  READ configurati
11c30 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a  on option.</dd>.
11c40 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
11c50 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44  ONFIG_SERIALIZED
11c60 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
11c70 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 3c  NFIG_SERIALIZED<
11c80 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72  /dt>.** <dd>Ther
11c90 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e  e are no argumen
11ca0 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f  ts to this optio
11cb0 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  n.  ^This option
11cc0 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68   sets the.** [th
11cd0 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f  reading mode] to
11ce0 20 53 65 72 69 61 6c 69 7a 65 64 2e 20 49 6e 20   Serialized. In 
11cf0 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 69  other words, thi
11d00 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65 73  s option enables
11d10 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73 20  .** all mutexes 
11d20 69 6e 63 6c 75 64 69 6e 67 20 74 68 65 20 72 65  including the re
11d30 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65 78  cursive.** mutex
11d40 65 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20  es on [database 
11d50 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20  connection] and 
11d60 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
11d70 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a  ent] objects..**
11d80 20 49 6e 20 74 68 69 73 20 6d 6f 64 65 20 28 77   In this mode (w
11d90 68 69 63 68 20 69 73 20 74 68 65 20 64 65 66 61  hich is the defa
11da0 75 6c 74 20 77 68 65 6e 20 53 51 4c 69 74 65 20  ult when SQLite 
11db0 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
11dc0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  .** [SQLITE_THRE
11dd0 41 44 53 41 46 45 3d 31 5d 29 20 74 68 65 20 53  ADSAFE=1]) the S
11de0 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77 69  QLite library wi
11df0 6c 6c 20 69 74 73 65 6c 66 20 73 65 72 69 61 6c  ll itself serial
11e00 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f  ize access.** to
11e10 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
11e20 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65  ctions] and [pre
11e30 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
11e40 5d 20 73 6f 20 74 68 61 74 20 74 68 65 0a 2a 2a  ] so that the.**
11e50 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20   application is 
11e60 66 72 65 65 20 74 6f 20 75 73 65 20 74 68 65 20  free to use the 
11e70 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63  same [database c
11e80 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74 68  onnection] or th
11e90 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70 61  e.** same [prepa
11ea0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69  red statement] i
11eb0 6e 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65  n different thre
11ec0 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20  ads at the same 
11ed0 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c  time..** ^If SQL
11ee0 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
11ef0 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  with.** the [SQL
11f00 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c  ITE_THREADSAFE |
11f10 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41   SQLITE_THREADSA
11f20 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  FE=0] compile-ti
11f30 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a  me option then.*
11f40 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73  * it is not poss
11f50 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20  ible to set the 
11f60 53 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65  Serialized [thre
11f70 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a  ading mode] and.
11f80 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
11f90 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  ig()] will retur
11fa0 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  n [SQLITE_ERROR]
11fb0 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20   if called with 
11fc0 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f  the.** SQLITE_CO
11fd0 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20  NFIG_SERIALIZED 
11fe0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
11ff0 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  tion.</dd>.**.**
12000 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
12010 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51  _MALLOC]] <dt>SQ
12020 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
12030 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  OC</dt>.** <dd> 
12040 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  ^(This option ta
12050 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
12060 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
12070 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a   pointer to an.*
12080 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  * instance of th
12090 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  e [sqlite3_mem_m
120a0 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
120b0 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74  e.  The argument
120c0 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c   specifies.** al
120d0 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65  ternative low-le
120e0 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  vel memory alloc
120f0 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74  ation routines t
12100 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61  o be used in pla
12110 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d  ce of.** the mem
12120 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
12130 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e  outines built in
12140 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 5e 53 51  to SQLite.)^ ^SQ
12150 4c 69 74 65 20 6d 61 6b 65 73 0a 2a 2a 20 69 74  Lite makes.** it
12160 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f  s own private co
12170 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 6e  py of the conten
12180 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  t of the [sqlite
12190 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73  3_mem_methods] s
121a0 74 72 75 63 74 75 72 65 0a 2a 2a 20 62 65 66 6f  tructure.** befo
121b0 72 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  re the [sqlite3_
121c0 63 6f 6e 66 69 67 28 29 5d 20 63 61 6c 6c 20 72  config()] call r
121d0 65 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a  eturns.</dd>.**.
121e0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
121f0 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d 20 3c  IG_GETMALLOC]] <
12200 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
12210 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a  _GETMALLOC</dt>.
12220 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f  ** <dd> ^(This o
12230 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
12240 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
12250 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ich is a pointer
12260 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e   to an.** instan
12270 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ce of the [sqlit
12280 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20  e3_mem_methods] 
12290 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 20  structure.  The 
122a0 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74  [sqlite3_mem_met
122b0 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75  hods].** structu
122c0 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74  re is filled wit
122d0 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20  h the currently 
122e0 64 65 66 69 6e 65 64 20 6d 65 6d 6f 72 79 20 61  defined memory a
122f0 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e  llocation routin
12300 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70  es.)^.** This op
12310 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64  tion can be used
12320 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65   to overload the
12330 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20   default memory 
12340 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f  allocation.** ro
12350 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77 72  utines with a wr
12360 61 70 70 65 72 20 74 68 61 74 20 73 69 6d 75 6c  apper that simul
12370 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 20 61 6c  ations memory al
12380 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 72 65  location failure
12390 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 20 6d 65   or.** tracks me
123a0 6d 6f 72 79 20 75 73 61 67 65 2c 20 66 6f 72 20  mory usage, for 
123b0 65 78 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e 0a 2a  example. </dd>.*
123c0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
123d0 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 5d  NFIG_MEMSTATUS]]
123e0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
123f0 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64 74  IG_MEMSTATUS</dt
12400 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20  >.** <dd> ^This 
12410 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e  option takes sin
12420 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20  gle argument of 
12430 74 79 70 65 20 69 6e 74 2c 20 69 6e 74 65 72 70  type int, interp
12440 72 65 74 65 64 20 61 73 20 61 20 0a 2a 2a 20 62  reted as a .** b
12450 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20 65 6e  oolean, which en
12460 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65  ables or disable
12470 73 20 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e  s the collection
12480 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63   of memory alloc
12490 61 74 69 6f 6e 20 0a 2a 2a 20 73 74 61 74 69 73  ation .** statis
124a0 74 69 63 73 2e 20 5e 28 57 68 65 6e 20 6d 65 6d  tics. ^(When mem
124b0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  ory allocation s
124c0 74 61 74 69 73 74 69 63 73 20 61 72 65 20 64 69  tatistics are di
124d0 73 61 62 6c 65 64 2c 20 74 68 65 20 0a 2a 2a 20  sabled, the .** 
124e0 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65  following SQLite
124f0 20 69 6e 74 65 72 66 61 63 65 73 20 62 65 63 6f   interfaces beco
12500 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e  me non-operation
12510 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a  al:.**   <ul>.**
12520 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33     <li> [sqlite3
12530 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a  _memory_used()].
12540 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74  **   <li> [sqlit
12550 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
12560 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e  ter()].**   <li>
12570 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68   [sqlite3_soft_h
12580 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 5d 0a 2a  eap_limit64()].*
12590 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65  *   <li> [sqlite
125a0 33 5f 73 74 61 74 75 73 28 29 5d 0a 2a 2a 20 20  3_status()].**  
125b0 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d   </ul>)^.** ^Mem
125c0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  ory allocation s
125d0 74 61 74 69 73 74 69 63 73 20 61 72 65 20 65 6e  tatistics are en
125e0 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
125f0 20 75 6e 6c 65 73 73 20 53 51 4c 69 74 65 20 69   unless SQLite i
12600 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69  s.** compiled wi
12610 74 68 20 5b 53 51 4c 49 54 45 5f 44 45 46 41 55  th [SQLITE_DEFAU
12620 4c 54 5f 4d 45 4d 53 54 41 54 55 53 5d 3d 30 20  LT_MEMSTATUS]=0 
12630 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 6d 65  in which case me
12640 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69  mory.** allocati
12650 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72  on statistics ar
12660 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65  e disabled by de
12670 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a  fault..** </dd>.
12680 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
12690 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 5d 20  ONFIG_SCRATCH]] 
126a0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
126b0 47 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a  G_SCRATCH</dt>.*
126c0 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74  * <dd> ^This opt
126d0 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20  ion specifies a 
126e0 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75  static memory bu
126f0 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 65  ffer that SQLite
12700 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20   can use for.** 
12710 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 2e 20  scratch memory. 
12720 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65   There are three
12730 20 61 72 67 75 6d 65 6e 74 73 3a 20 20 41 20 70   arguments:  A p
12740 6f 69 6e 74 65 72 20 61 6e 20 38 2d 62 79 74 65  ointer an 8-byte
12750 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 6d 65 6d 6f  .** aligned memo
12760 72 79 20 62 75 66 66 65 72 20 66 72 6f 6d 20 77  ry buffer from w
12770 68 69 63 68 20 74 68 65 20 73 63 72 61 74 63 68  hich the scratch
12780 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 77 69 6c   allocations wil
12790 6c 20 62 65 0a 2a 2a 20 64 72 61 77 6e 2c 20 74  l be.** drawn, t
127a0 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20  he size of each 
127b0 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69  scratch allocati
127c0 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20  on (sz),.** and 
127d0 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  the maximum numb
127e0 65 72 20 6f 66 20 73 63 72 61 74 63 68 20 61 6c  er of scratch al
127f0 6c 6f 63 61 74 69 6f 6e 73 20 28 4e 29 2e 20 20  locations (N).  
12800 54 68 65 20 73 7a 0a 2a 2a 20 61 72 67 75 6d 65  The sz.** argume
12810 6e 74 20 6d 75 73 74 20 62 65 20 61 20 6d 75 6c  nt must be a mul
12820 74 69 70 6c 65 20 6f 66 20 31 36 2e 0a 2a 2a 20  tiple of 16..** 
12830 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
12840 6e 74 20 6d 75 73 74 20 62 65 20 61 20 70 6f 69  nt must be a poi
12850 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d 62 79 74  nter to an 8-byt
12860 65 20 61 6c 69 67 6e 65 64 20 62 75 66 66 65 72  e aligned buffer
12870 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20  .** of at least 
12880 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65  sz*N bytes of me
12890 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  mory..** ^SQLite
128a0 20 77 69 6c 6c 20 75 73 65 20 6e 6f 20 6d 6f 72   will use no mor
128b0 65 20 74 68 61 6e 20 74 77 6f 20 73 63 72 61 74  e than two scrat
128c0 63 68 20 62 75 66 66 65 72 73 20 70 65 72 20 74  ch buffers per t
128d0 68 72 65 61 64 2e 20 20 53 6f 0a 2a 2a 20 4e 20  hread.  So.** N 
128e0 73 68 6f 75 6c 64 20 62 65 20 73 65 74 20 74 6f  should be set to
128f0 20 74 77 69 63 65 20 74 68 65 20 65 78 70 65 63   twice the expec
12900 74 65 64 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  ted maximum numb
12910 65 72 20 6f 66 20 74 68 72 65 61 64 73 2e 0a 2a  er of threads..*
12920 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e  * ^SQLite will n
12930 65 76 65 72 20 72 65 71 75 69 72 65 20 61 20 73  ever require a s
12940 63 72 61 74 63 68 20 62 75 66 66 65 72 20 74 68  cratch buffer th
12950 61 74 20 69 73 20 6d 6f 72 65 20 74 68 61 6e 20  at is more than 
12960 36 0a 2a 2a 20 74 69 6d 65 73 20 74 68 65 20 64  6.** times the d
12970 61 74 61 62 61 73 65 20 70 61 67 65 20 73 69 7a  atabase page siz
12980 65 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 6e 65  e. ^If SQLite ne
12990 65 64 73 20 6e 65 65 64 73 20 61 64 64 69 74 69  eds needs additi
129a0 6f 6e 61 6c 0a 2a 2a 20 73 63 72 61 74 63 68 20  onal.** scratch 
129b0 6d 65 6d 6f 72 79 20 62 65 79 6f 6e 64 20 77 68  memory beyond wh
129c0 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20 62  at is provided b
129d0 79 20 74 68 69 73 20 63 6f 6e 66 69 67 75 72 61  y this configura
129e0 74 69 6f 6e 20 6f 70 74 69 6f 6e 2c 20 74 68 65  tion option, the
129f0 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  n .** [sqlite3_m
12a00 61 6c 6c 6f 63 28 29 5d 20 77 69 6c 6c 20 62 65  alloc()] will be
12a10 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20   used to obtain 
12a20 74 68 65 20 6d 65 6d 6f 72 79 20 6e 65 65 64 65  the memory neede
12a30 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  d.</dd>.**.** [[
12a40 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
12a50 47 45 43 41 43 48 45 5d 5d 20 3c 64 74 3e 53 51  GECACHE]] <dt>SQ
12a60 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
12a70 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  CACHE</dt>.** <d
12a80 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
12a90 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74  specifies a stat
12aa0 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  ic memory buffer
12ab0 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e   that SQLite can
12ac0 20 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20   use for.** the 
12ad0 64 61 74 61 62 61 73 65 20 70 61 67 65 20 63 61  database page ca
12ae0 63 68 65 20 77 69 74 68 20 74 68 65 20 64 65 66  che with the def
12af0 61 75 6c 74 20 70 61 67 65 20 63 61 63 68 65 20  ault page cache 
12b00 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20  implementation. 
12b10 20 0a 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69 67   .** This config
12b20 75 72 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e  uration should n
12b30 6f 74 20 62 65 20 75 73 65 64 20 69 66 20 61 6e  ot be used if an
12b40 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
12b50 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63 61 63 68  ine page.** cach
12b60 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
12b70 20 69 73 20 6c 6f 61 64 65 64 20 75 73 69 6e 67   is loaded using
12b80 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46   the SQLITE_CONF
12b90 49 47 5f 50 43 41 43 48 45 32 20 6f 70 74 69 6f  IG_PCACHE2 optio
12ba0 6e 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20  n..** There are 
12bb0 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20  three arguments 
12bc0 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 3a 20  to this option: 
12bd0 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 38 2d 62  A pointer to 8-b
12be0 79 74 65 20 61 6c 69 67 6e 65 64 0a 2a 2a 20 6d  yte aligned.** m
12bf0 65 6d 6f 72 79 2c 20 74 68 65 20 73 69 7a 65 20  emory, the size 
12c00 6f 66 20 65 61 63 68 20 70 61 67 65 20 62 75 66  of each page buf
12c10 66 65 72 20 28 73 7a 29 2c 20 61 6e 64 20 74 68  fer (sz), and th
12c20 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 67 65  e number of page
12c30 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20 73 7a  s (N)..** The sz
12c40 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64   argument should
12c50 20 62 65 20 74 68 65 20 73 69 7a 65 20 6f 66 20   be the size of 
12c60 74 68 65 20 6c 61 72 67 65 73 74 20 64 61 74 61  the largest data
12c70 62 61 73 65 20 70 61 67 65 0a 2a 2a 20 28 61 20  base page.** (a 
12c80 70 6f 77 65 72 20 6f 66 20 74 77 6f 20 62 65 74  power of two bet
12c90 77 65 65 6e 20 35 31 32 20 61 6e 64 20 33 32 37  ween 512 and 327
12ca0 36 38 29 20 70 6c 75 73 20 61 20 6c 69 74 74 6c  68) plus a littl
12cb0 65 20 65 78 74 72 61 20 66 6f 72 20 65 61 63 68  e extra for each
12cc0 0a 2a 2a 20 70 61 67 65 20 68 65 61 64 65 72 2e  .** page header.
12cd0 20 20 5e 54 68 65 20 70 61 67 65 20 68 65 61 64    ^The page head
12ce0 65 72 20 73 69 7a 65 20 69 73 20 32 30 20 74 6f  er size is 20 to
12cf0 20 34 30 20 62 79 74 65 73 20 64 65 70 65 6e 64   40 bytes depend
12d00 69 6e 67 20 6f 6e 0a 2a 2a 20 74 68 65 20 68 6f  ing on.** the ho
12d10 73 74 20 61 72 63 68 69 74 65 63 74 75 72 65 2e  st architecture.
12d20 20 20 5e 49 74 20 69 73 20 68 61 72 6d 6c 65 73    ^It is harmles
12d30 73 2c 20 61 70 61 72 74 20 66 72 6f 6d 20 74 68  s, apart from th
12d40 65 20 77 61 73 74 65 64 20 6d 65 6d 6f 72 79 2c  e wasted memory,
12d50 0a 2a 2a 20 74 6f 20 6d 61 6b 65 20 73 7a 20 61  .** to make sz a
12d60 20 6c 69 74 74 6c 65 20 74 6f 6f 20 6c 61 72 67   little too larg
12d70 65 2e 20 20 54 68 65 20 66 69 72 73 74 0a 2a 2a  e.  The first.**
12d80 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64   argument should
12d90 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61 6c 6c   point to an all
12da0 6f 63 61 74 69 6f 6e 20 6f 66 20 61 74 20 6c 65  ocation of at le
12db0 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f  ast sz*N bytes o
12dc0 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51  f memory..** ^SQ
12dd0 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68  Lite will use th
12de0 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64 65  e memory provide
12df0 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 61  d by the first a
12e00 72 67 75 6d 65 6e 74 20 74 6f 20 73 61 74 69 73  rgument to satis
12e10 66 79 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72 79  fy its.** memory
12e20 20 6e 65 65 64 73 20 66 6f 72 20 74 68 65 20 66   needs for the f
12e30 69 72 73 74 20 4e 20 70 61 67 65 73 20 74 68 61  irst N pages tha
12e40 74 20 69 74 20 61 64 64 73 20 74 6f 20 63 61 63  t it adds to cac
12e50 68 65 2e 20 20 5e 49 66 20 61 64 64 69 74 69 6f  he.  ^If additio
12e60 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63 68  nal.** page cach
12e70 65 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65 64  e memory is need
12e80 65 64 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69  ed beyond what i
12e90 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68  s provided by th
12ea0 69 73 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 0a  is option, then.
12eb0 2a 2a 20 53 51 4c 69 74 65 20 67 6f 65 73 20 74  ** SQLite goes t
12ec0 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  o [sqlite3_mallo
12ed0 63 28 29 5d 20 66 6f 72 20 74 68 65 20 61 64 64  c()] for the add
12ee0 69 74 69 6f 6e 61 6c 20 73 74 6f 72 61 67 65 20  itional storage 
12ef0 73 70 61 63 65 2e 0a 2a 2a 20 54 68 65 20 70 6f  space..** The po
12f00 69 6e 74 65 72 20 69 6e 20 74 68 65 20 66 69 72  inter in the fir
12f10 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74  st argument must
12f20 0a 2a 2a 20 62 65 20 61 6c 69 67 6e 65 64 20 74  .** be aligned t
12f30 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e  o an 8-byte boun
12f40 64 61 72 79 20 6f 72 20 73 75 62 73 65 71 75 65  dary or subseque
12f50 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53  nt behavior of S
12f60 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 62 65  QLite.** will be
12f70 20 75 6e 64 65 66 69 6e 65 64 2e 3c 2f 64 64 3e   undefined.</dd>
12f80 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
12f90 43 4f 4e 46 49 47 5f 48 45 41 50 5d 5d 20 3c 64  CONFIG_HEAP]] <d
12fa0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
12fb0 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  HEAP</dt>.** <dd
12fc0 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73  > ^This option s
12fd0 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69  pecifies a stati
12fe0 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20  c memory buffer 
12ff0 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c  that SQLite will
13000 20 75 73 65 0a 2a 2a 20 66 6f 72 20 61 6c 6c 20   use.** for all 
13010 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d  of its dynamic m
13020 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
13030 20 6e 65 65 64 73 20 62 65 79 6f 6e 64 20 74 68   needs beyond th
13040 6f 73 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20  ose provided.** 
13050 66 6f 72 20 62 79 20 5b 53 51 4c 49 54 45 5f 43  for by [SQLITE_C
13060 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 20 61  ONFIG_SCRATCH] a
13070 6e 64 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  nd [SQLITE_CONFI
13080 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a  G_PAGECACHE]..**
13090 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65   There are three
130a0 20 61 72 67 75 6d 65 6e 74 73 3a 20 41 6e 20 38   arguments: An 8
130b0 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 70 6f  -byte aligned po
130c0 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 6d  inter to the mem
130d0 6f 72 79 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  ory,.** the numb
130e0 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
130f0 68 65 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  he memory buffer
13100 2c 20 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75  , and the minimu
13110 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a  m allocation siz
13120 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69  e..** ^If the fi
13130 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65  rst pointer (the
13140 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29   memory pointer)
13150 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53   is NULL, then S
13160 51 4c 69 74 65 20 72 65 76 65 72 74 73 0a 2a 2a  QLite reverts.**
13170 20 74 6f 20 75 73 69 6e 67 20 69 74 73 20 64 65   to using its de
13180 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c  fault memory all
13190 6f 63 61 74 6f 72 20 28 74 68 65 20 73 79 73 74  ocator (the syst
131a0 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c  em malloc() impl
131b0 65 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20  ementation),.** 
131c0 75 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f  undoing any prio
131d0 72 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20  r invocation of 
131e0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
131f0 41 4c 4c 4f 43 5d 2e 20 20 5e 49 66 20 74 68 65  ALLOC].  ^If the
13200 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74  .** memory point
13210 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61  er is not NULL a
13220 6e 64 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54  nd either [SQLIT
13230 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33  E_ENABLE_MEMSYS3
13240 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ] or.** [SQLITE_
13250 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20  ENABLE_MEMSYS5] 
13260 61 72 65 20 64 65 66 69 6e 65 64 2c 20 74 68 65  are defined, the
13270 6e 20 74 68 65 20 61 6c 74 65 72 6e 61 74 69 76  n the alternativ
13280 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  e memory.** allo
13290 63 61 74 6f 72 20 69 73 20 65 6e 67 61 67 65 64  cator is engaged
132a0 20 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f   to handle all o
132b0 66 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79  f SQLites memory
132c0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64   allocation need
132d0 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  s..** The first 
132e0 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d  pointer (the mem
132f0 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 6d 75 73  ory pointer) mus
13300 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20  t be aligned to 
13310 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 62 6f 75  an 8-byte.** bou
13320 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65 71 75  ndary or subsequ
13330 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20  ent behavior of 
13340 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 75  SQLite will be u
13350 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65  ndefined..** The
13360 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74   minimum allocat
13370 69 6f 6e 20 73 69 7a 65 20 69 73 20 63 61 70 70  ion size is capp
13380 65 64 20 61 74 20 32 2a 2a 31 32 2e 20 52 65 61  ed at 2**12. Rea
13390 73 6f 6e 61 62 6c 65 20 76 61 6c 75 65 73 0a 2a  sonable values.*
133a0 2a 20 66 6f 72 20 74 68 65 20 6d 69 6e 69 6d 75  * for the minimu
133b0 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a  m allocation siz
133c0 65 20 61 72 65 20 32 2a 2a 35 20 74 68 72 6f 75  e are 2**5 throu
133d0 67 68 20 32 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a  gh 2**8.</dd>.**
133e0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
133f0 46 49 47 5f 4d 55 54 45 58 5d 5d 20 3c 64 74 3e  FIG_MUTEX]] <dt>
13400 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
13410 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TEX</dt>.** <dd>
13420 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74   ^(This option t
13430 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
13440 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
13450 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
13460 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  ** instance of t
13470 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  he [sqlite3_mute
13480 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  x_methods] struc
13490 74 75 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d  ture.  The argum
134a0 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  ent specifies.**
134b0 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77   alternative low
134c0 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20 72 6f 75  -level mutex rou
134d0 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64  tines to be used
134e0 20 69 6e 20 70 6c 61 63 65 0a 2a 2a 20 74 68 65   in place.** the
134f0 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20   mutex routines 
13500 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74  built into SQLit
13510 65 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61  e.)^  ^SQLite ma
13520 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  kes a copy of th
13530 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 6f 66 20  e.** content of 
13540 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  the [sqlite3_mut
13550 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  ex_methods] stru
13560 63 74 75 72 65 20 62 65 66 6f 72 65 20 74 68 65  cture before the
13570 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
13580 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 72  ite3_config()] r
13590 65 74 75 72 6e 73 2e 20 5e 49 66 20 53 51 4c 69  eturns. ^If SQLi
135a0 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
135b0 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49  ith.** the [SQLI
135c0 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20  TE_THREADSAFE | 
135d0 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
135e0 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  E=0] compile-tim
135f0 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a  e option then.**
13600 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65   the entire mute
13610 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69  xing subsystem i
13620 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74  s omitted from t
13630 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e  he build and hen
13640 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b  ce calls to.** [
13650 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
13660 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54  ] with the SQLIT
13670 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 63  E_CONFIG_MUTEX c
13680 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
13690 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75  ion will.** retu
136a0 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  rn [SQLITE_ERROR
136b0 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  ].</dd>.**.** [[
136c0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
136d0 54 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c  TMUTEX]] <dt>SQL
136e0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55  ITE_CONFIG_GETMU
136f0 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TEX</dt>.** <dd>
13700 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74   ^(This option t
13710 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
13720 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
13730 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
13740 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  ** instance of t
13750 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  he [sqlite3_mute
13760 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  x_methods] struc
13770 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73  ture.  The.** [s
13780 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
13790 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75  hods].** structu
137a0 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74  re is filled wit
137b0 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20  h the currently 
137c0 64 65 66 69 6e 65 64 20 6d 75 74 65 78 20 72 6f  defined mutex ro
137d0 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69  utines.)^.** Thi
137e0 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20  s option can be 
137f0 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64  used to overload
13800 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74   the default mut
13810 65 78 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  ex allocation.**
13820 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61   routines with a
13830 20 77 72 61 70 70 65 72 20 75 73 65 64 20 74 6f   wrapper used to
13840 20 74 72 61 63 6b 20 6d 75 74 65 78 20 75 73 61   track mutex usa
13850 67 65 20 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e  ge for performan
13860 63 65 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20  ce.** profiling 
13870 6f 72 20 74 65 73 74 69 6e 67 2c 20 66 6f 72 20  or testing, for 
13880 65 78 61 6d 70 6c 65 2e 20 20 20 5e 49 66 20 53  example.   ^If S
13890 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
138a0 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53  d with.** the [S
138b0 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
138c0 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44   | SQLITE_THREAD
138d0 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d  SAFE=0] compile-
138e0 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e  time option then
138f0 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d  .** the entire m
13900 75 74 65 78 69 6e 67 20 73 75 62 73 79 73 74 65  utexing subsyste
13910 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f  m is omitted fro
13920 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20  m the build and 
13930 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a  hence calls to.*
13940 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
13950 67 28 29 5d 20 77 69 74 68 20 74 68 65 20 53 51  g()] with the SQ
13960 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
13970 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69  UTEX configurati
13980 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a  on option will.*
13990 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  * return [SQLITE
139a0 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a  _ERROR].</dd>.**
139b0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
139c0 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 5d 20  FIG_LOOKASIDE]] 
139d0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
139e0 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e  G_LOOKASIDE</dt>
139f0 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20  .** <dd> ^(This 
13a00 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f  option takes two
13a10 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20   arguments that 
13a20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64 65  determine the de
13a30 66 61 75 6c 74 0a 2a 2a 20 6d 65 6d 6f 72 79 20  fault.** memory 
13a40 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20 74  allocation for t
13a50 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  he lookaside mem
13a60 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 6f 6e  ory allocator on
13a70 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61   each.** [databa
13a80 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20  se connection]. 
13a90 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
13aa0 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69  ent is the.** si
13ab0 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61  ze of each looka
13ac0 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74  side buffer slot
13ad0 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20   and the second 
13ae0 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
13af0 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61  .** slots alloca
13b00 74 65 64 20 74 6f 20 65 61 63 68 20 64 61 74 61  ted to each data
13b10 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  base connection.
13b20 29 5e 20 20 5e 28 54 68 69 73 20 6f 70 74 69 6f  )^  ^(This optio
13b30 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 3c 69  n sets the.** <i
13b40 3e 64 65 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f  >default</i> loo
13b50 6b 61 73 69 64 65 20 73 69 7a 65 2e 20 54 68 65  kaside size. The
13b60 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49   [SQLITE_DBCONFI
13b70 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20  G_LOOKASIDE].** 
13b80 76 65 72 62 20 74 6f 20 5b 73 71 6c 69 74 65 33  verb to [sqlite3
13b90 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61  _db_config()] ca
13ba0 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63 68 61  n be used to cha
13bb0 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64  nge the lookasid
13bc0 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69  e.** configurati
13bd0 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c  on on individual
13be0 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e 20   connections.)^ 
13bf0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
13c00 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
13c10 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  HE2]] <dt>SQLITE
13c20 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 3c  _CONFIG_PCACHE2<
13c30 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
13c40 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
13c50 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
13c60 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f  nt which is a po
13c70 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 61 6e 20 5b  inter to.** an [
13c80 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d  sqlite3_pcache_m
13c90 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e  ethods2] object.
13ca0 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 73 70    This object sp
13cb0 65 63 69 66 69 65 73 20 74 68 65 20 69 6e 74 65  ecifies the inte
13cc0 72 66 61 63 65 0a 2a 2a 20 74 6f 20 61 20 63 75  rface.** to a cu
13cd0 73 74 6f 6d 20 70 61 67 65 20 63 61 63 68 65 20  stom page cache 
13ce0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 29  implementation.)
13cf0 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73  ^  ^SQLite makes
13d00 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a   a copy of the.*
13d10 2a 20 6f 62 6a 65 63 74 20 61 6e 64 20 75 73 65  * object and use
13d20 73 20 69 74 20 66 6f 72 20 70 61 67 65 20 63 61  s it for page ca
13d30 63 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  che memory alloc
13d40 61 74 69 6f 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a  ations.</dd>.**.
13d50 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
13d60 49 47 5f 47 45 54 50 43 41 43 48 45 32 5d 5d 20  IG_GETPCACHE2]] 
13d70 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
13d80 47 5f 47 45 54 50 43 41 43 48 45 32 3c 2f 64 74  G_GETPCACHE2</dt
13d90 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73  >.** <dd> ^(This
13da0 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
13db0 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
13dc0 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74  which is a point
13dd0 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c  er to an.** [sql
13de0 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68  ite3_pcache_meth
13df0 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20 53  ods2] object.  S
13e00 51 4c 69 74 65 20 63 6f 70 69 65 73 20 6f 66 20  QLite copies of 
13e10 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 70  the current.** p
13e20 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d  age cache implem
13e30 65 6e 74 61 74 69 6f 6e 20 69 6e 74 6f 20 74 68  entation into th
13e40 61 74 20 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f 64  at object.)^ </d
13e50 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
13e60 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 5d 5d 20 3c  E_CONFIG_LOG]] <
13e70 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
13e80 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  _LOG</dt>.** <dd
13e90 3e 20 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  > The SQLITE_CON
13ea0 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 69  FIG_LOG option i
13eb0 73 20 75 73 65 64 20 74 6f 20 63 6f 6e 66 69 67  s used to config
13ec0 75 72 65 20 74 68 65 20 53 51 4c 69 74 65 0a 2a  ure the SQLite.*
13ed0 2a 20 67 6c 6f 62 61 6c 20 5b 65 72 72 6f 72 20  * global [error 
13ee0 6c 6f 67 5d 2e 0a 2a 2a 20 28 5e 54 68 65 20 53  log]..** (^The S
13ef0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47  QLITE_CONFIG_LOG
13f00 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77   option takes tw
13f10 6f 20 61 72 67 75 6d 65 6e 74 73 3a 20 61 20 70  o arguments: a p
13f20 6f 69 6e 74 65 72 20 74 6f 20 61 0a 2a 2a 20 66  ointer to a.** f
13f30 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 63  unction with a c
13f40 61 6c 6c 20 73 69 67 6e 61 74 75 72 65 20 6f 66  all signature of
13f50 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 69   void(*)(void*,i
13f60 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c  nt,const char*),
13f70 20 0a 2a 2a 20 61 6e 64 20 61 20 70 6f 69 6e 74   .** and a point
13f80 65 72 20 74 6f 20 76 6f 69 64 2e 20 5e 49 66 20  er to void. ^If 
13f90 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69  the function poi
13fa0 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  nter is not NULL
13fb0 2c 20 69 74 20 69 73 0a 2a 2a 20 69 6e 76 6f 6b  , it is.** invok
13fc0 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c  ed by [sqlite3_l
13fd0 6f 67 28 29 5d 20 74 6f 20 70 72 6f 63 65 73 73  og()] to process
13fe0 20 65 61 63 68 20 6c 6f 67 67 69 6e 67 20 65 76   each logging ev
13ff0 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a  ent.  ^If the.**
14000 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65   function pointe
14010 72 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 20 5b  r is NULL, the [
14020 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 69  sqlite3_log()] i
14030 6e 74 65 72 66 61 63 65 20 62 65 63 6f 6d 65 73  nterface becomes
14040 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54 68   a no-op..** ^Th
14050 65 20 76 6f 69 64 20 70 6f 69 6e 74 65 72 20 74  e void pointer t
14060 68 61 74 20 69 73 20 74 68 65 20 73 65 63 6f 6e  hat is the secon
14070 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 53 51  d argument to SQ
14080 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20  LITE_CONFIG_LOG 
14090 69 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 68 72  is.** passed thr
140a0 6f 75 67 68 20 61 73 20 74 68 65 20 66 69 72 73  ough as the firs
140b0 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  t parameter to t
140c0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
140d0 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a  efined logger.**
140e0 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 6e 65 76   function whenev
140f0 65 72 20 74 68 61 74 20 66 75 6e 63 74 69 6f 6e  er that function
14100 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 54   is invoked.  ^T
14110 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
14120 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 6c 6f  ter to.** the lo
14130 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 20 69 73  gger function is
14140 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 66   a copy of the f
14150 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
14160 6f 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  o the correspond
14170 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
14180 6c 6f 67 28 29 5d 20 63 61 6c 6c 20 61 6e 64 20  log()] call and 
14190 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 62  is intended to b
141a0 65 20 61 20 5b 72 65 73 75 6c 74 20 63 6f 64 65  e a [result code
141b0 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 78 74 65  ] or an.** [exte
141c0 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
141d0 5d 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20 70  ].  ^The third p
141e0 61 72 61 6d 65 74 65 72 20 70 61 73 73 65 64 20  arameter passed 
141f0 74 6f 20 74 68 65 20 6c 6f 67 67 65 72 20 69 73  to the logger is
14200 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73 61 67 65 20  .** log message 
14210 61 66 74 65 72 20 66 6f 72 6d 61 74 74 69 6e 67  after formatting
14220 20 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 73 6e   via [sqlite3_sn
14230 70 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a 20 54 68  printf()]..** Th
14240 65 20 53 51 4c 69 74 65 20 6c 6f 67 67 69 6e 67  e SQLite logging
14250 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f   interface is no
14260 74 20 72 65 65 6e 74 72 61 6e 74 3b 20 74 68 65  t reentrant; the
14270 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e   logger function
14280 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20 62 79 20  .** supplied by 
14290 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
142a0 6d 75 73 74 20 6e 6f 74 20 69 6e 76 6f 6b 65 20  must not invoke 
142b0 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72  any SQLite inter
142c0 66 61 63 65 2e 0a 2a 2a 20 49 6e 20 61 20 6d 75  face..** In a mu
142d0 6c 74 69 2d 74 68 72 65 61 64 65 64 20 61 70 70  lti-threaded app
142e0 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65 20 61 70  lication, the ap
142f0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
14300 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63  d logger.** func
14310 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 74 68 72  tion must be thr
14320 65 61 64 73 61 66 65 2e 20 3c 2f 64 64 3e 0a 2a  eadsafe. </dd>.*
14330 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
14340 4e 46 49 47 5f 55 52 49 5d 5d 20 3c 64 74 3e 53  NFIG_URI]] <dt>S
14350 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49  QLITE_CONFIG_URI
14360 0a 2a 2a 20 3c 64 64 3e 5e 28 54 68 69 73 20 6f  .** <dd>^(This o
14370 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
14380 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66  ngle argument of
14390 20 74 79 70 65 20 69 6e 74 2e 20 49 66 20 6e 6f   type int. If no
143a0 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 0a 2a 2a 20  n-zero, then.** 
143b0 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20  URI handling is 
143c0 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c 65 64  globally enabled
143d0 2e 20 49 66 20 74 68 65 20 70 61 72 61 6d 65 74  . If the paramet
143e0 65 72 20 69 73 20 7a 65 72 6f 2c 20 74 68 65 6e  er is zero, then
143f0 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 0a 2a 2a   URI handling.**
14400 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73   is globally dis
14410 61 62 6c 65 64 2e 29 5e 20 5e 49 66 20 55 52 49  abled.)^ ^If URI
14420 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f   handling is glo
14430 62 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2c 20 61  bally enabled, a
14440 6c 6c 20 66 69 6c 65 6e 61 6d 65 73 0a 2a 2a 20  ll filenames.** 
14450 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74  passed to [sqlit
14460 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c  e3_open()], [sql
14470 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c  ite3_open_v2()],
14480 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
14490 28 29 5d 20 6f 72 0a 2a 2a 20 73 70 65 63 69 66  ()] or.** specif
144a0 69 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 5b  ied as part of [
144b0 41 54 54 41 43 48 5d 20 63 6f 6d 6d 61 6e 64 73  ATTACH] commands
144c0 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64   are interpreted
144d0 20 61 73 20 55 52 49 73 2c 20 72 65 67 61 72 64   as URIs, regard
144e0 6c 65 73 73 0a 2a 2a 20 6f 66 20 77 68 65 74 68  less.** of wheth
144f0 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 5b 53  er or not the [S
14500 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20  QLITE_OPEN_URI] 
14510 66 6c 61 67 20 69 73 20 73 65 74 20 77 68 65 6e  flag is set when
14520 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
14530 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f   connection is o
14540 70 65 6e 65 64 2e 20 5e 49 66 20 69 74 20 69 73  pened. ^If it is
14550 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c   globally disabl
14560 65 64 2c 20 66 69 6c 65 6e 61 6d 65 73 20 61 72  ed, filenames ar
14570 65 0a 2a 2a 20 6f 6e 6c 79 20 69 6e 74 65 72 70  e.** only interp
14580 72 65 74 65 64 20 61 73 20 55 52 49 73 20 69 66  reted as URIs if
14590 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e   the SQLITE_OPEN
145a0 5f 55 52 49 20 66 6c 61 67 20 69 73 20 73 65 74  _URI flag is set
145b0 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 64 61 74   when the.** dat
145c0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
145d0 20 69 73 20 6f 70 65 6e 65 64 2e 20 5e 28 42 79   is opened. ^(By
145e0 20 64 65 66 61 75 6c 74 2c 20 55 52 49 20 68 61   default, URI ha
145f0 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c  ndling is global
14600 6c 79 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 20  ly.** disabled. 
14610 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75  The default valu
14620 65 20 6d 61 79 20 62 65 20 63 68 61 6e 67 65 64  e may be changed
14630 20 62 79 20 63 6f 6d 70 69 6c 69 6e 67 20 77 69   by compiling wi
14640 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  th the.** [SQLIT
14650 45 5f 55 53 45 5f 55 52 49 5d 20 73 79 6d 62 6f  E_USE_URI] symbo
14660 6c 20 64 65 66 69 6e 65 64 2e 29 5e 0a 2a 2a 0a  l defined.)^.**.
14670 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
14680 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45  IG_COVERING_INDE
14690 58 5f 53 43 41 4e 5d 5d 20 3c 64 74 3e 53 51 4c  X_SCAN]] <dt>SQL
146a0 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52  ITE_CONFIG_COVER
146b0 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 0a 2a  ING_INDEX_SCAN.*
146c0 2a 20 3c 64 64 3e 5e 54 68 69 73 20 6f 70 74 69  * <dd>^This opti
146d0 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
146e0 65 20 69 6e 74 65 67 65 72 20 61 72 67 75 6d 65  e integer argume
146f0 6e 74 20 77 68 69 63 68 20 69 73 20 69 6e 74 65  nt which is inte
14700 72 70 72 65 74 65 64 20 61 73 0a 2a 2a 20 61 20  rpreted as.** a 
14710 62 6f 6f 6c 65 61 6e 20 69 6e 20 6f 72 64 65 72  boolean in order
14720 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69   to enable or di
14730 73 61 62 6c 65 20 74 68 65 20 75 73 65 20 6f 66  sable the use of
14740 20 63 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 65   covering indice
14750 73 20 66 6f 72 0a 2a 2a 20 66 75 6c 6c 20 74 61  s for.** full ta
14760 62 6c 65 20 73 63 61 6e 73 20 69 6e 20 74 68 65  ble scans in the
14770 20 71 75 65 72 79 20 6f 70 74 69 6d 69 7a 65 72   query optimizer
14780 2e 20 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20  .  ^The default 
14790 73 65 74 74 69 6e 67 20 69 73 20 64 65 74 65 72  setting is deter
147a0 6d 69 6e 65 64 0a 2a 2a 20 62 79 20 74 68 65 20  mined.** by the 
147b0 5b 53 51 4c 49 54 45 5f 41 4c 4c 4f 57 5f 43 4f  [SQLITE_ALLOW_CO
147c0 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41  VERING_INDEX_SCA
147d0 4e 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  N] compile-time 
147e0 6f 70 74 69 6f 6e 2c 20 6f 72 20 69 73 20 22 6f  option, or is "o
147f0 6e 22 0a 2a 2a 20 69 66 20 74 68 61 74 20 63 6f  n".** if that co
14800 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
14810 6e 20 69 73 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a  n is omitted..**
14820 20 54 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20   The ability to 
14830 64 69 73 61 62 6c 65 20 74 68 65 20 75 73 65 20  disable the use 
14840 6f 66 20 63 6f 76 65 72 69 6e 67 20 69 6e 64 69  of covering indi
14850 63 65 73 20 66 6f 72 20 66 75 6c 6c 20 74 61 62  ces for full tab
14860 6c 65 20 73 63 61 6e 73 0a 2a 2a 20 69 73 20 62  le scans.** is b
14870 65 63 61 75 73 65 20 73 6f 6d 65 20 69 6e 63 6f  ecause some inco
14880 72 72 65 63 74 6c 79 20 63 6f 64 65 64 20 6c 65  rrectly coded le
14890 67 61 63 79 20 61 70 70 6c 69 63 61 74 69 6f 6e  gacy application
148a0 73 20 6d 69 67 68 74 20 6d 61 6c 66 75 6e 63 74  s might malfunct
148b0 69 6f 6e 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20  ion.** when the 
148c0 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 69 73 20  optimization is 
148d0 65 6e 61 62 6c 65 64 2e 20 20 50 72 6f 76 69 64  enabled.  Provid
148e0 69 6e 67 20 74 68 65 20 61 62 69 6c 69 74 79 20  ing the ability 
148f0 74 6f 0a 2a 2a 20 64 69 73 61 62 6c 65 20 74 68  to.** disable th
14900 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 61  e optimization a
14910 6c 6c 6f 77 73 20 74 68 65 20 6f 6c 64 65 72 2c  llows the older,
14920 20 62 75 67 67 79 20 61 70 70 6c 69 63 61 74 69   buggy applicati
14930 6f 6e 20 63 6f 64 65 20 74 6f 20 77 6f 72 6b 0a  on code to work.
14940 2a 2a 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67  ** without chang
14950 65 20 65 76 65 6e 20 77 69 74 68 20 6e 65 77 65  e even with newe
14960 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  r versions of SQ
14970 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  Lite..**.** [[SQ
14980 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
14990 48 45 5d 5d 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  HE]] [[SQLITE_CO
149a0 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 5d 5d  NFIG_GETPCACHE]]
149b0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
149c0 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 61 6e 64  ONFIG_PCACHE and
149d0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
149e0 45 54 50 43 41 43 48 45 0a 2a 2a 20 3c 64 64 3e  ETPCACHE.** <dd>
149f0 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 73 20 61   These options a
14a00 72 65 20 6f 62 73 6f 6c 65 74 65 20 61 6e 64 20  re obsolete and 
14a10 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73  should not be us
14a20 65 64 20 62 79 20 6e 65 77 20 63 6f 64 65 2e 0a  ed by new code..
14a30 2a 2a 20 54 68 65 79 20 61 72 65 20 72 65 74 61  ** They are reta
14a40 69 6e 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72  ined for backwar
14a50 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
14a60 20 62 75 74 20 61 72 65 20 6e 6f 77 20 6e 6f 2d   but are now no-
14a70 6f 70 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a  ops..** </dd>.**
14a80 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
14a90 46 49 47 5f 53 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20  FIG_SQLLOG]].** 
14aa0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
14ab0 47 5f 53 51 4c 4c 4f 47 0a 2a 2a 20 3c 64 64 3e  G_SQLLOG.** <dd>
14ac0 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6f  This option is o
14ad0 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66  nly available if
14ae0 20 73 71 6c 69 74 65 20 69 73 20 63 6f 6d 70 69   sqlite is compi
14af0 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  led with the.** 
14b00 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53  [SQLITE_ENABLE_S
14b10 51 4c 4c 4f 47 5d 20 70 72 65 2d 70 72 6f 63 65  QLLOG] pre-proce
14b20 73 73 6f 72 20 6d 61 63 72 6f 20 64 65 66 69 6e  ssor macro defin
14b30 65 64 2e 20 54 68 65 20 66 69 72 73 74 20 61 72  ed. The first ar
14b40 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 0a 2a 2a  gument should.**
14b50 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   be a pointer to
14b60 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74   a function of t
14b70 79 70 65 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  ype void(*)(void
14b80 2a 2c 73 71 6c 69 74 65 33 2a 2c 63 6f 6e 73 74  *,sqlite3*,const
14b90 20 63 68 61 72 2a 2c 20 69 6e 74 29 2e 0a 2a 2a   char*, int)..**
14ba0 20 54 68 65 20 73 65 63 6f 6e 64 20 73 68 6f 75   The second shou
14bb0 6c 64 20 62 65 20 6f 66 20 74 79 70 65 20 28 76  ld be of type (v
14bc0 6f 69 64 2a 29 2e 20 54 68 65 20 63 61 6c 6c 62  oid*). The callb
14bd0 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 62  ack is invoked b
14be0 79 20 74 68 65 20 6c 69 62 72 61 72 79 0a 2a 2a  y the library.**
14bf0 20 69 6e 20 74 68 72 65 65 20 73 65 70 61 72 61   in three separa
14c00 74 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73  te circumstances
14c10 2c 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20  , identified by 
14c20 74 68 65 20 76 61 6c 75 65 20 70 61 73 73 65 64  the value passed
14c30 20 61 73 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74   as the.** fourt
14c40 68 20 70 61 72 61 6d 65 74 65 72 2e 20 49 66 20  h parameter. If 
14c50 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
14c60 65 74 65 72 20 69 73 20 30 2c 20 74 68 65 6e 20  eter is 0, then 
14c70 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
14c80 6e 65 63 74 69 6f 6e 0a 2a 2a 20 70 61 73 73 65  nection.** passe
14c90 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
14ca0 61 72 67 75 6d 65 6e 74 20 68 61 73 20 6a 75 73  argument has jus
14cb0 74 20 62 65 65 6e 20 6f 70 65 6e 65 64 2e 20 54  t been opened. T
14cc0 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
14cd0 74 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20 61  t.** points to a
14ce0 20 62 75 66 66 65 72 20 63 6f 6e 74 61 69 6e 69   buffer containi
14cf0 6e 67 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  ng the name of t
14d00 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65  he main database
14d10 20 66 69 6c 65 2e 20 49 66 20 74 68 65 0a 2a 2a   file. If the.**
14d20 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
14d30 72 20 69 73 20 31 2c 20 74 68 65 6e 20 74 68 65  r is 1, then the
14d40 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
14d50 68 61 74 20 74 68 65 20 74 68 69 72 64 20 70 61  hat the third pa
14d60 72 61 6d 65 74 65 72 0a 2a 2a 20 70 6f 69 6e 74  rameter.** point
14d70 73 20 74 6f 20 68 61 73 20 6a 75 73 74 20 62 65  s to has just be
14d80 65 6e 20 65 78 65 63 75 74 65 64 2e 20 4f 72 2c  en executed. Or,
14d90 20 69 66 20 74 68 65 20 66 6f 75 72 74 68 20 70   if the fourth p
14da0 61 72 61 6d 65 74 65 72 20 69 73 20 32 2c 20 74  arameter is 2, t
14db0 68 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6e 6e 65  hen.** the conne
14dc0 63 74 69 6f 6e 20 62 65 69 6e 67 20 70 61 73 73  ction being pass
14dd0 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
14de0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 62 65   parameter is be
14df0 69 6e 67 20 63 6c 6f 73 65 64 2e 20 54 68 65 0a  ing closed. The.
14e00 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  ** third paramet
14e10 65 72 20 69 73 20 70 61 73 73 65 64 20 4e 55 4c  er is passed NUL
14e20 4c 20 49 6e 20 74 68 69 73 20 63 61 73 65 2e 20  L In this case. 
14e30 20 41 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 75   An example of u
14e40 73 69 6e 67 20 74 68 69 73 0a 2a 2a 20 63 6f 6e  sing this.** con
14e50 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
14e60 6e 20 63 61 6e 20 62 65 20 73 65 65 6e 20 69 6e  n can be seen in
14e70 20 74 68 65 20 22 74 65 73 74 5f 73 71 6c 6c 6f   the "test_sqllo
14e80 67 2e 63 22 20 73 6f 75 72 63 65 20 66 69 6c 65  g.c" source file
14e90 20 69 6e 0a 2a 2a 20 74 68 65 20 63 61 6e 6f 6e   in.** the canon
14ea0 69 63 61 6c 20 53 51 4c 69 74 65 20 73 6f 75 72  ical SQLite sour
14eb0 63 65 20 74 72 65 65 2e 3c 2f 64 64 3e 0a 2a 2a  ce tree.</dd>.**
14ec0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
14ed0 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a  FIG_MMAP_SIZE]].
14ee0 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
14ef0 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 0a 2a  NFIG_MMAP_SIZE.*
14f00 2a 20 3c 64 64 3e 5e 53 51 4c 49 54 45 5f 43 4f  * <dd>^SQLITE_CO
14f10 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 20 74  NFIG_MMAP_SIZE t
14f20 61 6b 65 73 20 74 77 6f 20 36 34 2d 62 69 74 20  akes two 64-bit 
14f30 69 6e 74 65 67 65 72 20 28 73 71 6c 69 74 65 33  integer (sqlite3
14f40 5f 69 6e 74 36 34 29 20 76 61 6c 75 65 73 0a 2a  _int64) values.*
14f50 2a 20 74 68 61 74 20 61 72 65 20 74 68 65 20 64  * that are the d
14f60 65 66 61 75 6c 74 20 6d 6d 61 70 20 73 69 7a 65  efault mmap size
14f70 20 6c 69 6d 69 74 20 28 74 68 65 20 64 65 66 61   limit (the defa
14f80 75 6c 74 20 73 65 74 74 69 6e 67 20 66 6f 72 0a  ult setting for.
14f90 2a 2a 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f  ** [PRAGMA mmap_
14fa0 73 69 7a 65 5d 29 20 61 6e 64 20 74 68 65 20 6d  size]) and the m
14fb0 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d  aximum allowed m
14fc0 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69 74 2e 0a  map size limit..
14fd0 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20  ** ^The default 
14fe0 73 65 74 74 69 6e 67 20 63 61 6e 20 62 65 20 6f  setting can be o
14ff0 76 65 72 72 69 64 64 65 6e 20 62 79 20 65 61 63  verridden by eac
15000 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  h database conne
15010 63 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 65  ction using.** e
15020 69 74 68 65 72 20 74 68 65 20 5b 50 52 41 47 4d  ither the [PRAGM
15030 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 20 63 6f 6d  A mmap_size] com
15040 6d 61 6e 64 2c 20 6f 72 20 62 79 20 75 73 69 6e  mand, or by usin
15050 67 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  g the.** [SQLITE
15060 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45  _FCNTL_MMAP_SIZE
15070 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 2e 20  ] file control. 
15080 20 5e 28 54 68 65 20 6d 61 78 69 6d 75 6d 20 61   ^(The maximum a
15090 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a 65  llowed mmap size
150a0 0a 2a 2a 20 63 61 6e 6e 6f 74 20 62 65 20 63 68  .** cannot be ch
150b0 61 6e 67 65 64 20 61 74 20 72 75 6e 2d 74 69 6d  anged at run-tim
150c0 65 2e 20 20 4e 6f 72 20 6d 61 79 20 74 68 65 20  e.  Nor may the 
150d0 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20  maximum allowed 
150e0 6d 6d 61 70 20 73 69 7a 65 0a 2a 2a 20 65 78 63  mmap size.** exc
150f0 65 65 64 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d  eed the compile-
15100 74 69 6d 65 20 6d 61 78 69 6d 75 6d 20 6d 6d 61  time maximum mma
15110 70 20 73 69 7a 65 20 73 65 74 20 62 79 20 74 68  p size set by th
15120 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 41 58  e.** [SQLITE_MAX
15130 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 63 6f 6d 70  _MMAP_SIZE] comp
15140 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e  ile-time option.
15150 29 5e 0a 2a 2a 20 5e 49 66 20 65 69 74 68 65 72  )^.** ^If either
15160 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 69   argument to thi
15170 73 20 6f 70 74 69 6f 6e 20 69 73 20 6e 65 67 61  s option is nega
15180 74 69 76 65 2c 20 74 68 65 6e 20 74 68 61 74 20  tive, then that 
15190 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 63  argument is.** c
151a0 68 61 6e 67 65 64 20 74 6f 20 69 74 73 20 63 6f  hanged to its co
151b0 6d 70 69 6c 65 2d 74 69 6d 65 20 64 65 66 61 75  mpile-time defau
151c0 6c 74 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a  lt..** </dl>.*/.
151d0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
151e0 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
151f0 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f  AD  1  /* nil */
15200 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
15210 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
15220 41 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20 2a  AD   2  /* nil *
15230 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
15240 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a  _CONFIG_SERIALIZ
15250 45 44 20 20 20 20 33 20 20 2f 2a 20 6e 69 6c 20  ED    3  /* nil 
15260 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
15270 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20  E_CONFIG_MALLOC 
15280 20 20 20 20 20 20 20 34 20 20 2f 2a 20 73 71 6c         4  /* sql
15290 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
152a0 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
152b0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41  ITE_CONFIG_GETMA
152c0 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a 20 73  LLOC     5  /* s
152d0 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
152e0 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ds* */.#define S
152f0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
15300 41 54 43 48 20 20 20 20 20 20 20 36 20 20 2f 2a  ATCH       6  /*
15310 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20   void*, int sz, 
15320 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65  int N */.#define
15330 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
15340 41 47 45 43 41 43 48 45 20 20 20 20 20 37 20 20  AGECACHE     7  
15350 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a  /* void*, int sz
15360 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69  , int N */.#defi
15370 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
15380 5f 48 45 41 50 20 20 20 20 20 20 20 20 20 20 38  _HEAP          8
15390 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20    /* void*, int 
153a0 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20 2a  nByte, int min *
153b0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
153c0 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
153d0 53 20 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f 6c  S     9  /* bool
153e0 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ean */.#define S
153f0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54  QLITE_CONFIG_MUT
15400 45 58 20 20 20 20 20 20 20 20 31 30 20 20 2f 2a  EX        10  /*
15410 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d   sqlite3_mutex_m
15420 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69  ethods* */.#defi
15430 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
15440 5f 47 45 54 4d 55 54 45 58 20 20 20 20 20 31 31  _GETMUTEX     11
15450 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74    /* sqlite3_mut
15460 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f  ex_methods* */./
15470 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 53 51 4c  * previously SQL
15480 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e 4b  ITE_CONFIG_CHUNK
15490 41 4c 4c 4f 43 20 31 32 20 77 68 69 63 68 20 69  ALLOC 12 which i
154a0 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a 2f  s now unused. */
154b0 20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45   .#define SQLITE
154c0 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  _CONFIG_LOOKASID
154d0 45 20 20 20 20 31 33 20 20 2f 2a 20 69 6e 74 20  E    13  /* int 
154e0 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  int */.#define S
154f0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
15500 43 48 45 20 20 20 20 20 20 20 31 34 20 20 2f 2a  CHE       14  /*
15510 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e   no-op */.#defin
15520 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
15530 47 45 54 50 43 41 43 48 45 20 20 20 20 31 35 20  GETPCACHE    15 
15540 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65   /* no-op */.#de
15550 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
15560 49 47 5f 4c 4f 47 20 20 20 20 20 20 20 20 20 20  IG_LOG          
15570 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20 76 6f  16  /* xFunc, vo
15580 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  id* */.#define S
15590 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49  QLITE_CONFIG_URI
155a0 20 20 20 20 20 20 20 20 20 20 31 37 20 20 2f 2a            17  /*
155b0 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20   int */.#define 
155c0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
155d0 41 43 48 45 32 20 20 20 20 20 20 31 38 20 20 2f  ACHE2      18  /
155e0 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65  * sqlite3_pcache
155f0 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64  _methods2* */.#d
15600 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
15610 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 20 20  FIG_GETPCACHE2  
15620 20 31 39 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f   19  /* sqlite3_
15630 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a  pcache_methods2*
15640 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
15650 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49  TE_CONFIG_COVERI
15660 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20 32 30  NG_INDEX_SCAN 20
15670 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66    /* int */.#def
15680 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
15690 47 5f 53 51 4c 4c 4f 47 20 20 20 20 20 20 20 32  G_SQLLOG       2
156a0 31 20 20 2f 2a 20 78 53 71 6c 6c 6f 67 2c 20 76  1  /* xSqllog, v
156b0 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  oid* */.#define 
156c0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d  SQLITE_CONFIG_MM
156d0 41 50 5f 53 49 5a 45 20 20 20 20 32 32 20 20 2f  AP_SIZE    22  /
156e0 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c  * sqlite3_int64,
156f0 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a   sqlite3_int64 *
15700 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
15710 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e  F: Database Conn
15720 65 63 74 69 6f 6e 20 43 6f 6e 66 69 67 75 72 61  ection Configura
15730 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a  tion Options.**.
15740 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
15750 74 73 20 61 72 65 20 74 68 65 20 61 76 61 69 6c  ts are the avail
15760 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  able integer con
15770 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
15780 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62  ns that.** can b
15790 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
157a0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
157b0 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
157c0 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74  db_config()] int
157d0 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65  erface..**.** Ne
157e0 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  w configuration 
157f0 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61  options may be a
15800 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72  dded in future r
15810 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74  eleases of SQLit
15820 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63  e..** Existing c
15830 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
15840 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69  ions might be di
15850 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70  scontinued.  App
15860 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f  lications.** sho
15870 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 65  uld check the re
15880 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b  turn code from [
15890 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
158a0 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72  g()] to make sur
158b0 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61  e that.** the ca
158c0 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 5e 54 68 65  ll worked.  ^The
158d0 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
158e0 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  fig()] interface
158f0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a   will return a.*
15900 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f  * non-zero [erro
15910 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73  r code] if a dis
15920 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73  continued or uns
15930 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75  upported configu
15940 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a  ration option.**
15950 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a   is invoked..**.
15960 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53  ** <dl>.** <dt>S
15970 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
15980 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a  OOKASIDE</dt>.**
15990 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69   <dd> ^This opti
159a0 6f 6e 20 74 61 6b 65 73 20 74 68 72 65 65 20 61  on takes three a
159b0 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65  dditional argume
159c0 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d 69  nts that determi
159d0 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b  ne the .** [look
159e0 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  aside memory all
159f0 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72  ocator] configur
15a00 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64  ation for the [d
15a10 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
15a20 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72  on]..** ^The fir
15a30 73 74 20 61 72 67 75 6d 65 6e 74 20 28 74 68 65  st argument (the
15a40 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
15a50 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f   to [sqlite3_db_
15a60 63 6f 6e 66 69 67 28 29 5d 20 69 73 20 61 0a 2a  config()] is a.*
15a70 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d  * pointer to a m
15a80 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 6f 20  emory buffer to 
15a90 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64  use for lookasid
15aa0 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68  e memory..** ^Th
15ab0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
15ac0 20 61 66 74 65 72 20 74 68 65 20 53 51 4c 49 54   after the SQLIT
15ad0 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
15ae0 53 49 44 45 20 76 65 72 62 0a 2a 2a 20 6d 61 79  SIDE verb.** may
15af0 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63   be NULL in whic
15b00 68 20 63 61 73 65 20 53 51 4c 69 74 65 20 77 69  h case SQLite wi
15b10 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a  ll allocate the.
15b20 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66  ** lookaside buf
15b30 66 65 72 20 69 74 73 65 6c 66 20 75 73 69 6e 67  fer itself using
15b40 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
15b50 28 29 5d 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64  ()]. ^The second
15b60 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
15b70 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68  .** size of each
15b80 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65   lookaside buffe
15b90 72 20 73 6c 6f 74 2e 20 20 5e 54 68 65 20 74 68  r slot.  ^The th
15ba0 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ird argument is 
15bb0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
15bc0 20 73 6c 6f 74 73 2e 20 20 54 68 65 20 73 69 7a   slots.  The siz
15bd0 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20  e of the buffer 
15be0 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67  in the first arg
15bf0 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 67 72  ument must be gr
15c00 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72  eater than.** or
15c10 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20 70 72   equal to the pr
15c20 6f 64 75 63 74 20 6f 66 20 74 68 65 20 73 65 63  oduct of the sec
15c30 6f 6e 64 20 61 6e 64 20 74 68 69 72 64 20 61 72  ond and third ar
15c40 67 75 6d 65 6e 74 73 2e 20 20 54 68 65 20 62 75  guments.  The bu
15c50 66 66 65 72 0a 2a 2a 20 6d 75 73 74 20 62 65 20  ffer.** must be 
15c60 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d  aligned to an 8-
15c70 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2e 20 20  byte boundary.  
15c80 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61  ^If the second a
15c90 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 51  rgument to.** SQ
15ca0 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
15cb0 4f 4b 41 53 49 44 45 20 69 73 20 6e 6f 74 20 61  OKASIDE is not a
15cc0 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20   multiple of 8, 
15cd0 69 74 20 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79  it is internally
15ce0 0a 2a 2a 20 72 6f 75 6e 64 65 64 20 64 6f 77 6e  .** rounded down
15cf0 20 74 6f 20 74 68 65 20 6e 65 78 74 20 73 6d 61   to the next sma
15d00 6c 6c 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66  ller multiple of
15d10 20 38 2e 20 20 5e 28 54 68 65 20 6c 6f 6f 6b 61   8.  ^(The looka
15d20 73 69 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63  side memory.** c
15d30 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72  onfiguration for
15d40 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e   a database conn
15d50 65 63 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20  ection can only 
15d60 62 65 20 63 68 61 6e 67 65 64 20 77 68 65 6e 20  be changed when 
15d70 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  that.** connecti
15d80 6f 6e 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e  on is not curren
15d90 74 6c 79 20 75 73 69 6e 67 20 6c 6f 6f 6b 61 73  tly using lookas
15da0 69 64 65 20 6d 65 6d 6f 72 79 2c 20 6f 72 20 69  ide memory, or i
15db0 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 0a 2a 2a  n other words.**
15dc0 20 77 68 65 6e 20 74 68 65 20 22 63 75 72 72 65   when the "curre
15dd0 6e 74 20 76 61 6c 75 65 22 20 72 65 74 75 72 6e  nt value" return
15de0 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65  ed by.** [sqlite
15df0 33 5f 64 62 5f 73 74 61 74 75 73 5d 28 44 2c 5b  3_db_status](D,[
15e00 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
15e10 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29 20 69 73  OKASIDE],...) is
15e20 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74   zero..** Any at
15e30 74 65 6d 70 74 20 74 6f 20 63 68 61 6e 67 65 20  tempt to change 
15e40 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  the lookaside me
15e50 6d 6f 72 79 20 63 6f 6e 66 69 67 75 72 61 74 69  mory configurati
15e60 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61 73 69 64  on when lookasid
15e70 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69 73 20 69  e.** memory is i
15e80 6e 20 75 73 65 20 6c 65 61 76 65 73 20 74 68 65  n use leaves the
15e90 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75   configuration u
15ea0 6e 63 68 61 6e 67 65 64 20 61 6e 64 20 72 65 74  nchanged and ret
15eb0 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45  urns .** [SQLITE
15ec0 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a  _BUSY].)^</dd>.*
15ed0 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
15ee0 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f  DBCONFIG_ENABLE_
15ef0 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  FKEY</dt>.** <dd
15f00 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69  > ^This option i
15f10 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65  s used to enable
15f20 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65 20   or disable the 
15f30 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 66 0a 2a  enforcement of.*
15f40 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 63  * [foreign key c
15f50 6f 6e 73 74 72 61 69 6e 74 73 5d 2e 20 20 54 68  onstraints].  Th
15f60 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77  ere should be tw
15f70 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67  o additional arg
15f80 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66  uments..** The f
15f90 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73  irst argument is
15fa0 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63   an integer whic
15fb0 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c  h is 0 to disabl
15fc0 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74  e FK enforcement
15fd0 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f  ,.** positive to
15fe0 20 65 6e 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72   enable FK enfor
15ff0 63 65 6d 65 6e 74 20 6f 72 20 6e 65 67 61 74 69  cement or negati
16000 76 65 20 74 6f 20 6c 65 61 76 65 20 46 4b 20 65  ve to leave FK e
16010 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e  nforcement.** un
16020 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20 73 65  changed.  The se
16030 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
16040 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
16050 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77  n integer into w
16060 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74  hich.** is writt
16070 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64  en 0 or 1 to ind
16080 69 63 61 74 65 20 77 68 65 74 68 65 72 20 46 4b  icate whether FK
16090 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 69 73 20   enforcement is 
160a0 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c  off or on.** fol
160b0 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c  lowing this call
160c0 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  .  The second pa
160d0 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61  rameter may be a
160e0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69   NULL pointer, i
160f0 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20  n.** which case 
16100 74 68 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65  the FK enforceme
16110 6e 74 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f  nt setting is no
16120 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e  t reported back.
16130 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74   </dd>.**.** <dt
16140 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  >SQLITE_DBCONFIG
16150 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 3c  _ENABLE_TRIGGER<
16160 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
16170 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  is option is use
16180 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64  d to enable or d
16190 69 73 61 62 6c 65 20 5b 43 52 45 41 54 45 20 54  isable [CREATE T
161a0 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 72  RIGGER | trigger
161b0 73 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f  s]..** There sho
161c0 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74  uld be two addit
161d0 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e  ional arguments.
161e0 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
161f0 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74  gument is an int
16200 65 67 65 72 20 77 68 69 63 68 20 69 73 20 30 20  eger which is 0 
16210 74 6f 20 64 69 73 61 62 6c 65 20 74 72 69 67 67  to disable trigg
16220 65 72 73 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65  ers,.** positive
16230 20 74 6f 20 65 6e 61 62 6c 65 20 74 72 69 67 67   to enable trigg
16240 65 72 73 20 6f 72 20 6e 65 67 61 74 69 76 65 20  ers or negative 
16250 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65 74  to leave the set
16260 74 69 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a  ting unchanged..
16270 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  ** The second pa
16280 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69  rameter is a poi
16290 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67  nter to an integ
162a0 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a  er into which.**
162b0 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72   is written 0 or
162c0 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77   1 to indicate w
162d0 68 65 74 68 65 72 20 74 72 69 67 67 65 72 73 20  hether triggers 
162e0 61 72 65 20 64 69 73 61 62 6c 65 64 20 6f 72 20  are disabled or 
162f0 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f  enabled.** follo
16300 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20  wing this call. 
16310 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
16320 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e  meter may be a N
16330 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a  ULL pointer, in.
16340 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 68  ** which case th
16350 65 20 74 72 69 67 67 65 72 20 73 65 74 74 69 6e  e trigger settin
16360 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65  g is not reporte
16370 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a  d back. </dd>.**
16380 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65  .** </dl>.*/.#de
16390 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f  fine SQLITE_DBCO
163a0 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20  NFIG_LOOKASIDE  
163b0 20 20 20 20 20 31 30 30 31 20 20 2f 2a 20 76 6f       1001  /* vo
163c0 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23  id* int int */.#
163d0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42  define SQLITE_DB
163e0 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b  CONFIG_ENABLE_FK
163f0 45 59 20 20 20 20 20 31 30 30 32 20 20 2f 2a 20  EY     1002  /* 
16400 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66  int int* */.#def
16410 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ine SQLITE_DBCON
16420 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47  FIG_ENABLE_TRIGG
16430 45 52 20 20 31 30 30 33 20 20 2f 2a 20 69 6e 74  ER  1003  /* int
16440 20 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a   int* */.../*.**
16450 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c   CAPI3REF: Enabl
16460 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74  e Or Disable Ext
16470 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64  ended Result Cod
16480 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  es.**.** ^The sq
16490 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72  lite3_extended_r
164a0 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f  esult_codes() ro
164b0 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72  utine enables or
164c0 20 64 69 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a   disables the.**
164d0 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
164e0 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75 72 65  t codes] feature
164f0 20 6f 66 20 53 51 4c 69 74 65 2e 20 5e 54 68 65   of SQLite. ^The
16500 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
16510 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65 20 64 69  .** codes are di
16520 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  sabled by defaul
16530 74 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c  t for historical
16540 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a   compatibility..
16550 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
16560 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64  t sqlite3_extend
16570 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28  ed_result_codes(
16580 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 6e  sqlite3*, int on
16590 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  off);../*.** CAP
165a0 49 33 52 45 46 3a 20 4c 61 73 74 20 49 6e 73 65  I3REF: Last Inse
165b0 72 74 20 52 6f 77 69 64 0a 2a 2a 0a 2a 2a 20 5e  rt Rowid.**.** ^
165c0 45 61 63 68 20 65 6e 74 72 79 20 69 6e 20 6d 6f  Each entry in mo
165d0 73 74 20 53 51 4c 69 74 65 20 74 61 62 6c 65 73  st SQLite tables
165e0 20 28 65 78 63 65 70 74 20 66 6f 72 20 5b 57 49   (except for [WI
165f0 54 48 4f 55 54 20 52 4f 57 49 44 5d 20 74 61 62  THOUT ROWID] tab
16600 6c 65 73 29 0a 2a 2a 20 68 61 73 20 61 20 75 6e  les).** has a un
16610 69 71 75 65 20 36 34 2d 62 69 74 20 73 69 67 6e  ique 64-bit sign
16620 65 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65  ed.** integer ke
16630 79 20 63 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f  y called the [RO
16640 57 49 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20  WID | "rowid"]. 
16650 5e 54 68 65 20 72 6f 77 69 64 20 69 73 20 61 6c  ^The rowid is al
16660 77 61 79 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a  ways available.*
16670 2a 20 61 73 20 61 6e 20 75 6e 64 65 63 6c 61 72  * as an undeclar
16680 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20  ed column named 
16690 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f  ROWID, OID, or _
166a0 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61  ROWID_ as long a
166b0 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73  s those.** names
166c0 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73   are not also us
166d0 65 64 20 62 79 20 65 78 70 6c 69 63 69 74 6c 79  ed by explicitly
166e0 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e   declared column
166f0 73 2e 20 5e 49 66 0a 2a 2a 20 74 68 65 20 74 61  s. ^If.** the ta
16700 62 6c 65 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e  ble has a column
16710 20 6f 66 20 74 79 70 65 20 5b 49 4e 54 45 47 45   of type [INTEGE
16720 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 74  R PRIMARY KEY] t
16730 68 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a  hen that column.
16740 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72 20 61 6c  ** is another al
16750 69 61 73 20 66 6f 72 20 74 68 65 20 72 6f 77 69  ias for the rowi
16760 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
16770 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72  lite3_last_inser
16780 74 5f 72 6f 77 69 64 28 44 29 20 69 6e 74 65 72  t_rowid(D) inter
16790 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
167a0 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20   [rowid] of the 
167b0 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  .** most recent 
167c0 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45  successful [INSE
167d0 52 54 5d 20 69 6e 74 6f 20 61 20 72 6f 77 69 64  RT] into a rowid
167e0 20 74 61 62 6c 65 20 6f 72 20 5b 76 69 72 74 75   table or [virtu
167f0 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 6f 6e 20  al table].** on 
16800 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
16810 69 6f 6e 20 44 2e 0a 2a 2a 20 5e 49 6e 73 65 72  ion D..** ^Inser
16820 74 73 20 69 6e 74 6f 20 5b 57 49 54 48 4f 55 54  ts into [WITHOUT
16830 20 52 4f 57 49 44 5d 20 74 61 62 6c 65 73 20 61   ROWID] tables a
16840 72 65 20 6e 6f 74 20 72 65 63 6f 72 64 65 64 2e  re not recorded.
16850 0a 2a 2a 20 5e 49 66 20 6e 6f 20 73 75 63 63 65  .** ^If no succe
16860 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 73 20  ssful [INSERT]s 
16870 69 6e 74 6f 20 72 6f 77 69 64 20 74 61 62 6c 65  into rowid table
16880 73 0a 2a 2a 20 68 61 76 65 20 65 76 65 72 20 6f  s.** have ever o
16890 63 63 75 72 72 65 64 20 6f 6e 20 74 68 65 20 64  ccurred on the d
168a0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
168b0 6f 6e 20 44 2c 20 0a 2a 2a 20 74 68 65 6e 20 73  on D, .** then s
168c0 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
168d0 72 74 5f 72 6f 77 69 64 28 44 29 20 72 65 74 75  rt_rowid(D) retu
168e0 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20  rns zero..**.** 
168f0 5e 28 49 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d  ^(If an [INSERT]
16900 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61   occurs within a
16910 20 74 72 69 67 67 65 72 20 6f 72 20 77 69 74 68   trigger or with
16920 69 6e 20 61 20 5b 76 69 72 74 75 61 6c 20 74 61  in a [virtual ta
16930 62 6c 65 5d 0a 2a 2a 20 6d 65 74 68 6f 64 2c 20  ble].** method, 
16940 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e  then this routin
16950 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 74 68  e will return th
16960 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65  e [rowid] of the
16970 20 69 6e 73 65 72 74 65 64 0a 2a 2a 20 72 6f 77   inserted.** row
16980 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20   as long as the 
16990 74 72 69 67 67 65 72 20 6f 72 20 76 69 72 74 75  trigger or virtu
169a0 61 6c 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20  al table method 
169b0 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42  is running..** B
169c0 75 74 20 6f 6e 63 65 20 74 68 65 20 74 72 69 67  ut once the trig
169d0 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c 20 74  ger or virtual t
169e0 61 62 6c 65 20 6d 65 74 68 6f 64 20 65 6e 64 73  able method ends
169f0 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  , the value retu
16a00 72 6e 65 64 20 0a 2a 2a 20 62 79 20 74 68 69 73  rned .** by this
16a10 20 72 6f 75 74 69 6e 65 20 72 65 76 65 72 74 73   routine reverts
16a20 20 74 6f 20 77 68 61 74 20 69 74 20 77 61 73 20   to what it was 
16a30 62 65 66 6f 72 65 20 74 68 65 20 74 72 69 67 67  before the trigg
16a40 65 72 20 6f 72 20 76 69 72 74 75 61 6c 0a 2a 2a  er or virtual.**
16a50 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 62 65   table method be
16a60 67 61 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e  gan.)^.**.** ^An
16a70 20 5b 49 4e 53 45 52 54 5d 20 74 68 61 74 20 66   [INSERT] that f
16a80 61 69 6c 73 20 64 75 65 20 74 6f 20 61 20 63 6f  ails due to a co
16a90 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69  nstraint violati
16aa0 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73  on is not a.** s
16ab0 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52  uccessful [INSER
16ac0 54 5d 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20  T] and does not 
16ad0 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65  change the value
16ae0 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69   returned by thi
16af0 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20 5e  s.** routine.  ^
16b00 54 68 75 73 20 49 4e 53 45 52 54 20 4f 52 20 46  Thus INSERT OR F
16b10 41 49 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20 49  AIL, INSERT OR I
16b20 47 4e 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f 52  GNORE, INSERT OR
16b30 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e   ROLLBACK,.** an
16b40 64 20 49 4e 53 45 52 54 20 4f 52 20 41 42 4f 52  d INSERT OR ABOR
16b50 54 20 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65  T make no change
16b60 73 20 74 6f 20 74 68 65 20 72 65 74 75 72 6e 20  s to the return 
16b70 76 61 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a  value of this.**
16b80 20 72 6f 75 74 69 6e 65 20 77 68 65 6e 20 74 68   routine when th
16b90 65 69 72 20 69 6e 73 65 72 74 69 6f 6e 20 66 61  eir insertion fa
16ba0 69 6c 73 2e 20 20 5e 28 57 68 65 6e 20 49 4e 53  ils.  ^(When INS
16bb0 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 0a 2a  ERT OR REPLACE.*
16bc0 2a 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 20 63  * encounters a c
16bd0 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74  onstraint violat
16be0 69 6f 6e 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74  ion, it does not
16bf0 20 66 61 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49   fail.  The.** I
16c00 4e 53 45 52 54 20 63 6f 6e 74 69 6e 75 65 73 20  NSERT continues 
16c10 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66  to completion af
16c20 74 65 72 20 64 65 6c 65 74 69 6e 67 20 72 6f 77  ter deleting row
16c30 73 20 74 68 61 74 20 63 61 75 73 65 64 0a 2a 2a  s that caused.**
16c40 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 20   the constraint 
16c50 70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52  problem so INSER
16c60 54 20 4f 52 20 52 45 50 4c 41 43 45 20 77 69 6c  T OR REPLACE wil
16c70 6c 20 61 6c 77 61 79 73 20 63 68 61 6e 67 65 0a  l always change.
16c80 2a 2a 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  ** the return va
16c90 6c 75 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65  lue of this inte
16ca0 72 66 61 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  rface.)^.**.** ^
16cb0 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65 73  For the purposes
16cc0 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65   of this routine
16cd0 2c 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 69 73  , an [INSERT] is
16ce0 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a   considered to.*
16cf0 2a 20 62 65 20 73 75 63 63 65 73 73 66 75 6c 20  * be successful 
16d00 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 73 75  even if it is su
16d10 62 73 65 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65  bsequently rolle
16d20 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68  d back..**.** Th
16d30 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61  is function is a
16d40 63 63 65 73 73 69 62 6c 65 20 74 6f 20 53 51 4c  ccessible to SQL
16d50 20 73 74 61 74 65 6d 65 6e 74 73 20 76 69 61 20   statements via 
16d60 74 68 65 0a 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73  the.** [last_ins
16d70 65 72 74 5f 72 6f 77 69 64 28 29 20 53 51 4c 20  ert_rowid() SQL 
16d80 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a  function]..**.**
16d90 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74   If a separate t
16da0 68 72 65 61 64 20 70 65 72 66 6f 72 6d 73 20 61  hread performs a
16db0 20 6e 65 77 20 5b 49 4e 53 45 52 54 5d 20 6f 6e   new [INSERT] on
16dc0 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 64 61 74   the same.** dat
16dd0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
16de0 20 77 68 69 6c 65 20 74 68 65 20 5b 73 71 6c 69   while the [sqli
16df0 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
16e00 72 6f 77 69 64 28 29 5d 0a 2a 2a 20 66 75 6e 63  rowid()].** func
16e10 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20  tion is running 
16e20 61 6e 64 20 74 68 75 73 20 63 68 61 6e 67 65 73  and thus changes
16e30 20 74 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74   the last insert
16e40 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68 65   [rowid],.** the
16e50 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  n the value retu
16e60 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
16e70 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
16e80 69 64 28 29 5d 20 69 73 0a 2a 2a 20 75 6e 70 72  id()] is.** unpr
16e90 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6d 69  edictable and mi
16ea0 67 68 74 20 6e 6f 74 20 65 71 75 61 6c 20 65 69  ght not equal ei
16eb0 74 68 65 72 20 74 68 65 20 6f 6c 64 20 6f 72 20  ther the old or 
16ec0 74 68 65 20 6e 65 77 0a 2a 2a 20 6c 61 73 74 20  the new.** last 
16ed0 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2e 0a  insert [rowid]..
16ee0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71  */.SQLITE_API sq
16ef0 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
16f00 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
16f10 72 6f 77 69 64 28 73 71 6c 69 74 65 33 2a 29 3b  rowid(sqlite3*);
16f20 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
16f30 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62  : Count The Numb
16f40 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66  er Of Rows Modif
16f50 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  ied.**.** ^This 
16f60 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
16f70 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64   the number of d
16f80 61 74 61 62 61 73 65 20 72 6f 77 73 20 74 68 61  atabase rows tha
16f90 74 20 77 65 72 65 20 63 68 61 6e 67 65 64 0a 2a  t were changed.*
16fa0 2a 20 6f 72 20 69 6e 73 65 72 74 65 64 20 6f 72  * or inserted or
16fb0 20 64 65 6c 65 74 65 64 20 62 79 20 74 68 65 20   deleted by the 
16fc0 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f  most recently co
16fd0 6d 70 6c 65 74 65 64 20 53 51 4c 20 73 74 61 74  mpleted SQL stat
16fe0 65 6d 65 6e 74 0a 2a 2a 20 6f 6e 20 74 68 65 20  ement.** on the 
16ff0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
17000 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20  tion] specified 
17010 62 79 20 74 68 65 20 66 69 72 73 74 20 70 61 72  by the first par
17020 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 28 4f 6e 6c  ameter..** ^(Onl
17030 79 20 63 68 61 6e 67 65 73 20 74 68 61 74 20 61  y changes that a
17040 72 65 20 64 69 72 65 63 74 6c 79 20 73 70 65 63  re directly spec
17050 69 66 69 65 64 20 62 79 20 74 68 65 20 5b 49 4e  ified by the [IN
17060 53 45 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d 2c  SERT], [UPDATE],
17070 0a 2a 2a 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20  .** or [DELETE] 
17080 73 74 61 74 65 6d 65 6e 74 20 61 72 65 20 63 6f  statement are co
17090 75 6e 74 65 64 2e 20 20 41 75 78 69 6c 69 61 72  unted.  Auxiliar
170a0 79 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64  y changes caused
170b0 20 62 79 0a 2a 2a 20 74 72 69 67 67 65 72 73 20   by.** triggers 
170c0 6f 72 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20  or [foreign key 
170d0 61 63 74 69 6f 6e 73 5d 20 61 72 65 20 6e 6f 74  actions] are not
170e0 20 63 6f 75 6e 74 65 64 2e 29 5e 20 55 73 65 20   counted.)^ Use 
170f0 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
17100 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d  total_changes()]
17110 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 66 69 6e   function to fin
17120 64 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62  d the total numb
17130 65 72 20 6f 66 20 63 68 61 6e 67 65 73 0a 2a 2a  er of changes.**
17140 20 69 6e 63 6c 75 64 69 6e 67 20 63 68 61 6e 67   including chang
17150 65 73 20 63 61 75 73 65 64 20 62 79 20 74 72 69  es caused by tri
17160 67 67 65 72 73 20 61 6e 64 20 66 6f 72 65 69 67  ggers and foreig
17170 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 2e 0a 2a  n key actions..*
17180 2a 0a 2a 2a 20 5e 43 68 61 6e 67 65 73 20 74 6f  *.** ^Changes to
17190 20 61 20 76 69 65 77 20 74 68 61 74 20 61 72 65   a view that are
171a0 20 73 69 6d 75 6c 61 74 65 64 20 62 79 20 61 6e   simulated by an
171b0 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69   [INSTEAD OF tri
171c0 67 67 65 72 5d 0a 2a 2a 20 61 72 65 20 6e 6f 74  gger].** are not
171d0 20 63 6f 75 6e 74 65 64 2e 20 20 4f 6e 6c 79 20   counted.  Only 
171e0 72 65 61 6c 20 74 61 62 6c 65 20 63 68 61 6e 67  real table chang
171f0 65 73 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 0a  es are counted..
17200 2a 2a 0a 2a 2a 20 5e 28 41 20 22 72 6f 77 20 63  **.** ^(A "row c
17210 68 61 6e 67 65 22 20 69 73 20 61 20 63 68 61 6e  hange" is a chan
17220 67 65 20 74 6f 20 61 20 73 69 6e 67 6c 65 20 72  ge to a single r
17230 6f 77 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 74  ow of a single t
17240 61 62 6c 65 0a 2a 2a 20 63 61 75 73 65 64 20 62  able.** caused b
17250 79 20 61 6e 20 49 4e 53 45 52 54 2c 20 44 45 4c  y an INSERT, DEL
17260 45 54 45 2c 20 6f 72 20 55 50 44 41 54 45 20 73  ETE, or UPDATE s
17270 74 61 74 65 6d 65 6e 74 2e 20 20 52 6f 77 73 20  tatement.  Rows 
17280 74 68 61 74 0a 2a 2a 20 61 72 65 20 63 68 61 6e  that.** are chan
17290 67 65 64 20 61 73 20 73 69 64 65 20 65 66 66 65  ged as side effe
172a0 63 74 73 20 6f 66 20 5b 52 45 50 4c 41 43 45 5d  cts of [REPLACE]
172b0 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f   constraint reso
172c0 6c 75 74 69 6f 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62  lution,.** rollb
172d0 61 63 6b 2c 20 41 42 4f 52 54 20 70 72 6f 63 65  ack, ABORT proce
172e0 73 73 69 6e 67 2c 20 5b 44 52 4f 50 20 54 41 42  ssing, [DROP TAB
172f0 4c 45 5d 2c 20 6f 72 20 62 79 20 61 6e 79 20 6f  LE], or by any o
17300 74 68 65 72 0a 2a 2a 20 6d 65 63 68 61 6e 69 73  ther.** mechanis
17310 6d 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20  ms do not count 
17320 61 73 20 64 69 72 65 63 74 20 72 6f 77 20 63 68  as direct row ch
17330 61 6e 67 65 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41  anges.)^.**.** A
17340 20 22 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78   "trigger contex
17350 74 22 20 69 73 20 61 20 73 63 6f 70 65 20 6f 66  t" is a scope of
17360 20 65 78 65 63 75 74 69 6f 6e 20 74 68 61 74 20   execution that 
17370 62 65 67 69 6e 73 20 61 6e 64 0a 2a 2a 20 65 6e  begins and.** en
17380 64 73 20 77 69 74 68 20 74 68 65 20 73 63 72 69  ds with the scri
17390 70 74 20 6f 66 20 61 20 5b 43 52 45 41 54 45 20  pt of a [CREATE 
173a0 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65  TRIGGER | trigge
173b0 72 5d 2e 20 0a 2a 2a 20 4d 6f 73 74 20 53 51 4c  r]. .** Most SQL
173c0 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 0a   statements are.
173d0 2a 2a 20 65 76 61 6c 75 61 74 65 64 20 6f 75 74  ** evaluated out
173e0 73 69 64 65 20 6f 66 20 61 6e 79 20 74 72 69 67  side of any trig
173f0 67 65 72 2e 20 20 54 68 69 73 20 69 73 20 74 68  ger.  This is th
17400 65 20 22 74 6f 70 20 6c 65 76 65 6c 22 0a 2a 2a  e "top level".**
17410 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74   trigger context
17420 2e 20 20 49 66 20 61 20 74 72 69 67 67 65 72 20  .  If a trigger 
17430 66 69 72 65 73 20 66 72 6f 6d 20 74 68 65 20 74  fires from the t
17440 6f 70 20 6c 65 76 65 6c 2c 20 61 0a 2a 2a 20 6e  op level, a.** n
17450 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65  ew trigger conte
17460 78 74 20 69 73 20 65 6e 74 65 72 65 64 20 66 6f  xt is entered fo
17470 72 20 74 68 65 20 64 75 72 61 74 69 6f 6e 20 6f  r the duration o
17480 66 20 74 68 61 74 20 6f 6e 65 0a 2a 2a 20 74 72  f that one.** tr
17490 69 67 67 65 72 2e 20 20 53 75 62 74 72 69 67 67  igger.  Subtrigg
174a0 65 72 73 20 63 72 65 61 74 65 20 73 75 62 63 6f  ers create subco
174b0 6e 74 65 78 74 73 20 66 6f 72 20 74 68 65 69 72  ntexts for their
174c0 20 64 75 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   duration..**.**
174d0 20 5e 43 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74   ^Calling [sqlit
174e0 65 33 5f 65 78 65 63 28 29 5d 20 6f 72 20 5b 73  e3_exec()] or [s
174f0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72  qlite3_step()] r
17500 65 63 75 72 73 69 76 65 6c 79 20 64 6f 65 73 0a  ecursively does.
17510 2a 2a 20 6e 6f 74 20 63 72 65 61 74 65 20 61 20  ** not create a 
17520 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74  new trigger cont
17530 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  ext..**.** ^This
17540 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
17550 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
17560 64 69 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67  direct row chang
17570 65 73 20 69 6e 20 74 68 65 0a 2a 2a 20 6d 6f 73  es in the.** mos
17580 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c  t recent INSERT,
17590 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45   UPDATE, or DELE
175a0 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74  TE statement wit
175b0 68 69 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20  hin the same.** 
175c0 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e  trigger context.
175d0 0a 2a 2a 0a 2a 2a 20 5e 54 68 75 73 2c 20 77 68  .**.** ^Thus, wh
175e0 65 6e 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74  en called from t
175f0 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20 74 68  he top level, th
17600 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  is function retu
17610 72 6e 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65  rns the.** numbe
17620 72 20 6f 66 20 63 68 61 6e 67 65 73 20 69 6e 20  r of changes in 
17630 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
17640 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20  INSERT, UPDATE, 
17650 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61  or DELETE.** tha
17660 74 20 61 6c 73 6f 20 6f 63 63 75 72 72 65 64 20  t also occurred 
17670 61 74 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c  at the top level
17680 2e 20 20 5e 28 57 69 74 68 69 6e 20 74 68 65 20  .  ^(Within the 
17690 62 6f 64 79 20 6f 66 20 61 20 74 72 69 67 67 65  body of a trigge
176a0 72 2c 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65  r,.** the sqlite
176b0 33 5f 63 68 61 6e 67 65 73 28 29 20 69 6e 74 65  3_changes() inte
176c0 72 66 61 63 65 20 63 61 6e 20 62 65 20 63 61 6c  rface can be cal
176d0 6c 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20  led to find the 
176e0 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61  number of.** cha
176f0 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74  nges in the most
17700 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65   recently comple
17710 74 65 64 20 49 4e 53 45 52 54 2c 20 55 50 44 41  ted INSERT, UPDA
17720 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a  TE, or DELETE.**
17730 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69   statement withi
17740 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20 74 68  n the body of th
17750 65 20 73 61 6d 65 20 74 72 69 67 67 65 72 2e 0a  e same trigger..
17760 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20  ** However, the 
17770 6e 75 6d 62 65 72 20 72 65 74 75 72 6e 65 64 20  number returned 
17780 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65  does not include
17790 20 63 68 61 6e 67 65 73 0a 2a 2a 20 63 61 75 73   changes.** caus
177a0 65 64 20 62 79 20 73 75 62 74 72 69 67 67 65 72  ed by subtrigger
177b0 73 20 73 69 6e 63 65 20 74 68 6f 73 65 20 68 61  s since those ha
177c0 76 65 20 74 68 65 69 72 20 6f 77 6e 20 63 6f 6e  ve their own con
177d0 74 65 78 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65  text.)^.**.** Se
177e0 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69  e also the [sqli
177f0 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
17800 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20  s()] interface, 
17810 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68  the.** [count_ch
17820 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61  anges pragma], a
17830 6e 64 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28  nd the [changes(
17840 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e  ) SQL function].
17850 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61  .**.** If a sepa
17860 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65  rate thread make
17870 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65  s changes on the
17880 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
17890 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69  onnection.** whi
178a0 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e  le [sqlite3_chan
178b0 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e  ges()] is runnin
178c0 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65  g then the value
178d0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20   returned.** is 
178e0 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e  unpredictable an
178f0 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c  d not meaningful
17900 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
17910 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e  int sqlite3_chan
17920 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  ges(sqlite3*);..
17930 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
17940 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20  Total Number Of 
17950 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a  Rows Modified.**
17960 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69  .** ^This functi
17970 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  on returns the n
17980 75 6d 62 65 72 20 6f 66 20 72 6f 77 20 63 68 61  umber of row cha
17990 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20 5b  nges caused by [
179a0 49 4e 53 45 52 54 5d 2c 0a 2a 2a 20 5b 55 50 44  INSERT],.** [UPD
179b0 41 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d  ATE] or [DELETE]
179c0 20 73 74 61 74 65 6d 65 6e 74 73 20 73 69 6e 63   statements sinc
179d0 65 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  e the [database 
179e0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 61 73 20  connection] was 
179f0 6f 70 65 6e 65 64 2e 0a 2a 2a 20 5e 28 54 68 65  opened..** ^(The
17a00 20 63 6f 75 6e 74 20 72 65 74 75 72 6e 65 64 20   count returned 
17a10 62 79 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  by sqlite3_total
17a20 5f 63 68 61 6e 67 65 73 28 29 20 69 6e 63 6c 75  _changes() inclu
17a30 64 65 73 20 61 6c 6c 20 63 68 61 6e 67 65 73 0a  des all changes.
17a40 2a 2a 20 66 72 6f 6d 20 61 6c 6c 20 5b 43 52 45  ** from all [CRE
17a50 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72  ATE TRIGGER | tr
17a60 69 67 67 65 72 5d 20 63 6f 6e 74 65 78 74 73 20  igger] contexts 
17a70 61 6e 64 20 63 68 61 6e 67 65 73 20 6d 61 64 65  and changes made
17a80 20 62 79 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20   by.** [foreign 
17a90 6b 65 79 20 61 63 74 69 6f 6e 73 5d 2e 20 48 6f  key actions]. Ho
17aa0 77 65 76 65 72 2c 0a 2a 2a 20 74 68 65 20 63 6f  wever,.** the co
17ab0 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63  unt does not inc
17ac0 6c 75 64 65 20 63 68 61 6e 67 65 73 20 75 73 65  lude changes use
17ad0 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b  d to implement [
17ae0 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61  REPLACE] constra
17af0 69 6e 74 73 2c 0a 2a 2a 20 64 6f 20 72 6f 6c 6c  ints,.** do roll
17b00 62 61 63 6b 73 20 6f 72 20 41 42 4f 52 54 20 70  backs or ABORT p
17b10 72 6f 63 65 73 73 69 6e 67 2c 20 6f 72 20 5b 44  rocessing, or [D
17b20 52 4f 50 20 54 41 42 4c 45 5d 20 70 72 6f 63 65  ROP TABLE] proce
17b30 73 73 69 6e 67 2e 20 20 54 68 65 0a 2a 2a 20 63  ssing.  The.** c
17b40 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e  ount does not in
17b50 63 6c 75 64 65 20 72 6f 77 73 20 6f 66 20 76 69  clude rows of vi
17b60 65 77 73 20 74 68 61 74 20 66 69 72 65 20 61 6e  ews that fire an
17b70 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69   [INSTEAD OF tri
17b80 67 67 65 72 5d 2c 0a 2a 2a 20 74 68 6f 75 67 68  gger],.** though
17b90 20 69 66 20 74 68 65 20 49 4e 53 54 45 41 44 20   if the INSTEAD 
17ba0 4f 46 20 74 72 69 67 67 65 72 20 6d 61 6b 65 73  OF trigger makes
17bb0 20 63 68 61 6e 67 65 73 20 6f 66 20 69 74 73 20   changes of its 
17bc0 6f 77 6e 2c 20 74 68 6f 73 65 20 63 68 61 6e 67  own, those chang
17bd0 65 73 20 0a 2a 2a 20 61 72 65 20 63 6f 75 6e 74  es .** are count
17be0 65 64 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 73 71  ed.)^.** ^The sq
17bf0 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
17c00 67 65 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 63  ges() function c
17c10 6f 75 6e 74 73 20 74 68 65 20 63 68 61 6e 67 65  ounts the change
17c20 73 20 61 73 20 73 6f 6f 6e 20 61 73 0a 2a 2a 20  s as soon as.** 
17c30 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 68  the statement th
17c40 61 74 20 6d 61 6b 65 73 20 74 68 65 6d 20 69 73  at makes them is
17c50 20 63 6f 6d 70 6c 65 74 65 64 20 28 77 68 65 6e   completed (when
17c60 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68   the statement h
17c70 61 6e 64 6c 65 0a 2a 2a 20 69 73 20 70 61 73 73  andle.** is pass
17c80 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  ed to [sqlite3_r
17c90 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69  eset()] or [sqli
17ca0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 29  te3_finalize()])
17cb0 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
17cc0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68   the [sqlite3_ch
17cd0 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61  anges()] interfa
17ce0 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e  ce, the.** [coun
17cf0 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61  t_changes pragma
17d00 5d 2c 20 61 6e 64 20 74 68 65 20 5b 74 6f 74 61  ], and the [tota
17d10 6c 5f 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20  l_changes() SQL 
17d20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a  function]..**.**
17d30 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74   If a separate t
17d40 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e  hread makes chan
17d50 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  ges on the same 
17d60 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
17d70 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71  ion.** while [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 5d 20 69 73 20 72 75 6e 6e 69 6e  ges()] is runnin
17da0 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65  g then the value
17db0 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 73 20  .** returned is 
17dc0 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e  unpredictable an
17dd0 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c  d not meaningful
17de0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
17df0 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 6f 74 61  int sqlite3_tota
17e00 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65  l_changes(sqlite
17e10 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
17e20 33 52 45 46 3a 20 49 6e 74 65 72 72 75 70 74 20  3REF: Interrupt 
17e30 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 51  A Long-Running Q
17e40 75 65 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  uery.**.** ^This
17e50 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73   function causes
17e60 20 61 6e 79 20 70 65 6e 64 69 6e 67 20 64 61 74   any pending dat
17e70 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 20  abase operation 
17e80 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20  to abort and.** 
17e90 72 65 74 75 72 6e 20 61 74 20 69 74 73 20 65 61  return at its ea
17ea0 72 6c 69 65 73 74 20 6f 70 70 6f 72 74 75 6e 69  rliest opportuni
17eb0 74 79 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65  ty. This routine
17ec0 20 69 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a   is typically.**
17ed0 20 63 61 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f   called in respo
17ee0 6e 73 65 20 74 6f 20 61 20 75 73 65 72 20 61 63  nse to a user ac
17ef0 74 69 6f 6e 20 73 75 63 68 20 61 73 20 70 72 65  tion such as pre
17f00 73 73 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a  ssing "Cancel".*
17f10 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77 68 65 72  * or Ctrl-C wher
17f20 65 20 74 68 65 20 75 73 65 72 20 77 61 6e 74 73  e the user wants
17f30 20 61 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70   a long query op
17f40 65 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a  eration to halt.
17f50 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a  ** immediately..
17f60 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 73 61 66  **.** ^It is saf
17f70 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72  e to call this r
17f80 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61 20 74 68  outine from a th
17f90 72 65 61 64 20 64 69 66 66 65 72 65 6e 74 20 66  read different f
17fa0 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65 61  rom the.** threa
17fb0 64 20 74 68 61 74 20 69 73 20 63 75 72 72 65 6e  d that is curren
17fc0 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68 65 20  tly running the 
17fd0 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69  database operati
17fe0 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20 69  on.  But it.** i
17ff0 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 63 61  s not safe to ca
18000 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  ll this routine 
18010 77 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65  with a [database
18020 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61   connection] tha
18030 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f  t.** is closed o
18040 72 20 6d 69 67 68 74 20 63 6c 6f 73 65 20 62 65  r might close be
18050 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 69 6e 74  fore sqlite3_int
18060 65 72 72 75 70 74 28 29 20 72 65 74 75 72 6e 73  errupt() returns
18070 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 53  ..**.** ^If an S
18080 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20  QL operation is 
18090 76 65 72 79 20 6e 65 61 72 6c 79 20 66 69 6e 69  very nearly fini
180a0 73 68 65 64 20 61 74 20 74 68 65 20 74 69 6d 65  shed at the time
180b0 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33   when.** sqlite3
180c0 5f 69 6e 74 65 72 72 75 70 74 28 29 20 69 73 20  _interrupt() is 
180d0 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74 20  called, then it 
180e0 6d 69 67 68 74 20 6e 6f 74 20 68 61 76 65 20 61  might not have a
180f0 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a 2a 2a  n opportunity.**
18100 20 74 6f 20 62 65 20 69 6e 74 65 72 72 75 70 74   to be interrupt
18110 65 64 20 61 6e 64 20 6d 69 67 68 74 20 63 6f 6e  ed and might con
18120 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74  tinue to complet
18130 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53  ion..**.** ^An S
18140 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61  QL operation tha
18150 74 20 69 73 20 69 6e 74 65 72 72 75 70 74 65 64  t is interrupted
18160 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
18170 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e  LITE_INTERRUPT].
18180 0a 2a 2a 20 5e 49 66 20 74 68 65 20 69 6e 74 65  .** ^If the inte
18190 72 72 75 70 74 65 64 20 53 51 4c 20 6f 70 65 72  rrupted SQL oper
181a0 61 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45  ation is an INSE
181b0 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44  RT, UPDATE, or D
181c0 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 69 73  ELETE.** that is
181d0 20 69 6e 73 69 64 65 20 61 6e 20 65 78 70 6c 69   inside an expli
181e0 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c  cit transaction,
181f0 20 74 68 65 6e 20 74 68 65 20 65 6e 74 69 72 65   then the entire
18200 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20   transaction.** 
18210 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62  will be rolled b
18220 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ack automaticall
18230 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  y..**.** ^The sq
18240 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
18250 44 29 20 63 61 6c 6c 20 69 73 20 69 6e 20 65 66  D) call is in ef
18260 66 65 63 74 20 75 6e 74 69 6c 20 61 6c 6c 20 63  fect until all c
18270 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67  urrently running
18280 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
18290 74 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20  ts on [database 
182a0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 63 6f  connection] D co
182b0 6d 70 6c 65 74 65 2e 20 20 5e 41 6e 79 20 6e 65  mplete.  ^Any ne
182c0 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  w SQL statements
182d0 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61  .** that are sta
182e0 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20 73  rted after the s
182f0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
18300 28 29 20 63 61 6c 6c 20 61 6e 64 20 62 65 66 6f  () call and befo
18310 72 65 20 74 68 65 20 0a 2a 2a 20 72 75 6e 6e 69  re the .** runni
18320 6e 67 20 73 74 61 74 65 6d 65 6e 74 73 20 72 65  ng statements re
18330 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65 20 69  aches zero are i
18340 6e 74 65 72 72 75 70 74 65 64 20 61 73 20 69 66  nterrupted as if
18350 20 74 68 65 79 20 68 61 64 20 62 65 65 6e 0a 2a   they had been.*
18360 2a 20 72 75 6e 6e 69 6e 67 20 70 72 69 6f 72 20  * running prior 
18370 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  to the sqlite3_i
18380 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 2e  nterrupt() call.
18390 20 20 5e 4e 65 77 20 53 51 4c 20 73 74 61 74 65    ^New SQL state
183a0 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72  ments.** that ar
183b0 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20  e started after 
183c0 74 68 65 20 72 75 6e 6e 69 6e 67 20 73 74 61 74  the running stat
183d0 65 6d 65 6e 74 20 63 6f 75 6e 74 20 72 65 61 63  ement count reac
183e0 68 65 73 20 7a 65 72 6f 20 61 72 65 0a 2a 2a 20  hes zero are.** 
183f0 6e 6f 74 20 65 66 66 65 63 74 65 64 20 62 79 20  not effected by 
18400 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  the sqlite3_inte
18410 72 72 75 70 74 28 29 2e 0a 2a 2a 20 5e 41 20 63  rrupt()..** ^A c
18420 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69  all to sqlite3_i
18430 6e 74 65 72 72 75 70 74 28 44 29 20 74 68 61 74  nterrupt(D) that
18440 20 6f 63 63 75 72 73 20 77 68 65 6e 20 74 68 65   occurs when the
18450 72 65 20 61 72 65 20 6e 6f 20 72 75 6e 6e 69 6e  re are no runnin
18460 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  g.** SQL stateme
18470 6e 74 73 20 69 73 20 61 20 6e 6f 2d 6f 70 20 61  nts is a no-op a
18480 6e 64 20 68 61 73 20 6e 6f 20 65 66 66 65 63 74  nd has no effect
18490 20 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   on SQL statemen
184a0 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73  ts.** that are s
184b0 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65  tarted after the
184c0 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
184d0 70 74 28 29 20 63 61 6c 6c 20 72 65 74 75 72 6e  pt() call return
184e0 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  s..**.** If the 
184f0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
18500 69 6f 6e 20 63 6c 6f 73 65 73 20 77 68 69 6c 65  ion closes while
18510 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72   [sqlite3_interr
18520 75 70 74 28 29 5d 0a 2a 2a 20 69 73 20 72 75 6e  upt()].** is run
18530 6e 69 6e 67 20 74 68 65 6e 20 62 61 64 20 74 68  ning then bad th
18540 69 6e 67 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79  ings will likely
18550 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a 53 51 4c 49   happen..*/.SQLI
18560 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69  TE_API void sqli
18570 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 73 71  te3_interrupt(sq
18580 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
18590 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d  CAPI3REF: Determ
185a0 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74  ine If An SQL St
185b0 61 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c  atement Is Compl
185c0 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ete.**.** These 
185d0 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65  routines are use
185e0 66 75 6c 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61  ful during comma
185f0 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f  nd-line input to
18600 20 64 65 74 65 72 6d 69 6e 65 20 69 66 20 74 68   determine if th
18610 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 65  e.** currently e
18620 6e 74 65 72 65 64 20 74 65 78 74 20 73 65 65 6d  ntered text seem
18630 73 20 74 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70  s to form a comp
18640 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65  lete SQL stateme
18650 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69  nt or.** if addi
18660 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 20  tional input is 
18670 6e 65 65 64 65 64 20 62 65 66 6f 72 65 20 73 65  needed before se
18680 6e 64 69 6e 67 20 74 68 65 20 74 65 78 74 20 69  nding the text i
18690 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f  nto.** SQLite fo
186a0 72 20 70 61 72 73 69 6e 67 2e 20 20 5e 54 68 65  r parsing.  ^The
186b0 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  se routines retu
186c0 72 6e 20 31 20 69 66 20 74 68 65 20 69 6e 70 75  rn 1 if the inpu
186d0 74 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65  t string.** appe
186e0 61 72 73 20 74 6f 20 62 65 20 61 20 63 6f 6d 70  ars to be a comp
186f0 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65  lete SQL stateme
18700 6e 74 2e 20 20 5e 41 20 73 74 61 74 65 6d 65 6e  nt.  ^A statemen
18710 74 20 69 73 20 6a 75 64 67 65 64 20 74 6f 20 62  t is judged to b
18720 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66  e.** complete if
18730 20 69 74 20 65 6e 64 73 20 77 69 74 68 20 61 20   it ends with a 
18740 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20  semicolon token 
18750 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 72 65  and is not a pre
18760 66 69 78 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c  fix of a.** well
18770 2d 66 6f 72 6d 65 64 20 43 52 45 41 54 45 20 54  -formed CREATE T
18780 52 49 47 47 45 52 20 73 74 61 74 65 6d 65 6e 74  RIGGER statement
18790 2e 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20 74  .  ^Semicolons t
187a0 68 61 74 20 61 72 65 20 65 6d 62 65 64 64 65 64  hat are embedded
187b0 20 77 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e   within.** strin
187c0 67 20 6c 69 74 65 72 61 6c 73 20 6f 72 20 71 75  g literals or qu
187d0 6f 74 65 64 20 69 64 65 6e 74 69 66 69 65 72 20  oted identifier 
187e0 6e 61 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74  names or comment
187f0 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64  s are not.** ind
18800 65 70 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20  ependent tokens 
18810 28 74 68 65 79 20 61 72 65 20 70 61 72 74 20 6f  (they are part o
18820 66 20 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77  f the token in w
18830 68 69 63 68 20 74 68 65 79 20 61 72 65 0a 2a 2a  hich they are.**
18840 20 65 6d 62 65 64 64 65 64 29 20 61 6e 64 20 74   embedded) and t
18850 68 75 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74  hus do not count
18860 20 61 73 20 61 20 73 74 61 74 65 6d 65 6e 74 20   as a statement 
18870 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 57 68  terminator.  ^Wh
18880 69 74 65 73 70 61 63 65 0a 2a 2a 20 61 6e 64 20  itespace.** and 
18890 63 6f 6d 6d 65 6e 74 73 20 74 68 61 74 20 66 6f  comments that fo
188a0 6c 6c 6f 77 20 74 68 65 20 66 69 6e 61 6c 20 73  llow the final s
188b0 65 6d 69 63 6f 6c 6f 6e 20 61 72 65 20 69 67 6e  emicolon are ign
188c0 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ored..**.** ^The
188d0 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  se routines retu
188e0 72 6e 20 30 20 69 66 20 74 68 65 20 73 74 61 74  rn 0 if the stat
188f0 65 6d 65 6e 74 20 69 73 20 69 6e 63 6f 6d 70 6c  ement is incompl
18900 65 74 65 2e 20 20 5e 49 66 20 61 0a 2a 2a 20 6d  ete.  ^If a.** m
18910 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
18920 20 66 61 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c   fails, then SQL
18930 49 54 45 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74  ITE_NOMEM is ret
18940 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  urned..**.** ^Th
18950 65 73 65 20 72 6f 75 74 69 6e 65 73 20 64 6f 20  ese routines do 
18960 6e 6f 74 20 70 61 72 73 65 20 74 68 65 20 53 51  not parse the SQ
18970 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 75  L statements thu
18980 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65  s.** will not de
18990 74 65 63 74 20 73 79 6e 74 61 63 74 69 63 61 6c  tect syntactical
189a0 6c 79 20 69 6e 63 6f 72 72 65 63 74 20 53 51 4c  ly incorrect SQL
189b0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c  ..**.** ^(If SQL
189c0 69 74 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e  ite has not been
189d0 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 75 73 69   initialized usi
189e0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74  ng [sqlite3_init
189f0 69 61 6c 69 7a 65 28 29 5d 20 70 72 69 6f 72 20  ialize()] prior 
18a00 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20  .** to invoking 
18a10 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
18a20 31 36 28 29 20 74 68 65 6e 20 73 71 6c 69 74 65  16() then sqlite
18a30 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
18a40 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 74  s invoked.** aut
18a50 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71  omatically by sq
18a60 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
18a70 28 29 2e 20 20 49 66 20 74 68 61 74 20 69 6e 69  ().  If that ini
18a80 74 69 61 6c 69 7a 61 74 69 6f 6e 20 66 61 69 6c  tialization fail
18a90 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 72  s,.** then the r
18aa0 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d  eturn value from
18ab0 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
18ac0 65 31 36 28 29 20 77 69 6c 6c 20 62 65 20 6e 6f  e16() will be no
18ad0 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67 61 72 64  n-zero.** regard
18ae0 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20  less of whether 
18af0 6f 72 20 6e 6f 74 20 74 68 65 20 69 6e 70 75 74  or not the input
18b00 20 53 51 4c 20 69 73 20 63 6f 6d 70 6c 65 74 65   SQL is complete
18b10 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e  .)^.**.** The in
18b20 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  put to [sqlite3_
18b30 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6d 75 73 74  complete()] must
18b40 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   be a zero-termi
18b50 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73  nated.** UTF-8 s
18b60 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tring..**.** The
18b70 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74   input to [sqlit
18b80 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d  e3_complete16()]
18b90 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d   must be a zero-
18ba0 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54  terminated.** UT
18bb0 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e  F-16 string in n
18bc0 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
18bd0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
18be0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  int sqlite3_comp
18bf0 6c 65 74 65 28 63 6f 6e 73 74 20 63 68 61 72 20  lete(const char 
18c00 2a 73 71 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50  *sql);.SQLITE_AP
18c10 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  I int sqlite3_co
18c20 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73 74 20 76  mplete16(const v
18c30 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a  oid *sql);../*.*
18c40 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 67 69  * CAPI3REF: Regi
18c50 73 74 65 72 20 41 20 43 61 6c 6c 62 61 63 6b 20  ster A Callback 
18c60 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49 54 45  To Handle SQLITE
18c70 5f 42 55 53 59 20 45 72 72 6f 72 73 0a 2a 2a 0a  _BUSY Errors.**.
18c80 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65  ** ^This routine
18c90 20 73 65 74 73 20 61 20 63 61 6c 6c 62 61 63 6b   sets a callback
18ca0 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 6d   function that m
18cb0 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20  ight be invoked 
18cc0 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 61  whenever.** an a
18cd0 74 74 65 6d 70 74 20 69 73 20 6d 61 64 65 20 74  ttempt is made t
18ce0 6f 20 6f 70 65 6e 20 61 20 64 61 74 61 62 61 73  o open a databas
18cf0 65 20 74 61 62 6c 65 20 74 68 61 74 20 61 6e 6f  e table that ano
18d00 74 68 65 72 20 74 68 72 65 61 64 0a 2a 2a 20 6f  ther thread.** o
18d10 72 20 70 72 6f 63 65 73 73 20 68 61 73 20 6c 6f  r process has lo
18d20 63 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  cked..**.** ^If 
18d30 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63  the busy callbac
18d40 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20  k is NULL, then 
18d50 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72  [SQLITE_BUSY] or
18d60 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42   [SQLITE_IOERR_B
18d70 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 69 73 20 72 65  LOCKED].** is re
18d80 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65  turned immediate
18d90 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65  ly upon encounte
18da0 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20 20  ring the lock.  
18db0 5e 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c  ^If the busy cal
18dc0 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20  lback.** is not 
18dd0 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 63  NULL, then the c
18de0 61 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 62 65  allback might be
18df0 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 77   invoked with tw
18e00 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a  o arguments..**.
18e10 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
18e20 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 62 75  gument to the bu
18e30 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 61 20  sy handler is a 
18e40 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64  copy of the void
18e50 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 0a  * pointer which.
18e60 2a 2a 20 69 73 20 74 68 65 20 74 68 69 72 64 20  ** is the third 
18e70 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
18e80 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
18e90 28 29 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64  ().  ^The second
18ea0 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
18eb0 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
18ec0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65   callback is the
18ed0 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73   number of times
18ee0 20 74 68 61 74 20 74 68 65 20 62 75 73 79 20 68   that the busy h
18ef0 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65  andler has.** be
18f00 65 6e 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 74  en invoked for t
18f10 68 69 73 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e  his locking even
18f20 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 62  t.  ^If the.** b
18f30 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  usy callback ret
18f40 75 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20  urns 0, then no 
18f50 61 64 64 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d  additional attem
18f60 70 74 73 20 61 72 65 20 6d 61 64 65 20 74 6f 0a  pts are made to.
18f70 2a 2a 20 61 63 63 65 73 73 20 74 68 65 20 64 61  ** access the da
18f80 74 61 62 61 73 65 20 61 6e 64 20 5b 53 51 4c 49  tabase and [SQLI
18f90 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c  TE_BUSY] or [SQL
18fa0 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45  ITE_IOERR_BLOCKE
18fb0 44 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  D] is returned..
18fc0 2a 2a 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62  ** ^If the callb
18fd0 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d  ack returns non-
18fe0 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68  zero, then anoth
18ff0 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73  er attempt.** is
19000 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 74 68   made to open th
19010 65 20 64 61 74 61 62 61 73 65 20 66 6f 72 20 72  e database for r
19020 65 61 64 69 6e 67 20 61 6e 64 20 74 68 65 20 63  eading and the c
19030 79 63 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a  ycle repeats..**
19040 0a 2a 2a 20 54 68 65 20 70 72 65 73 65 6e 63 65  .** The presence
19050 20 6f 66 20 61 20 62 75 73 79 20 68 61 6e 64 6c   of a busy handl
19060 65 72 20 64 6f 65 73 20 6e 6f 74 20 67 75 61 72  er does not guar
19070 61 6e 74 65 65 20 74 68 61 74 20 69 74 20 77 69  antee that it wi
19080 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a  ll be invoked.**
19090 20 77 68 65 6e 20 74 68 65 72 65 20 69 73 20 6c   when there is l
190a0 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20  ock contention. 
190b0 5e 49 66 20 53 51 4c 69 74 65 20 64 65 74 65 72  ^If SQLite deter
190c0 6d 69 6e 65 73 20 74 68 61 74 20 69 6e 76 6f 6b  mines that invok
190d0 69 6e 67 20 74 68 65 20 62 75 73 79 0a 2a 2a 20  ing the busy.** 
190e0 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72 65  handler could re
190f0 73 75 6c 74 20 69 6e 20 61 20 64 65 61 64 6c 6f  sult in a deadlo
19100 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f 20 61  ck, it will go a
19110 68 65 61 64 20 61 6e 64 20 72 65 74 75 72 6e 20  head and return 
19120 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a  [SQLITE_BUSY].**
19130 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52   or [SQLITE_IOER
19140 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 6e 73 74 65  R_BLOCKED] inste
19150 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 74  ad of invoking t
19160 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e  he busy handler.
19170 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61 20 73  .** Consider a s
19180 63 65 6e 61 72 69 6f 20 77 68 65 72 65 20 6f 6e  cenario where on
19190 65 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c  e process is hol
191a0 64 69 6e 67 20 61 20 72 65 61 64 20 6c 6f 63 6b  ding a read lock
191b0 20 74 68 61 74 0a 2a 2a 20 69 74 20 69 73 20 74   that.** it is t
191c0 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65  rying to promote
191d0 20 74 6f 20 61 20 72 65 73 65 72 76 65 64 20 6c   to a reserved l
191e0 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63  ock and.** a sec
191f0 6f 6e 64 20 70 72 6f 63 65 73 73 20 69 73 20 68  ond process is h
19200 6f 6c 64 69 6e 67 20 61 20 72 65 73 65 72 76 65  olding a reserve
19210 64 20 6c 6f 63 6b 20 74 68 61 74 20 69 74 20 69  d lock that it i
19220 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70  s trying.** to p
19230 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78 63  romote to an exc
19240 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68  lusive lock.  Th
19250 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20  e first process 
19260 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a  cannot proceed.*
19270 2a 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20  * because it is 
19280 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 73  blocked by the s
19290 65 63 6f 6e 64 20 61 6e 64 20 74 68 65 20 73 65  econd and the se
192a0 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 63 61 6e  cond process can
192b0 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62  not.** proceed b
192c0 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f  ecause it is blo
192d0 63 6b 65 64 20 62 79 20 74 68 65 20 66 69 72 73  cked by the firs
192e0 74 2e 20 20 49 66 20 62 6f 74 68 20 70 72 6f 63  t.  If both proc
192f0 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20  esses.** invoke 
19300 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
19310 73 2c 20 6e 65 69 74 68 65 72 20 77 69 6c 6c 20  s, neither will 
19320 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67 72 65 73  make any progres
19330 73 2e 20 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a  s.  Therefore,.*
19340 2a 20 53 51 4c 69 74 65 20 72 65 74 75 72 6e 73  * SQLite returns
19350 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 66   [SQLITE_BUSY] f
19360 6f 72 20 74 68 65 20 66 69 72 73 74 20 70 72 6f  or the first pro
19370 63 65 73 73 2c 20 68 6f 70 69 6e 67 20 74 68 61  cess, hoping tha
19380 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69  t this.** will i
19390 6e 64 75 63 65 20 74 68 65 20 66 69 72 73 74 20  nduce the first 
193a0 70 72 6f 63 65 73 73 20 74 6f 20 72 65 6c 65 61  process to relea
193b0 73 65 20 69 74 73 20 72 65 61 64 20 6c 6f 63 6b  se its read lock
193c0 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68   and allow.** th
193d0 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73  e second process
193e0 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a   to proceed..**.
193f0 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20  ** ^The default 
19400 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73  busy callback is
19410 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   NULL..**.** ^Th
19420 65 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  e [SQLITE_BUSY] 
19430 65 72 72 6f 72 20 69 73 20 63 6f 6e 76 65 72 74  error is convert
19440 65 64 20 74 6f 20 5b 53 51 4c 49 54 45 5f 49 4f  ed to [SQLITE_IO
19450 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20  ERR_BLOCKED].** 
19460 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 69  when SQLite is i
19470 6e 20 74 68 65 20 6d 69 64 64 6c 65 20 6f 66 20  n the middle of 
19480 61 20 6c 61 72 67 65 20 74 72 61 6e 73 61 63 74  a large transact
19490 69 6f 6e 20 77 68 65 72 65 20 61 6c 6c 20 74 68  ion where all th
194a0 65 0a 2a 2a 20 63 68 61 6e 67 65 73 20 77 69 6c  e.** changes wil
194b0 6c 20 6e 6f 74 20 66 69 74 20 69 6e 74 6f 20 74  l not fit into t
194c0 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 20 63 61 63  he in-memory cac
194d0 68 65 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c  he.  SQLite will
194e0 0a 2a 2a 20 61 6c 72 65 61 64 79 20 68 6f 6c 64  .** already hold
194f0 20 61 20 52 45 53 45 52 56 45 44 20 6c 6f 63 6b   a RESERVED lock
19500 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65   on the database
19510 20 66 69 6c 65 2c 20 62 75 74 20 69 74 20 6e 65   file, but it ne
19520 65 64 73 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74  eds.** to promot
19530 65 20 74 68 69 73 20 6c 6f 63 6b 20 74 6f 20 45  e this lock to E
19540 58 43 4c 55 53 49 56 45 20 73 6f 20 74 68 61 74  XCLUSIVE so that
19550 20 69 74 20 63 61 6e 20 73 70 69 6c 6c 20 63 61   it can spill ca
19560 63 68 65 0a 2a 2a 20 70 61 67 65 73 20 69 6e 74  che.** pages int
19570 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  o the database f
19580 69 6c 65 20 77 69 74 68 6f 75 74 20 68 61 72 6d  ile without harm
19590 20 74 6f 20 63 6f 6e 63 75 72 72 65 6e 74 0a 2a   to concurrent.*
195a0 2a 20 72 65 61 64 65 72 73 2e 20 20 5e 49 66 20  * readers.  ^If 
195b0 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  it is unable to 
195c0 70 72 6f 6d 6f 74 65 20 74 68 65 20 6c 6f 63 6b  promote the lock
195d0 2c 20 74 68 65 6e 20 74 68 65 20 69 6e 2d 6d 65  , then the in-me
195e0 6d 6f 72 79 0a 2a 2a 20 63 61 63 68 65 20 77 69  mory.** cache wi
195f0 6c 6c 20 62 65 20 6c 65 66 74 20 69 6e 20 61 6e  ll be left in an
19600 20 69 6e 63 6f 6e 73 69 73 74 65 6e 74 20 73 74   inconsistent st
19610 61 74 65 20 61 6e 64 20 73 6f 20 74 68 65 20 65  ate and so the e
19620 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20 69 73 20  rror.** code is 
19630 70 72 6f 6d 6f 74 65 64 20 66 72 6f 6d 20 74 68  promoted from th
19640 65 20 72 65 6c 61 74 69 76 65 6c 79 20 62 65 6e  e relatively ben
19650 69 67 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  ign [SQLITE_BUSY
19660 5d 20 74 6f 0a 2a 2a 20 74 68 65 20 6d 6f 72 65  ] to.** the more
19670 20 73 65 76 65 72 65 20 5b 53 51 4c 49 54 45 5f   severe [SQLITE_
19680 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 20  IOERR_BLOCKED]. 
19690 20 5e 54 68 69 73 20 65 72 72 6f 72 20 63 6f 64   ^This error cod
196a0 65 20 70 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20 66  e promotion.** f
196b0 6f 72 63 65 73 20 61 6e 20 61 75 74 6f 6d 61 74  orces an automat
196c0 69 63 20 72 6f 6c 6c 62 61 63 6b 20 6f 66 20 74  ic rollback of t
196d0 68 65 20 63 68 61 6e 67 65 73 2e 20 20 53 65 65  he changes.  See
196e0 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d   the.** <a href=
196f0 22 2f 63 76 73 74 72 61 63 2f 77 69 6b 69 3f 70  "/cvstrac/wiki?p
19700 3d 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f  =CorruptionFollo
19710 77 69 6e 67 42 75 73 79 45 72 72 6f 72 22 3e 0a  wingBusyError">.
19720 2a 2a 20 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c  ** CorruptionFol
19730 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72 3c  lowingBusyError<
19740 2f 61 3e 20 77 69 6b 69 20 70 61 67 65 20 66 6f  /a> wiki page fo
19750 72 20 61 20 64 69 73 63 75 73 73 69 6f 6e 20 6f  r a discussion o
19760 66 20 77 68 79 0a 2a 2a 20 74 68 69 73 20 69 73  f why.** this is
19770 20 69 6d 70 6f 72 74 61 6e 74 2e 0a 2a 2a 0a 2a   important..**.*
19780 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e  * ^(There can on
19790 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62  ly be a single b
197a0 75 73 79 20 68 61 6e 64 6c 65 72 20 64 65 66 69  usy handler defi
197b0 6e 65 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20  ned for each.** 
197c0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
197d0 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20  tion].  Setting 
197e0 61 20 6e 65 77 20 62 75 73 79 20 68 61 6e 64 6c  a new busy handl
197f0 65 72 20 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a  er clears any.**
19800 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20   previously set 
19810 68 61 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74  handler.)^  ^Not
19820 65 20 74 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b  e that calling [
19830 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d  sqlite3_busy_tim
19840 65 6f 75 74 28 29 5d 0a 2a 2a 20 77 69 6c 6c 20  eout()].** will 
19850 61 6c 73 6f 20 73 65 74 20 6f 72 20 63 6c 65 61  also set or clea
19860 72 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  r the busy handl
19870 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75  er..**.** The bu
19880 73 79 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75  sy callback shou
19890 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61 6e 79 20  ld not take any 
198a0 61 63 74 69 6f 6e 73 20 77 68 69 63 68 20 6d 6f  actions which mo
198b0 64 69 66 79 20 74 68 65 0a 2a 2a 20 64 61 74 61  dify the.** data
198c0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
198d0 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
198e0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 20 20   busy handler.  
198f0 41 6e 79 20 73 75 63 68 20 61 63 74 69 6f 6e 73  Any such actions
19900 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e 20 75 6e  .** result in un
19910 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72  defined behavior
19920 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75 73 79 20  ..** .** A busy 
19930 68 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74  handler must not
19940 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62   close the datab
19950 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
19960 2a 20 6f 72 20 5b 70 72 65 70 61 72 65 64 20 73  * or [prepared s
19970 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69  tatement] that i
19980 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20  nvoked the busy 
19990 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 53 51 4c 49  handler..*/.SQLI
199a0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
199b0 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  e3_busy_handler(
199c0 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29  sqlite3*, int(*)
199d0 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76 6f 69  (void*,int), voi
199e0 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
199f0 33 52 45 46 3a 20 53 65 74 20 41 20 42 75 73 79  3REF: Set A Busy
19a00 20 54 69 6d 65 6f 75 74 0a 2a 2a 0a 2a 2a 20 5e   Timeout.**.** ^
19a10 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74  This routine set
19a20 73 20 61 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  s a [sqlite3_bus
19a30 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75 73 79  y_handler | busy
19a40 20 68 61 6e 64 6c 65 72 5d 20 74 68 61 74 20 73   handler] that s
19a50 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20 61 20 73  leeps.** for a s
19a60 70 65 63 69 66 69 65 64 20 61 6d 6f 75 6e 74 20  pecified amount 
19a70 6f 66 20 74 69 6d 65 20 77 68 65 6e 20 61 20 74  of time when a t
19a80 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20  able is locked. 
19a90 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 0a 2a 2a   ^The handler.**
19aa0 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74   will sleep mult
19ab0 69 70 6c 65 20 74 69 6d 65 73 20 75 6e 74 69 6c  iple times until
19ac0 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d   at least "ms" m
19ad0 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73  illiseconds of s
19ae0 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61 76 65 20  leeping.** have 
19af0 61 63 63 75 6d 75 6c 61 74 65 64 2e 20 20 5e 41  accumulated.  ^A
19b00 66 74 65 72 20 61 74 20 6c 65 61 73 74 20 22 6d  fter at least "m
19b10 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  s" milliseconds 
19b20 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20  of sleeping,.** 
19b30 74 68 65 20 68 61 6e 64 6c 65 72 20 72 65 74 75  the handler retu
19b40 72 6e 73 20 30 20 77 68 69 63 68 20 63 61 75 73  rns 0 which caus
19b50 65 73 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  es [sqlite3_step
19b60 28 29 5d 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a  ()] to return.**
19b70 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f   [SQLITE_BUSY] o
19b80 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  r [SQLITE_IOERR_
19b90 42 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20  BLOCKED]..**.** 
19ba0 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f  ^Calling this ro
19bb0 75 74 69 6e 65 20 77 69 74 68 20 61 6e 20 61 72  utine with an ar
19bc0 67 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 61 6e  gument less than
19bd0 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72   or equal to zer
19be0 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20 61  o.** turns off a
19bf0 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73  ll busy handlers
19c00 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20  ..**.** ^(There 
19c10 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69  can only be a si
19c20 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65  ngle busy handle
19c30 72 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c  r for a particul
19c40 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  ar.** [database 
19c50 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 79 20  connection] any 
19c60 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74  any given moment
19c70 2e 20 20 49 66 20 61 6e 6f 74 68 65 72 20 62 75  .  If another bu
19c80 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61  sy handler.** wa
19c90 73 20 64 65 66 69 6e 65 64 20 20 28 75 73 69 6e  s defined  (usin
19ca0 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  g [sqlite3_busy_
19cb0 68 61 6e 64 6c 65 72 28 29 5d 29 20 70 72 69 6f  handler()]) prio
19cc0 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20  r to calling.** 
19cd0 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 68  this routine, th
19ce0 61 74 20 6f 74 68 65 72 20 62 75 73 79 20 68 61  at other busy ha
19cf0 6e 64 6c 65 72 20 69 73 20 63 6c 65 61 72 65 64  ndler is cleared
19d00 2e 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  .)^.*/.SQLITE_AP
19d10 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75  I int sqlite3_bu
19d20 73 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69 74  sy_timeout(sqlit
19d30 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f  e3*, int ms);../
19d40 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
19d50 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75 74 69  onvenience Routi
19d60 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20  nes For Running 
19d70 51 75 65 72 69 65 73 0a 2a 2a 0a 2a 2a 20 54 68  Queries.**.** Th
19d80 69 73 20 69 73 20 61 20 6c 65 67 61 63 79 20 69  is is a legacy i
19d90 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 69 73  nterface that is
19da0 20 70 72 65 73 65 72 76 65 64 20 66 6f 72 20 62   preserved for b
19db0 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
19dc0 62 69 6c 69 74 79 2e 0a 2a 2a 20 55 73 65 20 6f  bility..** Use o
19dd0 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  f this interface
19de0 20 69 73 20 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e   is not recommen
19df0 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e  ded..**.** Defin
19e00 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75  ition: A <b>resu
19e10 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20  lt table</b> is 
19e20 6d 65 6d 6f 72 79 20 64 61 74 61 20 73 74 72 75  memory data stru
19e30 63 74 75 72 65 20 63 72 65 61 74 65 64 20 62 79  cture created by
19e40 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
19e50 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e  _get_table()] in
19e60 74 65 72 66 61 63 65 2e 20 20 41 20 72 65 73 75  terface.  A resu
19e70 6c 74 20 74 61 62 6c 65 20 72 65 63 6f 72 64 73  lt table records
19e80 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65   the.** complete
19e90 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 20 66   query results f
19ea0 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  rom one or more 
19eb0 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  queries..**.** T
19ec0 68 65 20 74 61 62 6c 65 20 63 6f 6e 63 65 70 74  he table concept
19ed0 75 61 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d 62  ually has a numb
19ee0 65 72 20 6f 66 20 72 6f 77 73 20 61 6e 64 20 63  er of rows and c
19ef0 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20  olumns.  But.** 
19f00 74 68 65 73 65 20 6e 75 6d 62 65 72 73 20 61 72  these numbers ar
19f10 65 20 6e 6f 74 20 70 61 72 74 20 6f 66 20 74 68  e not part of th
19f20 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69  e result table i
19f30 74 73 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a  tself.  These.**
19f40 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6f 62 74   numbers are obt
19f50 61 69 6e 65 64 20 73 65 70 61 72 61 74 65 6c 79  ained separately
19f60 2e 20 20 4c 65 74 20 4e 20 62 65 20 74 68 65 20  .  Let N be the 
19f70 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a  number of rows.*
19f80 2a 20 61 6e 64 20 4d 20 62 65 20 74 68 65 20 6e  * and M be the n
19f90 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
19fa0 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74  ..**.** A result
19fb0 20 74 61 62 6c 65 20 69 73 20 61 6e 20 61 72 72   table is an arr
19fc0 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74  ay of pointers t
19fd0 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  o zero-terminate
19fe0 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e  d UTF-8 strings.
19ff0 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 28 4e  .** There are (N
1a000 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69  +1)*M elements i
1a010 6e 20 74 68 65 20 61 72 72 61 79 2e 20 20 54 68  n the array.  Th
1a020 65 20 66 69 72 73 74 20 4d 20 70 6f 69 6e 74 65  e first M pointe
1a030 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a  rs point.** to z
1a040 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73  ero-terminated s
1a050 74 72 69 6e 67 73 20 74 68 61 74 20 20 63 6f 6e  trings that  con
1a060 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f  tain the names o
1a070 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a  f the columns..*
1a080 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20  * The remaining 
1a090 65 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e  entries all poin
1a0a0 74 20 74 6f 20 71 75 65 72 79 20 72 65 73 75 6c  t to query resul
1a0b0 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73  ts.  NULL values
1a0c0 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55   result.** in NU
1a0d0 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c  LL pointers.  Al
1a0e0 6c 20 6f 74 68 65 72 20 76 61 6c 75 65 73 20 61  l other values a
1a0f0 72 65 20 69 6e 20 74 68 65 69 72 20 55 54 46 2d  re in their UTF-
1a100 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  8 zero-terminate
1a110 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65 70 72  d.** string repr
1a120 65 73 65 6e 74 61 74 69 6f 6e 20 61 73 20 72 65  esentation as re
1a130 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
1a140 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
1a150 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c  ]..**.** A resul
1a160 74 20 74 61 62 6c 65 20 6d 69 67 68 74 20 63 6f  t table might co
1a170 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20  nsist of one or 
1a180 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  more memory allo
1a190 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69  cations..** It i
1a1a0 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 70 61  s not safe to pa
1a1b0 73 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c  ss a result tabl
1a1c0 65 20 64 69 72 65 63 74 6c 79 20 74 6f 20 5b 73  e directly to [s
1a1d0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a  qlite3_free()]..
1a1e0 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c  ** A result tabl
1a1f0 65 20 73 68 6f 75 6c 64 20 62 65 20 64 65 61 6c  e should be deal
1a200 6c 6f 63 61 74 65 64 20 75 73 69 6e 67 20 5b 73  located using [s
1a210 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c  qlite3_free_tabl
1a220 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73  e()]..**.** ^(As
1a230 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 74   an example of t
1a240 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  he result table 
1a250 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73 65 20  format, suppose 
1a260 61 20 71 75 65 72 79 20 72 65 73 75 6c 74 0a 2a  a query result.*
1a270 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  * is as follows:
1a280 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
1a290 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20  te><pre>.**     
1a2a0 20 20 20 4e 61 6d 65 20 20 20 20 20 20 20 20 7c     Name        |
1a2b0 20 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d   Age.**        -
1a2c0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1a2d0 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20  ------.**       
1a2e0 20 41 6c 69 63 65 20 20 20 20 20 20 20 7c 20 34   Alice       | 4
1a2f0 33 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 62 20  3.**        Bob 
1a300 20 20 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20          | 28.** 
1a310 20 20 20 20 20 20 20 43 69 6e 64 79 20 20 20 20         Cindy    
1a320 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65     | 21.** </pre
1a330 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
1a340 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74  *.** There are t
1a350 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29  wo column (M==2)
1a360 20 61 6e 64 20 74 68 72 65 65 20 72 6f 77 73 20   and three rows 
1a370 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20 74 68  (N==3).  Thus th
1a380 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61 62 6c  e.** result tabl
1a390 65 20 68 61 73 20 38 20 65 6e 74 72 69 65 73 2e  e has 8 entries.
1a3a0 20 20 53 75 70 70 6f 73 65 20 74 68 65 20 72 65    Suppose the re
1a3b0 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 73 74  sult table is st
1a3c0 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72  ored.** in an ar
1a3d0 72 61 79 20 6e 61 6d 65 73 20 61 7a 52 65 73 75  ray names azResu
1a3e0 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52 65 73 75  lt.  Then azResu
1a3f0 6c 74 20 68 6f 6c 64 73 20 74 68 69 73 20 63 6f  lt holds this co
1a400 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  ntent:.**.** <bl
1a410 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
1a420 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
1a430 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65  t&#91;0] = "Name
1a440 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
1a450 65 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22  esult&#91;1] = "
1a460 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  Age";.**        
1a470 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 32 5d 20  azResult&#91;2] 
1a480 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20  = "Alice";.**   
1a490 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
1a4a0 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20  1;3] = "43";.** 
1a4b0 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
1a4c0 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a  #91;4] = "Bob";.
1a4d0 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
1a4e0 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22 32 38 22  lt&#91;5] = "28"
1a4f0 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
1a500 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22 43  sult&#91;6] = "C
1a510 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20  indy";.**       
1a520 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 37 5d   azResult&#91;7]
1a530 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72   = "21";.** </pr
1a540 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29  e></blockquote>)
1a550 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ^.**.** ^The sql
1a560 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
1a570 20 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61   function evalua
1a580 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a  tes one or more.
1a590 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70  ** semicolon-sep
1a5a0 61 72 61 74 65 64 20 53 51 4c 20 73 74 61 74 65  arated SQL state
1a5b0 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72  ments in the zer
1a5c0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
1a5d0 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20  -8.** string of 
1a5e0 69 74 73 20 32 6e 64 20 70 61 72 61 6d 65 74 65  its 2nd paramete
1a5f0 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20  r and returns a 
1a600 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20  result table to 
1a610 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67  the.** pointer g
1a620 69 76 65 6e 20 69 6e 20 69 74 73 20 33 72 64 20  iven in its 3rd 
1a630 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
1a640 20 41 66 74 65 72 20 74 68 65 20 61 70 70 6c 69   After the appli
1a650 63 61 74 69 6f 6e 20 68 61 73 20 66 69 6e 69 73  cation has finis
1a660 68 65 64 20 77 69 74 68 20 74 68 65 20 72 65 73  hed with the res
1a670 75 6c 74 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ult from sqlite3
1a680 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a  _get_table(),.**
1a690 20 69 74 20 6d 75 73 74 20 70 61 73 73 20 74 68   it must pass th
1a6a0 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 70  e result table p
1a6b0 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ointer to sqlite
1a6c0 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 20 69  3_free_table() i
1a6d0 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65  n order to.** re
1a6e0 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79  lease the memory
1a6f0 20 74 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63   that was malloc
1a700 65 64 2e 20 20 42 65 63 61 75 73 65 20 6f 66 20  ed.  Because of 
1a710 74 68 65 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b  the way the.** [
1a720 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1a730 5d 20 68 61 70 70 65 6e 73 20 77 69 74 68 69 6e  ] happens within
1a740 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
1a750 6c 65 28 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e  le(), the callin
1a760 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75  g.** function mu
1a770 73 74 20 6e 6f 74 20 74 72 79 20 74 6f 20 63 61  st not try to ca
1a780 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ll [sqlite3_free
1a790 28 29 5d 20 64 69 72 65 63 74 6c 79 2e 20 20 4f  ()] directly.  O
1a7a0 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  nly.** [sqlite3_
1a7b0 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 20 69 73  free_table()] is
1a7c0 20 61 62 6c 65 20 74 6f 20 72 65 6c 65 61 73 65   able to release
1a7d0 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70   the memory prop
1a7e0 65 72 6c 79 20 61 6e 64 20 73 61 66 65 6c 79 2e  erly and safely.
1a7f0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
1a800 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 69  e3_get_table() i
1a810 6e 74 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c  nterface is impl
1a820 65 6d 65 6e 74 65 64 20 61 73 20 61 20 77 72 61  emented as a wra
1a830 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b  pper around.** [
1a840 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2e  sqlite3_exec()].
1a850 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65    The sqlite3_ge
1a860 74 5f 74 61 62 6c 65 28 29 20 72 6f 75 74 69 6e  t_table() routin
1a870 65 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20  e does not have 
1a880 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79  access.** to any
1a890 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 20 73   internal data s
1a8a0 74 72 75 63 74 75 72 65 73 20 6f 66 20 53 51 4c  tructures of SQL
1a8b0 69 74 65 2e 20 20 49 74 20 75 73 65 73 20 6f 6e  ite.  It uses on
1a8c0 6c 79 20 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a  ly the public.**
1a8d0 20 69 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e   interface defin
1a8e0 65 64 20 68 65 72 65 2e 20 20 41 73 20 61 20 63  ed here.  As a c
1a8f0 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65 72 72 6f  onsequence, erro
1a900 72 73 20 74 68 61 74 20 6f 63 63 75 72 20 69 6e  rs that occur in
1a910 20 74 68 65 0a 2a 2a 20 77 72 61 70 70 65 72 20   the.** wrapper 
1a920 6c 61 79 65 72 20 6f 75 74 73 69 64 65 20 6f 66  layer outside of
1a930 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73   the internal [s
1a940 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 63  qlite3_exec()] c
1a950 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72  all are not.** r
1a960 65 66 6c 65 63 74 65 64 20 69 6e 20 73 75 62 73  eflected in subs
1a970 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20  equent calls to 
1a980 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65  [sqlite3_errcode
1a990 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
1a9a0 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f  e3_errmsg()]..*/
1a9b0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
1a9c0 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
1a9d0 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  e(.  sqlite3 *db
1a9e0 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e  ,          /* An
1a9f0 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a   open database *
1aa00 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
1aa10 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c  zSql,     /* SQL
1aa20 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64   to be evaluated
1aa30 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61   */.  char ***pa
1aa40 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52  zResult,    /* R
1aa50 65 73 75 6c 74 73 20 6f 66 20 74 68 65 20 71 75  esults of the qu
1aa60 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e  ery */.  int *pn
1aa70 52 6f 77 2c 20 20 20 20 20 20 20 20 20 20 20 2f  Row,           /
1aa80 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75  * Number of resu
1aa90 6c 74 20 72 6f 77 73 20 77 72 69 74 74 65 6e 20  lt rows written 
1aaa0 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70  here */.  int *p
1aab0 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20  nColumn,        
1aac0 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73  /* Number of res
1aad0 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74  ult columns writ
1aae0 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63 68  ten here */.  ch
1aaf0 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20  ar **pzErrmsg   
1ab00 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67      /* Error msg
1ab10 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f   written here */
1ab20 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  .);.SQLITE_API v
1ab30 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65  oid sqlite3_free
1ab40 5f 74 61 62 6c 65 28 63 68 61 72 20 2a 2a 72 65  _table(char **re
1ab50 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  sult);../*.** CA
1ab60 50 49 33 52 45 46 3a 20 46 6f 72 6d 61 74 74 65  PI3REF: Formatte
1ab70 64 20 53 74 72 69 6e 67 20 50 72 69 6e 74 69 6e  d String Printin
1ab80 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a  g Functions.**.*
1ab90 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
1aba0 20 61 72 65 20 77 6f 72 6b 2d 61 6c 69 6b 65 73   are work-alikes
1abb0 20 6f 66 20 74 68 65 20 22 70 72 69 6e 74 66 28   of the "printf(
1abc0 29 22 20 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e  )" family of fun
1abd0 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74  ctions.** from t
1abe0 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  he standard C li
1abf0 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  brary..**.** ^Th
1ac00 65 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74  e sqlite3_mprint
1ac10 66 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  f() and sqlite3_
1ac20 76 6d 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69  vmprintf() routi
1ac30 6e 65 73 20 77 72 69 74 65 20 74 68 65 69 72 0a  nes write their.
1ac40 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f 20  ** results into 
1ac50 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20  memory obtained 
1ac60 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
1ac70 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  lloc()]..** The 
1ac80 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64  strings returned
1ac90 20 62 79 20 74 68 65 73 65 20 74 77 6f 20 72 6f   by these two ro
1aca0 75 74 69 6e 65 73 20 73 68 6f 75 6c 64 20 62 65  utines should be
1acb0 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20 62 79 20  .** released by 
1acc0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
1acd0 2e 20 20 5e 42 6f 74 68 20 72 6f 75 74 69 6e 65  .  ^Both routine
1ace0 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55  s return a.** NU
1acf0 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 5b 73  LL pointer if [s
1ad00 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
1ad10 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c   is unable to al
1ad20 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a  locate enough.**
1ad30 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20   memory to hold 
1ad40 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74  the resulting st
1ad50 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  ring..**.** ^(Th
1ad60 65 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  e sqlite3_snprin
1ad70 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20  tf() routine is 
1ad80 73 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70 72  similar to "snpr
1ad90 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20  intf()" from.** 
1ada0 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c  the standard C l
1adb0 69 62 72 61 72 79 2e 20 20 54 68 65 20 72 65 73  ibrary.  The res
1adc0 75 6c 74 20 69 73 20 77 72 69 74 74 65 6e 20 69  ult is written i
1add0 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66 65  nto the.** buffe
1ade0 72 20 73 75 70 70 6c 69 65 64 20 61 73 20 74 68  r supplied as th
1adf0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
1ae00 65 72 20 77 68 6f 73 65 20 73 69 7a 65 20 69 73  er whose size is
1ae10 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65   given by.** the
1ae20 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
1ae30 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20  . Note that the 
1ae40 6f 72 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20  order of the.** 
1ae50 66 69 72 73 74 20 74 77 6f 20 70 61 72 61 6d 65  first two parame
1ae60 74 65 72 73 20 69 73 20 72 65 76 65 72 73 65 64  ters is reversed
1ae70 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29   from snprintf()
1ae80 2e 29 5e 20 20 54 68 69 73 20 69 73 20 61 6e 0a  .)^  This is an.
1ae90 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c 20 61 63  ** historical ac
1aea0 63 69 64 65 6e 74 20 74 68 61 74 20 63 61 6e 6e  cident that cann
1aeb0 6f 74 20 62 65 20 66 69 78 65 64 20 77 69 74 68  ot be fixed with
1aec0 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20  out breaking.** 
1aed0 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
1aee0 69 62 69 6c 69 74 79 2e 20 20 5e 28 4e 6f 74 65  ibility.  ^(Note
1aef0 20 61 6c 73 6f 20 74 68 61 74 20 73 71 6c 69 74   also that sqlit
1af00 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a  e3_snprintf().**
1af10 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
1af20 65 72 20 74 6f 20 69 74 73 20 62 75 66 66 65 72  er to its buffer
1af30 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20   instead of the 
1af40 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61  number of.** cha
1af50 72 61 63 74 65 72 73 20 61 63 74 75 61 6c 6c 79  racters actually
1af60 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68   written into th
1af70 65 20 62 75 66 66 65 72 2e 29 5e 20 20 57 65 20  e buffer.)^  We 
1af80 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74 68  admit that.** th
1af90 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72  e number of char
1afa0 61 63 74 65 72 73 20 77 72 69 74 74 65 6e 20 77  acters written w
1afb0 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72 65 20 75  ould be a more u
1afc0 73 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20  seful return.** 
1afd0 76 61 6c 75 65 20 62 75 74 20 77 65 20 63 61 6e  value but we can
1afe0 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 69  not change the i
1aff0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
1b000 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
1b010 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f  f().** now witho
1b020 75 74 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70  ut breaking comp
1b030 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a  atibility..**.**
1b040 20 5e 41 73 20 6c 6f 6e 67 20 61 73 20 74 68 65   ^As long as the
1b050 20 62 75 66 66 65 72 20 73 69 7a 65 20 69 73 20   buffer size is 
1b060 67 72 65 61 74 65 72 20 74 68 61 6e 20 7a 65 72  greater than zer
1b070 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  o, sqlite3_snpri
1b080 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74  ntf().** guarant
1b090 65 65 73 20 74 68 61 74 20 74 68 65 20 62 75 66  ees that the buf
1b0a0 66 65 72 20 69 73 20 61 6c 77 61 79 73 20 7a 65  fer is always ze
1b0b0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20  ro-terminated.  
1b0c0 5e 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61  ^The first.** pa
1b0d0 72 61 6d 65 74 65 72 20 22 6e 22 20 69 73 20 74  rameter "n" is t
1b0e0 68 65 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66  he total size of
1b0f0 20 74 68 65 20 62 75 66 66 65 72 2c 20 69 6e 63   the buffer, inc
1b100 6c 75 64 69 6e 67 20 73 70 61 63 65 20 66 6f 72  luding space for
1b110 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74 65 72  .** the zero ter
1b120 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68 65  minator.  So the
1b130 20 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e 67 20   longest string 
1b140 74 68 61 74 20 63 61 6e 20 62 65 20 63 6f 6d 70  that can be comp
1b150 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65  letely.** writte
1b160 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68  n will be n-1 ch
1b170 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  aracters..**.** 
1b180 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 73 6e  ^The sqlite3_vsn
1b190 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65  printf() routine
1b1a0 20 69 73 20 61 20 76 61 72 61 72 67 73 20 76 65   is a varargs ve
1b1b0 72 73 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33  rsion of sqlite3
1b1c0 5f 73 6e 70 72 69 6e 74 66 28 29 2e 0a 2a 2a 0a  _snprintf()..**.
1b1d0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
1b1e0 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 20  s all implement 
1b1f0 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c 20  some additional 
1b200 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f 70  formatting.** op
1b210 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 75  tions that are u
1b220 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e 73 74 72  seful for constr
1b230 75 63 74 69 6e 67 20 53 51 4c 20 73 74 61 74 65  ucting SQL state
1b240 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66  ments..** All of
1b250 20 74 68 65 20 75 73 75 61 6c 20 70 72 69 6e 74   the usual print
1b260 66 28 29 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f  f() formatting o
1b270 70 74 69 6f 6e 73 20 61 70 70 6c 79 2e 20 20 49  ptions apply.  I
1b280 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74 68 65 72  n addition, ther
1b290 65 0a 2a 2a 20 69 73 20 61 72 65 20 22 25 71 22  e.** is are "%q"
1b2a0 2c 20 22 25 51 22 2c 20 61 6e 64 20 22 25 7a 22  , "%Q", and "%z"
1b2b0 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20   options..**.** 
1b2c0 5e 28 54 68 65 20 25 71 20 6f 70 74 69 6f 6e 20  ^(The %q option 
1b2d0 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e  works like %s in
1b2e0 20 74 68 61 74 20 69 74 20 73 75 62 73 74 69 74   that it substit
1b2f0 75 74 65 73 20 61 20 6e 75 6c 2d 74 65 72 6d 69  utes a nul-termi
1b300 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20  nated.** string 
1b310 66 72 6f 6d 20 74 68 65 20 61 72 67 75 6d 65 6e  from the argumen
1b320 74 20 6c 69 73 74 2e 20 20 42 75 74 20 25 71 20  t list.  But %q 
1b330 61 6c 73 6f 20 64 6f 75 62 6c 65 73 20 65 76 65  also doubles eve
1b340 72 79 20 27 5c 27 27 20 63 68 61 72 61 63 74 65  ry '\'' characte
1b350 72 2e 0a 2a 2a 20 25 71 20 69 73 20 64 65 73 69  r..** %q is desi
1b360 67 6e 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73  gned for use ins
1b370 69 64 65 20 61 20 73 74 72 69 6e 67 20 6c 69 74  ide a string lit
1b380 65 72 61 6c 2e 29 5e 20 20 42 79 20 64 6f 75 62  eral.)^  By doub
1b390 6c 69 6e 67 20 65 61 63 68 20 27 5c 27 27 0a 2a  ling each '\''.*
1b3a0 2a 20 63 68 61 72 61 63 74 65 72 20 69 74 20 65  * character it e
1b3b0 73 63 61 70 65 73 20 74 68 61 74 20 63 68 61 72  scapes that char
1b3c0 61 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73  acter and allows
1b3d0 20 69 74 20 74 6f 20 62 65 20 69 6e 73 65 72 74   it to be insert
1b3e0 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73  ed into.** the s
1b3f0 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72  tring..**.** For
1b400 20 65 78 61 6d 70 6c 65 2c 20 61 73 73 75 6d 65   example, assume
1b410 20 74 68 65 20 73 74 72 69 6e 67 20 76 61 72 69   the string vari
1b420 61 62 6c 65 20 7a 54 65 78 74 20 63 6f 6e 74 61  able zText conta
1b430 69 6e 73 20 74 65 78 74 20 61 73 20 66 6f 6c 6c  ins text as foll
1b440 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ows:.**.** <bloc
1b450 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
1b460 20 63 68 61 72 20 2a 7a 54 65 78 74 20 3d 20 22   char *zText = "
1b470 49 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79  It's a happy day
1b480 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  !";.** </pre></b
1b490 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
1b4a0 20 4f 6e 65 20 63 61 6e 20 75 73 65 20 74 68 69   One can use thi
1b4b0 73 20 74 65 78 74 20 69 6e 20 61 6e 20 53 51 4c  s text in an SQL
1b4c0 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20 66 6f   statement as fo
1b4d0 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  llows:.**.** <bl
1b4e0 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
1b4f0 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20  *  char *zSQL = 
1b500 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
1b510 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62  "INSERT INTO tab
1b520 6c 65 20 56 41 4c 55 45 53 28 27 25 71 27 29 22  le VALUES('%q')"
1b530 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71  , zText);.**  sq
1b540 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a  lite3_exec(db, z
1b550 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a  SQL, 0, 0, 0);.*
1b560 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  *  sqlite3_free(
1b570 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  zSQL);.** </pre>
1b580 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
1b590 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65 20  .** Because the 
1b5a0 25 71 20 66 6f 72 6d 61 74 20 73 74 72 69 6e 67  %q format string
1b5b0 20 69 73 20 75 73 65 64 2c 20 74 68 65 20 27 5c   is used, the '\
1b5c0 27 27 20 63 68 61 72 61 63 74 65 72 20 69 6e 20  '' character in 
1b5d0 7a 54 65 78 74 0a 2a 2a 20 69 73 20 65 73 63 61  zText.** is esca
1b5e0 70 65 64 20 61 6e 64 20 74 68 65 20 53 51 4c 20  ped and the SQL 
1b5f0 67 65 6e 65 72 61 74 65 64 20 69 73 20 61 73 20  generated is as 
1b600 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c  follows:.**.** <
1b610 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
1b620 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f  .**  INSERT INTO
1b630 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27   table1 VALUES('
1b640 49 74 27 27 73 20 61 20 68 61 70 70 79 20 64 61  It''s a happy da
1b650 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  y!').** </pre></
1b660 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
1b670 2a 20 54 68 69 73 20 69 73 20 63 6f 72 72 65 63  * This is correc
1b680 74 2e 20 20 48 61 64 20 77 65 20 75 73 65 64 20  t.  Had we used 
1b690 25 73 20 69 6e 73 74 65 61 64 20 6f 66 20 25 71  %s instead of %q
1b6a0 2c 20 74 68 65 20 67 65 6e 65 72 61 74 65 64 20  , the generated 
1b6b0 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76  SQL.** would hav
1b6c0 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68  e looked like th
1b6d0 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  is:.**.** <block
1b6e0 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
1b6f0 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c  INSERT INTO tabl
1b700 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 73 20  e1 VALUES('It's 
1b710 61 20 68 61 70 70 79 20 64 61 79 21 27 29 3b 0a  a happy day!');.
1b720 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
1b730 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  quote>.**.** Thi
1b740 73 20 73 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65  s second example
1b750 20 69 73 20 61 6e 20 53 51 4c 20 73 79 6e 74 61   is an SQL synta
1b760 78 20 65 72 72 6f 72 2e 20 20 41 73 20 61 20 67  x error.  As a g
1b770 65 6e 65 72 61 6c 20 72 75 6c 65 20 79 6f 75 20  eneral rule you 
1b780 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61 79 73  should.** always
1b790 20 75 73 65 20 25 71 20 69 6e 73 74 65 61 64 20   use %q instead 
1b7a0 6f 66 20 25 73 20 77 68 65 6e 20 69 6e 73 65 72  of %s when inser
1b7b0 74 69 6e 67 20 74 65 78 74 20 69 6e 74 6f 20 61  ting text into a
1b7c0 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e   string literal.
1b7d0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 51 20  .**.** ^(The %Q 
1b7e0 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b  option works lik
1b7f0 65 20 25 71 20 65 78 63 65 70 74 20 69 74 20 61  e %q except it a
1b800 6c 73 6f 20 61 64 64 73 20 73 69 6e 67 6c 65 20  lso adds single 
1b810 71 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a  quotes around.**
1b820 20 74 68 65 20 6f 75 74 73 69 64 65 20 6f 66 20   the outside of 
1b830 74 68 65 20 74 6f 74 61 6c 20 73 74 72 69 6e 67  the total string
1b840 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c  .  Additionally,
1b850 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
1b860 72 20 69 6e 20 74 68 65 0a 2a 2a 20 61 72 67 75  r in the.** argu
1b870 6d 65 6e 74 20 6c 69 73 74 20 69 73 20 61 20 4e  ment list is a N
1b880 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25 51 20  ULL pointer, %Q 
1b890 73 75 62 73 74 69 74 75 74 65 73 20 74 68 65 20  substitutes the 
1b8a0 74 65 78 74 20 22 4e 55 4c 4c 22 20 28 77 69 74  text "NULL" (wit
1b8b0 68 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 71  hout.** single q
1b8c0 75 6f 74 65 73 29 2e 29 5e 20 20 53 6f 2c 20 66  uotes).)^  So, f
1b8d0 6f 72 20 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 20  or example, one 
1b8e0 63 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a  could say:.**.**
1b8f0 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
1b900 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51  e>.**  char *zSQ
1b910 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69  L = sqlite3_mpri
1b920 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f  ntf("INSERT INTO
1b930 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 25 51   table VALUES(%Q
1b940 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20  )", zText);.**  
1b950 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c  sqlite3_exec(db,
1b960 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b   zSQL, 0, 0, 0);
1b970 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65  .**  sqlite3_fre
1b980 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72  e(zSQL);.** </pr
1b990 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
1b9a0 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 61  **.** The code a
1b9b0 62 6f 76 65 20 77 69 6c 6c 20 72 65 6e 64 65 72  bove will render
1b9c0 20 61 20 63 6f 72 72 65 63 74 20 53 51 4c 20 73   a correct SQL s
1b9d0 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20  tatement in the 
1b9e0 7a 53 51 4c 0a 2a 2a 20 76 61 72 69 61 62 6c 65  zSQL.** variable
1b9f0 20 65 76 65 6e 20 69 66 20 74 68 65 20 7a 54 65   even if the zTe
1ba00 78 74 20 76 61 72 69 61 62 6c 65 20 69 73 20 61  xt variable is a
1ba10 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
1ba20 2a 0a 2a 2a 20 5e 28 54 68 65 20 22 25 7a 22 20  *.** ^(The "%z" 
1ba30 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f  formatting optio
1ba40 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 22 25 73  n works like "%s
1ba50 22 20 62 75 74 20 77 69 74 68 20 74 68 65 0a 2a  " but with the.*
1ba60 2a 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74 20  * addition that 
1ba70 61 66 74 65 72 20 74 68 65 20 73 74 72 69 6e 67  after the string
1ba80 20 68 61 73 20 62 65 65 6e 20 72 65 61 64 20 61   has been read a
1ba90 6e 64 20 63 6f 70 69 65 64 20 69 6e 74 6f 0a 2a  nd copied into.*
1baa0 2a 20 74 68 65 20 72 65 73 75 6c 74 2c 20 5b 73  * the result, [s
1bab0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 69  qlite3_free()] i
1bac0 73 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20  s called on the 
1bad0 69 6e 70 75 74 20 73 74 72 69 6e 67 2e 29 5e 0a  input string.)^.
1bae0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68  */.SQLITE_API ch
1baf0 61 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69  ar *sqlite3_mpri
1bb00 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ntf(const char*,
1bb10 2e 2e 2e 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ...);.SQLITE_API
1bb20 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76   char *sqlite3_v
1bb30 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68  mprintf(const ch
1bb40 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 53  ar*, va_list);.S
1bb50 51 4c 49 54 45 5f 41 50 49 20 63 68 61 72 20 2a  QLITE_API char *
1bb60 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
1bb70 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74  (int,char*,const
1bb80 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 53 51   char*, ...);.SQ
1bb90 4c 49 54 45 5f 41 50 49 20 63 68 61 72 20 2a 73  LITE_API char *s
1bba0 71 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66  qlite3_vsnprintf
1bbb0 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74  (int,char*,const
1bbc0 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29   char*, va_list)
1bbd0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1bbe0 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61  F: Memory Alloca
1bbf0 74 69 6f 6e 20 53 75 62 73 79 73 74 65 6d 0a 2a  tion Subsystem.*
1bc00 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20  *.** The SQLite 
1bc10 63 6f 72 65 20 75 73 65 73 20 74 68 65 73 65 20  core uses these 
1bc20 74 68 72 65 65 20 72 6f 75 74 69 6e 65 73 20 66  three routines f
1bc30 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77  or all of its ow
1bc40 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65  n.** internal me
1bc50 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
1bc60 6e 65 65 64 73 2e 20 22 43 6f 72 65 22 20 69 6e  needs. "Core" in
1bc70 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 65   the previous se
1bc80 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e  ntence.** does n
1bc90 6f 74 20 69 6e 63 6c 75 64 65 20 6f 70 65 72 61  ot include opera
1bca0 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63  ting-system spec
1bcb0 69 66 69 63 20 56 46 53 20 69 6d 70 6c 65 6d 65  ific VFS impleme
1bcc0 6e 74 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a  ntation.  The.**
1bcd0 20 57 69 6e 64 6f 77 73 20 56 46 53 20 75 73 65   Windows VFS use
1bce0 73 20 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28  s native malloc(
1bcf0 29 20 61 6e 64 20 66 72 65 65 28 29 20 66 6f 72  ) and free() for
1bd00 20 73 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73   some operations
1bd10 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
1bd20 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f  ite3_malloc() ro
1bd30 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20  utine returns a 
1bd40 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f  pointer to a blo
1bd50 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20  ck.** of memory 
1bd60 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73  at least N bytes
1bd70 20 69 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65 72   in length, wher
1bd80 65 20 4e 20 69 73 20 74 68 65 20 70 61 72 61 6d  e N is the param
1bd90 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c  eter..** ^If sql
1bda0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73  ite3_malloc() is
1bdb0 20 75 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61 69   unable to obtai
1bdc0 6e 20 73 75 66 66 69 63 69 65 6e 74 20 66 72 65  n sufficient fre
1bdd0 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20  e.** memory, it 
1bde0 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70  returns a NULL p
1bdf0 6f 69 6e 74 65 72 2e 20 20 5e 49 66 20 74 68 65  ointer.  ^If the
1be00 20 70 61 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a   parameter N to.
1be10 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  ** sqlite3_mallo
1be20 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e  c() is zero or n
1be30 65 67 61 74 69 76 65 20 74 68 65 6e 20 73 71 6c  egative then sql
1be40 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65  ite3_malloc() re
1be50 74 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20  turns.** a NULL 
1be60 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  pointer..**.** ^
1be70 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f  Calling sqlite3_
1be80 66 72 65 65 28 29 20 77 69 74 68 20 61 20 70 6f  free() with a po
1be90 69 6e 74 65 72 20 70 72 65 76 69 6f 75 73 6c 79  inter previously
1bea0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20   returned.** by 
1beb0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1bec0 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   or sqlite3_real
1bed0 6c 6f 63 28 29 20 72 65 6c 65 61 73 65 73 20 74  loc() releases t
1bee0 68 61 74 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a  hat memory so.**
1bef0 20 74 68 61 74 20 69 74 20 6d 69 67 68 74 20 62   that it might b
1bf00 65 20 72 65 75 73 65 64 2e 20 20 5e 54 68 65 20  e reused.  ^The 
1bf10 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 72  sqlite3_free() r
1bf20 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e  outine is.** a n
1bf30 6f 2d 6f 70 20 69 66 20 69 73 20 63 61 6c 6c 65  o-op if is calle
1bf40 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f  d with a NULL po
1bf50 69 6e 74 65 72 2e 20 20 50 61 73 73 69 6e 67 20  inter.  Passing 
1bf60 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  a NULL pointer.*
1bf70 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65  * to sqlite3_fre
1bf80 65 28 29 20 69 73 20 68 61 72 6d 6c 65 73 73 2e  e() is harmless.
1bf90 20 20 41 66 74 65 72 20 62 65 69 6e 67 20 66 72    After being fr
1bfa0 65 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73  eed, memory.** s
1bfb0 68 6f 75 6c 64 20 6e 65 69 74 68 65 72 20 62 65  hould neither be
1bfc0 20 72 65 61 64 20 6e 6f 72 20 77 72 69 74 74 65   read nor writte
1bfd0 6e 2e 20 20 45 76 65 6e 20 72 65 61 64 69 6e 67  n.  Even reading
1bfe0 20 70 72 65 76 69 6f 75 73 6c 79 20 66 72 65 65   previously free
1bff0 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68  d.** memory migh
1c000 74 20 72 65 73 75 6c 74 20 69 6e 20 61 20 73 65  t result in a se
1c010 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74  gmentation fault
1c020 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65   or other severe
1c030 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72   error..** Memor
1c040 79 20 63 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20  y corruption, a 
1c050 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75  segmentation fau
1c060 6c 74 2c 20 6f 72 20 6f 74 68 65 72 20 73 65 76  lt, or other sev
1c070 65 72 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67  ere error.** mig
1c080 68 74 20 72 65 73 75 6c 74 20 69 66 20 73 71 6c  ht result if sql
1c090 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 63  ite3_free() is c
1c0a0 61 6c 6c 65 64 20 77 69 74 68 20 61 20 6e 6f 6e  alled with a non
1c0b0 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68  -NULL pointer th
1c0c0 61 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62  at.** was not ob
1c0d0 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69  tained from sqli
1c0e0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20  te3_malloc() or 
1c0f0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1c100 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73  )..**.** ^(The s
1c110 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1c120 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d   interface attem
1c130 70 74 73 20 74 6f 20 72 65 73 69 7a 65 20 61 0a  pts to resize a.
1c140 2a 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20  ** prior memory 
1c150 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65  allocation to be
1c160 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65   at least N byte
1c170 73 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  s, where N is th
1c180 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61  e.** second para
1c190 6d 65 74 65 72 2e 20 20 54 68 65 20 6d 65 6d 6f  meter.  The memo
1c1a0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f  ry allocation to
1c1b0 20 62 65 20 72 65 73 69 7a 65 64 20 69 73 20 74   be resized is t
1c1c0 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61  he first.** para
1c1d0 6d 65 74 65 72 2e 29 5e 20 5e 20 49 66 20 74 68  meter.)^ ^ If th
1c1e0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
1c1f0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61  r to sqlite3_rea
1c200 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 20 4e  lloc().** is a N
1c210 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e  ULL pointer then
1c220 20 69 74 73 20 62 65 68 61 76 69 6f 72 20 69 73   its behavior is
1c230 20 69 64 65 6e 74 69 63 61 6c 20 74 6f 20 63 61   identical to ca
1c240 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33  lling.** sqlite3
1c250 5f 6d 61 6c 6c 6f 63 28 4e 29 20 77 68 65 72 65  _malloc(N) where
1c260 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64   N is the second
1c270 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
1c280 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e  lite3_realloc().
1c290 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 65 63 6f  .** ^If the seco
1c2a0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  nd parameter to 
1c2b0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1c2c0 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20  ) is zero or.** 
1c2d0 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 74 68  negative then th
1c2e0 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 65 78  e behavior is ex
1c2f0 61 63 74 6c 79 20 74 68 65 20 73 61 6d 65 20 61  actly the same a
1c300 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c  s calling.** sql
1c310 69 74 65 33 5f 66 72 65 65 28 50 29 20 77 68 65  ite3_free(P) whe
1c320 72 65 20 50 20 69 73 20 74 68 65 20 66 69 72 73  re P is the firs
1c330 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  t parameter to s
1c340 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1c350 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65  ..** ^sqlite3_re
1c360 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 20  alloc() returns 
1c370 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d  a pointer to a m
1c380 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
1c390 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20  .** of at least 
1c3a0 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20  N bytes in size 
1c3b0 6f 72 20 4e 55 4c 4c 20 69 66 20 73 75 66 66 69  or NULL if suffi
1c3c0 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20  cient memory is 
1c3d0 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20  unavailable..** 
1c3e0 5e 49 66 20 4d 20 69 73 20 74 68 65 20 73 69 7a  ^If M is the siz
1c3f0 65 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61  e of the prior a
1c400 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20  llocation, then 
1c410 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a  min(N,M) bytes.*
1c420 2a 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61  * of the prior a
1c430 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20 63 6f  llocation are co
1c440 70 69 65 64 20 69 6e 74 6f 20 74 68 65 20 62 65  pied into the be
1c450 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66 65  ginning of buffe
1c460 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79  r returned.** by
1c470 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1c480 28 29 20 61 6e 64 20 74 68 65 20 70 72 69 6f 72  () and the prior
1c490 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66   allocation is f
1c4a0 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c  reed..** ^If sql
1c4b0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72  ite3_realloc() r
1c4c0 65 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 74 68 65  eturns NULL, the
1c4d0 6e 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f  n the prior allo
1c4e0 63 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6e 6f 74  cation.** is not
1c4f0 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54   freed..**.** ^T
1c500 68 65 20 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e  he memory return
1c510 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61  ed by sqlite3_ma
1c520 6c 6c 6f 63 28 29 20 61 6e 64 20 73 71 6c 69 74  lloc() and sqlit
1c530 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20  e3_realloc().** 
1c540 69 73 20 61 6c 77 61 79 73 20 61 6c 69 67 6e 65  is always aligne
1c550 64 20 74 6f 20 61 74 20 6c 65 61 73 74 20 61 6e  d to at least an
1c560 20 38 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79   8 byte boundary
1c570 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a 20 34 20 62  , or to a.** 4 b
1c580 79 74 65 20 62 6f 75 6e 64 61 72 79 20 69 66 20  yte boundary if 
1c590 74 68 65 20 5b 53 51 4c 49 54 45 5f 34 5f 42 59  the [SQLITE_4_BY
1c5a0 54 45 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f  TE_ALIGNED_MALLO
1c5b0 43 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a  C] compile-time.
1c5c0 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  ** option is use
1c5d0 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69  d..**.** In SQLi
1c5e0 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30  te version 3.5.0
1c5f0 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20 77   and 3.5.1, it w
1c600 61 73 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 64  as possible to d
1c610 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51 4c  efine.** the SQL
1c620 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f  ITE_OMIT_MEMORY_
1c630 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63 68  ALLOCATION which
1c640 20 77 6f 75 6c 64 20 63 61 75 73 65 20 74 68 65   would cause the
1c650 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70   built-in.** imp
1c660 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74  lementation of t
1c670 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 6f  hese routines to
1c680 20 62 65 20 6f 6d 69 74 74 65 64 2e 20 20 54 68   be omitted.  Th
1c690 61 74 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a  at capability.**
1c6a0 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70 72   is no longer pr
1c6b0 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62 75  ovided.  Only bu
1c6c0 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c  ilt-in memory al
1c6d0 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20 62 65 20  locators can be 
1c6e0 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f  used..**.** Prio
1c6f0 72 20 74 6f 20 53 51 4c 69 74 65 20 76 65 72 73  r to SQLite vers
1c700 69 6f 6e 20 33 2e 37 2e 31 30 2c 20 74 68 65 20  ion 3.7.10, the 
1c710 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65 72  Windows OS inter
1c720 66 61 63 65 20 6c 61 79 65 72 20 63 61 6c 6c 65  face layer calle
1c730 64 0a 2a 2a 20 74 68 65 20 73 79 73 74 65 6d 20  d.** the system 
1c740 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65  malloc() and fre
1c750 65 28 29 20 64 69 72 65 63 74 6c 79 20 77 68 65  e() directly whe
1c760 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20  n converting.** 
1c770 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 77 65 65  filenames betwee
1c780 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f  n the UTF-8 enco
1c790 64 69 6e 67 20 75 73 65 64 20 62 79 20 53 51 4c  ding used by SQL
1c7a0 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65  ite.** and whate
1c7b0 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63  ver filename enc
1c7c0 6f 64 69 6e 67 20 69 73 20 75 73 65 64 20 62 79  oding is used by
1c7d0 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20   the particular 
1c7e0 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61  Windows.** insta
1c7f0 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79  llation.  Memory
1c800 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f   allocation erro
1c810 72 73 20 77 65 72 65 20 64 65 74 65 63 74 65 64  rs were detected
1c820 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79 20 77 65  , but.** they we
1c830 72 65 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b  re reported back
1c840 20 61 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54   as [SQLITE_CANT
1c850 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c  OPEN] or.** [SQL
1c860 49 54 45 5f 49 4f 45 52 52 5d 20 72 61 74 68 65  ITE_IOERR] rathe
1c870 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e  r than [SQLITE_N
1c880 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  OMEM]..**.** The
1c890 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e   pointer argumen
1c8a0 74 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  ts to [sqlite3_f
1c8b0 72 65 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ree()] and [sqli
1c8c0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a  te3_realloc()].*
1c8d0 2a 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72  * must be either
1c8e0 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70 6f   NULL or else po
1c8f0 69 6e 74 65 72 73 20 6f 62 74 61 69 6e 65 64 20  inters obtained 
1c900 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20  from a prior.** 
1c910 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73  invocation of [s
1c920 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
1c930 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61   or [sqlite3_rea
1c940 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 68 61 76  lloc()] that hav
1c950 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62 65 65  e.** not yet bee
1c960 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a  n released..**.*
1c970 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
1c980 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65 61 64 20  n must not read 
1c990 6f 72 20 77 72 69 74 65 20 61 6e 79 20 70 61 72  or write any par
1c9a0 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20  t of.** a block 
1c9b0 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 65 72 20  of memory after 
1c9c0 69 74 20 68 61 73 20 62 65 65 6e 20 72 65 6c 65  it has been rele
1c9d0 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  ased using.** [s
1c9e0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f  qlite3_free()] o
1c9f0 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  r [sqlite3_reall
1ca00 6f 63 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45  oc()]..*/.SQLITE
1ca10 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74  _API void *sqlit
1ca20 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a  e3_malloc(int);.
1ca30 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
1ca40 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  *sqlite3_realloc
1ca50 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 53 51  (void*, int);.SQ
1ca60 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71  LITE_API void sq
1ca70 6c 69 74 65 33 5f 66 72 65 65 28 76 6f 69 64 2a  lite3_free(void*
1ca80 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1ca90 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63  EF: Memory Alloc
1caa0 61 74 6f 72 20 53 74 61 74 69 73 74 69 63 73 0a  ator Statistics.
1cab0 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f  **.** SQLite pro
1cac0 76 69 64 65 73 20 74 68 65 73 65 20 74 77 6f 20  vides these two 
1cad0 69 6e 74 65 72 66 61 63 65 73 20 66 6f 72 20 72  interfaces for r
1cae0 65 70 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65 20  eporting on the 
1caf0 73 74 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65  status.** of the
1cb00 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
1cb10 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72  ()], [sqlite3_fr
1cb20 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69  ee()], and [sqli
1cb30 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a  te3_realloc()].*
1cb40 2a 20 72 6f 75 74 69 6e 65 73 2c 20 77 68 69 63  * routines, whic
1cb50 68 20 66 6f 72 6d 20 74 68 65 20 62 75 69 6c 74  h form the built
1cb60 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  -in memory alloc
1cb70 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e  ation subsystem.
1cb80 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c  .**.** ^The [sql
1cb90 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
1cba0 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75  ()] routine retu
1cbb0 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
1cbc0 66 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 6d 65  f bytes.** of me
1cbd0 6d 6f 72 79 20 63 75 72 72 65 6e 74 6c 79 20 6f  mory currently o
1cbe0 75 74 73 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c  utstanding (mall
1cbf0 6f 63 65 64 20 62 75 74 20 6e 6f 74 20 66 72 65  oced but not fre
1cc00 65 64 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71  ed)..** ^The [sq
1cc10 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
1cc20 68 77 61 74 65 72 28 29 5d 20 72 6f 75 74 69 6e  hwater()] routin
1cc30 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6d 61  e returns the ma
1cc40 78 69 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f  ximum.** value o
1cc50 66 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  f [sqlite3_memor
1cc60 79 5f 75 73 65 64 28 29 5d 20 73 69 6e 63 65 20  y_used()] since 
1cc70 74 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d  the high-water m
1cc80 61 72 6b 0a 2a 2a 20 77 61 73 20 6c 61 73 74 20  ark.** was last 
1cc90 72 65 73 65 74 2e 20 20 5e 54 68 65 20 76 61 6c  reset.  ^The val
1cca0 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ues returned by 
1ccb0 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
1ccc0 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b  used()] and.** [
1ccd0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
1cce0 69 67 68 77 61 74 65 72 28 29 5d 20 69 6e 63 6c  ighwater()] incl
1ccf0 75 64 65 20 61 6e 79 20 6f 76 65 72 68 65 61 64  ude any overhead
1cd00 0a 2a 2a 20 61 64 64 65 64 20 62 79 20 53 51 4c  .** added by SQL
1cd10 69 74 65 20 69 6e 20 69 74 73 20 69 6d 70 6c 65  ite in its imple
1cd20 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 73 71  mentation of [sq
1cd30 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c  lite3_malloc()],
1cd40 0a 2a 2a 20 62 75 74 20 6e 6f 74 20 6f 76 65 72  .** but not over
1cd50 68 65 61 64 20 61 64 64 65 64 20 62 79 20 74 68  head added by th
1cd60 65 20 61 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67  e any underlying
1cd70 20 73 79 73 74 65 6d 20 6c 69 62 72 61 72 79 0a   system library.
1cd80 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74  ** routines that
1cd90 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
1cda0 28 29 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a  ()] may call..**
1cdb0 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20  .** ^The memory 
1cdc0 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 20  high-water mark 
1cdd0 69 73 20 72 65 73 65 74 20 74 6f 20 74 68 65 20  is reset to the 
1cde0 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66  current value of
1cdf0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  .** [sqlite3_mem
1ce00 6f 72 79 5f 75 73 65 64 28 29 5d 20 69 66 20 61  ory_used()] if a
1ce10 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 70  nd only if the p
1ce20 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b  arameter to.** [
1ce30 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
1ce40 69 67 68 77 61 74 65 72 28 29 5d 20 69 73 20 74  ighwater()] is t
1ce50 72 75 65 2e 20 20 5e 54 68 65 20 76 61 6c 75 65  rue.  ^The value
1ce60 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20   returned.** by 
1ce70 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
1ce80 68 69 67 68 77 61 74 65 72 28 31 29 5d 20 69 73  highwater(1)] is
1ce90 20 74 68 65 20 68 69 67 68 2d 77 61 74 65 72 20   the high-water 
1cea0 6d 61 72 6b 0a 2a 2a 20 70 72 69 6f 72 20 74 6f  mark.** prior to
1ceb0 20 74 68 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 53   the reset..*/.S
1cec0 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65  QLITE_API sqlite
1ced0 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
1cee0 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69 64  memory_used(void
1cef0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71  );.SQLITE_API sq
1cf00 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
1cf10 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
1cf20 61 74 65 72 28 69 6e 74 20 72 65 73 65 74 46 6c  ater(int resetFl
1cf30 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ag);../*.** CAPI
1cf40 33 52 45 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e  3REF: Pseudo-Ran
1cf50 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65 72  dom Number Gener
1cf60 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  ator.**.** SQLit
1cf70 65 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 69 67  e contains a hig
1cf80 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64 6f  h-quality pseudo
1cf90 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67  -random number g
1cfa0 65 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 29 20  enerator (PRNG) 
1cfb0 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63  used to.** selec
1cfc0 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44 20  t random [ROWID 
1cfd0 7c 20 52 4f 57 49 44 73 5d 20 77 68 65 6e 20 69  | ROWIDs] when i
1cfe0 6e 73 65 72 74 69 6e 67 20 6e 65 77 20 72 65 63  nserting new rec
1cff0 6f 72 64 73 20 69 6e 74 6f 20 61 20 74 61 62 6c  ords into a tabl
1d000 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64  e that.** alread
1d010 79 20 75 73 65 73 20 74 68 65 20 6c 61 72 67 65  y uses the large
1d020 73 74 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f 57  st possible [ROW
1d030 49 44 5d 2e 20 20 54 68 65 20 50 52 4e 47 20 69  ID].  The PRNG i
1d040 73 20 61 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a  s also used for.
1d050 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d 69 6e 20  ** the build-in 
1d060 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e  random() and ran
1d070 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66 75  domblob() SQL fu
1d080 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69 73 20 69  nctions.  This i
1d090 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a  nterface allows.
1d0a0 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** applications 
1d0b0 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 73 61  to access the sa
1d0c0 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f 74 68 65  me PRNG for othe
1d0d0 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a  r purposes..**.*
1d0e0 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 74 68 69  * ^A call to thi
1d0f0 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73  s routine stores
1d100 20 4e 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64   N bytes of rand
1d110 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 66 66  omness into buff
1d120 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  er P..**.** ^The
1d130 20 66 69 72 73 74 20 74 69 6d 65 20 74 68 69 73   first time this
1d140 20 72 6f 75 74 69 6e 65 20 69 73 20 69 6e 76 6f   routine is invo
1d150 6b 65 64 20 28 65 69 74 68 65 72 20 69 6e 74 65  ked (either inte
1d160 72 6e 61 6c 6c 79 20 6f 72 20 62 79 0a 2a 2a 20  rnally or by.** 
1d170 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 29  the application)
1d180 20 74 68 65 20 50 52 4e 47 20 69 73 20 73 65 65   the PRNG is see
1d190 64 65 64 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d  ded using random
1d1a0 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 0a 2a 2a  ness obtained.**
1d1b0 20 66 72 6f 6d 20 74 68 65 20 78 52 61 6e 64 6f   from the xRando
1d1c0 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20  mness method of 
1d1d0 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c  the default [sql
1d1e0 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
1d1f0 2e 0a 2a 2a 20 5e 4f 6e 20 61 6c 6c 20 73 75 62  ..** ^On all sub
1d200 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69  sequent invocati
1d210 6f 6e 73 2c 20 74 68 65 20 70 73 65 75 64 6f 2d  ons, the pseudo-
1d220 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67 65  randomness is ge
1d230 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72  nerated.** inter
1d240 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f 75  nally and withou
1d250 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20 74 68  t recourse to th
1d260 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  e [sqlite3_vfs] 
1d270 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d  xRandomness.** m
1d280 65 74 68 6f 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45  ethod..*/.SQLITE
1d290 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65  _API void sqlite
1d2a0 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e 74  3_randomness(int
1d2b0 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f   N, void *P);../
1d2c0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
1d2d0 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75 74 68  ompile-Time Auth
1d2e0 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 61  orization Callba
1d2f0 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  cks.**.** ^This 
1d300 72 6f 75 74 69 6e 65 20 72 65 67 69 73 74 65 72  routine register
1d310 73 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 20  s an authorizer 
1d320 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 61 20  callback with a 
1d330 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64  particular.** [d
1d340 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1d350 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 64 20 69 6e  on], supplied in
1d360 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
1d370 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 61 75 74  ent..** ^The aut
1d380 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1d390 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 20 53   is invoked as S
1d3a0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72  QL statements ar
1d3b0 65 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64  e being compiled
1d3c0 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  .** by [sqlite3_
1d3d0 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74  prepare()] or it
1d3e0 73 20 76 61 72 69 61 6e 74 73 20 5b 73 71 6c 69  s variants [sqli
1d3f0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1d400 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  ],.** [sqlite3_p
1d410 72 65 70 61 72 65 31 36 28 29 5d 20 61 6e 64 20  repare16()] and 
1d420 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1d430 31 36 5f 76 32 28 29 5d 2e 20 20 5e 41 74 20 76  16_v2()].  ^At v
1d440 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73  arious.** points
1d450 20 64 75 72 69 6e 67 20 74 68 65 20 63 6f 6d 70   during the comp
1d460 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c  ilation process,
1d470 20 61 73 20 6c 6f 67 69 63 20 69 73 20 62 65 69   as logic is bei
1d480 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f  ng created.** to
1d490 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73   perform various
1d4a0 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 20 61 75   actions, the au
1d4b0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1d4c0 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a  k is invoked to.
1d4d0 2a 2a 20 73 65 65 20 69 66 20 74 68 6f 73 65 20  ** see if those 
1d4e0 61 63 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f  actions are allo
1d4f0 77 65 64 2e 20 20 5e 54 68 65 20 61 75 74 68 6f  wed.  ^The autho
1d500 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 73  rizer callback s
1d510 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20  hould.** return 
1d520 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61  [SQLITE_OK] to a
1d530 6c 6c 6f 77 20 74 68 65 20 61 63 74 69 6f 6e 2c  llow the action,
1d540 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
1d550 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68 65   to disallow the
1d560 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 61 63 74  .** specific act
1d570 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74 68  ion but allow th
1d580 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
1d590 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62  to continue to b
1d5a0 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f  e.** compiled, o
1d5b0 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20  r [SQLITE_DENY] 
1d5c0 74 6f 20 63 61 75 73 65 20 74 68 65 20 65 6e 74  to cause the ent
1d5d0 69 72 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ire SQL statemen
1d5e0 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63  t to be.** rejec
1d5f0 74 65 64 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ted with an erro
1d600 72 2e 20 20 5e 49 66 20 74 68 65 20 61 75 74 68  r.  ^If the auth
1d610 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1d620 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76  returns.** any v
1d630 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e 20  alue other than 
1d640 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c  [SQLITE_IGNORE],
1d650 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72   [SQLITE_OK], or
1d660 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a   [SQLITE_DENY].*
1d670 2a 20 74 68 65 6e 20 74 68 65 20 5b 73 71 6c 69  * then the [sqli
1d680 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1d690 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20  ] or equivalent 
1d6a0 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65  call that trigge
1d6b0 72 65 64 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f  red.** the autho
1d6c0 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20  rizer will fail 
1d6d0 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65  with an error me
1d6e0 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65  ssage..**.** Whe
1d6f0 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  n the callback r
1d700 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
1d710 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74  K], that means t
1d720 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20  he operation.** 
1d730 72 65 71 75 65 73 74 65 64 20 69 73 20 6f 6b 2e  requested is ok.
1d740 20 20 5e 57 68 65 6e 20 74 68 65 20 63 61 6c 6c    ^When the call
1d750 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51  back returns [SQ
1d760 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a  LITE_DENY], the.
1d770 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
1d780 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75  are_v2()] or equ
1d790 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61  ivalent call tha
1d7a0 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65 0a  t triggered the.
1d7b0 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69  ** authorizer wi
1d7c0 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20  ll fail with an 
1d7d0 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 65 78  error message ex
1d7e0 70 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a  plaining that.**
1d7f0 20 61 63 63 65 73 73 20 69 73 20 64 65 6e 69 65   access is denie
1d800 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  d. .**.** ^The f
1d810 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
1d820 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  o the authorizer
1d830 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63   callback is a c
1d840 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69 72 64  opy of the third
1d850 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f  .** parameter to
1d860 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74   the sqlite3_set
1d870 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 20 69 6e  _authorizer() in
1d880 74 65 72 66 61 63 65 2e 20 5e 54 68 65 20 73 65  terface. ^The se
1d890 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a  cond parameter.*
1d8a0 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  * to the callbac
1d8b0 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  k is an integer 
1d8c0 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61  [SQLITE_COPY | a
1d8d0 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74  ction code] that
1d8e0 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68   specifies.** th
1d8f0 65 20 70 61 72 74 69 63 75 6c 61 72 20 61 63 74  e particular act
1d900 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72  ion to be author
1d910 69 7a 65 64 2e 20 5e 54 68 65 20 74 68 69 72 64  ized. ^The third
1d920 20 74 68 72 6f 75 67 68 20 73 69 78 74 68 20 70   through sixth p
1d930 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20  arameters.** to 
1d940 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 72 65  the callback are
1d950 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
1d960 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 63 6f   strings that co
1d970 6e 74 61 69 6e 20 61 64 64 69 74 69 6f 6e 61 6c  ntain additional
1d980 0a 2a 2a 20 64 65 74 61 69 6c 73 20 61 62 6f 75  .** details abou
1d990 74 20 74 68 65 20 61 63 74 69 6f 6e 20 74 6f 20  t the action to 
1d9a0 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a  be authorized..*
1d9b0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74  *.** ^If the act
1d9c0 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c  ion code is [SQL
1d9d0 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e 64  ITE_READ].** and
1d9e0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
1d9f0 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 49 47  turns [SQLITE_IG
1da00 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 0a 2a  NORE] then the.*
1da10 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
1da20 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65 6e 74  ement] statement
1da30 20 69 73 20 63 6f 6e 73 74 72 75 63 74 65 64 20   is constructed 
1da40 74 6f 20 73 75 62 73 74 69 74 75 74 65 0a 2a 2a  to substitute.**
1da50 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e   a NULL value in
1da60 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20 74 61   place of the ta
1da70 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20  ble column that 
1da80 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 62 65  would have.** be
1da90 65 6e 20 72 65 61 64 20 69 66 20 5b 53 51 4c 49  en read if [SQLI
1daa0 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20  TE_OK] had been 
1dab0 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 5b  returned.  The [
1dac0 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a  SQLITE_IGNORE].*
1dad0 2a 20 72 65 74 75 72 6e 20 63 61 6e 20 62 65 20  * return can be 
1dae0 75 73 65 64 20 74 6f 20 64 65 6e 79 20 61 6e 20  used to deny an 
1daf0 75 6e 74 72 75 73 74 65 64 20 75 73 65 72 20 61  untrusted user a
1db00 63 63 65 73 73 20 74 6f 20 69 6e 64 69 76 69 64  ccess to individ
1db10 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f  ual.** columns o
1db20 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 20 5e 49  f a table..** ^I
1db30 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64  f the action cod
1db40 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 44 45 4c  e is [SQLITE_DEL
1db50 45 54 45 5d 20 61 6e 64 20 74 68 65 20 63 61 6c  ETE] and the cal
1db60 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a  lback returns.**
1db70 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
1db80 20 74 68 65 6e 20 74 68 65 20 5b 44 45 4c 45 54   then the [DELET
1db90 45 5d 20 6f 70 65 72 61 74 69 6f 6e 20 70 72 6f  E] operation pro
1dba0 63 65 65 64 73 20 62 75 74 20 74 68 65 0a 2a 2a  ceeds but the.**
1dbb0 20 5b 74 72 75 6e 63 61 74 65 20 6f 70 74 69 6d   [truncate optim
1dbc0 69 7a 61 74 69 6f 6e 5d 20 69 73 20 64 69 73 61  ization] is disa
1dbd0 62 6c 65 64 20 61 6e 64 20 61 6c 6c 20 72 6f 77  bled and all row
1dbe0 73 20 61 72 65 20 64 65 6c 65 74 65 64 20 69 6e  s are deleted in
1dbf0 64 69 76 69 64 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a  dividually..**.*
1dc00 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20  * An authorizer 
1dc10 69 73 20 75 73 65 64 20 77 68 65 6e 20 5b 73 71  is used when [sq
1dc20 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20  lite3_prepare | 
1dc30 70 72 65 70 61 72 69 6e 67 5d 0a 2a 2a 20 53 51  preparing].** SQ
1dc40 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 66 72 6f  L statements fro
1dc50 6d 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73  m an untrusted s
1dc60 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73 75 72 65  ource, to ensure
1dc70 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 73 74   that the SQL st
1dc80 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e  atements.** do n
1dc90 6f 74 20 74 72 79 20 74 6f 20 61 63 63 65 73 73  ot try to access
1dca0 20 64 61 74 61 20 74 68 65 79 20 61 72 65 20 6e   data they are n
1dcb0 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73 65  ot allowed to se
1dcc0 65 2c 20 6f 72 20 74 68 61 74 20 74 68 65 79 20  e, or that they 
1dcd0 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79 20 74 6f  do not.** try to
1dce0 20 65 78 65 63 75 74 65 20 6d 61 6c 69 63 69 6f   execute malicio
1dcf0 75 73 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68  us statements th
1dd00 61 74 20 64 61 6d 61 67 65 20 74 68 65 20 64 61  at damage the da
1dd10 74 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a 20  tabase.  For.** 
1dd20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c  example, an appl
1dd30 69 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f  ication may allo
1dd40 77 20 61 20 75 73 65 72 20 74 6f 20 65 6e 74 65  w a user to ente
1dd50 72 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 53  r arbitrary.** S
1dd60 51 4c 20 71 75 65 72 69 65 73 20 66 6f 72 20 65  QL queries for e
1dd70 76 61 6c 75 61 74 69 6f 6e 20 62 79 20 61 20 64  valuation by a d
1dd80 61 74 61 62 61 73 65 2e 20 20 42 75 74 20 74 68  atabase.  But th
1dd90 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f  e application do
1dda0 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74  es.** not want t
1ddb0 68 65 20 75 73 65 72 20 74 6f 20 62 65 20 61 62  he user to be ab
1ddc0 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72 62 69 74  le to make arbit
1ddd0 72 61 72 79 20 63 68 61 6e 67 65 73 20 74 6f 20  rary changes to 
1dde0 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e  the.** database.
1ddf0 20 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20    An authorizer 
1de00 63 6f 75 6c 64 20 74 68 65 6e 20 62 65 20 70 75  could then be pu
1de10 74 20 69 6e 20 70 6c 61 63 65 20 77 68 69 6c 65  t in place while
1de20 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e 74   the.** user-ent
1de30 65 72 65 64 20 53 51 4c 20 69 73 20 62 65 69 6e  ered SQL is bein
1de40 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  g [sqlite3_prepa
1de50 72 65 20 7c 20 70 72 65 70 61 72 65 64 5d 20 74  re | prepared] t
1de60 68 61 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77 73  hat.** disallows
1de70 20 65 76 65 72 79 74 68 69 6e 67 20 65 78 63 65   everything exce
1de80 70 74 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74  pt [SELECT] stat
1de90 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70  ements..**.** Ap
1dea0 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
1deb0 6e 65 65 64 20 74 6f 20 70 72 6f 63 65 73 73 20  need to process 
1dec0 53 51 4c 20 66 72 6f 6d 20 75 6e 74 72 75 73 74  SQL from untrust
1ded0 65 64 20 73 6f 75 72 63 65 73 0a 2a 2a 20 6d 69  ed sources.** mi
1dee0 67 68 74 20 61 6c 73 6f 20 63 6f 6e 73 69 64 65  ght also conside
1def0 72 20 6c 6f 77 65 72 69 6e 67 20 72 65 73 6f 75  r lowering resou
1df00 72 63 65 20 6c 69 6d 69 74 73 20 75 73 69 6e 67  rce limits using
1df10 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28   [sqlite3_limit(
1df20 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69 74 69  )].** and limiti
1df30 6e 67 20 64 61 74 61 62 61 73 65 20 73 69 7a 65  ng database size
1df40 20 75 73 69 6e 67 20 74 68 65 20 5b 6d 61 78 5f   using the [max_
1df50 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41  page_count] [PRA
1df60 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64 64 69 74  GMA].** in addit
1df70 69 6f 6e 20 74 6f 20 75 73 69 6e 67 20 61 6e 20  ion to using an 
1df80 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a  authorizer..**.*
1df90 2a 20 5e 28 4f 6e 6c 79 20 61 20 73 69 6e 67 6c  * ^(Only a singl
1dfa0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6e  e authorizer can
1dfb0 20 62 65 20 69 6e 20 70 6c 61 63 65 20 6f 6e 20   be in place on 
1dfc0 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  a database conne
1dfd0 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20 74 69  ction.** at a ti
1dfe0 6d 65 2e 20 20 45 61 63 68 20 63 61 6c 6c 20 74  me.  Each call t
1dff0 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  o sqlite3_set_au
1e000 74 68 6f 72 69 7a 65 72 20 6f 76 65 72 72 69 64  thorizer overrid
1e010 65 73 20 74 68 65 0a 2a 2a 20 70 72 65 76 69 6f  es the.** previo
1e020 75 73 20 63 61 6c 6c 2e 29 5e 20 20 5e 44 69 73  us call.)^  ^Dis
1e030 61 62 6c 65 20 74 68 65 20 61 75 74 68 6f 72 69  able the authori
1e040 7a 65 72 20 62 79 20 69 6e 73 74 61 6c 6c 69 6e  zer by installin
1e050 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62 61 63  g a NULL callbac
1e060 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72  k..** The author
1e070 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c 65 64  izer is disabled
1e080 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a   by default..**.
1e090 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65  ** The authorize
1e0a0 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20  r callback must 
1e0b0 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20  not do anything 
1e0c0 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79  that will modify
1e0d0 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
1e0e0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74   connection that
1e0f0 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 61 75 74   invoked the aut
1e100 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1e110 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b  ..** Note that [
1e120 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1e130 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  v2()] and [sqlit
1e140 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20  e3_step()] both 
1e150 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20  modify their.** 
1e160 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1e170 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61  ions for the mea
1e180 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22  ning of "modify"
1e190 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61   in this paragra
1e1a0 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20  ph..**.** ^When 
1e1b0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1e1c0 5f 76 32 28 29 5d 20 69 73 20 75 73 65 64 20 74  _v2()] is used t
1e1d0 6f 20 70 72 65 70 61 72 65 20 61 20 73 74 61 74  o prepare a stat
1e1e0 65 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a 20 73 74  ement, the.** st
1e1f0 61 74 65 6d 65 6e 74 20 6d 69 67 68 74 20 62 65  atement might be
1e200 20 72 65 2d 70 72 65 70 61 72 65 64 20 64 75 72   re-prepared dur
1e210 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ing [sqlite3_ste
1e220 70 28 29 5d 20 64 75 65 20 74 6f 20 61 20 0a 2a  p()] due to a .*
1e230 2a 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e  * schema change.
1e240 20 20 48 65 6e 63 65 2c 20 74 68 65 20 61 70 70    Hence, the app
1e250 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  lication should 
1e260 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 0a  ensure that the.
1e270 2a 2a 20 63 6f 72 72 65 63 74 20 61 75 74 68 6f  ** correct autho
1e280 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72  rizer callback r
1e290 65 6d 61 69 6e 73 20 69 6e 20 70 6c 61 63 65 20  emains in place 
1e2a0 64 75 72 69 6e 67 20 74 68 65 20 5b 73 71 6c 69  during the [sqli
1e2b0 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a  te3_step()]..**.
1e2c0 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68  ** ^Note that th
1e2d0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1e2e0 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
1e2f0 20 6f 6e 6c 79 20 64 75 72 69 6e 67 0a 2a 2a 20   only during.** 
1e300 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1e310 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61  ()] or its varia
1e320 6e 74 73 2e 20 20 41 75 74 68 6f 72 69 7a 61 74  nts.  Authorizat
1e330 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20 70 65  ion is not.** pe
1e340 72 66 6f 72 6d 65 64 20 64 75 72 69 6e 67 20 73  rformed during s
1e350 74 61 74 65 6d 65 6e 74 20 65 76 61 6c 75 61 74  tatement evaluat
1e360 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f  ion in [sqlite3_
1e370 73 74 65 70 28 29 5d 2c 20 75 6e 6c 65 73 73 0a  step()], unless.
1e380 2a 2a 20 61 73 20 73 74 61 74 65 64 20 69 6e 20  ** as stated in 
1e390 74 68 65 20 70 72 65 76 69 6f 75 73 20 70 61 72  the previous par
1e3a0 61 67 72 61 70 68 2c 20 73 71 6c 69 74 65 33 5f  agraph, sqlite3_
1e3b0 73 74 65 70 28 29 20 69 6e 76 6f 6b 65 73 0a 2a  step() invokes.*
1e3c0 2a 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  * sqlite3_prepar
1e3d0 65 5f 76 32 28 29 20 74 6f 20 72 65 70 72 65 70  e_v2() to reprep
1e3e0 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74 20  are a statement 
1e3f0 61 66 74 65 72 20 61 20 73 63 68 65 6d 61 20 63  after a schema c
1e400 68 61 6e 67 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45  hange..*/.SQLITE
1e410 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
1e420 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28  _set_authorizer(
1e430 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69  .  sqlite3*,.  i
1e440 6e 74 20 28 2a 78 41 75 74 68 29 28 76 6f 69 64  nt (*xAuth)(void
1e450 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72  *,int,const char
1e460 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f  *,const char*,co
1e470 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20  nst char*,const 
1e480 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a  char*),.  void *
1e490 70 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a  pUserData.);../*
1e4a0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75  .** CAPI3REF: Au
1e4b0 74 68 6f 72 69 7a 65 72 20 52 65 74 75 72 6e 20  thorizer Return 
1e4c0 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20  Codes.**.** The 
1e4d0 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
1e4e0 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72  horizer | author
1e4f0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75  izer callback fu
1e500 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20  nction] must.** 
1e510 72 65 74 75 72 6e 20 65 69 74 68 65 72 20 5b 53  return either [S
1e520 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65  QLITE_OK] or one
1e530 20 6f 66 20 74 68 65 73 65 20 74 77 6f 20 63 6f   of these two co
1e540 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72 64 65 72  nstants in order
1e550 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53 51  .** to signal SQ
1e560 4c 69 74 65 20 77 68 65 74 68 65 72 20 6f 72 20  Lite whether or 
1e570 6e 6f 74 20 74 68 65 20 61 63 74 69 6f 6e 20 69  not the action i
1e580 73 20 70 65 72 6d 69 74 74 65 64 2e 20 20 53 65  s permitted.  Se
1e590 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  e the.** [sqlite
1e5a0 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
1e5b0 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 64 6f   | authorizer do
1e5c0 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72  cumentation] for
1e5d0 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69   additional.** i
1e5e0 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
1e5f0 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 49  * Note that SQLI
1e600 54 45 5f 49 47 4e 4f 52 45 20 69 73 20 61 6c 73  TE_IGNORE is als
1e610 6f 20 75 73 65 64 20 61 73 20 61 20 5b 53 51 4c  o used as a [SQL
1e620 49 54 45 5f 52 4f 4c 4c 42 41 43 4b 20 7c 20 72  ITE_ROLLBACK | r
1e630 65 74 75 72 6e 20 63 6f 64 65 5d 0a 2a 2a 20 66  eturn code].** f
1e640 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33  rom the [sqlite3
1e650 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63  _vtab_on_conflic
1e660 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a  t()] interface..
1e670 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1e680 45 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a 20  E_DENY   1   /* 
1e690 41 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74  Abort the SQL st
1e6a0 61 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e 20  atement with an 
1e6b0 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65  error */.#define
1e6c0 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32   SQLITE_IGNORE 2
1e6d0 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f     /* Don't allo
1e6e0 77 20 61 63 63 65 73 73 2c 20 62 75 74 20 64 6f  w access, but do
1e6f0 6e 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e 20  n't generate an 
1e700 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  error */../*.** 
1e710 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72  CAPI3REF: Author
1e720 69 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64 65  izer Action Code
1e730 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  s.**.** The [sql
1e740 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
1e750 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65  zer()] interface
1e760 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c   registers a cal
1e770 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a  lback function.*
1e780 2a 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65  * that is invoke
1e790 64 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 20 63  d to authorize c
1e7a0 65 72 74 61 69 6e 20 53 51 4c 20 73 74 61 74 65  ertain SQL state
1e7b0 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20 54  ment actions.  T
1e7c0 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72  he.** second par
1e7d0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 61  ameter to the ca
1e7e0 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74  llback is an int
1e7f0 65 67 65 72 20 63 6f 64 65 20 74 68 61 74 20 73  eger code that s
1e800 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 61 74  pecifies.** what
1e810 20 61 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67   action is being
1e820 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68   authorized.  Th
1e830 65 73 65 20 61 72 65 20 74 68 65 20 69 6e 74 65  ese are the inte
1e840 67 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 65 73  ger action codes
1e850 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 75 74   that.** the aut
1e860 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1e870 20 6d 61 79 20 62 65 20 70 61 73 73 65 64 2e 0a   may be passed..
1e880 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 74 69  **.** These acti
1e890 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 20 73  on code values s
1e8a0 69 67 6e 69 66 79 20 77 68 61 74 20 6b 69 6e 64  ignify what kind
1e8b0 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 69 73   of operation is
1e8c0 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72   to be.** author
1e8d0 69 7a 65 64 2e 20 20 54 68 65 20 33 72 64 20 61  ized.  The 3rd a
1e8e0 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  nd 4th parameter
1e8f0 73 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69  s to the authori
1e900 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61  zation.** callba
1e910 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c  ck function will
1e920 20 62 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f   be parameters o
1e930 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67  r NULL depending
1e940 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 68 65   on which of the
1e950 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20 75  se.** codes is u
1e960 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  sed as the secon
1e970 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 28  d parameter.  ^(
1e980 54 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  The 5th paramete
1e990 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68  r to the.** auth
1e9a0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1e9b0 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
1e9c0 68 65 20 64 61 74 61 62 61 73 65 20 28 22 6d 61  he database ("ma
1e9d0 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20  in", "temp",.** 
1e9e0 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61  etc.) if applica
1e9f0 62 6c 65 2e 29 5e 20 20 5e 54 68 65 20 36 74 68  ble.)^  ^The 6th
1ea00 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
1ea10 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1ea20 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20  lback.** is the 
1ea30 6e 61 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e 65  name of the inne
1ea40 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f  r-most trigger o
1ea50 72 20 76 69 65 77 20 74 68 61 74 20 69 73 20 72  r view that is r
1ea60 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a  esponsible for.*
1ea70 2a 20 74 68 65 20 61 63 63 65 73 73 20 61 74 74  * the access att
1ea80 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20  empt or NULL if 
1ea90 74 68 69 73 20 61 63 63 65 73 73 20 61 74 74 65  this access atte
1eaa0 6d 70 74 20 69 73 20 64 69 72 65 63 74 6c 79 20  mpt is directly 
1eab0 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65  from.** top-leve
1eac0 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f  l SQL code..*/./
1ead0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1eae0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1eaf0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20  *********** 3rd 
1eb00 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68  ************ 4th
1eb10 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64   ***********/.#d
1eb20 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
1eb30 41 54 45 5f 49 4e 44 45 58 20 20 20 20 20 20 20  ATE_INDEX       
1eb40 20 20 20 31 20 20 20 2f 2a 20 49 6e 64 65 78 20     1   /* Index 
1eb50 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
1eb60 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
1eb70 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
1eb80 54 45 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20  TE_TABLE        
1eb90 20 20 32 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e    2   /* Table N
1eba0 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
1ebb0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1ebc0 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
1ebd0 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20  E_TEMP_INDEX    
1ebe0 20 33 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61   3   /* Index Na
1ebf0 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61  me      Table Na
1ec00 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
1ec10 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
1ec20 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20  _TEMP_TABLE     
1ec30 34 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  4   /* Table Nam
1ec40 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
1ec50 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1ec60 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
1ec70 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 35  TEMP_TRIGGER   5
1ec80 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
1ec90 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
1eca0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1ecb0 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
1ecc0 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 36 20  EMP_VIEW      6 
1ecd0 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
1ece0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1ecf0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1ed00 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 52  SQLITE_CREATE_TR
1ed10 49 47 47 45 52 20 20 20 20 20 20 20 20 37 20 20  IGGER        7  
1ed20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65   /* Trigger Name
1ed30 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
1ed40 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1ed50 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 49 45  QLITE_CREATE_VIE
1ed60 57 20 20 20 20 20 20 20 20 20 20 20 38 20 20 20  W           8   
1ed70 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20  /* View Name    
1ed80 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1ed90 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1eda0 4c 49 54 45 5f 44 45 4c 45 54 45 20 20 20 20 20  LITE_DELETE     
1edb0 20 20 20 20 20 20 20 20 20 20 20 39 20 20 20 2f             9   /
1edc0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
1edd0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1ede0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1edf0 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20  ITE_DROP_INDEX  
1ee00 20 20 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a           10   /*
1ee10 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
1ee20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1ee30 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1ee40 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20 20  TE_DROP_TABLE   
1ee50 20 20 20 20 20 20 20 20 31 31 20 20 20 2f 2a 20          11   /* 
1ee60 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1ee70 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1ee80 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1ee90 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45  E_DROP_TEMP_INDE
1eea0 58 20 20 20 20 20 20 31 32 20 20 20 2f 2a 20 49  X      12   /* I
1eeb0 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54  ndex Name      T
1eec0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
1eed0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1eee0 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45  _DROP_TEMP_TABLE
1eef0 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20 54 61        13   /* Ta
1ef00 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
1ef10 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1ef20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1ef30 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47 45  DROP_TEMP_TRIGGE
1ef40 52 20 20 20 20 31 34 20 20 20 2f 2a 20 54 72 69  R    14   /* Tri
1ef50 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62  gger Name    Tab
1ef60 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
1ef70 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1ef80 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20 20 20  ROP_TEMP_VIEW   
1ef90 20 20 20 20 31 35 20 20 20 2f 2a 20 56 69 65 77      15   /* View
1efa0 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c   Name       NULL
1efb0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1efc0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
1efd0 4f 50 5f 54 52 49 47 47 45 52 20 20 20 20 20 20  OP_TRIGGER      
1efe0 20 20 20 31 36 20 20 20 2f 2a 20 54 72 69 67 67     16   /* Trigg
1eff0 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65  er Name    Table
1f000 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
1f010 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
1f020 50 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20  P_VIEW          
1f030 20 20 31 37 20 20 20 2f 2a 20 56 69 65 77 20 4e    17   /* View N
1f040 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  ame       NULL  
1f050 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1f060 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53 45  fine SQLITE_INSE
1f070 52 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20  RT              
1f080 20 31 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   18   /* Table N
1f090 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
1f0a0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1f0b0 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 41 47 4d  ine SQLITE_PRAGM
1f0c0 41 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  A               
1f0d0 31 39 20 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e  19   /* Pragma N
1f0e0 61 6d 65 20 20 20 20 20 31 73 74 20 61 72 67 20  ame     1st arg 
1f0f0 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69  or NULL */.#defi
1f100 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 20 20  ne SQLITE_READ  
1f110 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
1f120 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  0   /* Table Nam
1f130 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61  e      Column Na
1f140 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
1f150 65 20 53 51 4c 49 54 45 5f 53 45 4c 45 43 54 20  e SQLITE_SELECT 
1f160 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 31                21
1f170 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20     /* NULL      
1f180 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1f190 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1f1a0 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 41 43 54   SQLITE_TRANSACT
1f1b0 49 4f 4e 20 20 20 20 20 20 20 20 20 20 32 32 20  ION          22 
1f1c0 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20    /* Operation  
1f1d0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1f1e0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1f1f0 53 51 4c 49 54 45 5f 55 50 44 41 54 45 20 20 20  SQLITE_UPDATE   
1f200 20 20 20 20 20 20 20 20 20 20 20 20 32 33 20 20              23  
1f210 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
1f220 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20      Column Name 
1f230 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1f240 51 4c 49 54 45 5f 41 54 54 41 43 48 20 20 20 20  QLITE_ATTACH    
1f250 20 20 20 20 20 20 20 20 20 20 20 32 34 20 20 20             24   
1f260 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20 20 20  /* Filename     
1f270 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1f280 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1f290 4c 49 54 45 5f 44 45 54 41 43 48 20 20 20 20 20  LITE_DETACH     
1f2a0 20 20 20 20 20 20 20 20 20 20 32 35 20 20 20 2f            25   /
1f2b0 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20  * Database Name 
1f2c0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1f2d0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1f2e0 49 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20  ITE_ALTER_TABLE 
1f2f0 20 20 20 20 20 20 20 20 20 32 36 20 20 20 2f 2a           26   /*
1f300 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20   Database Name  
1f310 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1f320 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1f330 54 45 5f 52 45 49 4e 44 45 58 20 20 20 20 20 20  TE_REINDEX      
1f340 20 20 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20          27   /* 
1f350 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
1f360 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1f370 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1f380 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20 20 20  E_ANALYZE       
1f390 20 20 20 20 20 20 20 32 38 20 20 20 2f 2a 20 54         28   /* T
1f3a0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
1f3b0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1f3c0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1f3d0 5f 43 52 45 41 54 45 5f 56 54 41 42 4c 45 20 20  _CREATE_VTABLE  
1f3e0 20 20 20 20 20 20 32 39 20 20 20 2f 2a 20 54 61        29   /* Ta
1f3f0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f  ble Name      Mo
1f400 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f  dule Name     */
1f410 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1f420 44 52 4f 50 5f 56 54 41 42 4c 45 20 20 20 20 20  DROP_VTABLE     
1f430 20 20 20 20 20 33 30 20 20 20 2f 2a 20 54 61 62       30   /* Tab
1f440 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64  le Name      Mod
1f450 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a  ule Name     */.
1f460 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
1f470 55 4e 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20  UNCTION         
1f480 20 20 20 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c      31   /* NULL
1f490 20 20 20 20 20 20 20 20 20 20 20 20 46 75 6e 63              Func
1f4a0 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23  tion Name   */.#
1f4b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 41  define SQLITE_SA
1f4c0 56 45 50 4f 49 4e 54 20 20 20 20 20 20 20 20 20  VEPOINT         
1f4d0 20 20 20 33 32 20 20 20 2f 2a 20 4f 70 65 72 61     32   /* Opera
1f4e0 74 69 6f 6e 20 20 20 20 20 20 20 53 61 76 65 70  tion       Savep
1f4f0 6f 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64  oint Name  */.#d
1f500 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50  efine SQLITE_COP
1f510 59 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  Y               
1f520 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e     0   /* No lon
1f530 67 65 72 20 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a  ger used */../*.
1f540 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 72 61  ** CAPI3REF: Tra
1f550 63 69 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c 69  cing And Profili
1f560 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a  ng Functions.**.
1f570 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
1f580 73 20 72 65 67 69 73 74 65 72 20 63 61 6c 6c 62  s register callb
1f590 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74 68  ack functions th
1f5a0 61 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 66  at can be used f
1f5b0 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e  or.** tracing an
1f5c0 64 20 70 72 6f 66 69 6c 69 6e 67 20 74 68 65 20  d profiling the 
1f5d0 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c  execution of SQL
1f5e0 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a   statements..**.
1f5f0 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b  ** ^The callback
1f600 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74   function regist
1f610 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  ered by sqlite3_
1f620 74 72 61 63 65 28 29 20 69 73 20 69 6e 76 6f 6b  trace() is invok
1f630 65 64 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75 73  ed at.** various
1f640 20 74 69 6d 65 73 20 77 68 65 6e 20 61 6e 20 53   times when an S
1f650 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  QL statement is 
1f660 62 65 69 6e 67 20 72 75 6e 20 62 79 20 5b 73 71  being run by [sq
1f670 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a  lite3_step()]..*
1f680 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74  * ^The sqlite3_t
1f690 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 20  race() callback 
1f6a0 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20  is invoked with 
1f6b0 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69 6e  a UTF-8 renderin
1f6c0 67 20 6f 66 20 74 68 65 0a 2a 2a 20 53 51 4c 20  g of the.** SQL 
1f6d0 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61  statement text a
1f6e0 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  s the statement 
1f6f0 66 69 72 73 74 20 62 65 67 69 6e 73 20 65 78 65  first begins exe
1f700 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64  cuting..** ^(Add
1f710 69 74 69 6f 6e 61 6c 20 73 71 6c 69 74 65 33 5f  itional sqlite3_
1f720 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b  trace() callback
1f730 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a  s might occur.**
1f740 20 61 73 20 65 61 63 68 20 74 72 69 67 67 65 72   as each trigger
1f750 65 64 20 73 75 62 70 72 6f 67 72 61 6d 20 69 73  ed subprogram is
1f760 20 65 6e 74 65 72 65 64 2e 20 20 54 68 65 20 63   entered.  The c
1f770 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74 72 69  allbacks for tri
1f780 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e  ggers.** contain
1f790 20 61 20 55 54 46 2d 38 20 53 51 4c 20 63 6f 6d   a UTF-8 SQL com
1f7a0 6d 65 6e 74 20 74 68 61 74 20 69 64 65 6e 74 69  ment that identi
1f7b0 66 69 65 73 20 74 68 65 20 74 72 69 67 67 65 72  fies the trigger
1f7c0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53  .)^.**.** The [S
1f7d0 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 49 5a 45  QLITE_TRACE_SIZE
1f7e0 5f 4c 49 4d 49 54 5d 20 63 6f 6d 70 69 6c 65 2d  _LIMIT] compile-
1f7f0 74 69 6d 65 20 6f 70 74 69 6f 6e 20 63 61 6e 20  time option can 
1f800 62 65 20 75 73 65 64 20 74 6f 20 6c 69 6d 69 74  be used to limit
1f810 0a 2a 2a 20 74 68 65 20 6c 65 6e 67 74 68 20 6f  .** the length o
1f820 66 20 5b 62 6f 75 6e 64 20 70 61 72 61 6d 65 74  f [bound paramet
1f830 65 72 5d 20 65 78 70 61 6e 73 69 6f 6e 20 69 6e  er] expansion in
1f840 20 74 68 65 20 6f 75 74 70 75 74 20 6f 66 20 73   the output of s
1f850 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 2e 0a  qlite3_trace()..
1f860 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62  **.** ^The callb
1f870 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67  ack function reg
1f880 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74  istered by sqlit
1f890 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 69 73 20  e3_profile() is 
1f8a0 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61  invoked.** as ea
1f8b0 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ch SQL statement
1f8c0 20 66 69 6e 69 73 68 65 73 2e 20 20 5e 54 68 65   finishes.  ^The
1f8d0 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63   profile callbac
1f8e0 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68  k contains.** th
1f8f0 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65  e original state
1f900 6d 65 6e 74 20 74 65 78 74 20 61 6e 64 20 61 6e  ment text and an
1f910 20 65 73 74 69 6d 61 74 65 20 6f 66 20 77 61 6c   estimate of wal
1f920 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20  l-clock time.** 
1f930 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74  of how long that
1f940 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20   statement took 
1f950 74 6f 20 72 75 6e 2e 20 20 5e 54 68 65 20 70 72  to run.  ^The pr
1f960 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 0a 2a  ofile callback.*
1f970 2a 20 74 69 6d 65 20 69 73 20 69 6e 20 75 6e 69  * time is in uni
1f980 74 73 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64  ts of nanosecond
1f990 73 2c 20 68 6f 77 65 76 65 72 20 74 68 65 20 63  s, however the c
1f9a0 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74  urrent implement
1f9b0 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6f 6e 6c 79  ation.** is only
1f9c0 20 63 61 70 61 62 6c 65 20 6f 66 20 6d 69 6c 6c   capable of mill
1f9d0 69 73 65 63 6f 6e 64 20 72 65 73 6f 6c 75 74 69  isecond resoluti
1f9e0 6f 6e 20 73 6f 20 74 68 65 20 73 69 78 20 6c 65  on so the six le
1f9f0 61 73 74 20 73 69 67 6e 69 66 69 63 61 6e 74 0a  ast significant.
1fa00 2a 2a 20 64 69 67 69 74 73 20 69 6e 20 74 68 65  ** digits in the
1fa10 20 74 69 6d 65 20 61 72 65 20 6d 65 61 6e 69 6e   time are meanin
1fa20 67 6c 65 73 73 2e 20 20 46 75 74 75 72 65 20 76  gless.  Future v
1fa30 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
1fa40 65 0a 2a 2a 20 6d 69 67 68 74 20 70 72 6f 76 69  e.** might provi
1fa50 64 65 20 67 72 65 61 74 65 72 20 72 65 73 6f 6c  de greater resol
1fa60 75 74 69 6f 6e 20 6f 6e 20 74 68 65 20 70 72 6f  ution on the pro
1fa70 66 69 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20  filer callback. 
1fa80 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   The.** sqlite3_
1fa90 70 72 6f 66 69 6c 65 28 29 20 66 75 6e 63 74 69  profile() functi
1faa0 6f 6e 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64  on is considered
1fab0 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e   experimental an
1fac0 64 20 69 73 0a 2a 2a 20 73 75 62 6a 65 63 74 20  d is.** subject 
1fad0 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 66 75 74  to change in fut
1fae0 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
1faf0 53 51 4c 69 74 65 2e 0a 2a 2f 0a 53 51 4c 49 54  SQLite..*/.SQLIT
1fb00 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69  E_API void *sqli
1fb10 74 65 33 5f 74 72 61 63 65 28 73 71 6c 69 74 65  te3_trace(sqlite
1fb20 33 2a 2c 20 76 6f 69 64 28 2a 78 54 72 61 63 65  3*, void(*xTrace
1fb30 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68  )(void*,const ch
1fb40 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51  ar*), void*);.SQ
1fb50 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f  LITE_API SQLITE_
1fb60 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 76 6f 69  EXPERIMENTAL voi
1fb70 64 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f 66 69  d *sqlite3_profi
1fb80 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20  le(sqlite3*,.   
1fb90 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65 29 28  void(*xProfile)(
1fba0 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72  void*,const char
1fbb0 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  *,sqlite3_uint64
1fbc0 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a  ), void*);../*.*
1fbd0 2a 20 43 41 50 49 33 52 45 46 3a 20 51 75 65 72  * CAPI3REF: Quer
1fbe0 79 20 50 72 6f 67 72 65 73 73 20 43 61 6c 6c 62  y Progress Callb
1fbf0 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  acks.**.** ^The 
1fc00 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73  sqlite3_progress
1fc10 5f 68 61 6e 64 6c 65 72 28 44 2c 4e 2c 58 2c 50  _handler(D,N,X,P
1fc20 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73  ) interface caus
1fc30 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a  es the callback.
1fc40 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20 74 6f  ** function X to
1fc50 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 65 72 69   be invoked peri
1fc60 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 6e 67 20  odically during 
1fc70 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 63 61 6c  long running cal
1fc80 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ls to.** [sqlite
1fc90 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69  3_exec()], [sqli
1fca0 74 65 33 5f 73 74 65 70 28 29 5d 20 61 6e 64 20  te3_step()] and 
1fcb0 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62  [sqlite3_get_tab
1fcc0 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 64 61 74  le()] for.** dat
1fcd0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1fce0 20 44 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20   D.  An example 
1fcf0 75 73 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20  use for this.** 
1fd00 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 6f 20  interface is to 
1fd10 6b 65 65 70 20 61 20 47 55 49 20 75 70 64 61 74  keep a GUI updat
1fd20 65 64 20 64 75 72 69 6e 67 20 61 20 6c 61 72 67  ed during a larg
1fd30 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e  e query..**.** ^
1fd40 54 68 65 20 70 61 72 61 6d 65 74 65 72 20 50 20  The parameter P 
1fd50 69 73 20 70 61 73 73 65 64 20 74 68 72 6f 75 67  is passed throug
1fd60 68 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61  h as the only pa
1fd70 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 0a  rameter to the .
1fd80 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  ** callback func
1fd90 74 69 6f 6e 20 58 2e 20 20 5e 54 68 65 20 70 61  tion X.  ^The pa
1fda0 72 61 6d 65 74 65 72 20 4e 20 69 73 20 74 68 65  rameter N is the
1fdb0 20 61 70 70 72 6f 78 69 6d 61 74 65 20 6e 75 6d   approximate num
1fdc0 62 65 72 20 6f 66 20 0a 2a 2a 20 5b 76 69 72 74  ber of .** [virt
1fdd0 75 61 6c 20 6d 61 63 68 69 6e 65 20 69 6e 73 74  ual machine inst
1fde0 72 75 63 74 69 6f 6e 73 5d 20 74 68 61 74 20 61  ructions] that a
1fdf0 72 65 20 65 76 61 6c 75 61 74 65 64 20 62 65 74  re evaluated bet
1fe00 77 65 65 6e 20 73 75 63 63 65 73 73 69 76 65 0a  ween successive.
1fe10 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f  ** invocations o
1fe20 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 58  f the callback X
1fe30 2e 20 20 5e 49 66 20 4e 20 69 73 20 6c 65 73 73  .  ^If N is less
1fe40 20 74 68 61 6e 20 6f 6e 65 20 74 68 65 6e 20 74   than one then t
1fe50 68 65 20 70 72 6f 67 72 65 73 73 0a 2a 2a 20 68  he progress.** h
1fe60 61 6e 64 6c 65 72 20 69 73 20 64 69 73 61 62 6c  andler is disabl
1fe70 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20  ed..**.** ^Only 
1fe80 61 20 73 69 6e 67 6c 65 20 70 72 6f 67 72 65 73  a single progres
1fe90 73 20 68 61 6e 64 6c 65 72 20 6d 61 79 20 62 65  s handler may be
1fea0 20 64 65 66 69 6e 65 64 20 61 74 20 6f 6e 65 20   defined at one 
1feb0 74 69 6d 65 20 70 65 72 0a 2a 2a 20 5b 64 61 74  time per.** [dat
1fec0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1fed0 5d 3b 20 73 65 74 74 69 6e 67 20 61 20 6e 65 77  ]; setting a new
1fee0 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
1fef0 72 20 63 61 6e 63 65 6c 73 20 74 68 65 0a 2a 2a  r cancels the.**
1ff00 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53 65 74 74   old one.  ^Sett
1ff10 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 58 20  ing parameter X 
1ff20 74 6f 20 4e 55 4c 4c 20 64 69 73 61 62 6c 65 73  to NULL disables
1ff30 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 61   the progress ha
1ff40 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 70  ndler..** ^The p
1ff50 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20  rogress handler 
1ff60 69 73 20 61 6c 73 6f 20 64 69 73 61 62 6c 65 64  is also disabled
1ff70 20 62 79 20 73 65 74 74 69 6e 67 20 4e 20 74 6f   by setting N to
1ff80 20 61 20 76 61 6c 75 65 20 6c 65 73 73 0a 2a 2a   a value less.**
1ff90 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e   than 1..**.** ^
1ffa0 49 66 20 74 68 65 20 70 72 6f 67 72 65 73 73 20  If the progress 
1ffb0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
1ffc0 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f   non-zero, the o
1ffd0 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69  peration is.** i
1ffe0 6e 74 65 72 72 75 70 74 65 64 2e 20 20 54 68 69  nterrupted.  Thi
1fff0 73 20 66 65 61 74 75 72 65 20 63 61 6e 20 62 65  s feature can be
20000 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65   used to impleme
20010 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22  nt a.** "Cancel"
20020 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49   button on a GUI
20030 20 70 72 6f 67 72 65 73 73 20 64 69 61 6c 6f 67   progress dialog
20040 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20   box..**.** The 
20050 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
20060 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e   callback must n
20070 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74  ot do anything t
20080 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a  hat will modify.
20090 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
200a0 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20  connection that 
200b0 69 6e 76 6f 6b 65 64 20 74 68 65 20 70 72 6f 67  invoked the prog
200c0 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a  ress handler..**
200d0 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69   Note that [sqli
200e0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
200f0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73  ] and [sqlite3_s
20100 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69  tep()] both modi
20110 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61  fy their.** data
20120 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
20130 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67   for the meaning
20140 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20   of "modify" in 
20150 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a  this paragraph..
20160 2a 2a 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  **.*/.SQLITE_API
20170 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 70 72   void sqlite3_pr
20180 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 73  ogress_handler(s
20190 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e  qlite3*, int, in
201a0 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69  t(*)(void*), voi
201b0 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
201c0 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20  3REF: Opening A 
201d0 4e 65 77 20 44 61 74 61 62 61 73 65 20 43 6f 6e  New Database Con
201e0 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54  nection.**.** ^T
201f0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 70  hese routines op
20200 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 64 61 74  en an SQLite dat
20210 61 62 61 73 65 20 66 69 6c 65 20 61 73 20 73 70  abase file as sp
20220 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 0a  ecified by the .
20230 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75  ** filename argu
20240 6d 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c 65 6e  ment. ^The filen
20250 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ame argument is 
20260 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55  interpreted as U
20270 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69  TF-8 for.** sqli
20280 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73  te3_open() and s
20290 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
202a0 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36 20 69   and as UTF-16 i
202b0 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74  n the native byt
202c0 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20 73  e.** order for s
202d0 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e  qlite3_open16().
202e0 20 5e 28 41 20 5b 64 61 74 61 62 61 73 65 20 63   ^(A [database c
202f0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c  onnection] handl
20300 65 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20  e is usually.** 
20310 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 70 44  returned in *ppD
20320 62 2c 20 65 76 65 6e 20 69 66 20 61 6e 20 65 72  b, even if an er
20330 72 6f 72 20 6f 63 63 75 72 73 2e 20 20 54 68 65  ror occurs.  The
20340 20 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e 20   only exception 
20350 69 73 20 74 68 61 74 0a 2a 2a 20 69 66 20 53 51  is that.** if SQ
20360 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74  Lite is unable t
20370 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72  o allocate memor
20380 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73  y to hold the [s
20390 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a  qlite3] object,.
203a0 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62  ** a NULL will b
203b0 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a  e written into *
203c0 70 70 44 62 20 69 6e 73 74 65 61 64 20 6f 66 20  ppDb instead of 
203d0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
203e0 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62   [sqlite3].** ob
203f0 6a 65 63 74 2e 29 5e 20 5e 28 49 66 20 74 68 65  ject.)^ ^(If the
20400 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
20410 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 72 65 61  ned (and/or crea
20420 74 65 64 29 20 73 75 63 63 65 73 73 66 75 6c 6c  ted) successfull
20430 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49  y, then.** [SQLI
20440 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e  TE_OK] is return
20450 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61  ed.  Otherwise a
20460 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  n [error code] i
20470 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 5e 54  s returned.)^ ^T
20480 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  he.** [sqlite3_e
20490 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c  rrmsg()] or [sql
204a0 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d  ite3_errmsg16()]
204b0 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 65   routines can be
204c0 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a   used to obtain.
204d0 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61  ** an English la
204e0 6e 67 75 61 67 65 20 64 65 73 63 72 69 70 74 69  nguage descripti
204f0 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20  on of the error 
20500 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c  following a fail
20510 75 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66  ure of any.** of
20520 20 74 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65   the sqlite3_ope
20530 6e 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  n() routines..**
20540 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74  .** ^The default
20550 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 74 68   encoding for th
20560 65 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20  e database will 
20570 62 65 20 55 54 46 2d 38 20 69 66 0a 2a 2a 20 73  be UTF-8 if.** s
20580 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72  qlite3_open() or
20590 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
205a0 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 6e 64  () is called and
205b0 0a 2a 2a 20 55 54 46 2d 31 36 20 69 6e 20 74 68  .** UTF-16 in th
205c0 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  e native byte or
205d0 64 65 72 20 69 66 20 73 71 6c 69 74 65 33 5f 6f  der if sqlite3_o
205e0 70 65 6e 31 36 28 29 20 69 73 20 75 73 65 64 2e  pen16() is used.
205f0 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f  .**.** Whether o
20600 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f  r not an error o
20610 63 63 75 72 73 20 77 68 65 6e 20 69 74 20 69 73  ccurs when it is
20620 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75 72 63   opened, resourc
20630 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64  es.** associated
20640 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62   with the [datab
20650 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
20660 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62 65  handle should be
20670 20 72 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20   released by.** 
20680 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73  passing it to [s
20690 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20  qlite3_close()] 
206a0 77 68 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f  when it is no lo
206b0 6e 67 65 72 20 72 65 71 75 69 72 65 64 2e 0a 2a  nger required..*
206c0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
206d0 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74 65 72  _open_v2() inter
206e0 66 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20  face works like 
206f0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a  sqlite3_open().*
20700 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74  * except that it
20710 20 61 63 63 65 70 74 73 20 74 77 6f 20 61 64 64   accepts two add
20720 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65  itional paramete
20730 72 73 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  rs for additiona
20740 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65  l control.** ove
20750 72 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61  r the new databa
20760 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  se connection.  
20770 5e 28 54 68 65 20 66 6c 61 67 73 20 70 61 72 61  ^(The flags para
20780 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69  meter to.** sqli
20790 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 63 61  te3_open_v2() ca
207a0 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a  n take one of.**
207b0 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74   the following t
207c0 68 72 65 65 20 76 61 6c 75 65 73 2c 20 6f 70 74  hree values, opt
207d0 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64  ionally combined
207e0 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53   with the .** [S
207f0 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54  QLITE_OPEN_NOMUT
20800 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45  EX], [SQLITE_OPE
20810 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53  N_FULLMUTEX], [S
20820 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45  QLITE_OPEN_SHARE
20830 44 43 41 43 48 45 5d 2c 0a 2a 2a 20 5b 53 51 4c  DCACHE],.** [SQL
20840 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45  ITE_OPEN_PRIVATE
20850 43 41 43 48 45 5d 2c 20 61 6e 64 2f 6f 72 20 5b  CACHE], and/or [
20860 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d  SQLITE_OPEN_URI]
20870 20 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20   flags:)^.**.** 
20880 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53  <dl>.** ^(<dt>[S
20890 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
208a0 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NLY]</dt>.** <dd
208b0 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73  >The database is
208c0 20 6f 70 65 6e 65 64 20 69 6e 20 72 65 61 64 2d   opened in read-
208d0 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20 74  only mode.  If t
208e0 68 65 20 64 61 74 61 62 61 73 65 20 64 6f 65 73  he database does
208f0 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20   not.** already 
20900 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20  exist, an error 
20910 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64  is returned.</dd
20920 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e  >)^.**.** ^(<dt>
20930 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
20940 44 57 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20  DWRITE]</dt>.** 
20950 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65  <dd>The database
20960 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72   is opened for r
20970 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69  eading and writi
20980 6e 67 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20  ng if possible, 
20990 6f 72 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e  or reading.** on
209a0 6c 79 20 69 66 20 74 68 65 20 66 69 6c 65 20 69  ly if the file i
209b0 73 20 77 72 69 74 65 20 70 72 6f 74 65 63 74 65  s write protecte
209c0 64 20 62 79 20 74 68 65 20 6f 70 65 72 61 74 69  d by the operati
209d0 6e 67 20 73 79 73 74 65 6d 2e 20 20 49 6e 20 65  ng system.  In e
209e0 69 74 68 65 72 0a 2a 2a 20 63 61 73 65 20 74 68  ither.** case th
209f0 65 20 64 61 74 61 62 61 73 65 20 6d 75 73 74 20  e database must 
20a00 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 6f  already exist, o
20a10 74 68 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f  therwise an erro
20a20 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f  r is returned.</
20a30 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64  dd>)^.**.** ^(<d
20a40 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  t>[SQLITE_OPEN_R
20a50 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c  EADWRITE] | [SQL
20a60 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d  ITE_OPEN_CREATE]
20a70 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
20a80 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
20a90 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20  ned for reading 
20aa0 61 6e 64 20 77 72 69 74 69 6e 67 2c 20 61 6e 64  and writing, and
20ab0 20 69 73 20 63 72 65 61 74 65 64 20 69 66 0a 2a   is created if.*
20ac0 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c  * it does not al
20ad0 72 65 61 64 79 20 65 78 69 73 74 2e 20 54 68 69  ready exist. Thi
20ae0 73 20 69 73 20 74 68 65 20 62 65 68 61 76 69 6f  s is the behavio
20af0 72 20 74 68 61 74 20 69 73 20 61 6c 77 61 79 73  r that is always
20b00 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c   used for.** sql
20b10 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20  ite3_open() and 
20b20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
20b30 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c  .</dd>)^.** </dl
20b40 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33  >.**.** If the 3
20b50 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
20b60 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
20b70 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20  ) is not one of 
20b80 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69  the.** combinati
20b90 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20  ons shown above 
20ba0 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69  optionally combi
20bb0 6e 65 64 20 77 69 74 68 20 6f 74 68 65 72 0a 2a  ned with other.*
20bc0 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  * [SQLITE_OPEN_R
20bd0 45 41 44 4f 4e 4c 59 20 7c 20 53 51 4c 49 54 45  EADONLY | SQLITE
20be0 5f 4f 50 45 4e 5f 2a 20 62 69 74 73 5d 0a 2a 2a  _OPEN_* bits].**
20bf0 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
20c00 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  or is undefined.
20c10 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b  .**.** ^If the [
20c20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55  SQLITE_OPEN_NOMU
20c30 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74  TEX] flag is set
20c40 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  , then the datab
20c50 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
20c60 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68 65 20 6d  * opens in the m
20c70 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72  ulti-thread [thr
20c80 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20  eading mode] as 
20c90 6c 6f 6e 67 20 61 73 20 74 68 65 20 73 69 6e 67  long as the sing
20ca0 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64  le-thread.** mod
20cb0 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 73  e has not been s
20cc0 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69  et at compile-ti
20cd0 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65  me or start-time
20ce0 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53  .  ^If the.** [S
20cf0 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d  QLITE_OPEN_FULLM
20d00 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65  UTEX] flag is se
20d10 74 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  t then the datab
20d20 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f  ase connection o
20d30 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73  pens.** in the s
20d40 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61  erialized [threa
20d50 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73  ding mode] unles
20d60 73 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 20  s single-thread 
20d70 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  was.** previousl
20d80 79 20 73 65 6c 65 63 74 65 64 20 61 74 20 63 6f  y selected at co
20d90 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74  mpile-time or st
20da0 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68  art-time..** ^Th
20db0 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53  e [SQLITE_OPEN_S
20dc0 48 41 52 45 44 43 41 43 48 45 5d 20 66 6c 61 67  HAREDCACHE] flag
20dd0 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74 61   causes the data
20de0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
20df0 74 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c  to be.** eligibl
20e00 65 20 74 6f 20 75 73 65 20 5b 73 68 61 72 65 64  e to use [shared
20e10 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65   cache mode], re
20e20 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74  gardless of whet
20e30 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65  her or not share
20e40 64 0a 2a 2a 20 63 61 63 68 65 20 69 73 20 65 6e  d.** cache is en
20e50 61 62 6c 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  abled using [sql
20e60 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72  ite3_enable_shar
20e70 65 64 5f 63 61 63 68 65 28 29 5d 2e 20 20 5e 54  ed_cache()].  ^T
20e80 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  he.** [SQLITE_OP
20e90 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d  EN_PRIVATECACHE]
20ea0 20 66 6c 61 67 20 63 61 75 73 65 73 20 74 68 65   flag causes the
20eb0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
20ec0 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70  tion to not.** p
20ed0 61 72 74 69 63 69 70 61 74 65 20 69 6e 20 5b 73  articipate in [s
20ee0 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65  hared cache mode
20ef0 5d 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 20  ] even if it is 
20f00 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  enabled..**.** ^
20f10 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  The fourth param
20f20 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
20f30 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 74 68 65  open_v2() is the
20f40 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20   name of the.** 
20f50 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
20f60 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65  ject that define
20f70 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  s the operating 
20f80 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65  system interface
20f90 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77   that.** the new
20fa0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
20fb0 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e  tion should use.
20fc0 20 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68    ^If the fourth
20fd0 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a   parameter is.**
20fe0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
20ff0 74 68 65 6e 20 74 68 65 20 64 65 66 61 75 6c 74  then the default
21000 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
21010 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e 0a 2a  bject is used..*
21020 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c  *.** ^If the fil
21030 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72  ename is ":memor
21040 79 3a 22 2c 20 74 68 65 6e 20 61 20 70 72 69 76  y:", then a priv
21050 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 20 69  ate, temporary i
21060 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73  n-memory databas
21070 65 0a 2a 2a 20 69 73 20 63 72 65 61 74 65 64 20  e.** is created 
21080 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69  for the connecti
21090 6f 6e 2e 20 20 5e 54 68 69 73 20 69 6e 2d 6d 65  on.  ^This in-me
210a0 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20 77 69  mory database wi
210b0 6c 6c 20 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a  ll vanish when.*
210c0 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  * the database c
210d0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f  onnection is clo
210e0 73 65 64 2e 20 20 46 75 74 75 72 65 20 76 65 72  sed.  Future ver
210f0 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20  sions of SQLite 
21100 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73  might.** make us
21110 65 20 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c 20  e of additional 
21120 73 70 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65  special filename
21130 73 20 74 68 61 74 20 62 65 67 69 6e 20 77 69 74  s that begin wit
21140 68 20 74 68 65 20 22 3a 22 20 63 68 61 72 61 63  h the ":" charac
21150 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65  ter..** It is re
21160 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 77  commended that w
21170 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 66  hen a database f
21180 69 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79  ilename actually
21190 20 64 6f 65 73 20 62 65 67 69 6e 20 77 69 74 68   does begin with
211a0 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61 72 61 63  .** a ":" charac
211b0 74 65 72 20 79 6f 75 20 73 68 6f 75 6c 64 20 70  ter you should p
211c0 72 65 66 69 78 20 74 68 65 20 66 69 6c 65 6e 61  refix the filena
211d0 6d 65 20 77 69 74 68 20 61 20 70 61 74 68 6e 61  me with a pathna
211e0 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e  me such as.** ".
211f0 2f 22 20 74 6f 20 61 76 6f 69 64 20 61 6d 62 69  /" to avoid ambi
21200 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  guity..**.** ^If
21210 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73   the filename is
21220 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
21230 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65  , then a private
21240 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f  , temporary.** o
21250 6e 2d 64 69 73 6b 20 64 61 74 61 62 61 73 65 20  n-disk database 
21260 77 69 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e  will be created.
21270 20 20 5e 54 68 69 73 20 70 72 69 76 61 74 65 20    ^This private 
21280 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65  database will be
21290 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  .** automaticall
212a0 79 20 64 65 6c 65 74 65 64 20 61 73 20 73 6f 6f  y deleted as soo
212b0 6e 20 61 73 20 74 68 65 20 64 61 74 61 62 61 73  n as the databas
212c0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
212d0 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  closed..**.** [[
212e0 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 69 6e  URI filenames in
212f0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d   sqlite3_open()]
21300 5d 20 3c 68 33 3e 55 52 49 20 46 69 6c 65 6e 61  ] <h3>URI Filena
21310 6d 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e  mes</h3>.**.** ^
21320 49 66 20 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65  If [URI filename
21330 5d 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e  ] interpretation
21340 20 69 73 20 65 6e 61 62 6c 65 64 2c 20 61 6e 64   is enabled, and
21350 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72   the filename ar
21360 67 75 6d 65 6e 74 0a 2a 2a 20 62 65 67 69 6e 73  gument.** begins
21370 20 77 69 74 68 20 22 66 69 6c 65 3a 22 2c 20 74   with "file:", t
21380 68 65 6e 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  hen the filename
21390 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20   is interpreted 
213a0 61 73 20 61 20 55 52 49 2e 20 5e 55 52 49 0a 2a  as a URI. ^URI.*
213b0 2a 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72  * filename inter
213c0 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61  pretation is ena
213d0 62 6c 65 64 20 69 66 20 74 68 65 20 5b 53 51 4c  bled if the [SQL
213e0 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c  ITE_OPEN_URI] fl
213f0 61 67 20 69 73 0a 2a 2a 20 73 65 74 20 69 6e 20  ag is.** set in 
21400 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d  the fourth argum
21410 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f  ent to sqlite3_o
21420 70 65 6e 5f 76 32 28 29 2c 20 6f 72 20 69 66 20  pen_v2(), or if 
21430 69 74 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65  it has.** been e
21440 6e 61 62 6c 65 64 20 67 6c 6f 62 61 6c 6c 79 20  nabled globally 
21450 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54  using the [SQLIT
21460 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 20 6f 70  E_CONFIG_URI] op
21470 74 69 6f 6e 20 77 69 74 68 20 74 68 65 0a 2a 2a  tion with the.**
21480 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
21490 28 29 5d 20 6d 65 74 68 6f 64 20 6f 72 20 62 79  ()] method or by
214a0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 45   the [SQLITE_USE
214b0 5f 55 52 49 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  _URI] compile-ti
214c0 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 41 73  me option..** As
214d0 20 6f 66 20 53 51 4c 69 74 65 20 76 65 72 73 69   of SQLite versi
214e0 6f 6e 20 33 2e 37 2e 37 2c 20 55 52 49 20 66 69  on 3.7.7, URI fi
214f0 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74  lename interpret
21500 61 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20  ation is turned 
21510 6f 66 66 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c  off.** by defaul
21520 74 2c 20 62 75 74 20 66 75 74 75 72 65 20 72 65  t, but future re
21530 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
21540 20 6d 69 67 68 74 20 65 6e 61 62 6c 65 20 55 52   might enable UR
21550 49 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e  I filename.** in
21560 74 65 72 70 72 65 74 61 74 69 6f 6e 20 62 79 20  terpretation by 
21570 64 65 66 61 75 6c 74 2e 20 20 53 65 65 20 22 5b  default.  See "[
21580 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 5d 22 20  URI filenames]" 
21590 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  for additional.*
215a0 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  * information..*
215b0 2a 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d  *.** URI filenam
215c0 65 73 20 61 72 65 20 70 61 72 73 65 64 20 61 63  es are parsed ac
215d0 63 6f 72 64 69 6e 67 20 74 6f 20 52 46 43 20 33  cording to RFC 3
215e0 39 38 36 2e 20 5e 49 66 20 74 68 65 20 55 52 49  986. ^If the URI
215f0 20 63 6f 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a 20   contains an.** 
21600 61 75 74 68 6f 72 69 74 79 2c 20 74 68 65 6e 20  authority, then 
21610 69 74 20 6d 75 73 74 20 62 65 20 65 69 74 68 65  it must be eithe
21620 72 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  r an empty strin
21630 67 20 6f 72 20 74 68 65 20 73 74 72 69 6e 67 20  g or the string 
21640 0a 2a 2a 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2e  .** "localhost".
21650 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72 69   ^If the authori
21660 74 79 20 69 73 20 6e 6f 74 20 61 6e 20 65 6d 70  ty is not an emp
21670 74 79 20 73 74 72 69 6e 67 20 6f 72 20 22 6c 6f  ty string or "lo
21680 63 61 6c 68 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a  calhost", an .**
21690 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e   error is return
216a0 65 64 20 74 6f 20 74 68 65 20 63 61 6c 6c 65 72  ed to the caller
216b0 2e 20 5e 54 68 65 20 66 72 61 67 6d 65 6e 74 20  . ^The fragment 
216c0 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55  component of a U
216d0 52 49 2c 20 69 66 20 0a 2a 2a 20 70 72 65 73 65  RI, if .** prese
216e0 6e 74 2c 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a  nt, is ignored..
216f0 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73  **.** ^SQLite us
21700 65 73 20 74 68 65 20 70 61 74 68 20 63 6f 6d 70  es the path comp
21710 6f 6e 65 6e 74 20 6f 66 20 74 68 65 20 55 52 49  onent of the URI
21720 20 61 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   as the name of 
21730 74 68 65 20 64 69 73 6b 20 66 69 6c 65 0a 2a 2a  the disk file.**
21740 20 77 68 69 63 68 20 63 6f 6e 74 61 69 6e 73 20   which contains 
21750 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 5e 49  the database. ^I
21760 66 20 74 68 65 20 70 61 74 68 20 62 65 67 69 6e  f the path begin
21770 73 20 77 69 74 68 20 61 20 27 2f 27 20 63 68 61  s with a '/' cha
21780 72 61 63 74 65 72 2c 20 0a 2a 2a 20 74 68 65 6e  racter, .** then
21790 20 69 74 20 69 73 20 69 6e 74 65 72 70 72 65 74   it is interpret
217a0 65 64 20 61 73 20 61 6e 20 61 62 73 6f 6c 75 74  ed as an absolut
217b0 65 20 70 61 74 68 2e 20 5e 49 66 20 74 68 65 20  e path. ^If the 
217c0 70 61 74 68 20 64 6f 65 73 20 6e 6f 74 20 62 65  path does not be
217d0 67 69 6e 20 0a 2a 2a 20 77 69 74 68 20 61 20 27  gin .** with a '
217e0 2f 27 20 28 6d 65 61 6e 69 6e 67 20 74 68 61 74  /' (meaning that
217f0 20 74 68 65 20 61 75 74 68 6f 72 69 74 79 20 73   the authority s
21800 65 63 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65  ection is omitte
21810 64 20 66 72 6f 6d 20 74 68 65 20 55 52 49 29 0a  d from the URI).
21820 2a 2a 20 74 68 65 6e 20 74 68 65 20 70 61 74 68  ** then the path
21830 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20   is interpreted 
21840 61 73 20 61 20 72 65 6c 61 74 69 76 65 20 70 61  as a relative pa
21850 74 68 2e 20 0a 2a 2a 20 5e 4f 6e 20 77 69 6e 64  th. .** ^On wind
21860 6f 77 73 2c 20 74 68 65 20 66 69 72 73 74 20 63  ows, the first c
21870 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 6e 20 61  omponent of an a
21880 62 73 6f 6c 75 74 65 20 70 61 74 68 20 0a 2a 2a  bsolute path .**
21890 20 69 73 20 61 20 64 72 69 76 65 20 73 70 65 63   is a drive spec
218a0 69 66 69 63 61 74 69 6f 6e 20 28 65 2e 67 2e 20  ification (e.g. 
218b0 22 43 3a 22 29 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 63  "C:")..**.** [[c
218c0 6f 72 65 20 55 52 49 20 71 75 65 72 79 20 70 61  ore URI query pa
218d0 72 61 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20 54 68  rameters]].** Th
218e0 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e  e query componen
218f0 74 20 6f 66 20 61 20 55 52 49 20 6d 61 79 20 63  t of a URI may c
21900 6f 6e 74 61 69 6e 20 70 61 72 61 6d 65 74 65 72  ontain parameter
21910 73 20 74 68 61 74 20 61 72 65 20 69 6e 74 65 72  s that are inter
21920 70 72 65 74 65 64 0a 2a 2a 20 65 69 74 68 65 72  preted.** either
21930 20 62 79 20 53 51 4c 69 74 65 20 69 74 73 65 6c   by SQLite itsel
21940 66 2c 20 6f 72 20 62 79 20 61 20 5b 56 46 53 20  f, or by a [VFS 
21950 7c 20 63 75 73 74 6f 6d 20 56 46 53 20 69 6d 70  | custom VFS imp
21960 6c 65 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a 2a  lementation]..**
21970 20 53 51 4c 69 74 65 20 69 6e 74 65 72 70 72 65   SQLite interpre
21980 74 73 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  ts the following
21990 20 74 68 72 65 65 20 71 75 65 72 79 20 70 61 72   three query par
219a0 61 6d 65 74 65 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ameters:.**.** <
219b0 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62  ul>.**   <li> <b
219c0 3e 76 66 73 3c 2f 62 3e 3a 20 5e 54 68 65 20 22  >vfs</b>: ^The "
219d0 76 66 73 22 20 70 61 72 61 6d 65 74 65 72 20 6d  vfs" parameter m
219e0 61 79 20 62 65 20 75 73 65 64 20 74 6f 20 73 70  ay be used to sp
219f0 65 63 69 66 79 20 74 68 65 20 6e 61 6d 65 20 6f  ecify the name o
21a00 66 0a 2a 2a 20 20 20 20 20 61 20 56 46 53 20 6f  f.**     a VFS o
21a10 62 6a 65 63 74 20 74 68 61 74 20 70 72 6f 76 69  bject that provi
21a20 64 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e  des the operatin
21a30 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61  g system interfa
21a40 63 65 20 74 68 61 74 20 73 68 6f 75 6c 64 0a 2a  ce that should.*
21a50 2a 20 20 20 20 20 62 65 20 75 73 65 64 20 74 6f  *     be used to
21a60 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61   access the data
21a70 62 61 73 65 20 66 69 6c 65 20 6f 6e 20 64 69 73  base file on dis
21a80 6b 2e 20 5e 49 66 20 74 68 69 73 20 6f 70 74 69  k. ^If this opti
21a90 6f 6e 20 69 73 20 73 65 74 20 74 6f 0a 2a 2a 20  on is set to.** 
21aa0 20 20 20 20 61 6e 20 65 6d 70 74 79 20 73 74 72      an empty str
21ab0 69 6e 67 20 74 68 65 20 64 65 66 61 75 6c 74 20  ing the default 
21ac0 56 46 53 20 6f 62 6a 65 63 74 20 69 73 20 75 73  VFS object is us
21ad0 65 64 2e 20 5e 53 70 65 63 69 66 79 69 6e 67 20  ed. ^Specifying 
21ae0 61 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20 20  an unknown.**   
21af0 20 20 56 46 53 20 69 73 20 61 6e 20 65 72 72 6f    VFS is an erro
21b00 72 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f  r. ^If sqlite3_o
21b10 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64  pen_v2() is used
21b20 20 61 6e 64 20 74 68 65 20 76 66 73 20 6f 70 74   and the vfs opt
21b30 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 70 72  ion is.**     pr
21b40 65 73 65 6e 74 2c 20 74 68 65 6e 20 74 68 65 20  esent, then the 
21b50 56 46 53 20 73 70 65 63 69 66 69 65 64 20 62 79  VFS specified by
21b60 20 74 68 65 20 6f 70 74 69 6f 6e 20 74 61 6b 65   the option take
21b70 73 20 70 72 65 63 65 64 65 6e 63 65 20 6f 76 65  s precedence ove
21b80 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 76 61 6c  r.**     the val
21b90 75 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  ue passed as the
21ba0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
21bb0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  r to sqlite3_ope
21bc0 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20  n_v2()..**.**   
21bd0 3c 6c 69 3e 20 3c 62 3e 6d 6f 64 65 3c 2f 62 3e  <li> <b>mode</b>
21be0 3a 20 5e 28 54 68 65 20 6d 6f 64 65 20 70 61 72  : ^(The mode par
21bf0 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73 65  ameter may be se
21c00 74 20 74 6f 20 65 69 74 68 65 72 20 22 72 6f 22  t to either "ro"
21c10 2c 20 22 72 77 22 2c 0a 2a 2a 20 20 20 20 20 22  , "rw",.**     "
21c20 72 77 63 22 2c 20 6f 72 20 22 6d 65 6d 6f 72 79  rwc", or "memory
21c30 22 2e 20 41 74 74 65 6d 70 74 69 6e 67 20 74 6f  ". Attempting to
21c40 20 73 65 74 20 69 74 20 74 6f 20 61 6e 79 20 6f   set it to any o
21c50 74 68 65 72 20 76 61 6c 75 65 20 69 73 0a 2a 2a  ther value is.**
21c60 20 20 20 20 20 61 6e 20 65 72 72 6f 72 29 5e 2e       an error)^.
21c70 20 0a 2a 2a 20 20 20 20 20 5e 49 66 20 22 72 6f   .**     ^If "ro
21c80 22 20 69 73 20 73 70 65 63 69 66 69 65 64 2c 20  " is specified, 
21c90 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  then the databas
21ca0 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20  e is opened for 
21cb0 72 65 61 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 20  read-only .**   
21cc0 20 20 61 63 63 65 73 73 2c 20 6a 75 73 74 20 61    access, just a
21cd0 73 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45  s if the [SQLITE
21ce0 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20  _OPEN_READONLY] 
21cf0 66 6c 61 67 20 68 61 64 20 62 65 65 6e 20 73 65  flag had been se
21d00 74 20 69 6e 20 74 68 65 20 0a 2a 2a 20 20 20 20  t in the .**    
21d10 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
21d20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
21d30 76 32 28 29 2e 20 5e 49 66 20 74 68 65 20 6d 6f  v2(). ^If the mo
21d40 64 65 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74  de option is set
21d50 20 74 6f 20 0a 2a 2a 20 20 20 20 20 22 72 77 22   to .**     "rw"
21d60 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  , then the datab
21d70 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f  ase is opened fo
21d80 72 20 72 65 61 64 2d 77 72 69 74 65 20 28 62 75  r read-write (bu
21d90 74 20 6e 6f 74 20 63 72 65 61 74 65 29 20 0a 2a  t not create) .*
21da0 2a 20 20 20 20 20 61 63 63 65 73 73 2c 20 61 73  *     access, as
21db0 20 69 66 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f   if SQLITE_OPEN_
21dc0 52 45 41 44 57 52 49 54 45 20 28 62 75 74 20 6e  READWRITE (but n
21dd0 6f 74 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  ot SQLITE_OPEN_C
21de0 52 45 41 54 45 29 20 68 61 64 20 0a 2a 2a 20 20  REATE) had .**  
21df0 20 20 20 62 65 65 6e 20 73 65 74 2e 20 5e 56 61     been set. ^Va
21e00 6c 75 65 20 22 72 77 63 22 20 69 73 20 65 71 75  lue "rwc" is equ
21e10 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69  ivalent to setti
21e20 6e 67 20 62 6f 74 68 20 0a 2a 2a 20 20 20 20 20  ng both .**     
21e30 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
21e40 57 52 49 54 45 20 61 6e 64 20 53 51 4c 49 54 45  WRITE and SQLITE
21e50 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2e 20 20 5e  _OPEN_CREATE.  ^
21e60 49 66 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69  If the mode opti
21e70 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 73 65 74  on is.**     set
21e80 20 74 6f 20 22 6d 65 6d 6f 72 79 22 20 74 68 65   to "memory" the
21e90 6e 20 61 20 70 75 72 65 20 5b 69 6e 2d 6d 65 6d  n a pure [in-mem
21ea0 6f 72 79 20 64 61 74 61 62 61 73 65 5d 20 74 68  ory database] th
21eb0 61 74 20 6e 65 76 65 72 20 72 65 61 64 73 0a 2a  at never reads.*
21ec0 2a 20 20 20 20 20 6f 72 20 77 72 69 74 65 73 20  *     or writes 
21ed0 66 72 6f 6d 20 64 69 73 6b 20 69 73 20 75 73 65  from disk is use
21ee0 64 2e 20 5e 49 74 20 69 73 20 61 6e 20 65 72 72  d. ^It is an err
21ef0 6f 72 20 74 6f 20 73 70 65 63 69 66 79 20 61 20  or to specify a 
21f00 76 61 6c 75 65 20 66 6f 72 0a 2a 2a 20 20 20 20  value for.**    
21f10 20 74 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65   the mode parame
21f20 74 65 72 20 74 68 61 74 20 69 73 20 6c 65 73 73  ter that is less
21f30 20 72 65 73 74 72 69 63 74 69 76 65 20 74 68 61   restrictive tha
21f40 6e 20 74 68 61 74 20 73 70 65 63 69 66 69 65 64  n that specified
21f50 20 62 79 0a 2a 2a 20 20 20 20 20 74 68 65 20 66   by.**     the f
21f60 6c 61 67 73 20 70 61 73 73 65 64 20 69 6e 20 74  lags passed in t
21f70 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
21f80 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  er to sqlite3_op
21f90 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20  en_v2()..**.**  
21fa0 20 3c 6c 69 3e 20 3c 62 3e 63 61 63 68 65 3c 2f   <li> <b>cache</
21fb0 62 3e 3a 20 5e 54 68 65 20 63 61 63 68 65 20 70  b>: ^The cache p
21fc0 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20  arameter may be 
21fd0 73 65 74 20 74 6f 20 65 69 74 68 65 72 20 22 73  set to either "s
21fe0 68 61 72 65 64 22 20 6f 72 0a 2a 2a 20 20 20 20  hared" or.**    
21ff0 20 22 70 72 69 76 61 74 65 22 2e 20 5e 53 65 74   "private". ^Set
22000 74 69 6e 67 20 69 74 20 74 6f 20 22 73 68 61 72  ting it to "shar
22010 65 64 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e  ed" is equivalen
22020 74 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65  t to setting the
22030 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f  .**     SQLITE_O
22040 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20  PEN_SHAREDCACHE 
22050 62 69 74 20 69 6e 20 74 68 65 20 66 6c 61 67 73  bit in the flags
22060 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64   argument passed
22070 20 74 6f 0a 2a 2a 20 20 20 20 20 73 71 6c 69 74   to.**     sqlit
22080 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 53  e3_open_v2(). ^S
22090 65 74 74 69 6e 67 20 74 68 65 20 63 61 63 68 65  etting the cache
220a0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 22 70   parameter to "p
220b0 72 69 76 61 74 65 22 20 69 73 20 0a 2a 2a 20 20  rivate" is .**  
220c0 20 20 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f     equivalent to
220d0 20 73 65 74 74 69 6e 67 20 74 68 65 20 53 51 4c   setting the SQL
220e0 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45  ITE_OPEN_PRIVATE
220f0 43 41 43 48 45 20 62 69 74 2e 0a 2a 2a 20 20 20  CACHE bit..**   
22100 20 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70    ^If sqlite3_op
22110 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64 20  en_v2() is used 
22120 61 6e 64 20 74 68 65 20 22 63 61 63 68 65 22 20  and the "cache" 
22130 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 72 65  parameter is pre
22140 73 65 6e 74 20 69 6e 0a 2a 2a 20 20 20 20 20 61  sent in.**     a
22150 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 2c 20 69   URI filename, i
22160 74 73 20 76 61 6c 75 65 20 6f 76 65 72 72 69 64  ts value overrid
22170 65 73 20 61 6e 79 20 62 65 68 61 76 69 6f 72 20  es any behavior 
22180 72 65 71 75 65 73 74 65 64 20 62 79 20 73 65 74  requested by set
22190 74 69 6e 67 0a 2a 2a 20 20 20 20 20 53 51 4c 49  ting.**     SQLI
221a0 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
221b0 41 43 48 45 20 6f 72 20 53 51 4c 49 54 45 5f 4f  ACHE or SQLITE_O
221c0 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20  PEN_SHAREDCACHE 
221d0 66 6c 61 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  flag..** </ul>.*
221e0 2a 0a 2a 2a 20 5e 53 70 65 63 69 66 79 69 6e 67  *.** ^Specifying
221f0 20 61 6e 20 75 6e 6b 6e 6f 77 6e 20 70 61 72 61   an unknown para
22200 6d 65 74 65 72 20 69 6e 20 74 68 65 20 71 75 65  meter in the que
22210 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20  ry component of 
22220 61 20 55 52 49 20 69 73 20 6e 6f 74 20 61 6e 0a  a URI is not an.
22230 2a 2a 20 65 72 72 6f 72 2e 20 20 46 75 74 75 72  ** error.  Futur
22240 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
22250 4c 69 74 65 20 6d 69 67 68 74 20 75 6e 64 65 72  Lite might under
22260 73 74 61 6e 64 20 61 64 64 69 74 69 6f 6e 61 6c  stand additional
22270 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65   query.** parame
22280 74 65 72 73 2e 20 20 53 65 65 20 22 5b 71 75 65  ters.  See "[que
22290 72 79 20 70 61 72 61 6d 65 74 65 72 73 20 77 69  ry parameters wi
222a0 74 68 20 73 70 65 63 69 61 6c 20 6d 65 61 6e 69  th special meani
222b0 6e 67 20 74 6f 20 53 51 4c 69 74 65 5d 22 20 66  ng to SQLite]" f
222c0 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c  or.** additional
222d0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
222e0 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61  .** [[URI filena
222f0 6d 65 20 65 78 61 6d 70 6c 65 73 5d 5d 20 3c 68  me examples]] <h
22300 33 3e 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65  3>URI filename e
22310 78 61 6d 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a 0a  xamples</h3>.**.
22320 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72  ** <table border
22330 3d 22 31 22 20 61 6c 69 67 6e 3d 63 65 6e 74 65  ="1" align=cente
22340 72 20 63 65 6c 6c 70 61 64 64 69 6e 67 3d 35 3e  r cellpadding=5>
22350 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 55 52 49  .** <tr><th> URI
22360 20 66 69 6c 65 6e 61 6d 65 73 20 3c 74 68 3e 20   filenames <th> 
22370 52 65 73 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e 3c  Results.** <tr><
22380 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62  td> file:data.db
22390 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20   <td> .**       
223a0 20 20 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65     Open the file
223b0 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68   "data.db" in th
223c0 65 20 63 75 72 72 65 6e 74 20 64 69 72 65 63 74  e current direct
223d0 6f 72 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  ory..** <tr><td>
223e0 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64   file:/home/fred
223f0 2f 64 61 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a 20  /data.db<br>.** 
22400 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f           file://
22410 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
22420 64 62 20 3c 62 72 3e 20 0a 2a 2a 20 20 20 20 20  db <br> .**     
22430 20 20 20 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63 61       file://loca
22440 6c 68 6f 73 74 2f 68 6f 6d 65 2f 66 72 65 64 2f  lhost/home/fred/
22450 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 3c 74 64  data.db <br> <td
22460 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f  > .**          O
22470 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  pen the database
22480 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65   file "/home/fre
22490 64 2f 64 61 74 61 2e 64 62 22 2e 0a 2a 2a 20 3c  d/data.db"..** <
224a0 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f 64  tr><td> file://d
224b0 61 72 6b 73 74 61 72 2f 68 6f 6d 65 2f 66 72 65  arkstar/home/fre
224c0 64 2f 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a  d/data.db <td> .
224d0 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20 65  **          An e
224e0 72 72 6f 72 2e 20 22 64 61 72 6b 73 74 61 72 22  rror. "darkstar"
224f0 20 69 73 20 6e 6f 74 20 61 20 72 65 63 6f 67 6e   is not a recogn
22500 69 7a 65 64 20 61 75 74 68 6f 72 69 74 79 2e 0a  ized authority..
22510 2a 2a 20 3c 74 72 3e 3c 74 64 20 73 74 79 6c 65  ** <tr><td style
22520 3d 22 77 68 69 74 65 2d 73 70 61 63 65 3a 6e 6f  ="white-space:no
22530 77 72 61 70 22 3e 20 0a 2a 2a 20 20 20 20 20 20  wrap"> .**      
22540 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f 44      file:///C:/D
22550 6f 63 75 6d 65 6e 74 73 25 32 30 61 6e 64 25 32  ocuments%20and%2
22560 30 53 65 74 74 69 6e 67 73 2f 66 72 65 64 2f 44  0Settings/fred/D
22570 65 73 6b 74 6f 70 2f 64 61 74 61 2e 64 62 0a 2a  esktop/data.db.*
22580 2a 20 20 20 20 20 3c 74 64 3e 20 57 69 6e 64 6f  *     <td> Windo
22590 77 73 20 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74 68  ws only: Open th
225a0 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22  e file "data.db"
225b0 20 6f 6e 20 66 72 65 64 27 73 20 64 65 73 6b 74   on fred's deskt
225c0 6f 70 20 6f 6e 20 64 72 69 76 65 0a 2a 2a 20 20  op on drive.**  
225d0 20 20 20 20 20 20 20 20 43 3a 2e 20 4e 6f 74 65          C:. Note
225e0 20 74 68 61 74 20 74 68 65 20 25 32 30 20 65 73   that the %20 es
225f0 63 61 70 69 6e 67 20 69 6e 20 74 68 69 73 20 65  caping in this e
22600 78 61 6d 70 6c 65 20 69 73 20 6e 6f 74 20 73 74  xample is not st
22610 72 69 63 74 6c 79 20 0a 2a 2a 20 20 20 20 20 20  rictly .**      
22620 20 20 20 20 6e 65 63 65 73 73 61 72 79 20 2d 20      necessary - 
22630 73 70 61 63 65 20 63 68 61 72 61 63 74 65 72 73  space characters
22640 20 63 61 6e 20 62 65 20 75 73 65 64 20 6c 69 74   can be used lit
22650 65 72 61 6c 6c 79 0a 2a 2a 20 20 20 20 20 20 20  erally.**       
22660 20 20 20 69 6e 20 55 52 49 20 66 69 6c 65 6e 61     in URI filena
22670 6d 65 73 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  mes..** <tr><td>
22680 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f   file:data.db?mo
22690 64 65 3d 72 6f 26 63 61 63 68 65 3d 70 72 69 76  de=ro&cache=priv
226a0 61 74 65 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20  ate <td> .**    
226b0 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20        Open file 
226c0 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65  "data.db" in the
226d0 20 63 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f   current directo
226e0 72 79 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79  ry for read-only
226f0 20 61 63 63 65 73 73 2e 0a 2a 2a 20 20 20 20 20   access..**     
22700 20 20 20 20 20 52 65 67 61 72 64 6c 65 73 73 20       Regardless 
22710 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
22720 74 20 73 68 61 72 65 64 2d 63 61 63 68 65 20 6d  t shared-cache m
22730 6f 64 65 20 69 73 20 65 6e 61 62 6c 65 64 20 62  ode is enabled b
22740 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 65  y.**          de
22750 66 61 75 6c 74 2c 20 75 73 65 20 61 20 70 72 69  fault, use a pri
22760 76 61 74 65 20 63 61 63 68 65 2e 0a 2a 2a 20 3c  vate cache..** <
22770 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f  tr><td> file:/ho
22780 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3f  me/fred/data.db?
22790 76 66 73 3d 75 6e 69 78 2d 6e 6f 6c 6f 63 6b 20  vfs=unix-nolock 
227a0 3c 74 64 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20  <td>.**         
227b0 20 4f 70 65 6e 20 66 69 6c 65 20 22 2f 68 6f 6d   Open file "/hom
227c0 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e  e/fred/data.db".
227d0 20 55 73 65 20 74 68 65 20 73 70 65 63 69 61 6c   Use the special
227e0 20 56 46 53 20 22 75 6e 69 78 2d 6e 6f 6c 6f 63   VFS "unix-noloc
227f0 6b 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  k"..** <tr><td> 
22800 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64  file:data.db?mod
22810 65 3d 72 65 61 64 6f 6e 6c 79 20 3c 74 64 3e 20  e=readonly <td> 
22820 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20  .**          An 
22830 65 72 72 6f 72 2e 20 22 72 65 61 64 6f 6e 6c 79  error. "readonly
22840 22 20 69 73 20 6e 6f 74 20 61 20 76 61 6c 69 64  " is not a valid
22850 20 6f 70 74 69 6f 6e 20 66 6f 72 20 74 68 65 20   option for the 
22860 22 6d 6f 64 65 22 20 70 61 72 61 6d 65 74 65 72  "mode" parameter
22870 2e 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a  ..** </table>.**
22880 0a 2a 2a 20 5e 55 52 49 20 68 65 78 61 64 65 63  .** ^URI hexadec
22890 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 75  imal escape sequ
228a0 65 6e 63 65 73 20 28 25 48 48 29 20 61 72 65 20  ences (%HH) are 
228b0 73 75 70 70 6f 72 74 65 64 20 77 69 74 68 69 6e  supported within
228c0 20 74 68 65 20 70 61 74 68 20 61 6e 64 0a 2a 2a   the path and.**
228d0 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74   query component
228e0 73 20 6f 66 20 61 20 55 52 49 2e 20 41 20 68 65  s of a URI. A he
228f0 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65  xadecimal escape
22900 20 73 65 71 75 65 6e 63 65 20 63 6f 6e 73 69 73   sequence consis
22910 74 73 20 6f 66 20 61 0a 2a 2a 20 70 65 72 63 65  ts of a.** perce
22920 6e 74 20 73 69 67 6e 20 2d 20 22 25 22 20 2d 20  nt sign - "%" - 
22930 66 6f 6c 6c 6f 77 65 64 20 62 79 20 65 78 61 63  followed by exac
22940 74 6c 79 20 74 77 6f 20 68 65 78 61 64 65 63 69  tly two hexadeci
22950 6d 61 6c 20 64 69 67 69 74 73 20 0a 2a 2a 20 73  mal digits .** s
22960 70 65 63 69 66 79 69 6e 67 20 61 6e 20 6f 63 74  pecifying an oct
22970 65 74 20 76 61 6c 75 65 2e 20 5e 42 65 66 6f 72  et value. ^Befor
22980 65 20 74 68 65 20 70 61 74 68 20 6f 72 20 71 75  e the path or qu
22990 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f  ery components o
229a0 66 20 61 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e  f a.** URI filen
229b0 61 6d 65 20 61 72 65 20 69 6e 74 65 72 70 72 65  ame are interpre
229c0 74 65 64 2c 20 74 68 65 79 20 61 72 65 20 65 6e  ted, they are en
229d0 63 6f 64 65 64 20 75 73 69 6e 67 20 55 54 46 2d  coded using UTF-
229e0 38 20 61 6e 64 20 61 6c 6c 20 0a 2a 2a 20 68 65  8 and all .** he
229f0 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65  xadecimal escape
22a00 20 73 65 71 75 65 6e 63 65 73 20 72 65 70 6c 61   sequences repla
22a10 63 65 64 20 62 79 20 61 20 73 69 6e 67 6c 65 20  ced by a single 
22a20 62 79 74 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20  byte containing 
22a30 74 68 65 0a 2a 2a 20 63 6f 72 72 65 73 70 6f 6e  the.** correspon
22a40 64 69 6e 67 20 6f 63 74 65 74 2e 20 49 66 20 74  ding octet. If t
22a50 68 69 73 20 70 72 6f 63 65 73 73 20 67 65 6e 65  his process gene
22a60 72 61 74 65 73 20 61 6e 20 69 6e 76 61 6c 69 64  rates an invalid
22a70 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 2c   UTF-8 encoding,
22a80 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 73 20  .** the results 
22a90 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
22aa0 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20  *.** <b>Note to 
22ab0 57 69 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f  Windows users:</
22ac0 62 3e 20 20 54 68 65 20 65 6e 63 6f 64 69 6e 67  b>  The encoding
22ad0 20 75 73 65 64 20 66 6f 72 20 74 68 65 20 66 69   used for the fi
22ae0 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a  lename argument.
22af0 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70  ** of sqlite3_op
22b00 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  en() and sqlite3
22b10 5f 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73 74 20  _open_v2() must 
22b20 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68  be UTF-8, not wh
22b30 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61  atever.** codepa
22b40 67 65 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20  ge is currently 
22b50 64 65 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61  defined.  Filena
22b60 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69  mes containing i
22b70 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20  nternational.** 
22b80 63 68 61 72 61 63 74 65 72 73 20 6d 75 73 74 20  characters must 
22b90 62 65 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20  be converted to 
22ba0 55 54 46 2d 38 20 70 72 69 6f 72 20 74 6f 20 70  UTF-8 prior to p
22bb0 61 73 73 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f  assing them into
22bc0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  .** sqlite3_open
22bd0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  () or sqlite3_op
22be0 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c  en_v2()..**.** <
22bf0 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77  b>Note to Window
22c00 73 20 52 75 6e 74 69 6d 65 20 75 73 65 72 73 3a  s Runtime users:
22c10 3c 2f 62 3e 20 20 54 68 65 20 74 65 6d 70 6f 72  </b>  The tempor
22c20 61 72 79 20 64 69 72 65 63 74 6f 72 79 20 6d 75  ary directory mu
22c30 73 74 20 62 65 20 73 65 74 0a 2a 2a 20 70 72 69  st be set.** pri
22c40 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20 73 71  or to calling sq
22c50 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20  lite3_open() or 
22c60 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
22c70 29 2e 20 20 4f 74 68 65 72 77 69 73 65 2c 20 76  ).  Otherwise, v
22c80 61 72 69 6f 75 73 0a 2a 2a 20 66 65 61 74 75 72  arious.** featur
22c90 65 73 20 74 68 61 74 20 72 65 71 75 69 72 65 20  es that require 
22ca0 74 68 65 20 75 73 65 20 6f 66 20 74 65 6d 70 6f  the use of tempo
22cb0 72 61 72 79 20 66 69 6c 65 73 20 6d 61 79 20 66  rary files may f
22cc0 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ail..**.** See a
22cd0 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 74 65  lso: [sqlite3_te
22ce0 6d 70 5f 64 69 72 65 63 74 6f 72 79 5d 0a 2a 2f  mp_directory].*/
22cf0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
22d00 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20  sqlite3_open(.  
22d10 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65  const char *file
22d20 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62  name,   /* Datab
22d30 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54  ase filename (UT
22d40 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65  F-8) */.  sqlite
22d50 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20  3 **ppDb        
22d60 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65    /* OUT: SQLite
22d70 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b   db handle */.);
22d80 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
22d90 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a  sqlite3_open16(.
22da0 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69    const void *fi
22db0 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74  lename,   /* Dat
22dc0 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28  abase filename (
22dd0 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c  UTF-16) */.  sql
22de0 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20  ite3 **ppDb     
22df0 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c       /* OUT: SQL
22e00 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f  ite db handle */
22e10 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .);.SQLITE_API i
22e20 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  nt sqlite3_open_
22e30 76 32 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  v2(.  const char
22e40 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a   *filename,   /*
22e50 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   Database filena
22e60 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20  me (UTF-8) */.  
22e70 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c 20  sqlite3 **ppDb, 
22e80 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20          /* OUT: 
22e90 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65  SQLite db handle
22ea0 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c   */.  int flags,
22eb0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
22ec0 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73   Flags */.  cons
22ed0 74 20 63 68 61 72 20 2a 7a 56 66 73 20 20 20 20  t char *zVfs    
22ee0 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56      /* Name of V
22ef0 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65  FS module to use
22f00 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.);../*.** CA
22f10 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 56  PI3REF: Obtain V
22f20 61 6c 75 65 73 20 46 6f 72 20 55 52 49 20 50 61  alues For URI Pa
22f30 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 54  rameters.**.** T
22f40 68 65 73 65 20 61 72 65 20 75 74 69 6c 69 74 79  hese are utility
22f50 20 72 6f 75 74 69 6e 65 73 2c 20 75 73 65 66 75   routines, usefu
22f60 6c 20 74 6f 20 56 46 53 20 69 6d 70 6c 65 6d 65  l to VFS impleme
22f70 6e 74 61 74 69 6f 6e 73 2c 20 74 68 61 74 20 63  ntations, that c
22f80 68 65 63 6b 0a 2a 2a 20 74 6f 20 73 65 65 20 69  heck.** to see i
22f90 66 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c  f a database fil
22fa0 65 20 77 61 73 20 61 20 55 52 49 20 74 68 61 74  e was a URI that
22fb0 20 63 6f 6e 74 61 69 6e 65 64 20 61 20 73 70 65   contained a spe
22fc0 63 69 66 69 63 20 71 75 65 72 79 20 0a 2a 2a 20  cific query .** 
22fd0 70 61 72 61 6d 65 74 65 72 2c 20 61 6e 64 20 69  parameter, and i
22fe0 66 20 73 6f 20 6f 62 74 61 69 6e 73 20 74 68 65  f so obtains the
22ff0 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20 71   value of that q
23000 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 2e 0a  uery parameter..
23010 2a 2a 0a 2a 2a 20 49 66 20 46 20 69 73 20 74 68  **.** If F is th
23020 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e  e database filen
23030 61 6d 65 20 70 6f 69 6e 74 65 72 20 70 61 73 73  ame pointer pass
23040 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65  ed into the xOpe
23050 6e 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 0a 2a  n() method of .*
23060 2a 20 61 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  * a VFS implemen
23070 74 61 74 69 6f 6e 20 77 68 65 6e 20 74 68 65 20  tation when the 
23080 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20  flags parameter 
23090 74 6f 20 78 4f 70 65 6e 28 29 20 68 61 73 20 6f  to xOpen() has o
230a0 6e 65 20 6f 72 20 0a 2a 2a 20 6d 6f 72 65 20 6f  ne or .** more o
230b0 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  f the [SQLITE_OP
230c0 45 4e 5f 55 52 49 5d 20 6f 72 20 5b 53 51 4c 49  EN_URI] or [SQLI
230d0 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d  TE_OPEN_MAIN_DB]
230e0 20 62 69 74 73 20 73 65 74 20 61 6e 64 0a 2a 2a   bits set and.**
230f0 20 50 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f   P is the name o
23100 66 20 74 68 65 20 71 75 65 72 79 20 70 61 72 61  f the query para
23110 6d 65 74 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 73  meter, then.** s
23120 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d  qlite3_uri_param
23130 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e  eter(F,P) return
23140 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  s the value of t
23150 68 65 20 50 0a 2a 2a 20 70 61 72 61 6d 65 74 65  he P.** paramete
23160 72 20 69 66 20 69 74 20 65 78 69 73 74 73 20 6f  r if it exists o
23170 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  r a NULL pointer
23180 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 20 61   if P does not a
23190 70 70 65 61 72 20 61 73 20 61 20 0a 2a 2a 20 71  ppear as a .** q
231a0 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f  uery parameter o
231b0 6e 20 46 2e 20 20 49 66 20 50 20 69 73 20 61 20  n F.  If P is a 
231c0 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20  query parameter 
231d0 6f 66 20 46 0a 2a 2a 20 68 61 73 20 6e 6f 20 65  of F.** has no e
231e0 78 70 6c 69 63 69 74 20 76 61 6c 75 65 2c 20 74  xplicit value, t
231f0 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  hen sqlite3_uri_
23200 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72  parameter(F,P) r
23210 65 74 75 72 6e 73 0a 2a 2a 20 61 20 70 6f 69 6e  eturns.** a poin
23220 74 65 72 20 74 6f 20 61 6e 20 65 6d 70 74 79 20  ter to an empty 
23230 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68  string..**.** Th
23240 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f  e sqlite3_uri_bo
23250 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75  olean(F,P,B) rou
23260 74 69 6e 65 20 61 73 73 75 6d 65 73 20 74 68 61  tine assumes tha
23270 74 20 50 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e  t P is a boolean
23280 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 61 6e  .** parameter an
23290 64 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28  d returns true (
232a0 31 29 20 6f 72 20 66 61 6c 73 65 20 28 30 29 20  1) or false (0) 
232b0 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 74 68 65  according to the
232c0 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 50 2e 20   value.** of P. 
232d0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69   The sqlite3_uri
232e0 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20  _boolean(F,P,B) 
232f0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
23300 74 72 75 65 20 28 31 29 20 69 66 20 74 68 65 0a  true (1) if the.
23310 2a 2a 20 76 61 6c 75 65 20 6f 66 20 71 75 65 72  ** value of quer
23320 79 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 73  y parameter P is
23330 20 6f 6e 65 20 6f 66 20 22 79 65 73 22 2c 20 22   one of "yes", "
23340 74 72 75 65 22 2c 20 6f 72 20 22 6f 6e 22 20 69  true", or "on" i
23350 6e 20 61 6e 79 0a 2a 2a 20 63 61 73 65 20 6f 72  n any.** case or
23360 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 62 65   if the value be
23370 67 69 6e 73 20 77 69 74 68 20 61 20 6e 6f 6e 2d  gins with a non-
23380 7a 65 72 6f 20 6e 75 6d 62 65 72 2e 20 20 54 68  zero number.  Th
23390 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72  e .** sqlite3_ur
233a0 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29  i_boolean(F,P,B)
233b0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
233c0 73 20 66 61 6c 73 65 20 28 30 29 20 69 66 20 74  s false (0) if t
233d0 68 65 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 71  he value of.** q
233e0 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 50  uery parameter P
233f0 20 69 73 20 6f 6e 65 20 6f 66 20 22 6e 6f 22 2c   is one of "no",
23400 20 22 66 61 6c 73 65 22 2c 20 6f 72 20 22 6f 66   "false", or "of
23410 66 22 20 69 6e 20 61 6e 79 20 63 61 73 65 20 6f  f" in any case o
23420 72 0a 2a 2a 20 69 66 20 74 68 65 20 76 61 6c 75  r.** if the valu
23430 65 20 62 65 67 69 6e 73 20 77 69 74 68 20 61 20  e begins with a 
23440 6e 75 6d 65 72 69 63 20 7a 65 72 6f 2e 20 20 49  numeric zero.  I
23450 66 20 50 20 69 73 20 6e 6f 74 20 61 20 71 75 65  f P is not a que
23460 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  ry.** parameter 
23470 6f 6e 20 46 20 6f 72 20 69 66 20 74 68 65 20 76  on F or if the v
23480 61 6c 75 65 20 6f 66 20 50 20 69 73 20 64 6f 65  alue of P is doe
23490 73 20 6e 6f 74 20 6d 61 74 63 68 20 61 6e 79 20  s not match any 
234a0 6f 66 20 74 68 65 0a 2a 2a 20 61 62 6f 76 65 2c  of the.** above,
234b0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72   then sqlite3_ur
234c0 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29  i_boolean(F,P,B)
234d0 20 72 65 74 75 72 6e 73 20 28 42 21 3d 30 29 2e   returns (B!=0).
234e0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
234f0 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 46 2c 50  e3_uri_int64(F,P
23500 2c 44 29 20 72 6f 75 74 69 6e 65 20 63 6f 6e 76  ,D) routine conv
23510 65 72 74 73 20 74 68 65 20 76 61 6c 75 65 20 6f  erts the value o
23520 66 20 50 20 69 6e 74 6f 20 61 0a 2a 2a 20 36 34  f P into a.** 64
23530 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
23540 67 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20  ger and returns 
23550 74 68 61 74 20 69 6e 74 65 67 65 72 2c 20 6f 72  that integer, or
23560 20 44 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74   D if P does not
23570 0a 2a 2a 20 65 78 69 73 74 2e 20 20 49 66 20 74  .** exist.  If t
23580 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69 73  he value of P is
23590 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72   something other
235a0 20 74 68 61 6e 20 61 6e 20 69 6e 74 65 67 65 72   than an integer
235b0 2c 20 74 68 65 6e 0a 2a 2a 20 7a 65 72 6f 20 69  , then.** zero i
235c0 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 0a  s returned..** .
235d0 2a 2a 20 49 66 20 46 20 69 73 20 61 20 4e 55 4c  ** If F is a NUL
235e0 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20  L pointer, then 
235f0 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61  sqlite3_uri_para
23600 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72  meter(F,P) retur
23610 6e 73 20 4e 55 4c 4c 20 61 6e 64 0a 2a 2a 20 73  ns NULL and.** s
23620 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65  qlite3_uri_boole
23630 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 72 6e  an(F,P,B) return
23640 73 20 42 2e 20 20 49 66 20 46 20 69 73 20 6e 6f  s B.  If F is no
23650 74 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  t a NULL pointer
23660 20 61 6e 64 0a 2a 2a 20 69 73 20 6e 6f 74 20 61   and.** is not a
23670 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 70   database file p
23680 61 74 68 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20  athname pointer 
23690 74 68 61 74 20 53 51 4c 69 74 65 20 70 61 73 73  that SQLite pass
236a0 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65  ed into the xOpe
236b0 6e 0a 2a 2a 20 56 46 53 20 6d 65 74 68 6f 64 2c  n.** VFS method,
236c0 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
236d0 6f 72 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69  or of this routi
236e0 6e 65 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20  ne is undefined 
236f0 61 6e 64 20 70 72 6f 62 61 62 6c 79 0a 2a 2a 20  and probably.** 
23700 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2f 0a  undesirable..*/.
23710 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
23720 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 75   char *sqlite3_u
23730 72 69 5f 70 61 72 61 6d 65 74 65 72 28 63 6f 6e  ri_parameter(con
23740 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61  st char *zFilena
23750 6d 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  me, const char *
23760 7a 50 61 72 61 6d 29 3b 0a 53 51 4c 49 54 45 5f  zParam);.SQLITE_
23770 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
23780 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 63 6f 6e 73  uri_boolean(cons
23790 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20 63  t char *zFile, c
237a0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61  onst char *zPara
237b0 6d 2c 20 69 6e 74 20 62 44 65 66 61 75 6c 74 29  m, int bDefault)
237c0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c  ;.SQLITE_API sql
237d0 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
237e0 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 63 6f 6e  e3_uri_int64(con
237f0 73 74 20 63 68 61 72 2a 2c 20 63 6f 6e 73 74 20  st char*, const 
23800 63 68 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69  char*, sqlite3_i
23810 6e 74 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43  nt64);.../*.** C
23820 41 50 49 33 52 45 46 3a 20 45 72 72 6f 72 20 43  API3REF: Error C
23830 6f 64 65 73 20 41 6e 64 20 4d 65 73 73 61 67 65  odes And Message
23840 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
23850 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69  ite3_errcode() i
23860 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
23870 20 74 68 65 20 6e 75 6d 65 72 69 63 20 5b 72 65   the numeric [re
23880 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a  sult code] or.**
23890 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
238a0 74 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20  t code] for the 
238b0 6d 6f 73 74 20 72 65 63 65 6e 74 20 66 61 69 6c  most recent fail
238c0 65 64 20 73 71 6c 69 74 65 33 5f 2a 20 41 50 49  ed sqlite3_* API
238d0 20 63 61 6c 6c 0a 2a 2a 20 61 73 73 6f 63 69 61   call.** associa
238e0 74 65 64 20 77 69 74 68 20 61 20 5b 64 61 74 61  ted with a [data
238f0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
23900 2e 20 49 66 20 61 20 70 72 69 6f 72 20 41 50 49  . If a prior API
23910 20 63 61 6c 6c 20 66 61 69 6c 65 64 0a 2a 2a 20   call failed.** 
23920 62 75 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63  but the most rec
23930 65 6e 74 20 41 50 49 20 63 61 6c 6c 20 73 75 63  ent API call suc
23940 63 65 65 64 65 64 2c 20 74 68 65 20 72 65 74 75  ceeded, the retu
23950 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 0a 2a 2a  rn value from.**
23960 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65   sqlite3_errcode
23970 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  () is undefined.
23980 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65    ^The sqlite3_e
23990 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28  xtended_errcode(
239a0 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69  ).** interface i
239b0 73 20 74 68 65 20 73 61 6d 65 20 65 78 63 65 70  s the same excep
239c0 74 20 74 68 61 74 20 69 74 20 61 6c 77 61 79 73  t that it always
239d0 20 72 65 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a   returns the .**
239e0 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
239f0 74 20 63 6f 64 65 5d 20 65 76 65 6e 20 77 68 65  t code] even whe
23a00 6e 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  n extended resul
23a10 74 20 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64  t codes are.** d
23a20 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  isabled..**.** ^
23a30 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 6d  The sqlite3_errm
23a40 73 67 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  sg() and sqlite3
23a50 5f 65 72 72 6d 73 67 31 36 28 29 20 72 65 74 75  _errmsg16() retu
23a60 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75  rn English-langu
23a70 61 67 65 0a 2a 2a 20 74 65 78 74 20 74 68 61 74  age.** text that
23a80 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65   describes the e
23a90 72 72 6f 72 2c 20 61 73 20 65 69 74 68 65 72 20  rror, as either 
23aa0 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20  UTF-8 or UTF-16 
23ab0 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a  respectively..**
23ac0 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c   ^(Memory to hol
23ad0 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  d the error mess
23ae0 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61  age string is ma
23af0 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79  naged internally
23b00 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
23b10 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65  tion does not ne
23b20 65 64 20 74 6f 20 77 6f 72 72 79 20 61 62 6f 75  ed to worry abou
23b30 74 20 66 72 65 65 69 6e 67 20 74 68 65 20 72 65  t freeing the re
23b40 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72  sult..** However
23b50 2c 20 74 68 65 20 65 72 72 6f 72 20 73 74 72 69  , the error stri
23b60 6e 67 20 6d 69 67 68 74 20 62 65 20 6f 76 65 72  ng might be over
23b70 77 72 69 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c  written or deall
23b80 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20 73 75 62  ocated by.** sub
23b90 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
23ba0 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e   other SQLite in
23bb0 74 65 72 66 61 63 65 20 66 75 6e 63 74 69 6f 6e  terface function
23bc0 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  s.)^.**.** ^The 
23bd0 73 71 6c 69 74 65 33 5f 65 72 72 73 74 72 28 29  sqlite3_errstr()
23be0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
23bf0 6e 73 20 74 68 65 20 45 6e 67 6c 69 73 68 2d 6c  ns the English-l
23c00 61 6e 67 75 61 67 65 20 74 65 78 74 0a 2a 2a 20  anguage text.** 
23c10 74 68 61 74 20 64 65 73 63 72 69 62 65 73 20 74  that describes t
23c20 68 65 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d  he [result code]
23c30 2c 20 61 73 20 55 54 46 2d 38 2e 0a 2a 2a 20 5e  , as UTF-8..** ^
23c40 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20  (Memory to hold 
23c50 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
23c60 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61  e string is mana
23c70 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a  ged internally.*
23c80 2a 20 61 6e 64 20 6d 75 73 74 20 6e 6f 74 20 62  * and must not b
23c90 65 20 66 72 65 65 64 20 62 79 20 74 68 65 20 61  e freed by the a
23ca0 70 70 6c 69 63 61 74 69 6f 6e 29 5e 2e 0a 2a 2a  pplication)^..**
23cb0 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 73 65 72  .** When the ser
23cc0 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69  ialized [threadi
23cd0 6e 67 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75  ng mode] is in u
23ce0 73 65 2c 20 69 74 20 6d 69 67 68 74 20 62 65 20  se, it might be 
23cf0 74 68 65 0a 2a 2a 20 63 61 73 65 20 74 68 61 74  the.** case that
23d00 20 61 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20   a second error 
23d10 6f 63 63 75 72 73 20 6f 6e 20 61 20 73 65 70 61  occurs on a sepa
23d20 72 61 74 65 20 74 68 72 65 61 64 20 69 6e 20 62  rate thread in b
23d30 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69  etween.** the ti
23d40 6d 65 20 6f 66 20 74 68 65 20 66 69 72 73 74 20  me of the first 
23d50 65 72 72 6f 72 20 61 6e 64 20 74 68 65 20 63 61  error and the ca
23d60 6c 6c 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65  ll to these inte
23d70 72 66 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20  rfaces..** When 
23d80 74 68 61 74 20 68 61 70 70 65 6e 73 2c 20 74 68  that happens, th
23d90 65 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 77  e second error w
23da0 69 6c 6c 20 62 65 20 72 65 70 6f 72 74 65 64 20  ill be reported 
23db0 73 69 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20 69  since these.** i
23dc0 6e 74 65 72 66 61 63 65 73 20 61 6c 77 61 79 73  nterfaces always
23dd0 20 72 65 70 6f 72 74 20 74 68 65 20 6d 6f 73 74   report the most
23de0 20 72 65 63 65 6e 74 20 72 65 73 75 6c 74 2e 20   recent result. 
23df0 20 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69   To avoid.** thi
23e00 73 2c 20 65 61 63 68 20 74 68 72 65 61 64 20 63  s, each thread c
23e10 61 6e 20 6f 62 74 61 69 6e 20 65 78 63 6c 75 73  an obtain exclus
23e20 69 76 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b  ive use of the [
23e30 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
23e40 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76  ion] D.** by inv
23e50 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d  oking [sqlite3_m
23e60 75 74 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c  utex_enter]([sql
23e70 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44  ite3_db_mutex](D
23e80 29 29 20 62 65 66 6f 72 65 20 62 65 67 69 6e 6e  )) before beginn
23e90 69 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20  ing.** to use D 
23ea0 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71  and invoking [sq
23eb0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76  lite3_mutex_leav
23ec0 65 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d  e]([sqlite3_db_m
23ed0 75 74 65 78 5d 28 44 29 29 20 61 66 74 65 72 0a  utex](D)) after.
23ee0 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20  ** all calls to 
23ef0 74 68 65 20 69 6e 74 65 72 66 61 63 65 73 20 6c  the interfaces l
23f00 69 73 74 65 64 20 68 65 72 65 20 61 72 65 20 63  isted here are c
23f10 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  ompleted..**.** 
23f20 49 66 20 61 6e 20 69 6e 74 65 72 66 61 63 65 20  If an interface 
23f30 66 61 69 6c 73 20 77 69 74 68 20 53 51 4c 49 54  fails with SQLIT
23f40 45 5f 4d 49 53 55 53 45 2c 20 74 68 61 74 20 6d  E_MISUSE, that m
23f50 65 61 6e 73 20 74 68 65 20 69 6e 74 65 72 66 61  eans the interfa
23f60 63 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65  ce.** was invoke
23f70 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 62 79  d incorrectly by
23f80 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
23f90 2e 20 20 49 6e 20 74 68 61 74 20 63 61 73 65 2c  .  In that case,
23fa0 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f   the.** error co
23fb0 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65 20 6d  de and message m
23fc0 61 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65  ay or may not be
23fd0 20 73 65 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f   set..*/.SQLITE_
23fe0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
23ff0 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20  errcode(sqlite3 
24000 2a 64 62 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  *db);.SQLITE_API
24010 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74   int sqlite3_ext
24020 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 73 71  ended_errcode(sq
24030 6c 69 74 65 33 20 2a 64 62 29 3b 0a 53 51 4c 49  lite3 *db);.SQLI
24040 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61  TE_API const cha
24050 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  r *sqlite3_errms
24060 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a 53 51 4c  g(sqlite3*);.SQL
24070 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f  ITE_API const vo
24080 69 64 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d  id *sqlite3_errm
24090 73 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a  sg16(sqlite3*);.
240a0 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
240b0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65   char *sqlite3_e
240c0 72 72 73 74 72 28 69 6e 74 29 3b 0a 0a 2f 2a 0a  rrstr(int);../*.
240d0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c  ** CAPI3REF: SQL
240e0 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63   Statement Objec
240f0 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  t.** KEYWORDS: {
24100 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
24110 6e 74 7d 20 7b 70 72 65 70 61 72 65 64 20 73 74  nt} {prepared st
24120 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20  atements}.**.** 
24130 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  An instance of t
24140 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65  his object repre
24150 73 65 6e 74 73 20 61 20 73 69 6e 67 6c 65 20 53  sents a single S
24160 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a  QL statement..**
24170 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20   This object is 
24180 76 61 72 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20  variously known 
24190 61 73 20 61 20 22 70 72 65 70 61 72 65 64 20 73  as a "prepared s
241a0 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 61 0a 2a  tatement" or a.*
241b0 2a 20 22 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20  * "compiled SQL 
241c0 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 73 69  statement" or si
241d0 6d 70 6c 79 20 61 73 20 61 20 22 73 74 61 74 65  mply as a "state
241e0 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ment"..**.** The
241f0 20 6c 69 66 65 20 6f 66 20 61 20 73 74 61 74 65   life of a state
24200 6d 65 6e 74 20 6f 62 6a 65 63 74 20 67 6f 65 73  ment object goes
24210 20 73 6f 6d 65 74 68 69 6e 67 20 6c 69 6b 65 20   something like 
24220 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e  this:.**.** <ol>
24230 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 20  .** <li> Create 
24240 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67  the object using
24250 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
24260 65 5f 76 32 28 29 5d 20 6f 72 20 61 20 72 65 6c  e_v2()] or a rel
24270 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 66 75 6e  ated.**      fun
24280 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42  ction..** <li> B
24290 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 5b 68  ind values to [h
242a0 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 5d 20  ost parameters] 
242b0 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65  using the sqlite
242c0 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20  3_bind_*().**   
242d0 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a     interfaces..*
242e0 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20 53  * <li> Run the S
242f0 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73  QL by calling [s
24300 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f  qlite3_step()] o
24310 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73  ne or more times
24320 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20  ..** <li> Reset 
24330 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 75 73  the statement us
24340 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ing [sqlite3_res
24350 65 74 28 29 5d 20 74 68 65 6e 20 67 6f 20 62 61  et()] then go ba
24360 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73 74  ck.**      to st
24370 65 70 20 32 2e 20 20 44 6f 20 74 68 69 73 20 7a  ep 2.  Do this z
24380 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65  ero or more time
24390 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72  s..** <li> Destr
243a0 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73  oy the object us
243b0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  ing [sqlite3_fin
243c0 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f  alize()]..** </o
243d0 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72 20 74  l>.**.** Refer t
243e0 6f 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20  o documentation 
243f0 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 6d 65  on individual me
24400 74 68 6f 64 73 20 61 62 6f 76 65 20 66 6f 72 20  thods above for 
24410 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e  additional.** in
24420 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79  formation..*/.ty
24430 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
24440 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69 74 65  ite3_stmt sqlite
24450 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43  3_stmt;../*.** C
24460 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d  API3REF: Run-tim
24470 65 20 4c 69 6d 69 74 73 0a 2a 2a 0a 2a 2a 20 5e  e Limits.**.** ^
24480 28 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20  (This interface 
24490 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a 65 20  allows the size 
244a0 6f 66 20 76 61 72 69 6f 75 73 20 63 6f 6e 73 74  of various const
244b0 72 75 63 74 73 20 74 6f 20 62 65 20 6c 69 6d 69  ructs to be limi
244c0 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e  ted.** on a conn
244d0 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63  ection by connec
244e0 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 54 68 65  tion basis.  The
244f0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
24500 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61   is the.** [data
24510 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
24520 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 69 73 20   whose limit is 
24530 74 6f 20 62 65 20 73 65 74 20 6f 72 20 71 75 65  to be set or que
24540 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65  ried.  The.** se
24550 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
24560 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69  s one of the [li
24570 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 5d 20  mit categories] 
24580 74 68 61 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a  that define a.**
24590 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74 72   class of constr
245a0 75 63 74 73 20 74 6f 20 62 65 20 73 69 7a 65 20  ucts to be size 
245b0 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 20 74 68  limited.  The th
245c0 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ird parameter is
245d0 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69   the.** new limi
245e0 74 20 66 6f 72 20 74 68 61 74 20 63 6f 6e 73 74  t for that const
245f0 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49  ruct.)^.**.** ^I
24600 66 20 74 68 65 20 6e 65 77 20 6c 69 6d 69 74 20  f the new limit 
24610 69 73 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75  is a negative nu
24620 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d 69 74 20  mber, the limit 
24630 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a  is unchanged..**
24640 20 5e 28 46 6f 72 20 65 61 63 68 20 6c 69 6d 69   ^(For each limi
24650 74 20 63 61 74 65 67 6f 72 79 20 53 51 4c 49 54  t category SQLIT
24660 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45 3c  E_LIMIT_<i>NAME<
24670 2f 69 3e 20 74 68 65 72 65 20 69 73 20 61 20 0a  /i> there is a .
24680 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68 61 72  ** [limits | har
24690 64 20 75 70 70 65 72 20 62 6f 75 6e 64 5d 0a 2a  d upper bound].*
246a0 2a 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65  * set at compile
246b0 2d 74 69 6d 65 20 62 79 20 61 20 43 20 70 72 65  -time by a C pre
246c0 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20  processor macro 
246d0 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69 74  called.** [limit
246e0 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41 58 5f 3c  s | SQLITE_MAX_<
246f0 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20  i>NAME</i>]..** 
24700 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69  (The "_LIMIT_" i
24710 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 20 63 68  n the name is ch
24720 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22  anged to "_MAX_"
24730 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70 74  .))^.** ^Attempt
24740 73 20 74 6f 20 69 6e 63 72 65 61 73 65 20 61 20  s to increase a 
24750 6c 69 6d 69 74 20 61 62 6f 76 65 20 69 74 73 20  limit above its 
24760 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64  hard upper bound
24770 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79   are.** silently
24780 20 74 72 75 6e 63 61 74 65 64 20 74 6f 20 74 68   truncated to th
24790 65 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75  e hard upper bou
247a0 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61 72  nd..**.** ^Regar
247b0 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72  dless of whether
247c0 20 6f 72 20 6e 6f 74 20 74 68 65 20 6c 69 6d 69   or not the limi
247d0 74 20 77 61 73 20 63 68 61 6e 67 65 64 2c 20 74  t was changed, t
247e0 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  he .** [sqlite3_
247f0 6c 69 6d 69 74 28 29 5d 20 69 6e 74 65 72 66 61  limit()] interfa
24800 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 70  ce returns the p
24810 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 68  rior value of th
24820 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65 6e  e limit..** ^Hen
24830 63 65 2c 20 74 6f 20 66 69 6e 64 20 74 68 65 20  ce, to find the 
24840 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66  current value of
24850 20 61 20 6c 69 6d 69 74 20 77 69 74 68 6f 75 74   a limit without
24860 20 63 68 61 6e 67 69 6e 67 20 69 74 2c 0a 2a 2a   changing it,.**
24870 20 73 69 6d 70 6c 79 20 69 6e 76 6f 6b 65 20 74   simply invoke t
24880 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 77 69  his interface wi
24890 74 68 20 74 68 65 20 74 68 69 72 64 20 70 61 72  th the third par
248a0 61 6d 65 74 65 72 20 73 65 74 20 74 6f 20 2d 31  ameter set to -1
248b0 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d 65  ..**.** Run-time
248c0 20 6c 69 6d 69 74 73 20 61 72 65 20 69 6e 74 65   limits are inte
248d0 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20  nded for use in 
248e0 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  applications tha
248f0 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68  t manage.** both
24900 20 74 68 65 69 72 20 6f 77 6e 20 69 6e 74 65 72   their own inter
24910 6e 61 6c 20 64 61 74 61 62 61 73 65 20 61 6e 64  nal database and
24920 20 61 6c 73 6f 20 64 61 74 61 62 61 73 65 73 20   also databases 
24930 74 68 61 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c  that are control
24940 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73  led.** by untrus
24950 74 65 64 20 65 78 74 65 72 6e 61 6c 20 73 6f 75  ted external sou
24960 72 63 65 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c  rces.  An exampl
24970 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69  e application mi
24980 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 65 62 20  ght be a.** web 
24990 62 72 6f 77 73 65 72 20 74 68 61 74 20 68 61 73  browser that has
249a0 20 69 74 73 20 6f 77 6e 20 64 61 74 61 62 61 73   its own databas
249b0 65 73 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 68  es for storing h
249c0 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65  istory and.** se
249d0 70 61 72 61 74 65 20 64 61 74 61 62 61 73 65 73  parate databases
249e0 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a   controlled by J
249f0 61 76 61 53 63 72 69 70 74 20 61 70 70 6c 69 63  avaScript applic
24a00 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65  ations downloade
24a10 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e 74  d.** off the Int
24a20 65 72 6e 65 74 2e 20 20 54 68 65 20 69 6e 74 65  ernet.  The inte
24a30 72 6e 61 6c 20 64 61 74 61 62 61 73 65 73 20 63  rnal databases c
24a40 61 6e 20 62 65 20 67 69 76 65 6e 20 74 68 65 0a  an be given the.
24a50 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66 61 75 6c  ** large, defaul
24a60 74 20 6c 69 6d 69 74 73 2e 20 20 44 61 74 61 62  t limits.  Datab
24a70 61 73 65 73 20 6d 61 6e 61 67 65 64 20 62 79 20  ases managed by 
24a80 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73  external sources
24a90 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e   can.** be given
24aa0 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69   much smaller li
24ab0 6d 69 74 73 20 64 65 73 69 67 6e 65 64 20 74 6f  mits designed to
24ac0 20 70 72 65 76 65 6e 74 20 61 20 64 65 6e 69 61   prevent a denia
24ad0 6c 20 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a 20  l of service.** 
24ae0 61 74 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70  attack.  Develop
24af0 65 72 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 77  ers might also w
24b00 61 6e 74 20 74 6f 20 75 73 65 20 74 68 65 20 5b  ant to use the [
24b10 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
24b20 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74  orizer()].** int
24b30 65 72 66 61 63 65 20 74 6f 20 66 75 72 74 68 65  erface to furthe
24b40 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73  r control untrus
24b50 74 65 64 20 53 51 4c 2e 20 20 54 68 65 20 73 69  ted SQL.  The si
24b60 7a 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  ze of the databa
24b70 73 65 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79  se.** created by
24b80 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73 63   an untrusted sc
24b90 72 69 70 74 20 63 61 6e 20 62 65 20 63 6f 6e 74  ript can be cont
24ba0 61 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65 0a  ained using the.
24bb0 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75  ** [max_page_cou
24bc0 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a  nt] [PRAGMA]..**
24bd0 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65  .** New run-time
24be0 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65   limit categorie
24bf0 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69  s may be added i
24c00 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
24c10 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  s..*/.SQLITE_API
24c20 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 6d   int sqlite3_lim
24c30 69 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  it(sqlite3*, int
24c40 20 69 64 2c 20 69 6e 74 20 6e 65 77 56 61 6c 29   id, int newVal)
24c50 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
24c60 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 6d 69  F: Run-Time Limi
24c70 74 20 43 61 74 65 67 6f 72 69 65 73 0a 2a 2a 20  t Categories.** 
24c80 4b 45 59 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74  KEYWORDS: {limit
24c90 20 63 61 74 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d   category} {*lim
24ca0 69 74 20 63 61 74 65 67 6f 72 69 65 73 7d 0a 2a  it categories}.*
24cb0 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
24cc0 61 6e 74 73 20 64 65 66 69 6e 65 20 76 61 72 69  ants define vari
24cd0 6f 75 73 20 70 65 72 66 6f 72 6d 61 6e 63 65 20  ous performance 
24ce0 6c 69 6d 69 74 73 0a 2a 2a 20 74 68 61 74 20 63  limits.** that c
24cf0 61 6e 20 62 65 20 6c 6f 77 65 72 65 64 20 61 74  an be lowered at
24d00 20 72 75 6e 2d 74 69 6d 65 20 75 73 69 6e 67 20   run-time using 
24d10 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29  [sqlite3_limit()
24d20 5d 2e 0a 2a 2a 20 54 68 65 20 73 79 6e 6f 70 73  ]..** The synops
24d30 69 73 20 6f 66 20 74 68 65 20 6d 65 61 6e 69 6e  is of the meanin
24d40 67 73 20 6f 66 20 74 68 65 20 76 61 72 69 6f 75  gs of the variou
24d50 73 20 6c 69 6d 69 74 73 20 69 73 20 73 68 6f 77  s limits is show
24d60 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69  n below..** Addi
24d70 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69  tional informati
24d80 6f 6e 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20  on is available 
24d90 61 74 20 5b 6c 69 6d 69 74 73 20 7c 20 4c 69 6d  at [limits | Lim
24da0 69 74 73 20 69 6e 20 53 51 4c 69 74 65 5d 2e 0a  its in SQLite]..
24db0 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b  **.** <dl>.** [[
24dc0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e  SQLITE_LIMIT_LEN
24dd0 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  GTH]] ^(<dt>SQLI
24de0 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c  TE_LIMIT_LENGTH<
24df0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
24e00 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20  maximum size of 
24e10 61 6e 79 20 73 74 72 69 6e 67 20 6f 72 20 42 4c  any string or BL
24e20 4f 42 20 6f 72 20 74 61 62 6c 65 20 72 6f 77 2c  OB or table row,
24e30 20 69 6e 20 62 79 74 65 73 2e 3c 64 64 3e 29 5e   in bytes.<dd>)^
24e40 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
24e50 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48  LIMIT_SQL_LENGTH
24e60 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
24e70 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48  LIMIT_SQL_LENGTH
24e80 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
24e90 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   maximum length 
24ea0 6f 66 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  of an SQL statem
24eb0 65 6e 74 2c 20 69 6e 20 62 79 74 65 73 2e 3c 2f  ent, in bytes.</
24ec0 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
24ed0 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d  LITE_LIMIT_COLUM
24ee0 4e 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  N]] ^(<dt>SQLITE
24ef0 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64  _LIMIT_COLUMN</d
24f00 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
24f10 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
24f20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61 62  columns in a tab
24f30 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72  le definition or
24f40 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c   in the.** resul
24f50 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45  t set of a [SELE
24f60 43 54 5d 20 6f 72 20 74 68 65 20 6d 61 78 69 6d  CT] or the maxim
24f70 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  um number of col
24f80 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65 78  umns in an index
24f90 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44  .** or in an ORD
24fa0 45 52 20 42 59 20 6f 72 20 47 52 4f 55 50 20 42  ER BY or GROUP B
24fb0 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 29 5e  Y clause.</dd>)^
24fc0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
24fd0 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48  LIMIT_EXPR_DEPTH
24fe0 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
24ff0 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48  LIMIT_EXPR_DEPTH
25000 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
25010 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f   maximum depth o
25020 66 20 74 68 65 20 70 61 72 73 65 20 74 72 65 65  f the parse tree
25030 20 6f 6e 20 61 6e 79 20 65 78 70 72 65 73 73 69   on any expressi
25040 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  on.</dd>)^.**.**
25050 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
25060 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 5d  COMPOUND_SELECT]
25070 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
25080 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45  IMIT_COMPOUND_SE
25090 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  LECT</dt>.** <dd
250a0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
250b0 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20  ber of terms in 
250c0 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43  a compound SELEC
250d0 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64  T statement.</dd
250e0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
250f0 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50  TE_LIMIT_VDBE_OP
25100 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
25110 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f 64  LIMIT_VDBE_OP</d
25120 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
25130 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
25140 69 6e 73 74 72 75 63 74 69 6f 6e 73 20 69 6e 20  instructions in 
25150 61 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e  a virtual machin
25160 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 65  e program.** use
25170 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61  d to implement a
25180 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  n SQL statement.
25190 20 20 54 68 69 73 20 6c 69 6d 69 74 20 69 73 20    This limit is 
251a0 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 0a 2a 2a  not currently.**
251b0 20 65 6e 66 6f 72 63 65 64 2c 20 74 68 6f 75 67   enforced, thoug
251c0 68 20 74 68 61 74 20 6d 69 67 68 74 20 62 65 20  h that might be 
251d0 61 64 64 65 64 20 69 6e 20 73 6f 6d 65 20 66 75  added in some fu
251e0 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a  ture release of.
251f0 2a 2a 20 53 51 4c 69 74 65 2e 3c 2f 64 64 3e 29  ** SQLite.</dd>)
25200 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
25210 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f  _LIMIT_FUNCTION_
25220 41 52 47 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  ARG]] ^(<dt>SQLI
25230 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f  TE_LIMIT_FUNCTIO
25240 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  N_ARG</dt>.** <d
25250 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
25260 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74  mber of argument
25270 73 20 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e  s on a function.
25280 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
25290 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54  SQLITE_LIMIT_ATT
252a0 41 43 48 45 44 5d 5d 20 5e 28 3c 64 74 3e 53 51  ACHED]] ^(<dt>SQ
252b0 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43  LITE_LIMIT_ATTAC
252c0 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  HED</dt>.** <dd>
252d0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
252e0 65 72 20 6f 66 20 5b 41 54 54 41 43 48 20 7c 20  er of [ATTACH | 
252f0 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73  attached databas
25300 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  es].)^</dd>.**.*
25310 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
25320 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45  _LIKE_PATTERN_LE
25330 4e 47 54 48 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e  NGTH]].** ^(<dt>
25340 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b  SQLITE_LIMIT_LIK
25350 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48  E_PATTERN_LENGTH
25360 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
25370 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   maximum length 
25380 6f 66 20 74 68 65 20 70 61 74 74 65 72 6e 20 61  of the pattern a
25390 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b  rgument to the [
253a0 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f  LIKE] or.** [GLO
253b0 42 5d 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f 64  B] operators.</d
253c0 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
253d0 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42  ITE_LIMIT_VARIAB
253e0 4c 45 5f 4e 55 4d 42 45 52 5d 5d 0a 2a 2a 20 5e  LE_NUMBER]].** ^
253f0 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
25400 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45  T_VARIABLE_NUMBE
25410 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  R</dt>.** <dd>Th
25420 65 20 6d 61 78 69 6d 75 6d 20 69 6e 64 65 78 20  e maximum index 
25430 6e 75 6d 62 65 72 20 6f 66 20 61 6e 79 20 5b 70  number of any [p
25440 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 61 6e 20  arameter] in an 
25450 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 29 5e  SQL statement.)^
25460 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
25470 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45  LIMIT_TRIGGER_DE
25480 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  PTH]] ^(<dt>SQLI
25490 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52  TE_LIMIT_TRIGGER
254a0 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  _DEPTH</dt>.** <
254b0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64  dd>The maximum d
254c0 65 70 74 68 20 6f 66 20 72 65 63 75 72 73 69 6f  epth of recursio
254d0 6e 20 66 6f 72 20 74 72 69 67 67 65 72 73 2e 3c  n for triggers.<
254e0 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a  /dd>)^.** </dl>.
254f0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
25500 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20  E_LIMIT_LENGTH  
25510 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
25520 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    0.#define SQLI
25530 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e  TE_LIMIT_SQL_LEN
25540 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20  GTH             
25550 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c     1.#define SQL
25560 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e  ITE_LIMIT_COLUMN
25570 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
25580 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
25590 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f  LITE_LIMIT_EXPR_
255a0 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20  DEPTH           
255b0 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53       3.#define S
255c0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50  QLITE_LIMIT_COMP
255d0 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 20 20  OUND_SELECT     
255e0 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20        4.#define 
255f0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42  SQLITE_LIMIT_VDB
25600 45 5f 4f 50 20 20 20 20 20 20 20 20 20 20 20 20  E_OP            
25610 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65         5.#define
25620 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55   SQLITE_LIMIT_FU
25630 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 20 20  NCTION_ARG      
25640 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e          6.#defin
25650 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41  e SQLITE_LIMIT_A
25660 54 54 41 43 48 45 44 20 20 20 20 20 20 20 20 20  TTACHED         
25670 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 69           7.#defi
25680 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
25690 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e  LIKE_PATTERN_LEN
256a0 47 54 48 20 20 20 20 20 20 20 38 0a 23 64 65 66  GTH       8.#def
256b0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
256c0 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52  _VARIABLE_NUMBER
256d0 20 20 20 20 20 20 20 20 20 20 20 39 0a 23 64 65             9.#de
256e0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
256f0 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 20  T_TRIGGER_DEPTH 
25700 20 20 20 20 20 20 20 20 20 20 20 31 30 0a 0a 2f             10../
25710 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
25720 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20  ompiling An SQL 
25730 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45 59  Statement.** KEY
25740 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74 61 74  WORDS: {SQL stat
25750 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a  ement compiler}.
25760 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 65  **.** To execute
25770 20 61 6e 20 53 51 4c 20 71 75 65 72 79 2c 20 69   an SQL query, i
25780 74 20 6d 75 73 74 20 66 69 72 73 74 20 62 65 20  t must first be 
25790 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61 20  compiled into a 
257a0 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f  byte-code.** pro
257b0 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f  gram using one o
257c0 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
257d0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
257e0 74 20 61 72 67 75 6d 65 6e 74 2c 20 22 64 62 22  t argument, "db"
257f0 2c 20 69 73 20 61 20 5b 64 61 74 61 62 61 73 65  , is a [database
25800 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74   connection] obt
25810 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20  ained from a.** 
25820 70 72 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c  prior successful
25830 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
25840 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69  3_open()], [sqli
25850 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6f  te3_open_v2()] o
25860 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70  r.** [sqlite3_op
25870 65 6e 31 36 28 29 5d 2e 20 20 54 68 65 20 64 61  en16()].  The da
25880 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
25890 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61 76 65 20  n must not have 
258a0 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a  been closed..**.
258b0 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72  ** The second ar
258c0 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20  gument, "zSql", 
258d0 69 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  is the statement
258e0 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c   to be compiled,
258f0 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65   encoded.** as e
25900 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55  ither UTF-8 or U
25910 54 46 2d 31 36 2e 20 20 54 68 65 20 73 71 6c 69  TF-16.  The sqli
25920 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 61 6e  te3_prepare() an
25930 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  d sqlite3_prepar
25940 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72 66  e_v2().** interf
25950 61 63 65 73 20 75 73 65 20 55 54 46 2d 38 2c 20  aces use UTF-8, 
25960 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
25970 61 72 65 31 36 28 29 20 61 6e 64 20 73 71 6c 69  are16() and sqli
25980 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
25990 28 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31 36  ().** use UTF-16
259a0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
259b0 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20 69  nByte argument i
259c0 73 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 6f  s less than zero
259d0 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20 72  , then zSql is r
259e0 65 61 64 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a  ead up to the.**
259f0 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d   first zero term
25a00 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e 42 79 74  inator. ^If nByt
25a10 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  e is non-negativ
25a20 65 2c 20 74 68 65 6e 20 69 74 20 69 73 20 74 68  e, then it is th
25a30 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 6e 75 6d  e maximum.** num
25a40 62 65 72 20 6f 66 20 20 62 79 74 65 73 20 72 65  ber of  bytes re
25a50 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e  ad from zSql.  ^
25a60 57 68 65 6e 20 6e 42 79 74 65 20 69 73 20 6e 6f  When nByte is no
25a70 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 0a  n-negative, the.
25a80 2a 2a 20 7a 53 71 6c 20 73 74 72 69 6e 67 20 65  ** zSql string e
25a90 6e 64 73 20 61 74 20 65 69 74 68 65 72 20 74 68  nds at either th
25aa0 65 20 66 69 72 73 74 20 27 5c 30 30 30 27 20 6f  e first '\000' o
25ab0 72 20 27 5c 75 30 30 30 30 27 20 63 68 61 72 61  r '\u0000' chara
25ac0 63 74 65 72 20 6f 72 0a 2a 2a 20 74 68 65 20 6e  cter or.** the n
25ad0 42 79 74 65 2d 74 68 20 62 79 74 65 2c 20 77 68  Byte-th byte, wh
25ae0 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69  ichever comes fi
25af0 72 73 74 2e 20 49 66 20 74 68 65 20 63 61 6c 6c  rst. If the call
25b00 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20 74 68 61 74  er knows.** that
25b10 20 74 68 65 20 73 75 70 70 6c 69 65 64 20 73 74   the supplied st
25b20 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d  ring is nul-term
25b30 69 6e 61 74 65 64 2c 20 74 68 65 6e 20 74 68 65  inated, then the
25b40 72 65 20 69 73 20 61 20 73 6d 61 6c 6c 0a 2a 2a  re is a small.**
25b50 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 61 64 76   performance adv
25b60 61 6e 74 61 67 65 20 74 6f 20 62 65 20 67 61 69  antage to be gai
25b70 6e 65 64 20 62 79 20 70 61 73 73 69 6e 67 20 61  ned by passing a
25b80 6e 20 6e 42 79 74 65 20 70 61 72 61 6d 65 74 65  n nByte paramete
25b90 72 20 74 68 61 74 0a 2a 2a 20 69 73 20 65 71 75  r that.** is equ
25ba0 61 6c 20 74 6f 20 74 68 65 20 6e 75 6d 62 65 72  al to the number
25bb0 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
25bc0 20 69 6e 70 75 74 20 73 74 72 69 6e 67 20 3c 69   input string <i
25bd0 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a  >including</i>.*
25be0 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69 6e  * the nul-termin
25bf0 61 74 6f 72 20 62 79 74 65 73 20 61 73 20 74 68  ator bytes as th
25c00 69 73 20 73 61 76 65 73 20 53 51 4c 69 74 65 20  is saves SQLite 
25c10 66 72 6f 6d 20 68 61 76 69 6e 67 20 74 6f 0a 2a  from having to.*
25c20 2a 20 6d 61 6b 65 20 61 20 63 6f 70 79 20 6f 66  * make a copy of
25c30 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e   the input strin
25c40 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a 54  g..**.** ^If pzT
25c50 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20  ail is not NULL 
25c60 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73 20  then *pzTail is 
25c70 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f  made to point to
25c80 20 74 68 65 20 66 69 72 73 74 20 62 79 74 65 0a   the first byte.
25c90 2a 2a 20 70 61 73 74 20 74 68 65 20 65 6e 64 20  ** past the end 
25ca0 6f 66 20 74 68 65 20 66 69 72 73 74 20 53 51 4c  of the first SQL
25cb0 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53   statement in zS
25cc0 71 6c 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69  ql.  These routi
25cd0 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70  nes only.** comp
25ce0 69 6c 65 20 74 68 65 20 66 69 72 73 74 20 73 74  ile the first st
25cf0 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c  atement in zSql,
25d00 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c   so *pzTail is l
25d10 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 0a  eft pointing to.
25d20 2a 2a 20 77 68 61 74 20 72 65 6d 61 69 6e 73 20  ** what remains 
25d30 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a  uncompiled..**.*
25d40 2a 20 5e 2a 70 70 53 74 6d 74 20 69 73 20 6c 65  * ^*ppStmt is le
25d50 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61  ft pointing to a
25d60 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70 61   compiled [prepa
25d70 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
25d80 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78  hat can be.** ex
25d90 65 63 75 74 65 64 20 75 73 69 6e 67 20 5b 73 71  ecuted using [sq
25da0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 20 20  lite3_step()].  
25db0 5e 49 66 20 74 68 65 72 65 20 69 73 20 61 6e 20  ^If there is an 
25dc0 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69  error, *ppStmt i
25dd0 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c  s set.** to NULL
25de0 2e 20 20 5e 49 66 20 74 68 65 20 69 6e 70 75 74  .  ^If the input
25df0 20 74 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e   text contains n
25e00 6f 20 53 51 4c 20 28 69 66 20 74 68 65 20 69 6e  o SQL (if the in
25e10 70 75 74 20 69 73 20 61 6e 20 65 6d 70 74 79 0a  put is an empty.
25e20 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20 61 20 63  ** string or a c
25e30 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70 70  omment) then *pp
25e40 53 74 6d 74 20 69 73 20 73 65 74 20 74 6f 20 4e  Stmt is set to N
25e50 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c  ULL..** The call
25e60 69 6e 67 20 70 72 6f 63 65 64 75 72 65 20 69 73  ing procedure is
25e70 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72   responsible for
25e80 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f   deleting the co
25e90 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74  mpiled.** SQL st
25ea0 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73  atement using [s
25eb0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
25ec0 29 5d 20 61 66 74 65 72 20 69 74 20 68 61 73 20  )] after it has 
25ed0 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74  finished with it
25ee0 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 6d 61 79 20  ..** ppStmt may 
25ef0 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a  not be NULL..**.
25f00 2a 2a 20 5e 4f 6e 20 73 75 63 63 65 73 73 2c 20  ** ^On success, 
25f10 74 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70  the sqlite3_prep
25f20 61 72 65 28 29 20 66 61 6d 69 6c 79 20 6f 66 20  are() family of 
25f30 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
25f40 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20  [SQLITE_OK];.** 
25f50 6f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72  otherwise an [er
25f60 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74  ror code] is ret
25f70 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  urned..**.** The
25f80 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
25f90 5f 76 32 28 29 20 61 6e 64 20 73 71 6c 69 74 65  _v2() and sqlite
25fa0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
25fb0 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 0a   interfaces are.
25fc0 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66  ** recommended f
25fd0 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72  or all new progr
25fe0 61 6d 73 2e 20 54 68 65 20 74 77 6f 20 6f 6c 64  ams. The two old
25ff0 65 72 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  er interfaces ar
26000 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a 20 66 6f  e retained.** fo
26010 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70  r backwards comp
26020 61 74 69 62 69 6c 69 74 79 2c 20 62 75 74 20 74  atibility, but t
26030 68 65 69 72 20 75 73 65 20 69 73 20 64 69 73 63  heir use is disc
26040 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e 20  ouraged..** ^In 
26050 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
26060 63 65 73 2c 20 74 68 65 20 70 72 65 70 61 72 65  ces, the prepare
26070 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74  d statement.** t
26080 68 61 74 20 69 73 20 72 65 74 75 72 6e 65 64 20  hat is returned 
26090 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74  (the [sqlite3_st
260a0 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74  mt] object) cont
260b0 61 69 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74  ains a copy of t
260c0 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53  he.** original S
260d0 51 4c 20 74 65 78 74 2e 20 54 68 69 73 20 63 61  QL text. This ca
260e0 75 73 65 73 20 74 68 65 20 5b 73 71 6c 69 74 65  uses the [sqlite
260f0 33 5f 73 74 65 70 28 29 5d 20 69 6e 74 65 72 66  3_step()] interf
26100 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65  ace to.** behave
26110 20 64 69 66 66 65 72 65 6e 74 6c 79 20 69 6e 20   differently in 
26120 74 68 72 65 65 20 77 61 79 73 3a 0a 2a 2a 0a 2a  three ways:.**.*
26130 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a  * <ol>.** <li>.*
26140 2a 20 5e 49 66 20 74 68 65 20 64 61 74 61 62 61  * ^If the databa
26150 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65  se schema change
26160 73 2c 20 69 6e 73 74 65 61 64 20 6f 66 20 72 65  s, instead of re
26170 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f  turning [SQLITE_
26180 53 43 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a  SCHEMA] as it.**
26190 20 61 6c 77 61 79 73 20 75 73 65 64 20 74 6f 20   always used to 
261a0 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  do, [sqlite3_ste
261b0 70 28 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61  p()] will automa
261c0 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c  tically recompil
261d0 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61  e the SQL.** sta
261e0 74 65 6d 65 6e 74 20 61 6e 64 20 74 72 79 20 74  tement and try t
261f0 6f 20 72 75 6e 20 69 74 20 61 67 61 69 6e 2e 20  o run it again. 
26200 41 73 20 6d 61 6e 79 20 61 73 20 5b 53 51 4c 49  As many as [SQLI
26210 54 45 5f 4d 41 58 5f 53 43 48 45 4d 41 5f 52 45  TE_MAX_SCHEMA_RE
26220 54 52 59 5d 0a 2a 2a 20 72 65 74 72 69 65 73 20  TRY].** retries 
26230 77 69 6c 6c 20 6f 63 63 75 72 20 62 65 66 6f 72  will occur befor
26240 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  e sqlite3_step()
26250 20 67 69 76 65 73 20 75 70 20 61 6e 64 20 72 65   gives up and re
26260 74 75 72 6e 73 20 61 6e 20 65 72 72 6f 72 2e 0a  turns an error..
26270 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c  ** </li>.**.** <
26280 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61 6e 20  li>.** ^When an 
26290 65 72 72 6f 72 20 6f 63 63 75 72 73 2c 20 5b 73  error occurs, [s
262a0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77  qlite3_step()] w
262b0 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f  ill return one o
262c0 66 20 74 68 65 20 64 65 74 61 69 6c 65 64 0a 2a  f the detailed.*
262d0 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20  * [error codes] 
262e0 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72  or [extended err
262f0 6f 72 20 63 6f 64 65 73 5d 2e 20 20 5e 54 68 65  or codes].  ^The
26300 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72   legacy behavior
26310 20 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b 73 71   was that.** [sq
26320 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 6f  lite3_step()] wo
26330 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20  uld only return 
26340 61 20 67 65 6e 65 72 69 63 20 5b 53 51 4c 49 54  a generic [SQLIT
26350 45 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c 74 20  E_ERROR] result 
26360 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 74 68 65 20  code.** and the 
26370 61 70 70 6c 69 63 61 74 69 6f 6e 20 77 6f 75 6c  application woul
26380 64 20 68 61 76 65 20 74 6f 20 6d 61 6b 65 20 61  d have to make a
26390 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 20   second call to 
263a0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
263b0 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 74 6f  ].** in order to
263c0 20 66 69 6e 64 20 74 68 65 20 75 6e 64 65 72 6c   find the underl
263d0 79 69 6e 67 20 63 61 75 73 65 20 6f 66 20 74 68  ying cause of th
263e0 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69 74 68 20  e problem. With 
263f0 74 68 65 20 22 76 32 22 20 70 72 65 70 61 72 65  the "v2" prepare
26400 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2c 20  .** interfaces, 
26410 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 72  the underlying r
26420 65 61 73 6f 6e 20 66 6f 72 20 74 68 65 20 65 72  eason for the er
26430 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 20  ror is returned 
26440 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20  immediately..** 
26450 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  </li>.**.** <li>
26460 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 70 65 63  .** ^If the spec
26470 69 66 69 63 20 76 61 6c 75 65 20 62 6f 75 6e 64  ific value bound
26480 20 74 6f 20 5b 70 61 72 61 6d 65 74 65 72 20 7c   to [parameter |
26490 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 5d   host parameter]
264a0 20 69 6e 20 74 68 65 20 0a 2a 2a 20 57 48 45 52   in the .** WHER
264b0 45 20 63 6c 61 75 73 65 20 6d 69 67 68 74 20 69  E clause might i
264c0 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 63 68 6f  nfluence the cho
264d0 69 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61  ice of query pla
264e0 6e 20 66 6f 72 20 61 20 73 74 61 74 65 6d 65 6e  n for a statemen
264f0 74 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 73  t,.** then the s
26500 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65  tatement will be
26510 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72   automatically r
26520 65 63 6f 6d 70 69 6c 65 64 2c 20 61 73 20 69 66  ecompiled, as if
26530 20 74 68 65 72 65 20 68 61 64 20 62 65 65 6e 20   there had been 
26540 0a 2a 2a 20 61 20 73 63 68 65 6d 61 20 63 68 61  .** a schema cha
26550 6e 67 65 2c 20 6f 6e 20 74 68 65 20 66 69 72 73  nge, on the firs
26560 74 20 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  t  [sqlite3_step
26570 28 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77 69  ()] call followi
26580 6e 67 20 61 6e 79 20 63 68 61 6e 67 65 0a 2a 2a  ng any change.**
26590 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
265a0 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 62 69 6e  _bind_text | bin
265b0 64 69 6e 67 73 5d 20 6f 66 20 74 68 61 74 20 5b  dings] of that [
265c0 70 61 72 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a 20  parameter]. .** 
265d0 5e 54 68 65 20 73 70 65 63 69 66 69 63 20 76 61  ^The specific va
265e0 6c 75 65 20 6f 66 20 57 48 45 52 45 2d 63 6c 61  lue of WHERE-cla
265f0 75 73 65 20 5b 70 61 72 61 6d 65 74 65 72 5d 20  use [parameter] 
26600 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20  might influence 
26610 74 68 65 20 0a 2a 2a 20 63 68 6f 69 63 65 20 6f  the .** choice o
26620 66 20 71 75 65 72 79 20 70 6c 61 6e 20 69 66 20  f query plan if 
26630 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73  the parameter is
26640 20 74 68 65 20 6c 65 66 74 2d 68 61 6e 64 20 73   the left-hand s
26650 69 64 65 20 6f 66 20 61 20 5b 4c 49 4b 45 5d 0a  ide of a [LIKE].
26660 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20 6f 70 65  ** or [GLOB] ope
26670 72 61 74 6f 72 20 6f 72 20 69 66 20 74 68 65 20  rator or if the 
26680 70 61 72 61 6d 65 74 65 72 20 69 73 20 63 6f 6d  parameter is com
26690 70 61 72 65 64 20 74 6f 20 61 6e 20 69 6e 64 65  pared to an inde
266a0 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e  xed column.** an
266b0 64 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 45 4e  d the [SQLITE_EN
266c0 41 42 4c 45 5f 53 54 41 54 33 5d 20 63 6f 6d 70  ABLE_STAT3] comp
266d0 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
266e0 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 74  is enabled..** t
266f0 68 65 20 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20  he .** </li>.** 
26700 3c 2f 6f 6c 3e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  </ol>.*/.SQLITE_
26710 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
26720 70 72 65 70 61 72 65 28 0a 20 20 73 71 6c 69 74  prepare(.  sqlit
26730 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
26740 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68     /* Database h
26750 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
26760 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20   char *zSql,    
26770 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d     /* SQL statem
26780 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64  ent, UTF-8 encod
26790 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
267a0 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
267b0 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
267c0 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
267d0 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  es. */.  sqlite3
267e0 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
267f0 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
26800 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
26810 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61  onst char **pzTa
26820 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
26830 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
26840 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
26850 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50   */.);.SQLITE_AP
26860 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72  I int sqlite3_pr
26870 65 70 61 72 65 5f 76 32 28 0a 20 20 73 71 6c 69  epare_v2(.  sqli
26880 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
26890 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
268a0 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
268b0 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20  t char *zSql,   
268c0 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65      /* SQL state
268d0 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f  ment, UTF-8 enco
268e0 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79  ded */.  int nBy
268f0 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  te,             
26900 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67   /* Maximum leng
26910 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79  th of zSql in by
26920 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65  tes. */.  sqlite
26930 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c  3_stmt **ppStmt,
26940 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d    /* OUT: Statem
26950 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ent handle */.  
26960 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54  const char **pzT
26970 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20  ail     /* OUT: 
26980 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65  Pointer to unuse
26990 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71  d portion of zSq
269a0 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41  l */.);.SQLITE_A
269b0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  PI int sqlite3_p
269c0 72 65 70 61 72 65 31 36 28 0a 20 20 73 71 6c 69  repare16(.  sqli
269d0 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
269e0 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
269f0 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
26a00 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20  t void *zSql,   
26a10 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65      /* SQL state
26a20 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63  ment, UTF-16 enc
26a30 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42  oded */.  int nB
26a40 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20  yte,            
26a50 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e    /* Maximum len
26a60 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62  gth of zSql in b
26a70 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74  ytes. */.  sqlit
26a80 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74  e3_stmt **ppStmt
26a90 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65  ,  /* OUT: State
26aa0 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  ment handle */. 
26ab0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a   const void **pz
26ac0 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a  Tail     /* OUT:
26ad0 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73   Pointer to unus
26ae0 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53  ed portion of zS
26af0 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f  ql */.);.SQLITE_
26b00 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
26b10 70 72 65 70 61 72 65 31 36 5f 76 32 28 0a 20 20  prepare16_v2(.  
26b20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
26b30 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
26b40 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ase handle */.  
26b50 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c  const void *zSql
26b60 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73  ,       /* SQL s
26b70 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36  tatement, UTF-16
26b80 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
26b90 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
26ba0 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
26bb0 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
26bc0 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73  in bytes. */.  s
26bd0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
26be0 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
26bf0 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
26c00 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
26c10 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
26c20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
26c30 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
26c40 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a  f zSql */.);../*
26c50 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
26c60 74 72 69 65 76 69 6e 67 20 53 74 61 74 65 6d 65  trieving Stateme
26c70 6e 74 20 53 51 4c 0a 2a 2a 0a 2a 2a 20 5e 54 68  nt SQL.**.** ^Th
26c80 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e  is interface can
26c90 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 74 72   be used to retr
26ca0 69 65 76 65 20 61 20 73 61 76 65 64 20 63 6f 70  ieve a saved cop
26cb0 79 20 6f 66 20 74 68 65 20 6f 72 69 67 69 6e 61  y of the origina
26cc0 6c 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20 75 73  l.** SQL text us
26cd0 65 64 20 74 6f 20 63 72 65 61 74 65 20 61 20 5b  ed to create a [
26ce0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
26cf0 6e 74 5d 20 69 66 20 74 68 61 74 20 73 74 61 74  nt] if that stat
26d00 65 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 63 6f 6d  ement was.** com
26d10 70 69 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68  piled using eith
26d20 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  er [sqlite3_prep
26d30 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71  are_v2()] or [sq
26d40 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
26d50 76 32 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45  v2()]..*/.SQLITE
26d60 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20  _API const char 
26d70 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c  *sqlite3_sql(sql
26d80 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
26d90 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
26da0 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66  EF: Determine If
26db0 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e   An SQL Statemen
26dc0 74 20 57 72 69 74 65 73 20 54 68 65 20 44 61 74  t Writes The Dat
26dd0 61 62 61 73 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  abase.**.** ^The
26de0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65   sqlite3_stmt_re
26df0 61 64 6f 6e 6c 79 28 58 29 20 69 6e 74 65 72 66  adonly(X) interf
26e00 61 63 65 20 72 65 74 75 72 6e 73 20 74 72 75 65  ace returns true
26e10 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 0a 2a   (non-zero) if.*
26e20 2a 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68  * and only if th
26e30 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
26e40 65 6d 65 6e 74 5d 20 58 20 6d 61 6b 65 73 20 6e  ement] X makes n
26e50 6f 20 64 69 72 65 63 74 20 63 68 61 6e 67 65 73  o direct changes
26e60 20 74 6f 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65   to.** the conte
26e70 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  nt of the databa
26e80 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e  se file..**.** N
26e90 6f 74 65 20 74 68 61 74 20 5b 61 70 70 6c 69 63  ote that [applic
26ea0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
26eb0 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 6f 72 0a  L functions] or.
26ec0 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c  ** [virtual tabl
26ed0 65 73 5d 20 6d 69 67 68 74 20 63 68 61 6e 67 65  es] might change
26ee0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 6e   the database in
26ef0 64 69 72 65 63 74 6c 79 20 61 73 20 61 20 73 69  directly as a si
26f00 64 65 20 65 66 66 65 63 74 2e 20 20 0a 2a 2a 20  de effect.  .** 
26f10 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69  ^(For example, i
26f20 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  f an application
26f30 20 64 65 66 69 6e 65 73 20 61 20 66 75 6e 63 74   defines a funct
26f40 69 6f 6e 20 22 65 76 61 6c 28 29 22 20 74 68 61  ion "eval()" tha
26f50 74 20 0a 2a 2a 20 63 61 6c 6c 73 20 5b 73 71 6c  t .** calls [sql
26f60 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 74 68  ite3_exec()], th
26f70 65 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  en the following
26f80 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77   SQL statement w
26f90 6f 75 6c 64 0a 2a 2a 20 63 68 61 6e 67 65 20 74  ould.** change t
26fa0 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
26fb0 20 74 68 72 6f 75 67 68 20 73 69 64 65 2d 65 66   through side-ef
26fc0 66 65 63 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  fects:.**.** <bl
26fd0 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
26fe0 2a 20 20 20 20 53 45 4c 45 43 54 20 65 76 61 6c  *    SELECT eval
26ff0 28 27 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 31  ('DELETE FROM t1
27000 27 29 20 46 52 4f 4d 20 74 32 3b 0a 2a 2a 20 3c  ') FROM t2;.** <
27010 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
27020 65 3e 0a 2a 2a 0a 2a 2a 20 42 75 74 20 62 65 63  e>.**.** But bec
27030 61 75 73 65 20 74 68 65 20 5b 53 45 4c 45 43 54  ause the [SELECT
27040 5d 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73  ] statement does
27050 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20   not change the 
27060 64 61 74 61 62 61 73 65 20 66 69 6c 65 0a 2a 2a  database file.**
27070 20 64 69 72 65 63 74 6c 79 2c 20 73 71 6c 69 74   directly, sqlit
27080 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
27090 28 29 20 77 6f 75 6c 64 20 73 74 69 6c 6c 20 72  () would still r
270a0 65 74 75 72 6e 20 74 72 75 65 2e 29 5e 0a 2a 2a  eturn true.)^.**
270b0 0a 2a 2a 20 5e 54 72 61 6e 73 61 63 74 69 6f 6e  .** ^Transaction
270c0 20 63 6f 6e 74 72 6f 6c 20 73 74 61 74 65 6d 65   control stateme
270d0 6e 74 73 20 73 75 63 68 20 61 73 20 5b 42 45 47  nts such as [BEG
270e0 49 4e 5d 2c 20 5b 43 4f 4d 4d 49 54 5d 2c 20 5b  IN], [COMMIT], [
270f0 52 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a 20 5b 53  ROLLBACK],.** [S
27100 41 56 45 50 4f 49 4e 54 5d 2c 20 61 6e 64 20 5b  AVEPOINT], and [
27110 52 45 4c 45 41 53 45 5d 20 63 61 75 73 65 20 73  RELEASE] cause s
27120 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64  qlite3_stmt_read
27130 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e  only() to return
27140 20 74 72 75 65 2c 0a 2a 2a 20 73 69 6e 63 65 20   true,.** since 
27150 74 68 65 20 73 74 61 74 65 6d 65 6e 74 73 20 74  the statements t
27160 68 65 6d 73 65 6c 76 65 73 20 64 6f 20 6e 6f 74  hemselves do not
27170 20 61 63 74 75 61 6c 6c 79 20 6d 6f 64 69 66 79   actually modify
27180 20 74 68 65 20 64 61 74 61 62 61 73 65 20 62 75   the database bu
27190 74 0a 2a 2a 20 72 61 74 68 65 72 20 74 68 65 79  t.** rather they
271a0 20 63 6f 6e 74 72 6f 6c 20 74 68 65 20 74 69 6d   control the tim
271b0 69 6e 67 20 6f 66 20 77 68 65 6e 20 6f 74 68 65  ing of when othe
271c0 72 20 73 74 61 74 65 6d 65 6e 74 73 20 6d 6f 64  r statements mod
271d0 69 66 79 20 74 68 65 20 0a 2a 2a 20 64 61 74 61  ify the .** data
271e0 62 61 73 65 2e 20 20 5e 54 68 65 20 5b 41 54 54  base.  ^The [ATT
271f0 41 43 48 5d 20 61 6e 64 20 5b 44 45 54 41 43 48  ACH] and [DETACH
27200 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 61 6c 73  ] statements als
27210 6f 20 63 61 75 73 65 0a 2a 2a 20 73 71 6c 69 74  o cause.** sqlit
27220 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
27230 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75  () to return tru
27240 65 20 73 69 6e 63 65 2c 20 77 68 69 6c 65 20 74  e since, while t
27250 68 6f 73 65 20 73 74 61 74 65 6d 65 6e 74 73 0a  hose statements.
27260 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 63 6f  ** change the co
27270 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 66 20 61  nfiguration of a
27280 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
27290 74 69 6f 6e 2c 20 74 68 65 79 20 64 6f 20 6e 6f  tion, they do no
272a0 74 20 6d 61 6b 65 20 0a 2a 2a 20 63 68 61 6e 67  t make .** chang
272b0 65 73 20 74 6f 20 74 68 65 20 63 6f 6e 74 65 6e  es to the conten
272c0 74 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  t of the databas
272d0 65 20 66 69 6c 65 73 20 6f 6e 20 64 69 73 6b 2e  e files on disk.
272e0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
272f0 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  nt sqlite3_stmt_
27300 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74 65 33  readonly(sqlite3
27310 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
27320 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
27330 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 20 50  Determine If A P
27340 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
27350 74 20 48 61 73 20 42 65 65 6e 20 52 65 73 65 74  t Has Been Reset
27360 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
27370 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29  te3_stmt_busy(S)
27380 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
27390 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72  ns true (non-zer
273a0 6f 29 20 69 66 20 74 68 65 0a 2a 2a 20 5b 70 72  o) if the.** [pr
273b0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
273c0 5d 20 53 20 68 61 73 20 62 65 65 6e 20 73 74 65  ] S has been ste
273d0 70 70 65 64 20 61 74 20 6c 65 61 73 74 20 6f 6e  pped at least on
273e0 63 65 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71  ce using .** [sq
273f0 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 62  lite3_step(S)] b
27400 75 74 20 68 61 73 20 6e 6f 74 20 72 75 6e 20 74  ut has not run t
27410 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 6e 64  o completion and
27420 2f 6f 72 20 68 61 73 20 6e 6f 74 20 0a 2a 2a 20  /or has not .** 
27430 62 65 65 6e 20 72 65 73 65 74 20 75 73 69 6e 67  been reset using
27440 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
27450 53 29 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  S)].  ^The sqlit
27460 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 0a  e3_stmt_busy(S).
27470 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  ** interface ret
27480 75 72 6e 73 20 66 61 6c 73 65 20 69 66 20 53 20  urns false if S 
27490 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
274a0 72 2e 20 20 49 66 20 53 20 69 73 20 6e 6f 74 20  r.  If S is not 
274b0 61 20 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74  a .** NULL point
274c0 65 72 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20  er and is not a 
274d0 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c  pointer to a val
274e0 69 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  id [prepared sta
274f0 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63  tement].** objec
27500 74 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  t, then the beha
27510 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
27520 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 75  d and probably u
27530 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2a 0a 2a  ndesirable..**.*
27540 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65  * This interface
27550 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e 20   can be used in 
27560 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 5b 73 71 6c  combination [sql
27570 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 29  ite3_next_stmt()
27580 5d 0a 2a 2a 20 74 6f 20 6c 6f 63 61 74 65 20 61  ].** to locate a
27590 6c 6c 20 70 72 65 70 61 72 65 64 20 73 74 61 74  ll prepared stat
275a0 65 6d 65 6e 74 73 20 61 73 73 6f 63 69 61 74 65  ements associate
275b0 64 20 77 69 74 68 20 61 20 64 61 74 61 62 61 73  d with a databas
275c0 65 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  e .** connection
275d0 20 74 68 61 74 20 61 72 65 20 69 6e 20 6e 65 65   that are in nee
275e0 64 20 6f 66 20 62 65 69 6e 67 20 72 65 73 65 74  d of being reset
275f0 2e 20 20 54 68 69 73 20 63 61 6e 20 62 65 20 75  .  This can be u
27600 73 65 64 2c 0a 2a 2a 20 66 6f 72 20 65 78 61 6d  sed,.** for exam
27610 70 6c 65 2c 20 69 6e 20 64 69 61 67 6e 6f 73 74  ple, in diagnost
27620 69 63 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 73  ic routines to s
27630 65 61 72 63 68 20 66 6f 72 20 70 72 65 70 61 72  earch for prepar
27640 65 64 20 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  ed .** statement
27650 73 20 74 68 61 74 20 61 72 65 20 68 6f 6c 64 69  s that are holdi
27660 6e 67 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e  ng a transaction
27670 20 6f 70 65 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45   open..*/.SQLITE
27680 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
27690 5f 73 74 6d 74 5f 62 75 73 79 28 73 71 6c 69 74  _stmt_busy(sqlit
276a0 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a  e3_stmt*);../*.*
276b0 2a 20 43 41 50 49 33 52 45 46 3a 20 44 79 6e 61  * CAPI3REF: Dyna
276c0 6d 69 63 61 6c 6c 79 20 54 79 70 65 64 20 56 61  mically Typed Va
276d0 6c 75 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45  lue Object.** KE
276e0 59 57 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63 74  YWORDS: {protect
276f0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
27700 7d 20 7b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  } {unprotected s
27710 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a  qlite3_value}.**
27720 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20  .** SQLite uses 
27730 74 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  the sqlite3_valu
27740 65 20 6f 62 6a 65 63 74 20 74 6f 20 72 65 70 72  e object to repr
27750 65 73 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73  esent all values
27760 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20  .** that can be 
27770 73 74 6f 72 65 64 20 69 6e 20 61 20 64 61 74 61  stored in a data
27780 62 61 73 65 20 74 61 62 6c 65 2e 20 53 51 4c 69  base table. SQLi
27790 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20  te uses dynamic 
277a0 74 79 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 68  typing.** for th
277b0 65 20 76 61 6c 75 65 73 20 69 74 20 73 74 6f 72  e values it stor
277c0 65 73 2e 20 20 5e 56 61 6c 75 65 73 20 73 74 6f  es.  ^Values sto
277d0 72 65 64 20 69 6e 20 73 71 6c 69 74 65 33 5f 76  red in sqlite3_v
277e0 61 6c 75 65 20 6f 62 6a 65 63 74 73 0a 2a 2a 20  alue objects.** 
277f0 63 61 6e 20 62 65 20 69 6e 74 65 67 65 72 73 2c  can be integers,
27800 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
27810 76 61 6c 75 65 73 2c 20 73 74 72 69 6e 67 73 2c  values, strings,
27820 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e   BLOBs, or NULL.
27830 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65  .**.** An sqlite
27840 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d  3_value object m
27850 61 79 20 62 65 20 65 69 74 68 65 72 20 22 70 72  ay be either "pr
27860 6f 74 65 63 74 65 64 22 20 6f 72 20 22 75 6e 70  otected" or "unp
27870 72 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f  rotected"..** So
27880 6d 65 20 69 6e 74 65 72 66 61 63 65 73 20 72 65  me interfaces re
27890 71 75 69 72 65 20 61 20 70 72 6f 74 65 63 74 65  quire a protecte
278a0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e  d sqlite3_value.
278b0 20 20 4f 74 68 65 72 20 69 6e 74 65 72 66 61 63    Other interfac
278c0 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70  es.** will accep
278d0 74 20 65 69 74 68 65 72 20 61 20 70 72 6f 74 65  t either a prote
278e0 63 74 65 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f  cted or an unpro
278f0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
27900 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69  alue..** Every i
27910 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 61 63  nterface that ac
27920 63 65 70 74 73 20 73 71 6c 69 74 65 33 5f 76 61  cepts sqlite3_va
27930 6c 75 65 20 61 72 67 75 6d 65 6e 74 73 20 73 70  lue arguments sp
27940 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 65 74 68  ecifies.** wheth
27950 65 72 20 6f 72 20 6e 6f 74 20 69 74 20 72 65 71  er or not it req
27960 75 69 72 65 73 20 61 20 70 72 6f 74 65 63 74 65  uires a protecte
27970 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e  d sqlite3_value.
27980 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73  .**.** The terms
27990 20 22 70 72 6f 74 65 63 74 65 64 22 20 61 6e 64   "protected" and
279a0 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 20 72   "unprotected" r
279b0 65 66 65 72 20 74 6f 20 77 68 65 74 68 65 72 20  efer to whether 
279c0 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65  or not.** a mute
279d0 78 20 69 73 20 68 65 6c 64 2e 20 20 41 6e 20 69  x is held.  An i
279e0 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 73  nternal mutex is
279f0 20 68 65 6c 64 20 66 6f 72 20 61 20 70 72 6f 74   held for a prot
27a00 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ected.** sqlite3
27a10 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 62 75  _value object bu
27a20 74 20 6e 6f 20 6d 75 74 65 78 20 69 73 20 68 65  t no mutex is he
27a30 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74  ld for an unprot
27a40 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ected.** sqlite3
27a50 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20  _value object.  
27a60 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
27a70 70 69 6c 65 64 20 74 6f 20 62 65 20 73 69 6e 67  piled to be sing
27a80 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 28  le-threaded.** (
27a90 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 54 48 52  with [SQLITE_THR
27aa0 45 41 44 53 41 46 45 3d 30 5d 20 61 6e 64 20 77  EADSAFE=0] and w
27ab0 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 74 68 72  ith [sqlite3_thr
27ac0 65 61 64 73 61 66 65 28 29 5d 20 72 65 74 75 72  eadsafe()] retur
27ad0 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66  ning 0).** or if
27ae0 20 53 51 4c 69 74 65 20 69 73 20 72 75 6e 20 69   SQLite is run i
27af0 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75 63 65 64  n one of reduced
27b00 20 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a   mutex modes .**
27b10 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
27b20 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f 72  SINGLETHREAD] or
27b30 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
27b40 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20  MULTITHREAD].** 
27b50 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 6e 6f  then there is no
27b60 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74   distinction bet
27b70 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61  ween protected a
27b80 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a  nd unprotected.*
27b90 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  * sqlite3_value 
27ba0 6f 62 6a 65 63 74 73 20 61 6e 64 20 74 68 65 79  objects and they
27bb0 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e 74   can be used int
27bc0 65 72 63 68 61 6e 67 65 61 62 6c 79 2e 20 20 48  erchangeably.  H
27bd0 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d  owever,.** for m
27be0 61 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74  aximum code port
27bf0 61 62 69 6c 69 74 79 20 69 74 20 69 73 20 72 65  ability it is re
27c00 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61  commended that a
27c10 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73  pplications.** s
27c20 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64 69  till make the di
27c30 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65  stinction betwee
27c40 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20  n protected and 
27c50 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  unprotected.** s
27c60 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
27c70 65 63 74 73 20 65 76 65 6e 20 77 68 65 6e 20 6e  ects even when n
27c80 6f 74 20 73 74 72 69 63 74 6c 79 20 72 65 71 75  ot strictly requ
27c90 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ired..**.** ^The
27ca0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
27cb0 62 6a 65 63 74 73 20 74 68 61 74 20 61 72 65 20  bjects that are 
27cc0 70 61 73 73 65 64 20 61 73 20 70 61 72 61 6d 65  passed as parame
27cd0 74 65 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a  ters into the.**
27ce0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
27cf0 6f 66 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  of [application-
27d00 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
27d10 74 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74 65  tions] are prote
27d20 63 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  cted..** ^The sq
27d30 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
27d40 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  ct returned by.*
27d50 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
27d60 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 6e  n_value()] is un
27d70 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e  protected..** Un
27d80 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
27d90 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20  3_value objects 
27da0 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64  may only be used
27db0 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65   with.** [sqlite
27dc0 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29  3_result_value()
27dd0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62  ] and [sqlite3_b
27de0 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a  ind_value()]..**
27df0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   The [sqlite3_va
27e00 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74  lue_blob | sqlit
27e10 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 29 5d  e3_value_type()]
27e20 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e   family of.** in
27e30 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65  terfaces require
27e40 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74   protected sqlit
27e50 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
27e60 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
27e70 75 63 74 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f  uct Mem sqlite3_
27e80 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  value;../*.** CA
27e90 50 49 33 52 45 46 3a 20 53 51 4c 20 46 75 6e 63  PI3REF: SQL Func
27ea0 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a  tion Context Obj
27eb0 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f  ect.**.** The co
27ec0 6e 74 65 78 74 20 69 6e 20 77 68 69 63 68 20 61  ntext in which a
27ed0 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65  n SQL function e
27ee0 78 65 63 75 74 65 73 20 69 73 20 73 74 6f 72 65  xecutes is store
27ef0 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74  d in an.** sqlit
27f00 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63  e3_context objec
27f10 74 2e 20 20 5e 41 20 70 6f 69 6e 74 65 72 20 74  t.  ^A pointer t
27f20 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e  o an sqlite3_con
27f30 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69  text object.** i
27f40 73 20 61 6c 77 61 79 73 20 66 69 72 73 74 20 70  s always first p
27f50 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 61 70 70  arameter to [app
27f60 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
27f70 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e   SQL functions].
27f80 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
27f90 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
27fa0 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65  function impleme
27fb0 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73  ntation will pas
27fc0 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65  s this.** pointe
27fd0 72 20 74 68 72 6f 75 67 68 20 69 6e 74 6f 20 63  r through into c
27fe0 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
27ff0 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71  _result_int | sq
28000 6c 69 74 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c  lite3_result()],
28010 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67 67  .** [sqlite3_agg
28020 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
28030 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72  ], [sqlite3_user
28040 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71  _data()],.** [sq
28050 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62  lite3_context_db
28060 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c  _handle()], [sql
28070 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
28080 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b  ()],.** and/or [
28090 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
280a0 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64  ata()]..*/.typed
280b0 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
280c0 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 74 65  3_context sqlite
280d0 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a  3_context;../*.*
280e0 2a 20 43 41 50 49 33 52 45 46 3a 20 42 69 6e 64  * CAPI3REF: Bind
280f0 69 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50 72  ing Values To Pr
28100 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
28110 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
28120 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 7d 20  host parameter} 
28130 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73  {host parameters
28140 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65  } {host paramete
28150 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f  r name}.** KEYWO
28160 52 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65  RDS: {SQL parame
28170 74 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65  ter} {SQL parame
28180 74 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 65 72  ters} {parameter
28190 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20   binding}.**.** 
281a0 5e 28 49 6e 20 74 68 65 20 53 51 4c 20 73 74 61  ^(In the SQL sta
281b0 74 65 6d 65 6e 74 20 74 65 78 74 20 69 6e 70 75  tement text inpu
281c0 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72  t to [sqlite3_pr
281d0 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
281e0 69 74 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a  its variants,.**
281f0 20 6c 69 74 65 72 61 6c 73 20 6d 61 79 20 62 65   literals may be
28200 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 5b   replaced by a [
28210 70 61 72 61 6d 65 74 65 72 5d 20 74 68 61 74 20  parameter] that 
28220 6d 61 74 63 68 65 73 20 6f 6e 65 20 6f 66 20 66  matches one of f
28230 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d 70  ollowing.** temp
28240 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  lates:.**.** <ul
28250 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20  >.** <li>  ?.** 
28260 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c  <li>  ?NNN.** <l
28270 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e  i>  :VVV.** <li>
28280 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20    @VVV.** <li>  
28290 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  $VVV.** </ul>.**
282a0 0a 2a 2a 20 49 6e 20 74 68 65 20 74 65 6d 70 6c  .** In the templ
282b0 61 74 65 73 20 61 62 6f 76 65 2c 20 4e 4e 4e 20  ates above, NNN 
282c0 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 69 6e  represents an in
282d0 74 65 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a  teger literal,.*
282e0 2a 20 61 6e 64 20 56 56 56 20 72 65 70 72 65 73  * and VVV repres
282f0 65 6e 74 73 20 61 6e 20 61 6c 70 68 61 6e 75 6d  ents an alphanum
28300 65 72 69 63 20 69 64 65 6e 74 69 66 69 65 72 2e  eric identifier.
28310 29 5e 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20  )^  ^The values 
28320 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70 61 72 61  of these.** para
28330 6d 65 74 65 72 73 20 28 61 6c 73 6f 20 63 61 6c  meters (also cal
28340 6c 65 64 20 22 68 6f 73 74 20 70 61 72 61 6d 65  led "host parame
28350 74 65 72 20 6e 61 6d 65 73 22 20 6f 72 20 22 53  ter names" or "S
28360 51 4c 20 70 61 72 61 6d 65 74 65 72 73 22 29 0a  QL parameters").
28370 2a 2a 20 63 61 6e 20 62 65 20 73 65 74 20 75 73  ** can be set us
28380 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ing the sqlite3_
28390 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65  bind_*() routine
283a0 73 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 0a  s defined here..
283b0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
283c0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
283d0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
283e0 29 20 72 6f 75 74 69 6e 65 73 20 69 73 20 61 6c  ) routines is al
283f0 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65  ways.** a pointe
28400 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  r to the [sqlite
28410 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72  3_stmt] object r
28420 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20  eturned from.** 
28430 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
28440 5f 76 32 28 29 5d 20 6f 72 20 69 74 73 20 76 61  _v2()] or its va
28450 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  riants..**.** ^T
28460 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
28470 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20  nt is the index 
28480 6f 66 20 74 68 65 20 53 51 4c 20 70 61 72 61 6d  of the SQL param
28490 65 74 65 72 20 74 6f 20 62 65 20 73 65 74 2e 0a  eter to be set..
284a0 2a 2a 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74  ** ^The leftmost
284b0 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 68   SQL parameter h
284c0 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31  as an index of 1
284d0 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 73 61 6d  .  ^When the sam
284e0 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70  e named.** SQL p
284f0 61 72 61 6d 65 74 65 72 20 69 73 20 75 73 65 64  arameter is used
28500 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c   more than once,
28510 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73   second and subs
28520 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72  equent.** occurr
28530 65 6e 63 65 73 20 68 61 76 65 20 74 68 65 20 73  ences have the s
28540 61 6d 65 20 69 6e 64 65 78 20 61 73 20 74 68 65  ame index as the
28550 20 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63   first occurrenc
28560 65 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e 64 65 78  e..** ^The index
28570 20 66 6f 72 20 6e 61 6d 65 64 20 70 61 72 61 6d   for named param
28580 65 74 65 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f  eters can be loo
28590 6b 65 64 20 75 70 20 75 73 69 6e 67 20 74 68 65  ked up using the
285a0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
285b0 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
285c0 78 28 29 5d 20 41 50 49 20 69 66 20 64 65 73 69  x()] API if desi
285d0 72 65 64 2e 20 20 5e 54 68 65 20 69 6e 64 65 78  red.  ^The index
285e0 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70  .** for "?NNN" p
285f0 61 72 61 6d 65 74 65 72 73 20 69 73 20 74 68 65  arameters is the
28600 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a   value of NNN..*
28610 2a 20 5e 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65  * ^The NNN value
28620 20 6d 75 73 74 20 62 65 20 62 65 74 77 65 65 6e   must be between
28630 20 31 20 61 6e 64 20 74 68 65 20 5b 73 71 6c 69   1 and the [sqli
28640 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20  te3_limit()].** 
28650 70 61 72 61 6d 65 74 65 72 20 5b 53 51 4c 49 54  parameter [SQLIT
28660 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45  E_LIMIT_VARIABLE
28670 5f 4e 55 4d 42 45 52 5d 20 28 64 65 66 61 75 6c  _NUMBER] (defaul
28680 74 20 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a  t value: 999)..*
28690 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20  *.** ^The third 
286a0 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
286b0 76 61 6c 75 65 20 74 6f 20 62 69 6e 64 20 74 6f  value to bind to
286c0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a   the parameter..
286d0 2a 2a 20 5e 49 66 20 74 68 65 20 74 68 69 72 64  ** ^If the third
286e0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
286f0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
28700 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e  ) or sqlite3_bin
28710 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 6f 72  d_text16().** or
28720 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c   sqlite3_bind_bl
28730 6f 62 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70  ob() is a NULL p
28740 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20  ointer then the 
28750 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
28760 0a 2a 2a 20 69 73 20 69 67 6e 6f 72 65 64 20 61  .** is ignored a
28770 6e 64 20 74 68 65 20 65 6e 64 20 72 65 73 75 6c  nd the end resul
28780 74 20 69 73 20 74 68 65 20 73 61 6d 65 20 61 73  t is the same as
28790 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75   sqlite3_bind_nu
287a0 6c 6c 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e  ll()..**.** ^(In
287b0 20 74 68 6f 73 65 20 72 6f 75 74 69 6e 65 73 20   those routines 
287c0 74 68 61 74 20 68 61 76 65 20 61 20 66 6f 75 72  that have a four
287d0 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 73  th argument, its
287e0 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a   value is the.**
287f0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
28800 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65   in the paramete
28810 72 2e 20 20 54 6f 20 62 65 20 63 6c 65 61 72 3a  r.  To be clear:
28820 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 74 68   the value is th
28830 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c  e.** number of <
28840 75 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74  u>bytes</u> in t
28850 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68  he value, not th
28860 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72  e number of char
28870 61 63 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66  acters.)^.** ^If
28880 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
28890 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
288a0 5f 62 69 6e 64 5f 74 65 78 74 28 29 20 6f 72 20  _bind_text() or 
288b0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
288c0 74 31 36 28 29 0a 2a 2a 20 69 73 20 6e 65 67 61  t16().** is nega
288d0 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20 6c  tive, then the l
288e0 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73 74 72  ength of the str
288f0 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75  ing is.** the nu
28900 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 75 70  mber of bytes up
28910 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65   to the first ze
28920 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a  ro terminator..*
28930 2a 20 49 66 20 74 68 65 20 66 6f 75 72 74 68 20  * If the fourth 
28940 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
28950 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29  ite3_bind_blob()
28960 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
28970 65 6e 0a 2a 2a 20 74 68 65 20 62 65 68 61 76 69  en.** the behavi
28980 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  or is undefined.
28990 0a 2a 2a 20 49 66 20 61 20 6e 6f 6e 2d 6e 65 67  .** If a non-neg
289a0 61 74 69 76 65 20 66 6f 75 72 74 68 20 70 61 72  ative fourth par
289b0 61 6d 65 74 65 72 20 69 73 20 70 72 6f 76 69 64  ameter is provid
289c0 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  ed to sqlite3_bi
289d0 6e 64 5f 74 65 78 74 28 29 0a 2a 2a 20 6f 72 20  nd_text().** or 
289e0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
289f0 74 31 36 28 29 20 74 68 65 6e 20 74 68 61 74 20  t16() then that 
28a00 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62  parameter must b
28a10 65 20 74 68 65 20 62 79 74 65 20 6f 66 66 73 65  e the byte offse
28a20 74 0a 2a 2a 20 77 68 65 72 65 20 74 68 65 20 4e  t.** where the N
28a30 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f  UL terminator wo
28a40 75 6c 64 20 6f 63 63 75 72 20 61 73 73 75 6d 69  uld occur assumi
28a50 6e 67 20 74 68 65 20 73 74 72 69 6e 67 20 77 65  ng the string we
28a60 72 65 20 4e 55 4c 0a 2a 2a 20 74 65 72 6d 69 6e  re NUL.** termin
28a70 61 74 65 64 2e 20 20 49 66 20 61 6e 79 20 4e 55  ated.  If any NU
28a80 4c 20 63 68 61 72 61 63 74 65 72 73 20 6f 63 63  L characters occ
28a90 75 72 20 61 74 20 62 79 74 65 20 6f 66 66 73 65  ur at byte offse
28aa0 74 73 20 6c 65 73 73 20 74 68 61 6e 20 0a 2a 2a  ts less than .**
28ab0 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
28ac0 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
28ad0 65 72 20 74 68 65 6e 20 74 68 65 20 72 65 73 75  er then the resu
28ae0 6c 74 69 6e 67 20 73 74 72 69 6e 67 20 76 61 6c  lting string val
28af0 75 65 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 61  ue will.** conta
28b00 69 6e 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73  in embedded NULs
28b10 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 6f 66  .  The result of
28b20 20 65 78 70 72 65 73 73 69 6f 6e 73 20 69 6e 76   expressions inv
28b30 6f 6c 76 69 6e 67 20 73 74 72 69 6e 67 73 0a 2a  olving strings.*
28b40 2a 20 77 69 74 68 20 65 6d 62 65 64 64 65 64 20  * with embedded 
28b50 4e 55 4c 73 20 69 73 20 75 6e 64 65 66 69 6e 65  NULs is undefine
28b60 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  d..**.** ^The fi
28b70 66 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  fth argument to 
28b80 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
28b90 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 62 69 6e  b(), sqlite3_bin
28ba0 64 5f 74 65 78 74 28 29 2c 20 61 6e 64 0a 2a 2a  d_text(), and.**
28bb0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
28bc0 78 74 31 36 28 29 20 69 73 20 61 20 64 65 73 74  xt16() is a dest
28bd0 72 75 63 74 6f 72 20 75 73 65 64 20 74 6f 20 64  ructor used to d
28be0 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c  ispose of the BL
28bf0 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20  OB or.** string 
28c00 61 66 74 65 72 20 53 51 4c 69 74 65 20 68 61 73  after SQLite has
28c10 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69   finished with i
28c20 74 2e 20 20 5e 54 68 65 20 64 65 73 74 72 75 63  t.  ^The destruc
28c30 74 6f 72 20 69 73 20 63 61 6c 6c 65 64 0a 2a 2a  tor is called.**
28c40 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74   to dispose of t
28c50 68 65 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e  he BLOB or strin
28c60 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 63 61  g even if the ca
28c70 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  ll to sqlite3_bi
28c80 6e 64 5f 62 6c 6f 62 28 29 2c 0a 2a 2a 20 73 71  nd_blob(),.** sq
28c90 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
28ca0 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69  ), or sqlite3_bi
28cb0 6e 64 5f 74 65 78 74 31 36 28 29 20 66 61 69 6c  nd_text16() fail
28cc0 73 2e 20 20 0a 2a 2a 20 5e 49 66 20 74 68 65 20  s.  .** ^If the 
28cd0 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 69  fifth argument i
28ce0 73 0a 2a 2a 20 74 68 65 20 73 70 65 63 69 61 6c  s.** the special
28cf0 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53   value [SQLITE_S
28d00 54 41 54 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c  TATIC], then SQL
28d10 69 74 65 20 61 73 73 75 6d 65 73 20 74 68 61 74  ite assumes that
28d20 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74   the.** informat
28d30 69 6f 6e 20 69 73 20 69 6e 20 73 74 61 74 69 63  ion is in static
28d40 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 63  , unmanaged spac
28d50 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e  e and does not n
28d60 65 65 64 20 74 6f 20 62 65 20 66 72 65 65 64 2e  eed to be freed.
28d70 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74  .** ^If the fift
28d80 68 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20 74  h argument has t
28d90 68 65 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45  he value [SQLITE
28da0 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65  _TRANSIENT], the
28db0 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65  n.** SQLite make
28dc0 73 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74  s its own privat
28dd0 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 64 61  e copy of the da
28de0 74 61 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20  ta immediately, 
28df0 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71  before.** the sq
28e00 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
28e10 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a  outine returns..
28e20 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
28e30 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62  e3_bind_zeroblob
28e40 28 29 20 72 6f 75 74 69 6e 65 20 62 69 6e 64 73  () routine binds
28e50 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74   a BLOB of lengt
28e60 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20 66  h N that.** is f
28e70 69 6c 6c 65 64 20 77 69 74 68 20 7a 65 72 6f 65  illed with zeroe
28e80 73 2e 20 20 5e 41 20 7a 65 72 6f 62 6c 6f 62 20  s.  ^A zeroblob 
28e90 75 73 65 73 20 61 20 66 69 78 65 64 20 61 6d 6f  uses a fixed amo
28ea0 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a  unt of memory.**
28eb0 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 65 67 65   (just an intege
28ec0 72 20 74 6f 20 68 6f 6c 64 20 69 74 73 20 73 69  r to hold its si
28ed0 7a 65 29 20 77 68 69 6c 65 20 69 74 20 69 73 20  ze) while it is 
28ee0 62 65 69 6e 67 20 70 72 6f 63 65 73 73 65 64 2e  being processed.
28ef0 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72  .** Zeroblobs ar
28f00 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 73 65  e intended to se
28f10 72 76 65 20 61 73 20 70 6c 61 63 65 68 6f 6c 64  rve as placehold
28f20 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 20 77 68  ers for BLOBs wh
28f30 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69  ose.** content i
28f40 73 20 6c 61 74 65 72 20 77 72 69 74 74 65 6e 20  s later written 
28f50 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
28f60 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e  3_blob_open | in
28f70 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49  cremental BLOB I
28f80 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  /O] routines..**
28f90 20 5e 41 20 6e 65 67 61 74 69 76 65 20 76 61 6c   ^A negative val
28fa0 75 65 20 66 6f 72 20 74 68 65 20 7a 65 72 6f 62  ue for the zerob
28fb0 6c 6f 62 20 72 65 73 75 6c 74 73 20 69 6e 20 61  lob results in a
28fc0 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f   zero-length BLO
28fd0 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79  B..**.** ^If any
28fe0 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
28ff0 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65  bind_*() routine
29000 73 20 61 72 65 20 63 61 6c 6c 65 64 20 77 69 74  s are called wit
29010 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  h a NULL pointer
29020 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b 70 72 65  .** for the [pre
29030 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
29040 20 6f 72 20 77 69 74 68 20 61 20 70 72 65 70 61   or with a prepa
29050 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 66 6f  red statement fo
29060 72 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69  r which.** [sqli
29070 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20  te3_step()] has 
29080 62 65 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72 65  been called more
29090 20 72 65 63 65 6e 74 6c 79 20 74 68 61 6e 20 5b   recently than [
290a0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
290b0 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 61  ,.** then the ca
290c0 6c 6c 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b  ll will return [
290d0 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20  SQLITE_MISUSE]. 
290e0 20 49 66 20 61 6e 79 20 73 71 6c 69 74 65 33 5f   If any sqlite3_
290f0 62 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74 69  bind_().** routi
29100 6e 65 20 69 73 20 70 61 73 73 65 64 20 61 20 5b  ne is passed a [
29110 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
29120 6e 74 5d 20 74 68 61 74 20 68 61 73 20 62 65 65  nt] that has bee
29130 6e 20 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68 65  n finalized, the
29140 0a 2a 2a 20 72 65 73 75 6c 74 20 69 73 20 75 6e  .** result is un
29150 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62  defined and prob
29160 61 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a  ably harmful..**
29170 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61 72  .** ^Bindings ar
29180 65 20 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 79  e not cleared by
29190 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65   the [sqlite3_re
291a0 73 65 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a  set()] routine..
291b0 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72 61  ** ^Unbound para
291c0 6d 65 74 65 72 73 20 61 72 65 20 69 6e 74 65 72  meters are inter
291d0 70 72 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a  preted as NULL..
291e0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
291f0 65 33 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69 6e  e3_bind_* routin
29200 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  es return [SQLIT
29210 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73  E_OK] on success
29220 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72   or an.** [error
29230 20 63 6f 64 65 5d 20 69 66 20 61 6e 79 74 68 69   code] if anythi
29240 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a  ng goes wrong..*
29250 2a 20 5e 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45  * ^[SQLITE_RANGE
29260 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66  ] is returned if
29270 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a   the parameter.*
29280 2a 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f  * index is out o
29290 66 20 72 61 6e 67 65 2e 20 20 5e 5b 53 51 4c 49  f range.  ^[SQLI
292a0 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74  TE_NOMEM] is ret
292b0 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28  urned if malloc(
292c0 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53  ) fails..**.** S
292d0 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
292e0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
292f0 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73  _count()],.** [s
29300 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
29310 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61  meter_name()], a
29320 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  nd [sqlite3_bind
29330 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
29340 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ()]..*/.SQLITE_A
29350 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  PI int sqlite3_b
29360 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33  ind_blob(sqlite3
29370 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
29380 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c  st void*, int n,
29390 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
293a0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
293b0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f   sqlite3_bind_do
293c0 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  uble(sqlite3_stm
293d0 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29  t*, int, double)
293e0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
293f0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e   sqlite3_bind_in
29400 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  t(sqlite3_stmt*,
29410 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 53 51 4c 49   int, int);.SQLI
29420 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
29430 65 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73 71  e3_bind_int64(sq
29440 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
29450 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29  , sqlite3_int64)
29460 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
29470 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75   sqlite3_bind_nu
29480 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ll(sqlite3_stmt*
29490 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41  , int);.SQLITE_A
294a0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  PI int sqlite3_b
294b0 69 6e 64 5f 74 65 78 74 28 73 71 6c 69 74 65 33  ind_text(sqlite3
294c0 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
294d0 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 20 6e 2c  st char*, int n,
294e0 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
294f0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
29500 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
29510 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  xt16(sqlite3_stm
29520 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76  t*, int, const v
29530 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28  oid*, int, void(
29540 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49  *)(void*));.SQLI
29550 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
29560 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 71  e3_bind_value(sq
29570 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
29580 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f  , const sqlite3_
29590 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f  value*);.SQLITE_
295a0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
295b0 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71  bind_zeroblob(sq
295c0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
295d0 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a  , int n);../*.**
295e0 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65   CAPI3REF: Numbe
295f0 72 20 4f 66 20 53 51 4c 20 50 61 72 61 6d 65 74  r Of SQL Paramet
29600 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  ers.**.** ^This 
29610 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 75  routine can be u
29620 73 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20  sed to find the 
29630 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20 70  number of [SQL p
29640 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e  arameters].** in
29650 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
29660 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61  tement].  SQL pa
29670 72 61 6d 65 74 65 72 73 20 61 72 65 20 74 6f 6b  rameters are tok
29680 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f  ens of the.** fo
29690 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20  rm "?", "?NNN", 
296a0 22 3a 41 41 41 22 2c 20 22 24 41 41 41 22 2c 20  ":AAA", "$AAA", 
296b0 6f 72 20 22 40 41 41 41 22 20 74 68 61 74 20 73  or "@AAA" that s
296c0 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65  erve as.** place
296d0 68 6f 6c 64 65 72 73 20 66 6f 72 20 76 61 6c 75  holders for valu
296e0 65 73 20 74 68 61 74 20 61 72 65 20 5b 73 71 6c  es that are [sql
296f0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c  ite3_bind_blob |
29700 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68   bound].** to th
29710 65 20 70 61 72 61 6d 65 74 65 72 73 20 61 74 20  e parameters at 
29720 61 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a  a later time..**
29730 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 69  .** ^(This routi
29740 6e 65 20 61 63 74 75 61 6c 6c 79 20 72 65 74 75  ne actually retu
29750 72 6e 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66  rns the index of
29760 20 74 68 65 20 6c 61 72 67 65 73 74 20 28 72 69   the largest (ri
29770 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61  ghtmost).** para
29780 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66  meter. For all f
29790 6f 72 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e  orms except ?NNN
297a0 2c 20 74 68 69 73 20 77 69 6c 6c 20 63 6f 72 72  , this will corr
297b0 65 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a  espond to the.**
297c0 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69 71 75   number of uniqu
297d0 65 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 49  e parameters.  I
297e0 66 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20  f parameters of 
297f0 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72  the ?NNN form ar
29800 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65  e used,.** there
29810 20 6d 61 79 20 62 65 20 67 61 70 73 20 69 6e 20   may be gaps in 
29820 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a  the list.)^.**.*
29830 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
29840 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73  ite3_bind_blob|s
29850 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a  qlite3_bind()],.
29860 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
29870 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
29880 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
29890 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
298a0 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a  er_index()]..*/.
298b0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
298c0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
298d0 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69  meter_count(sqli
298e0 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
298f0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d  ** CAPI3REF: Nam
29900 65 20 4f 66 20 41 20 48 6f 73 74 20 50 61 72 61  e Of A Host Para
29910 6d 65 74 65 72 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  meter.**.** ^The
29920 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61   sqlite3_bind_pa
29930 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 50 2c 4e  rameter_name(P,N
29940 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
29950 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20  rns.** the name 
29960 6f 66 20 74 68 65 20 4e 2d 74 68 20 5b 53 51 4c  of the N-th [SQL
29970 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74   parameter] in t
29980 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
29990 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28  tement] P..** ^(
299a0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 6f  SQL parameters o
299b0 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e  f the form "?NNN
299c0 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22  " or ":AAA" or "
299d0 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a  @AAA" or "$AAA".
299e0 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d 65 20 77  ** have a name w
299f0 68 69 63 68 20 69 73 20 74 68 65 20 73 74 72 69  hich is the stri
29a00 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41  ng "?NNN" or ":A
29a10 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72  AA" or "@AAA" or
29a20 20 22 24 41 41 41 22 0a 2a 2a 20 72 65 73 70 65   "$AAA".** respe
29a30 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f  ctively..** In o
29a40 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20  ther words, the 
29a50 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 22  initial ":" or "
29a60 24 22 20 6f 72 20 22 40 22 20 6f 72 20 22 3f 22  $" or "@" or "?"
29a70 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65 64 20  .** is included 
29a80 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 6e  as part of the n
29a90 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d  ame.)^.** ^Param
29aa0 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72  eters of the for
29ab0 6d 20 22 3f 22 20 77 69 74 68 6f 75 74 20 61 20  m "?" without a 
29ac0 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65  following intege
29ad0 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a  r have no name.*
29ae0 2a 20 61 6e 64 20 61 72 65 20 72 65 66 65 72 72  * and are referr
29af0 65 64 20 74 6f 20 61 73 20 22 6e 61 6d 65 6c 65  ed to as "namele
29b00 73 73 22 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75  ss" or "anonymou
29b10 73 20 70 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a  s parameters"..*
29b20 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
29b30 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 68  host parameter h
29b40 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31  as an index of 1
29b50 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e  , not 0..**.** ^
29b60 49 66 20 74 68 65 20 76 61 6c 75 65 20 4e 20 69  If the value N i
29b70 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f  s out of range o
29b80 72 20 69 66 20 74 68 65 20 4e 2d 74 68 20 70 61  r if the N-th pa
29b90 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61  rameter is.** na
29ba0 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c  meless, then NUL
29bb0 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  L is returned.  
29bc0 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74  ^The returned st
29bd0 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79  ring is.** alway
29be0 73 20 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64  s in UTF-8 encod
29bf0 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 20  ing even if the 
29c00 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20  named parameter 
29c10 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c  was.** originall
29c20 79 20 73 70 65 63 69 66 69 65 64 20 61 73 20 55  y specified as U
29c30 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 65  TF-16 in [sqlite
29c40 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 6f  3_prepare16()] o
29c50 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  r.** [sqlite3_pr
29c60 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a  epare16_v2()]..*
29c70 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
29c80 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
29c90 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29  b|sqlite3_bind()
29ca0 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
29cb0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f  ind_parameter_co
29cc0 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b  unt()], and.** [
29cd0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
29ce0 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e  ameter_index()].
29cf0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  .*/.SQLITE_API c
29d00 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
29d10 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
29d20 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  r_name(sqlite3_s
29d30 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a  tmt*, int);../*.
29d40 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 64  ** CAPI3REF: Ind
29d50 65 78 20 4f 66 20 41 20 50 61 72 61 6d 65 74 65  ex Of A Paramete
29d60 72 20 57 69 74 68 20 41 20 47 69 76 65 6e 20 4e  r With A Given N
29d70 61 6d 65 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72  ame.**.** ^Retur
29d80 6e 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 61  n the index of a
29d90 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  n SQL parameter 
29da0 67 69 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20  given its name. 
29db0 20 5e 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76   ^The.** index v
29dc0 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69 73  alue returned is
29dd0 20 73 75 69 74 61 62 6c 65 20 66 6f 72 20 75 73   suitable for us
29de0 65 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a  e as the second.
29df0 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  ** parameter to 
29e00 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
29e10 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28  ob|sqlite3_bind(
29e20 29 5d 2e 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20  )].  ^A zero.** 
29e30 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6e  is returned if n
29e40 6f 20 6d 61 74 63 68 69 6e 67 20 70 61 72 61 6d  o matching param
29e50 65 74 65 72 20 69 73 20 66 6f 75 6e 64 2e 20 20  eter is found.  
29e60 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a  ^The parameter.*
29e70 2a 20 6e 61 6d 65 20 6d 75 73 74 20 62 65 20 67  * name must be g
29e80 69 76 65 6e 20 69 6e 20 55 54 46 2d 38 20 65 76  iven in UTF-8 ev
29e90 65 6e 20 69 66 20 74 68 65 20 6f 72 69 67 69 6e  en if the origin
29ea0 61 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  al statement.** 
29eb0 77 61 73 20 70 72 65 70 61 72 65 64 20 66 72 6f  was prepared fro
29ec0 6d 20 55 54 46 2d 31 36 20 74 65 78 74 20 75 73  m UTF-16 text us
29ed0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ing [sqlite3_pre
29ee0 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a  pare16_v2()]..**
29ef0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
29f00 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
29f10 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d  |sqlite3_bind()]
29f20 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  ,.** [sqlite3_bi
29f30 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75  nd_parameter_cou
29f40 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73  nt()], and.** [s
29f50 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
29f60 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a  meter_index()]..
29f70 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
29f80 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70  t sqlite3_bind_p
29f90 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 73  arameter_index(s
29fa0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f  qlite3_stmt*, co
29fb0 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29  nst char *zName)
29fc0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
29fd0 46 3a 20 52 65 73 65 74 20 41 6c 6c 20 42 69 6e  F: Reset All Bin
29fe0 64 69 6e 67 73 20 4f 6e 20 41 20 50 72 65 70 61  dings On A Prepa
29ff0 72 65 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a  red Statement.**
2a000 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20 74 6f  .** ^Contrary to
2a010 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f   the intuition o
2a020 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33  f many, [sqlite3
2a030 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73 20 6e  _reset()] does n
2a040 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74 68 65 20  ot reset.** the 
2a050 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
2a060 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f  ob | bindings] o
2a070 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  n a [prepared st
2a080 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73  atement]..** ^Us
2a090 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74  e this routine t
2a0a0 6f 20 72 65 73 65 74 20 61 6c 6c 20 68 6f 73 74  o reset all host
2a0b0 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 4e   parameters to N
2a0c0 55 4c 4c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ULL..*/.SQLITE_A
2a0d0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  PI int sqlite3_c
2a0e0 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 73 71  lear_bindings(sq
2a0f0 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
2a100 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
2a110 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73  umber Of Columns
2a120 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74   In A Result Set
2a130 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74  .**.** ^Return t
2a140 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
2a150 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75  umns in the resu
2a160 6c 74 20 73 65 74 20 72 65 74 75 72 6e 65 64 20  lt set returned 
2a170 62 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  by the.** [prepa
2a180 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20  red statement]. 
2a190 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65  ^This routine re
2a1a0 74 75 72 6e 73 20 30 20 69 66 20 70 53 74 6d 74  turns 0 if pStmt
2a1b0 20 69 73 20 61 6e 20 53 51 4c 0a 2a 2a 20 73 74   is an SQL.** st
2a1c0 61 74 65 6d 65 6e 74 20 74 68 61 74 20 64 6f 65  atement that doe
2a1d0 73 20 6e 6f 74 20 72 65 74 75 72 6e 20 64 61 74  s not return dat
2a1e0 61 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 61  a (for example a
2a1f0 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2a 0a  n [UPDATE])..**.
2a200 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
2a210 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
2a220 28 29 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ()].*/.SQLITE_AP
2a230 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  I int sqlite3_co
2a240 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74  lumn_count(sqlit
2a250 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
2a260 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2a270 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49  : Column Names I
2a280 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a  n A Result Set.*
2a290 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
2a2a0 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20  ines return the 
2a2b0 6e 61 6d 65 20 61 73 73 69 67 6e 65 64 20 74 6f  name assigned to
2a2c0 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 63 6f   a particular co
2a2d0 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72  lumn.** in the r
2a2e0 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b  esult set of a [
2a2f0 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
2a300 74 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  t.  ^The sqlite3
2a310 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a  _column_name().*
2a320 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  * interface retu
2a330 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
2a340 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
2a350 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a  ed UTF-8 string.
2a360 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  ** and sqlite3_c
2a370 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72  olumn_name16() r
2a380 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
2a390 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   to a zero-termi
2a3a0 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20  nated.** UTF-16 
2a3b0 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 66 69  string.  ^The fi
2a3c0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
2a3d0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
2a3e0 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61  tatement].** tha
2a3f0 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65  t implements the
2a400 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
2a410 65 6e 74 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64  ent. ^The second
2a420 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
2a430 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62  e.** column numb
2a440 65 72 2e 20 20 5e 54 68 65 20 6c 65 66 74 6d 6f  er.  ^The leftmo
2a450 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d  st column is num
2a460 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ber 0..**.** ^Th
2a470 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e  e returned strin
2a480 67 20 70 6f 69 6e 74 65 72 20 69 73 20 76 61 6c  g pointer is val
2a490 69 64 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20  id until either 
2a4a0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
2a4b0 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64  atement].** is d
2a4c0 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c  estroyed by [sql
2a4d0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
2a4e0 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74   or until the st
2a4f0 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d  atement is autom
2a500 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72  atically.** repr
2a510 65 70 61 72 65 64 20 62 79 20 74 68 65 20 66 69  epared by the fi
2a520 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  rst call to [sql
2a530 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72  ite3_step()] for
2a540 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 75   a particular ru
2a550 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68  n.** or until th
2a560 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a  e next call to.*
2a570 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
2a580 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c 69 74  _name() or sqlit
2a590 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36  e3_column_name16
2a5a0 28 29 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 63  () on the same c
2a5b0 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  olumn..**.** ^If
2a5c0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
2a5d0 29 20 66 61 69 6c 73 20 64 75 72 69 6e 67 20 74  ) fails during t
2a5e0 68 65 20 70 72 6f 63 65 73 73 69 6e 67 20 6f 66  he processing of
2a5f0 20 65 69 74 68 65 72 20 72 6f 75 74 69 6e 65 0a   either routine.
2a600 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20  ** (for example 
2a610 64 75 72 69 6e 67 20 61 20 63 6f 6e 76 65 72 73  during a convers
2a620 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20 74  ion from UTF-8 t
2a630 6f 20 55 54 46 2d 31 36 29 20 74 68 65 6e 20 61  o UTF-16) then a
2a640 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  .** NULL pointer
2a650 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
2a660 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66  .** ^The name of
2a670 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e   a result column
2a680 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66   is the value of
2a690 20 74 68 65 20 22 41 53 22 20 63 6c 61 75 73 65   the "AS" clause
2a6a0 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c   for.** that col
2a6b0 75 6d 6e 2c 20 69 66 20 74 68 65 72 65 20 69 73  umn, if there is
2a6c0 20 61 6e 20 41 53 20 63 6c 61 75 73 65 2e 20 20   an AS clause.  
2a6d0 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 41  If there is no A
2a6e0 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e  S clause.** then
2a6f0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
2a700 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65   column is unspe
2a710 63 69 66 69 65 64 20 61 6e 64 20 6d 61 79 20 63  cified and may c
2a720 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e  hange from.** on
2a730 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c  e release of SQL
2a740 69 74 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e  ite to the next.
2a750 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  .*/.SQLITE_API c
2a760 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
2a770 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73  e3_column_name(s
2a780 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2a790 74 20 4e 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  t N);.SQLITE_API
2a7a0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c   const void *sql
2a7b0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
2a7c0 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
2a7d0 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a  , int N);../*.**
2a7e0 20 43 41 50 49 33 52 45 46 3a 20 53 6f 75 72 63   CAPI3REF: Sourc
2a7f0 65 20 4f 66 20 44 61 74 61 20 49 6e 20 41 20 51  e Of Data In A Q
2a800 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a  uery Result.**.*
2a810 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
2a820 73 20 70 72 6f 76 69 64 65 20 61 20 6d 65 61 6e  s provide a mean
2a830 73 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 74  s to determine t
2a840 68 65 20 64 61 74 61 62 61 73 65 2c 20 74 61 62  he database, tab
2a850 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74 61 62 6c 65  le, and.** table
2a860 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73 20   column that is 
2a870 74 68 65 20 6f 72 69 67 69 6e 20 6f 66 20 61 20  the origin of a 
2a880 70 61 72 74 69 63 75 6c 61 72 20 72 65 73 75 6c  particular resul
2a890 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b  t column in.** [
2a8a0 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
2a8b0 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20  t..** ^The name 
2a8c0 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
2a8d0 6f 72 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75  or table or colu
2a8e0 6d 6e 20 63 61 6e 20 62 65 20 72 65 74 75 72 6e  mn can be return
2a8f0 65 64 20 61 73 0a 2a 2a 20 65 69 74 68 65 72 20  ed as.** either 
2a900 61 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31  a UTF-8 or UTF-1
2a910 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20  6 string.  ^The 
2a920 5f 64 61 74 61 62 61 73 65 5f 20 72 6f 75 74 69  _database_ routi
2a930 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68  nes return.** th
2a940 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 2c  e database name,
2a950 20 74 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75   the _table_ rou
2a960 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65  tines return the
2a970 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64   table name, and
2a980 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f 20  .** the origin_ 
2a990 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
2a9a0 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e  the column name.
2a9b0 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65  .** ^The returne
2a9c0 64 20 73 74 72 69 6e 67 20 69 73 20 76 61 6c 69  d string is vali
2a9d0 64 20 75 6e 74 69 6c 20 74 68 65 20 5b 70 72 65  d until the [pre
2a9e0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2a9f0 20 69 73 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a   is destroyed.**
2aa00 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
2aa10 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75  finalize()] or u
2aa20 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65  ntil the stateme
2aa30 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61  nt is automatica
2aa40 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65  lly.** reprepare
2aa50 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 63  d by the first c
2aa60 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
2aa70 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61  step()] for a pa
2aa80 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20  rticular run.** 
2aa90 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 61 6d  or until the sam
2aaa0 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  e information is
2aab0 20 72 65 71 75 65 73 74 65 64 0a 2a 2a 20 61 67   requested.** ag
2aac0 61 69 6e 20 69 6e 20 61 20 64 69 66 66 65 72 65  ain in a differe
2aad0 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a  nt encoding..**.
2aae0 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 73 20 72 65  ** ^The names re
2aaf0 74 75 72 6e 65 64 20 61 72 65 20 74 68 65 20 6f  turned are the o
2ab00 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73  riginal un-alias
2ab10 65 64 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a  ed names of the.
2ab20 2a 2a 20 64 61 74 61 62 61 73 65 2c 20 74 61 62  ** database, tab
2ab30 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a  le, and column..
2ab40 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
2ab50 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
2ab60 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 69 73  se interfaces is
2ab70 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
2ab80 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65  tement]..** ^The
2ab90 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74  se functions ret
2aba0 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  urn information 
2abb0 61 62 6f 75 74 20 74 68 65 20 4e 74 68 20 72 65  about the Nth re
2abc0 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 72 65 74 75  sult column retu
2abd0 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 73  rned by.** the s
2abe0 74 61 74 65 6d 65 6e 74 2c 20 77 68 65 72 65 20  tatement, where 
2abf0 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20  N is the second 
2ac00 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e  function argumen
2ac10 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 2d  t..** ^The left-
2ac20 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 63  most column is c
2ac30 6f 6c 75 6d 6e 20 30 20 66 6f 72 20 74 68 65 73  olumn 0 for thes
2ac40 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a  e routines..**.*
2ac50 2a 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f  * ^If the Nth co
2ac60 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79  lumn returned by
2ac70 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
2ac80 73 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 20  s an expression 
2ac90 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72 79 20 61  or.** subquery a
2aca0 6e 64 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75  nd is not a colu
2acb0 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 61  mn value, then a
2acc0 6c 6c 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63  ll of these func
2acd0 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20  tions return.** 
2ace0 4e 55 4c 4c 2e 20 20 5e 54 68 65 73 65 20 72 6f  NULL.  ^These ro
2acf0 75 74 69 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f  utine might also
2ad00 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20   return NULL if 
2ad10 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
2ad20 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63  ion error.** occ
2ad30 75 72 73 2e 20 20 5e 4f 74 68 65 72 77 69 73 65  urs.  ^Otherwise
2ad40 2c 20 74 68 65 79 20 72 65 74 75 72 6e 20 74 68  , they return th
2ad50 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 61 74  e name of the at
2ad60 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 2c  tached database,
2ad70 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f   table,.** or co
2ad80 6c 75 6d 6e 20 74 68 61 74 20 71 75 65 72 79 20  lumn that query 
2ad90 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61  result column wa
2ada0 73 20 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d  s extracted from
2adb0 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69 74 68  ..**.** ^As with
2adc0 20 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69 74   all other SQLit
2add0 65 20 41 50 49 73 2c 20 74 68 6f 73 65 20 77 68  e APIs, those wh
2ade0 6f 73 65 20 6e 61 6d 65 73 20 65 6e 64 20 77 69  ose names end wi
2adf0 74 68 20 22 31 36 22 20 72 65 74 75 72 6e 0a 2a  th "16" return.*
2ae00 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64  * UTF-16 encoded
2ae10 20 73 74 72 69 6e 67 73 20 61 6e 64 20 74 68 65   strings and the
2ae20 20 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 73   other functions
2ae30 20 72 65 74 75 72 6e 20 55 54 46 2d 38 2e 0a 2a   return UTF-8..*
2ae40 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 41 50 49 73  *.** ^These APIs
2ae50 20 61 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61   are only availa
2ae60 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 61  ble if the libra
2ae70 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20  ry was compiled 
2ae80 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  with the.** [SQL
2ae90 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d  ITE_ENABLE_COLUM
2aea0 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 72  N_METADATA] C-pr
2aeb0 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f  eprocessor symbo
2aec0 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20  l..**.** If two 
2aed0 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20  or more threads 
2aee0 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  call one or more
2aef0 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
2af00 65 73 20 61 67 61 69 6e 73 74 20 74 68 65 20 73  es against the s
2af10 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 20  ame.** prepared 
2af20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f  statement and co
2af30 6c 75 6d 6e 20 61 74 20 74 68 65 20 73 61 6d 65  lumn at the same
2af40 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72   time then the r
2af50 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e  esults are.** un
2af60 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  defined..**.** I
2af70 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68  f two or more th
2af80 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f  reads call one o
2af90 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74  r more.** [sqlit
2afa0 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61  e3_column_databa
2afb0 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e  se_name | column
2afc0 20 6d 65 74 61 64 61 74 61 20 69 6e 74 65 72 66   metadata interf
2afd0 61 63 65 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 65  aces].** for the
2afe0 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20   same [prepared 
2aff0 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72  statement] and r
2b000 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  esult column.** 
2b010 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
2b020 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74   then the result
2b030 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
2b040 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  .*/.SQLITE_API c
2b050 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
2b060 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61  e3_column_databa
2b070 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f  se_name(sqlite3_
2b080 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49  stmt*,int);.SQLI
2b090 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69  TE_API const voi
2b0a0 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
2b0b0 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31  n_database_name1
2b0c0 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
2b0d0 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  int);.SQLITE_API
2b0e0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c   const char *sql
2b0f0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c  ite3_column_tabl
2b100 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  e_name(sqlite3_s
2b110 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54  tmt*,int);.SQLIT
2b120 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64  E_API const void
2b130 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2b140 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71  _table_name16(sq
2b150 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
2b160 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  ;.SQLITE_API con
2b170 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
2b180 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e  _column_origin_n
2b190 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
2b1a0 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41  *,int);.SQLITE_A
2b1b0 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  PI const void *s
2b1c0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72  qlite3_column_or
2b1d0 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69  igin_name16(sqli
2b1e0 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
2b1f0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2b200 20 44 65 63 6c 61 72 65 64 20 44 61 74 61 74 79   Declared Dataty
2b210 70 65 20 4f 66 20 41 20 51 75 65 72 79 20 52 65  pe Of A Query Re
2b220 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  sult.**.** ^(The
2b230 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
2b240 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20   is a [prepared 
2b250 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49  statement]..** I
2b260 66 20 74 68 69 73 20 73 74 61 74 65 6d 65 6e 74  f this statement
2b270 20 69 73 20 61 20 5b 53 45 4c 45 43 54 5d 20 73   is a [SELECT] s
2b280 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 68 65  tatement and the
2b290 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74   Nth column of t
2b2a0 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 72  he.** returned r
2b2b0 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68 61  esult set of tha
2b2c0 74 20 5b 53 45 4c 45 43 54 5d 20 69 73 20 61 20  t [SELECT] is a 
2b2d0 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f  table column (no
2b2e0 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69  t an.** expressi
2b2f0 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 29 20  on or subquery) 
2b300 74 68 65 6e 20 74 68 65 20 64 65 63 6c 61 72 65  then the declare
2b310 64 20 74 79 70 65 20 6f 66 20 74 68 65 20 74 61  d type of the ta
2b320 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73  ble.** column is
2b330 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 20 5e 49   returned.)^  ^I
2b340 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  f the Nth column
2b350 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
2b360 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72  et is an.** expr
2b370 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65  ession or subque
2b380 72 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20  ry, then a NULL 
2b390 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72  pointer is retur
2b3a0 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74  ned..** ^The ret
2b3b0 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20  urned string is 
2b3c0 61 6c 77 61 79 73 20 55 54 46 2d 38 20 65 6e 63  always UTF-8 enc
2b3d0 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f  oded..**.** ^(Fo
2b3e0 72 20 65 78 61 6d 70 6c 65 2c 20 67 69 76 65 6e  r example, given
2b3f0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63   the database sc
2b400 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41  hema:.**.** CREA
2b410 54 45 20 54 41 42 4c 45 20 74 31 28 63 31 20 56  TE TABLE t1(c1 V
2b420 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61  ARIANT);.**.** a
2b430 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  nd the following
2b440 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65   statement to be
2b450 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a   compiled:.**.**
2b460 20 53 45 4c 45 43 54 20 63 31 20 2b 20 31 2c 20   SELECT c1 + 1, 
2b470 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a  c1 FROM t1;.**.*
2b480 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  * this routine w
2b490 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20  ould return the 
2b4a0 73 74 72 69 6e 67 20 22 56 41 52 49 41 4e 54 22  string "VARIANT"
2b4b0 20 66 6f 72 20 74 68 65 20 73 65 63 6f 6e 64 20   for the second 
2b4c0 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e  result.** column
2b4d0 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e   (i==1), and a N
2b4e0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20  ULL pointer for 
2b4f0 74 68 65 20 66 69 72 73 74 20 72 65 73 75 6c 74  the first result
2b500 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e 29   column (i==0).)
2b510 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ^.**.** ^SQLite 
2b520 75 73 65 73 20 64 79 6e 61 6d 69 63 20 72 75 6e  uses dynamic run
2b530 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e 20 20 5e  -time typing.  ^
2b540 53 6f 20 6a 75 73 74 20 62 65 63 61 75 73 65 20  So just because 
2b550 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64  a column.** is d
2b560 65 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74 61  eclared to conta
2b570 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  in a particular 
2b580 74 79 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65  type does not me
2b590 61 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 64  an that the.** d
2b5a0 61 74 61 20 73 74 6f 72 65 64 20 69 6e 20 74 68  ata stored in th
2b5b0 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20  at column is of 
2b5c0 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70  the declared typ
2b5d0 65 2e 20 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a  e.  SQLite is.**
2b5e0 20 73 74 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c   strongly typed,
2b5f0 20 62 75 74 20 74 68 65 20 74 79 70 69 6e 67 20   but the typing 
2b600 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73  is dynamic not s
2b610 74 61 74 69 63 2e 20 20 5e 54 79 70 65 0a 2a 2a  tatic.  ^Type.**
2b620 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 20 77   is associated w
2b630 69 74 68 20 69 6e 64 69 76 69 64 75 61 6c 20 76  ith individual v
2b640 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74 68 20  alues, not with 
2b650 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a  the containers.*
2b660 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 74  * used to hold t
2b670 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a  hose values..*/.
2b680 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
2b690 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
2b6a0 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73  olumn_decltype(s
2b6b0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
2b6c0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
2b6d0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
2b6e0 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70  3_column_decltyp
2b6f0 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
2b700 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  *,int);../*.** C
2b710 41 50 49 33 52 45 46 3a 20 45 76 61 6c 75 61 74  API3REF: Evaluat
2b720 65 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65  e An SQL Stateme
2b730 6e 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61  nt.**.** After a
2b740 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2b750 6d 65 6e 74 5d 20 68 61 73 20 62 65 65 6e 20 70  ment] has been p
2b760 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 65 69  repared using ei
2b770 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ther.** [sqlite3
2b780 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
2b790 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
2b7a0 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e  re16_v2()] or on
2b7b0 65 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 0a  e of the legacy.
2b7c0 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73  ** interfaces [s
2b7d0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
2b7e0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ] or [sqlite3_pr
2b7f0 65 70 61 72 65 31 36 28 29 5d 2c 20 74 68 69 73  epare16()], this
2b800 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73   function.** mus
2b810 74 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20  t be called one 
2b820 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f  or more times to
2b830 20 65 76 61 6c 75 61 74 65 20 74 68 65 20 73 74   evaluate the st
2b840 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54  atement..**.** T
2b850 68 65 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68  he details of th
2b860 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68  e behavior of th
2b870 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  e sqlite3_step()
2b880 20 69 6e 74 65 72 66 61 63 65 20 64 65 70 65 6e   interface depen
2b890 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20  d.** on whether 
2b8a0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61  the statement wa
2b8b0 73 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67  s prepared using
2b8c0 20 74 68 65 20 6e 65 77 65 72 20 22 76 32 22 20   the newer "v2" 
2b8d0 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71  interface.** [sq
2b8e0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2b8f0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
2b900 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
2b910 20 6f 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65   or the older le
2b920 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63  gacy.** interfac
2b930 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  e [sqlite3_prepa
2b940 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  re()] and [sqlit
2b950 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e  e3_prepare16()].
2b960 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65    The use of the
2b970 0a 2a 2a 20 6e 65 77 20 22 76 32 22 20 69 6e 74  .** new "v2" int
2b980 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d  erface is recomm
2b990 65 6e 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70  ended for new ap
2b9a0 70 6c 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74  plications but t
2b9b0 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74  he legacy.** int
2b9c0 65 72 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74  erface will cont
2b9d0 69 6e 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f  inue to be suppo
2b9e0 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20  rted..**.** ^In 
2b9f0 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72  the legacy inter
2ba00 66 61 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e  face, the return
2ba10 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65   value will be e
2ba20 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55  ither [SQLITE_BU
2ba30 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  SY],.** [SQLITE_
2ba40 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52  DONE], [SQLITE_R
2ba50 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52  OW], [SQLITE_ERR
2ba60 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  OR], or [SQLITE_
2ba70 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74  MISUSE]..** ^Wit
2ba80 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  h the "v2" inter
2ba90 66 61 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65  face, any of the
2baa0 20 6f 74 68 65 72 20 5b 72 65 73 75 6c 74 20 63   other [result c
2bab0 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74  odes] or.** [ext
2bac0 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
2bad0 65 73 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74  es] might be ret
2bae0 75 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a  urned as well..*
2baf0 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55  *.** ^[SQLITE_BU
2bb00 53 59 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74  SY] means that t
2bb10 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 67 69  he database engi
2bb20 6e 65 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f  ne was unable to
2bb30 20 61 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20   acquire the.** 
2bb40 64 61 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69  database locks i
2bb50 74 20 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74  t needs to do it
2bb60 73 20 6a 6f 62 2e 20 20 5e 49 66 20 74 68 65 20  s job.  ^If the 
2bb70 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b  statement is a [
2bb80 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63  COMMIT].** or oc
2bb90 63 75 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20  curs outside of 
2bba0 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e  an explicit tran
2bbb0 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f  saction, then yo
2bbc0 75 20 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a  u can retry the.
2bbd0 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49  ** statement.  I
2bbe0 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
2bbf0 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54  is not a [COMMIT
2bc00 5d 20 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74  ] and occurs wit
2bc10 68 69 6e 20 61 6e 0a 2a 2a 20 65 78 70 6c 69 63  hin an.** explic
2bc20 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74  it transaction t
2bc30 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 72  hen you should r
2bc40 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 61 6e  ollback the tran
2bc50 73 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a  saction before.*
2bc60 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a  * continuing..**
2bc70 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e  .** ^[SQLITE_DON
2bc80 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  E] means that th
2bc90 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20  e statement has 
2bca0 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69  finished executi
2bcb0 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c  ng.** successful
2bcc0 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65  ly.  sqlite3_ste
2bcd0 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62  p() should not b
2bce0 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f  e called again o
2bcf0 6e 20 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a  n this virtual.*
2bd00 2a 20 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75  * machine withou
2bd10 74 20 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20  t first calling 
2bd20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2bd30 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 76  ] to reset the v
2bd40 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e  irtual.** machin
2bd50 65 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e  e back to its in
2bd60 69 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a  itial state..**.
2bd70 2a 2a 20 5e 49 66 20 74 68 65 20 53 51 4c 20 73  ** ^If the SQL s
2bd80 74 61 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65  tatement being e
2bd90 78 65 63 75 74 65 64 20 72 65 74 75 72 6e 73 20  xecuted returns 
2bda0 61 6e 79 20 64 61 74 61 2c 20 74 68 65 6e 20 5b  any data, then [
2bdb0 53 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69  SQLITE_ROW].** i
2bdc0 73 20 72 65 74 75 72 6e 65 64 20 65 61 63 68 20  s returned each 
2bdd0 74 69 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f  time a new row o
2bde0 66 20 64 61 74 61 20 69 73 20 72 65 61 64 79 20  f data is ready 
2bdf0 66 6f 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62  for processing b
2be00 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e  y the.** caller.
2be10 20 54 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20   The values may 
2be20 62 65 20 61 63 63 65 73 73 65 64 20 75 73 69 6e  be accessed usin
2be30 67 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63  g the [column ac
2be40 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e  cess functions].
2be50 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70  .** sqlite3_step
2be60 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61  () is called aga
2be70 69 6e 20 74 6f 20 72 65 74 72 69 65 76 65 20 74  in to retrieve t
2be80 68 65 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64  he next row of d
2be90 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c  ata..**.** ^[SQL
2bea0 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73  ITE_ERROR] means
2beb0 20 74 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65   that a run-time
2bec0 20 65 72 72 6f 72 20 28 73 75 63 68 20 61 73 20   error (such as 
2bed0 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20  a constraint.** 
2bee0 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f  violation) has o
2bef0 63 63 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65  ccurred.  sqlite
2bf00 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20  3_step() should 
2bf10 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67  not be called ag
2bf20 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d  ain on.** the VM
2bf30 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69  . More informati
2bf40 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20  on may be found 
2bf50 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  by calling [sqli
2bf60 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a  te3_errmsg()]..*
2bf70 2a 20 5e 57 69 74 68 20 74 68 65 20 6c 65 67 61  * ^With the lega
2bf80 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 61 20  cy interface, a 
2bf90 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72  more specific er
2bfa0 72 6f 72 20 63 6f 64 65 20 28 66 6f 72 20 65 78  ror code (for ex
2bfb0 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54  ample,.** [SQLIT
2bfc0 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53  E_INTERRUPT], [S
2bfd0 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b  QLITE_SCHEMA], [
2bfe0 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c  SQLITE_CORRUPT],
2bff0 20 61 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a   and so forth).*
2c000 2a 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65  * can be obtaine
2c010 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71  d by calling [sq
2c020 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
2c030 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  n the.** [prepar
2c040 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20  ed statement].  
2c050 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74  ^In the "v2" int
2c060 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d  erface,.** the m
2c070 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72  ore specific err
2c080 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74 75 72  or code is retur
2c090 6e 65 64 20 64 69 72 65 63 74 6c 79 20 62 79 20  ned directly by 
2c0a0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 0a  sqlite3_step()..
2c0b0 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49  **.** [SQLITE_MI
2c0c0 53 55 53 45 5d 20 6d 65 61 6e 73 20 74 68 61 74  SUSE] means that
2c0d0 20 74 68 65 20 74 68 69 73 20 72 6f 75 74 69 6e   the this routin
2c0e0 65 20 77 61 73 20 63 61 6c 6c 65 64 20 69 6e 61  e was called ina
2c0f0 70 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a  ppropriately..**
2c100 20 50 65 72 68 61 70 73 20 69 74 20 77 61 73 20   Perhaps it was 
2c110 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65  called on a [pre
2c120 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2c130 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72   that has.** alr
2c140 65 61 64 79 20 62 65 65 6e 20 5b 73 71 6c 69 74  eady been [sqlit
2c150 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69  e3_finalize | fi
2c160 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f  nalized] or on o
2c170 6e 65 20 74 68 61 74 20 68 61 64 0a 2a 2a 20 70  ne that had.** p
2c180 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e  reviously return
2c190 65 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ed [SQLITE_ERROR
2c1a0 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  ] or [SQLITE_DON
2c1b0 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c 64  E].  Or it could
2c1c0 0a 2a 2a 20 62 65 20 74 68 65 20 63 61 73 65 20  .** be the case 
2c1d0 74 68 61 74 20 74 68 65 20 73 61 6d 65 20 64 61  that the same da
2c1e0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2c1f0 6e 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 20  n is being used 
2c200 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72  by two or.** mor
2c210 65 20 74 68 72 65 61 64 73 20 61 74 20 74 68 65  e threads at the
2c220 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20   same moment in 
2c230 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20  time..**.** For 
2c240 61 6c 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  all versions of 
2c250 53 51 4c 69 74 65 20 75 70 20 74 6f 20 61 6e 64  SQLite up to and
2c260 20 69 6e 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32   including 3.6.2
2c270 33 2e 31 2c 20 61 20 63 61 6c 6c 20 74 6f 0a 2a  3.1, a call to.*
2c280 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  * [sqlite3_reset
2c290 28 29 5d 20 77 61 73 20 72 65 71 75 69 72 65 64  ()] was required
2c2a0 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 73   after sqlite3_s
2c2b0 74 65 70 28 29 20 72 65 74 75 72 6e 65 64 20 61  tep() returned a
2c2c0 6e 79 74 68 69 6e 67 0a 2a 2a 20 6f 74 68 65 72  nything.** other
2c2d0 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f   than [SQLITE_RO
2c2e0 57 5d 20 62 65 66 6f 72 65 20 61 6e 79 20 73 75  W] before any su
2c2f0 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74  bsequent invocat
2c300 69 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65  ion of.** sqlite
2c310 33 5f 73 74 65 70 28 29 2e 20 20 46 61 69 6c 75  3_step().  Failu
2c320 72 65 20 74 6f 20 72 65 73 65 74 20 74 68 65 20  re to reset the 
2c330 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2c340 6e 74 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71  nt using .** [sq
2c350 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77  lite3_reset()] w
2c360 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61  ould result in a
2c370 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  n [SQLITE_MISUSE
2c380 5d 20 72 65 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a  ] return from.**
2c390 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e   sqlite3_step().
2c3a0 20 20 42 75 74 20 61 66 74 65 72 20 76 65 72 73    But after vers
2c3b0 69 6f 6e 20 33 2e 36 2e 32 33 2e 31 2c 20 73 71  ion 3.6.23.1, sq
2c3c0 6c 69 74 65 33 5f 73 74 65 70 28 29 20 62 65 67  lite3_step() beg
2c3d0 61 6e 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 5b 73  an.** calling [s
2c3e0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
2c3f0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e  automatically in
2c400 20 74 68 69 73 20 63 69 72 63 75 6d 73 74 61 6e   this circumstan
2c410 63 65 20 72 61 74 68 65 72 0a 2a 2a 20 74 68 61  ce rather.** tha
2c420 6e 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c  n returning [SQL
2c430 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 54 68  ITE_MISUSE].  Th
2c440 69 73 20 69 73 20 6e 6f 74 20 63 6f 6e 73 69 64  is is not consid
2c450 65 72 65 64 20 61 20 63 6f 6d 70 61 74 69 62 69  ered a compatibi
2c460 6c 69 74 79 0a 2a 2a 20 62 72 65 61 6b 20 62 65  lity.** break be
2c470 63 61 75 73 65 20 61 6e 79 20 61 70 70 6c 69 63  cause any applic
2c480 61 74 69 6f 6e 20 74 68 61 74 20 65 76 65 72 20  ation that ever 
2c490 72 65 63 65 69 76 65 73 20 61 6e 20 53 51 4c 49  receives an SQLI
2c4a0 54 45 5f 4d 49 53 55 53 45 20 65 72 72 6f 72 0a  TE_MISUSE error.
2c4b0 2a 2a 20 69 73 20 62 72 6f 6b 65 6e 20 62 79 20  ** is broken by 
2c4c0 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 65  definition.  The
2c4d0 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55   [SQLITE_OMIT_AU
2c4e0 54 4f 52 45 53 45 54 5d 20 63 6f 6d 70 69 6c 65  TORESET] compile
2c4f0 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20  -time option.** 
2c500 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72  can be used to r
2c510 65 73 74 6f 72 65 20 74 68 65 20 6c 65 67 61 63  estore the legac
2c520 79 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a  y behavior..**.*
2c530 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72  * <b>Goofy Inter
2c540 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20  face Alert:</b> 
2c550 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e  In the legacy in
2c560 74 65 72 66 61 63 65 2c 20 74 68 65 20 73 71 6c  terface, the sql
2c570 69 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41  ite3_step().** A
2c580 50 49 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  PI always return
2c590 73 20 61 20 67 65 6e 65 72 69 63 20 65 72 72 6f  s a generic erro
2c5a0 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f  r code, [SQLITE_
2c5b0 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e  ERROR], followin
2c5c0 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f  g any.** error o
2c5d0 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
2c5e0 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c  E_BUSY] and [SQL
2c5f0 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f  ITE_MISUSE].  Yo
2c600 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b  u must call.** [
2c610 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2c620 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   or [sqlite3_fin
2c630 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65  alize()] in orde
2c640 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66  r to find one of
2c650 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63   the.** specific
2c660 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 74   [error codes] t
2c670 68 61 74 20 62 65 74 74 65 72 20 64 65 73 63 72  hat better descr
2c680 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2e 0a  ibes the error..
2c690 2a 2a 20 57 65 20 61 64 6d 69 74 20 74 68 61 74  ** We admit that
2c6a0 20 74 68 69 73 20 69 73 20 61 20 67 6f 6f 66 79   this is a goofy
2c6b0 20 64 65 73 69 67 6e 2e 20 20 54 68 65 20 70 72   design.  The pr
2c6c0 6f 62 6c 65 6d 20 68 61 73 20 62 65 65 6e 20 66  oblem has been f
2c6d0 69 78 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65  ixed.** with the
2c6e0 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2e   "v2" interface.
2c6f0 20 20 49 66 20 79 6f 75 20 70 72 65 70 61 72 65    If you prepare
2c700 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c   all of your SQL
2c710 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75   statements.** u
2c720 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c  sing either [sql
2c730 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2c740 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70  )] or [sqlite3_p
2c750 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 69  repare16_v2()] i
2c760 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65  nstead.** of the
2c770 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33   legacy [sqlite3
2c780 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20  _prepare()] and 
2c790 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2c7a0 31 36 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73  16()] interfaces
2c7b0 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f  ,.** then the mo
2c7c0 72 65 20 73 70 65 63 69 66 69 63 20 5b 65 72 72  re specific [err
2c7d0 6f 72 20 63 6f 64 65 73 5d 20 61 72 65 20 72 65  or codes] are re
2c7e0 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 0a  turned directly.
2c7f0 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74  ** by sqlite3_st
2c800 65 70 28 29 2e 20 20 54 68 65 20 75 73 65 20 6f  ep().  The use o
2c810 66 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  f the "v2" inter
2c820 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e  face is recommen
2c830 64 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ded..*/.SQLITE_A
2c840 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  PI int sqlite3_s
2c850 74 65 70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  tep(sqlite3_stmt
2c860 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
2c870 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63  REF: Number of c
2c880 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65 73 75  olumns in a resu
2c890 6c 74 20 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  lt set.**.** ^Th
2c8a0 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63  e sqlite3_data_c
2c8b0 6f 75 6e 74 28 50 29 20 69 6e 74 65 72 66 61 63  ount(P) interfac
2c8c0 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
2c8d0 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
2c8e0 69 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e  in the.** curren
2c8f0 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73  t row of the res
2c900 75 6c 74 20 73 65 74 20 6f 66 20 5b 70 72 65 70  ult set of [prep
2c910 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2c920 50 2e 0a 2a 2a 20 5e 49 66 20 70 72 65 70 61 72  P..** ^If prepar
2c930 65 64 20 73 74 61 74 65 6d 65 6e 74 20 50 20 64  ed statement P d
2c940 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 72 65 73  oes not have res
2c950 75 6c 74 73 20 72 65 61 64 79 20 74 6f 20 72 65  ults ready to re
2c960 74 75 72 6e 0a 2a 2a 20 28 76 69 61 20 63 61 6c  turn.** (via cal
2c970 6c 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  ls to the [sqlit
2c980 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20  e3_column_int | 
2c990 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a  sqlite3_column_*
2c9a0 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66  ()] of.** interf
2c9b0 61 63 65 73 29 20 74 68 65 6e 20 73 71 6c 69 74  aces) then sqlit
2c9c0 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29  e3_data_count(P)
2c9d0 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a 20 5e   returns 0..** ^
2c9e0 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61  The sqlite3_data
2c9f0 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e  _count(P) routin
2ca00 65 20 61 6c 73 6f 20 72 65 74 75 72 6e 73 20 30  e also returns 0
2ca10 20 69 66 20 50 20 69 73 20 61 20 4e 55 4c 4c 20   if P is a NULL 
2ca20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 5e 54 68 65  pointer..** ^The
2ca30 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
2ca40 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20 72  unt(P) routine r
2ca50 65 74 75 72 6e 73 20 30 20 69 66 20 74 68 65 20  eturns 0 if the 
2ca60 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f  previous call to
2ca70 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  .** [sqlite3_ste
2ca80 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64 20 5b  p](P) returned [
2ca90 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 5e  SQLITE_DONE].  ^
2caa0 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61  The sqlite3_data
2cab0 5f 63 6f 75 6e 74 28 50 29 0a 2a 2a 20 77 69 6c  _count(P).** wil
2cac0 6c 20 72 65 74 75 72 6e 20 6e 6f 6e 2d 7a 65 72  l return non-zer
2cad0 6f 20 69 66 20 70 72 65 76 69 6f 75 73 20 63 61  o if previous ca
2cae0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
2caf0 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64  tep](P) returned
2cb00 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  .** [SQLITE_ROW]
2cb10 2c 20 65 78 63 65 70 74 20 69 6e 20 74 68 65 20  , except in the 
2cb20 63 61 73 65 20 6f 66 20 74 68 65 20 5b 50 52 41  case of the [PRA
2cb30 47 4d 41 20 69 6e 63 72 65 6d 65 6e 74 61 6c 5f  GMA incremental_
2cb40 76 61 63 75 75 6d 5d 0a 2a 2a 20 77 68 65 72 65  vacuum].** where
2cb50 20 69 74 20 61 6c 77 61 79 73 20 72 65 74 75 72   it always retur
2cb60 6e 73 20 7a 65 72 6f 20 73 69 6e 63 65 20 65 61  ns zero since ea
2cb70 63 68 20 73 74 65 70 20 6f 66 20 74 68 61 74 20  ch step of that 
2cb80 6d 75 6c 74 69 2d 73 74 65 70 0a 2a 2a 20 70 72  multi-step.** pr
2cb90 61 67 6d 61 20 72 65 74 75 72 6e 73 20 30 20 63  agma returns 0 c
2cba0 6f 6c 75 6d 6e 73 20 6f 66 20 64 61 74 61 2e 0a  olumns of data..
2cbb0 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
2cbc0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2cbd0 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 53 51 4c 49  count()].*/.SQLI
2cbe0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
2cbf0 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 71  e3_data_count(sq
2cc00 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
2cc10 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
2cc20 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c  REF: Fundamental
2cc30 20 44 61 74 61 74 79 70 65 73 0a 2a 2a 20 4b 45   Datatypes.** KE
2cc40 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54  YWORDS: SQLITE_T
2cc50 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72  EXT.**.** ^(Ever
2cc60 79 20 76 61 6c 75 65 20 69 6e 20 53 51 4c 69 74  y value in SQLit
2cc70 65 20 68 61 73 20 6f 6e 65 20 6f 66 20 66 69 76  e has one of fiv
2cc80 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61  e fundamental da
2cc90 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c  tatypes:.**.** <
2cca0 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62  ul>.** <li> 64-b
2ccb0 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65  it signed intege
2ccc0 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74  r.** <li> 64-bit
2ccd0 20 49 45 45 45 20 66 6c 6f 61 74 69 6e 67 20 70   IEEE floating p
2cce0 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c  oint number.** <
2ccf0 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c  li> string.** <l
2cd00 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20  i> BLOB.** <li> 
2cd10 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a  NULL.** </ul>)^.
2cd20 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
2cd30 74 61 6e 74 73 20 61 72 65 20 63 6f 64 65 73 20  tants are codes 
2cd40 66 6f 72 20 65 61 63 68 20 6f 66 20 74 68 6f 73  for each of thos
2cd50 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e  e types..**.** N
2cd60 6f 74 65 20 74 68 61 74 20 74 68 65 20 53 51 4c  ote that the SQL
2cd70 49 54 45 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e  ITE_TEXT constan
2cd80 74 20 77 61 73 20 61 6c 73 6f 20 75 73 65 64 20  t was also used 
2cd90 69 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  in SQLite versio
2cda0 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d  n 2.** for a com
2cdb0 70 6c 65 74 65 6c 79 20 64 69 66 66 65 72 65 6e  pletely differen
2cdc0 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74  t meaning.  Soft
2cdd0 77 61 72 65 20 74 68 61 74 20 6c 69 6e 6b 73 20  ware that links 
2cde0 61 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20  against both.** 
2cdf0 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32  SQLite version 2
2ce00 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73   and SQLite vers
2ce10 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75 73 65  ion 3 should use
2ce20 20 53 51 4c 49 54 45 33 5f 54 45 58 54 2c 20 6e   SQLITE3_TEXT, n
2ce30 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58  ot.** SQLITE_TEX
2ce40 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  T..*/.#define SQ
2ce50 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 20 31 0a  LITE_INTEGER  1.
2ce60 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
2ce70 4c 4f 41 54 20 20 20 20 32 0a 23 64 65 66 69 6e  LOAT    2.#defin
2ce80 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20  e SQLITE_BLOB   
2ce90 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    4.#define SQLI
2cea0 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69  TE_NULL     5.#i
2ceb0 66 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54  fdef SQLITE_TEXT
2cec0 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f  .# undef SQLITE_
2ced0 54 45 58 54 0a 23 65 6c 73 65 0a 23 20 64 65 66  TEXT.#else.# def
2cee0 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20  ine SQLITE_TEXT 
2cef0 20 20 20 20 33 0a 23 65 6e 64 69 66 0a 23 64 65      3.#endif.#de
2cf00 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 54 45 58  fine SQLITE3_TEX
2cf10 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43  T     3../*.** C
2cf20 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20  API3REF: Result 
2cf30 56 61 6c 75 65 73 20 46 72 6f 6d 20 41 20 51 75  Values From A Qu
2cf40 65 72 79 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ery.** KEYWORDS:
2cf50 20 7b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20   {column access 
2cf60 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a  functions}.**.**
2cf70 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
2cf80 66 6f 72 6d 20 74 68 65 20 22 72 65 73 75 6c 74  form the "result
2cf90 20 73 65 74 22 20 69 6e 74 65 72 66 61 63 65 2e   set" interface.
2cfa0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
2cfb0 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 69 6e  utines return in
2cfc0 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20  formation about 
2cfd0 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20  a single column 
2cfe0 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a  of the current.*
2cff0 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 6f 66 20  * result row of 
2d000 61 20 71 75 65 72 79 2e 20 20 5e 49 6e 20 65 76  a query.  ^In ev
2d010 65 72 79 20 63 61 73 65 20 74 68 65 20 66 69 72  ery case the fir
2d020 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  st argument is a
2d030 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74   pointer.** to t
2d040 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
2d050 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 73 20  tement] that is 
2d060 62 65 69 6e 67 20 65 76 61 6c 75 61 74 65 64 20  being evaluated 
2d070 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74  (the [sqlite3_st
2d080 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73  mt*].** that was
2d090 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b   returned from [
2d0a0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2d0b0 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20  v2()] or one of 
2d0c0 69 74 73 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a  its variants).**
2d0d0 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20   and the second 
2d0e0 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
2d0f0 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c  index of the col
2d100 75 6d 6e 20 66 6f 72 20 77 68 69 63 68 20 69 6e  umn for which in
2d110 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f  formation.** sho
2d120 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e  uld be returned.
2d130 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63   ^The leftmost c
2d140 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73  olumn of the res
2d150 75 6c 74 20 73 65 74 20 68 61 73 20 74 68 65 20  ult set has the 
2d160 69 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e 54 68 65  index 0..** ^The
2d170 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
2d180 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74  ns in the result
2d190 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e   can be determin
2d1a0 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  ed using.** [sql
2d1b0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e  ite3_column_coun
2d1c0 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  t()]..**.** If t
2d1d0 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
2d1e0 20 64 6f 65 73 20 6e 6f 74 20 63 75 72 72 65 6e   does not curren
2d1f0 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61 20 76  tly point to a v
2d200 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69 66 20  alid row, or if 
2d210 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e  the.** column in
2d220 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61  dex is out of ra
2d230 6e 67 65 2c 20 74 68 65 20 72 65 73 75 6c 74 20  nge, the result 
2d240 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
2d250 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
2d260 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c  may only be call
2d270 65 64 20 77 68 65 6e 20 74 68 65 20 6d 6f 73 74  ed when the most
2d280 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a   recent call to.
2d290 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
2d2a0 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64  ()] has returned
2d2b0 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e   [SQLITE_ROW] an
2d2c0 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71  d neither.** [sq
2d2d0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6e  lite3_reset()] n
2d2e0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  or [sqlite3_fina
2d2f0 6c 69 7a 65 28 29 5d 20 68 61 76 65 20 62 65 65  lize()] have bee
2d300 6e 20 63 61 6c 6c 65 64 20 73 75 62 73 65 71 75  n called subsequ
2d310 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79  ently..** If any
2d320 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
2d330 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 61 66  es are called af
2d340 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ter [sqlite3_res
2d350 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  et()] or.** [sql
2d360 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
2d370 20 6f 72 20 61 66 74 65 72 20 5b 73 71 6c 69 74   or after [sqlit
2d380 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72  e3_step()] has r
2d390 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74  eturned.** somet
2d3a0 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20  hing other than 
2d3b0 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68  [SQLITE_ROW], th
2d3c0 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
2d3d0 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b  defined..** If [
2d3e0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2d3f0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  or [sqlite3_rese
2d400 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  t()] or [sqlite3
2d410 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20  _finalize()].** 
2d420 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20  are called from 
2d430 61 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65  a different thre
2d440 61 64 20 77 68 69 6c 65 20 61 6e 79 20 6f 66 20  ad while any of 
2d450 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a  these routines.*
2d460 2a 20 61 72 65 20 70 65 6e 64 69 6e 67 2c 20 74  * are pending, t
2d470 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20  hen the results 
2d480 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
2d490 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2d4a0 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20  3_column_type() 
2d4b0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
2d4c0 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49  the.** [SQLITE_I
2d4d0 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70  NTEGER | datatyp
2d4e0 65 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20  e code] for the 
2d4f0 69 6e 69 74 69 61 6c 20 64 61 74 61 20 74 79 70  initial data typ
2d500 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75  e.** of the resu
2d510 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65  lt column.  ^The
2d520 20 72 65 74 75 72 6e 65 64 20 76 61 6c 75 65 20   returned value 
2d530 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  is one of [SQLIT
2d540 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b  E_INTEGER],.** [
2d550 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b  SQLITE_FLOAT], [
2d560 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53  SQLITE_TEXT], [S
2d570 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20  QLITE_BLOB], or 
2d580 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20  [SQLITE_NULL].  
2d590 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74  The value.** ret
2d5a0 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
2d5b0 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69  _column_type() i
2d5c0 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75  s only meaningfu
2d5d0 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20  l if no type.** 
2d5e0 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61 76 65  conversions have
2d5f0 20 6f 63 63 75 72 72 65 64 20 61 73 20 64 65 73   occurred as des
2d600 63 72 69 62 65 64 20 62 65 6c 6f 77 2e 20 20 41  cribed below.  A
2d610 66 74 65 72 20 61 20 74 79 70 65 20 63 6f 6e 76  fter a type conv
2d620 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76  ersion,.** the v
2d630 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
2d640 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2d650 74 79 70 65 28 29 20 69 73 20 75 6e 64 65 66 69  type() is undefi
2d660 6e 65 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20  ned.  Future.** 
2d670 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
2d680 74 65 20 6d 61 79 20 63 68 61 6e 67 65 20 74 68  te may change th
2d690 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71  e behavior of sq
2d6a0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
2d6b0 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67  e().** following
2d6c0 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69   a type conversi
2d6d0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  on..**.** ^If th
2d6e0 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c  e result is a BL
2d6f0 4f 42 20 6f 72 20 55 54 46 2d 38 20 73 74 72 69  OB or UTF-8 stri
2d700 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69  ng then the sqli
2d710 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2d720 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65  ().** routine re
2d730 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
2d740 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61   of bytes in tha
2d750 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67  t BLOB or string
2d760 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
2d770 75 6c 74 20 69 73 20 61 20 55 54 46 2d 31 36 20  ult is a UTF-16 
2d780 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c  string, then sql
2d790 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2d7a0 73 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20  s() converts.** 
2d7b0 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54  the string to UT
2d7c0 46 2d 38 20 61 6e 64 20 74 68 65 6e 20 72 65 74  F-8 and then ret
2d7d0 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
2d7e0 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66  of bytes..** ^If
2d7f0 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
2d800 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74   numeric value t
2d810 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
2d820 6d 6e 5f 62 79 74 65 73 28 29 20 75 73 65 73 0a  mn_bytes() uses.
2d830 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72  ** [sqlite3_snpr
2d840 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65  intf()] to conve
2d850 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f  rt that value to
2d860 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20   a UTF-8 string 
2d870 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74  and returns.** t
2d880 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
2d890 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e  es in that strin
2d8a0 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  g..** ^If the re
2d8b0 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68  sult is NULL, th
2d8c0 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
2d8d0 6e 5f 62 79 74 65 73 28 29 20 72 65 74 75 72 6e  n_bytes() return
2d8e0 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49  s zero..**.** ^I
2d8f0 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
2d900 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 31 36  a BLOB or UTF-16
2d910 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65   string then the
2d920 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2d930 62 79 74 65 73 31 36 28 29 0a 2a 2a 20 72 6f 75  bytes16().** rou
2d940 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
2d950 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
2d960 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72   in that BLOB or
2d970 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20   string..** ^If 
2d980 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
2d990 55 54 46 2d 38 20 73 74 72 69 6e 67 2c 20 74 68  UTF-8 string, th
2d9a0 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
2d9b0 6e 5f 62 79 74 65 73 31 36 28 29 20 63 6f 6e 76  n_bytes16() conv
2d9c0 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69  erts.** the stri
2d9d0 6e 67 20 74 6f 20 55 54 46 2d 31 36 20 61 6e 64  ng to UTF-16 and
2d9e0 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68   then returns th
2d9f0 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
2da00 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  s..** ^If the re
2da10 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69  sult is a numeri
2da20 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c  c value then sql
2da30 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2da40 73 31 36 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73  s16() uses.** [s
2da50 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
2da60 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68  )] to convert th
2da70 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54  at value to a UT
2da80 46 2d 31 36 20 73 74 72 69 6e 67 20 61 6e 64 20  F-16 string and 
2da90 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e  returns.** the n
2daa0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
2dab0 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a  n that string..*
2dac0 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
2dad0 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73   is NULL, then s
2dae0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2daf0 74 65 73 31 36 28 29 20 72 65 74 75 72 6e 73 20  tes16() returns 
2db00 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  zero..**.** ^The
2db10 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64   values returned
2db20 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   by [sqlite3_col
2db30 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64  umn_bytes()] and
2db40 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f   .** [sqlite3_co
2db50 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20  lumn_bytes16()] 
2db60 64 6f 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74  do not include t
2db70 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  he zero terminat
2db80 6f 72 73 20 61 74 20 74 68 65 20 65 6e 64 0a 2a  ors at the end.*
2db90 2a 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 2e  * of the string.
2dba0 20 20 5e 46 6f 72 20 63 6c 61 72 69 74 79 3a 20    ^For clarity: 
2dbb0 74 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72  the values retur
2dbc0 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74  ned by.** [sqlit
2dbd0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2dbe0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
2dbf0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
2dc00 5d 20 61 72 65 20 74 68 65 20 6e 75 6d 62 65 72  ] are the number
2dc10 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20   of.** bytes in 
2dc20 74 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20  the string, not 
2dc30 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  the number of ch
2dc40 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  aracters..**.** 
2dc50 5e 53 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65  ^Strings returne
2dc60 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
2dc70 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64 20 73  umn_text() and s
2dc80 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2dc90 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20  xt16(),.** even 
2dca0 65 6d 70 74 79 20 73 74 72 69 6e 67 73 2c 20 61  empty strings, a
2dcb0 72 65 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74  re always zero-t
2dcc0 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65  erminated.  ^The
2dcd0 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65   return.** value
2dce0 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f   from sqlite3_co
2dcf0 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20  lumn_blob() for 
2dd00 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c  a zero-length BL
2dd10 4f 42 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  OB is a NULL poi
2dd20 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  nter..**.** ^The
2dd30 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64   object returned
2dd40 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   by [sqlite3_col
2dd50 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20  umn_value()] is 
2dd60 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74  an.** [unprotect
2dd70 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2dd80 5d 20 6f 62 6a 65 63 74 2e 20 20 41 6e 20 75 6e  ] object.  An un
2dd90 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2dda0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 0a 2a  3_value object.*
2ddb0 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73  * may only be us
2ddc0 65 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33  ed with [sqlite3
2ddd0 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 20 61  _bind_value()] a
2dde0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  nd [sqlite3_resu
2ddf0 6c 74 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20  lt_value()]..** 
2de00 49 66 20 74 68 65 20 5b 75 6e 70 72 6f 74 65 63  If the [unprotec
2de10 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2de20 65 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  e] object return
2de30 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65  ed by.** [sqlite
2de40 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29  3_column_value()
2de50 5d 20 69 73 20 75 73 65 64 20 69 6e 20 61 6e 79  ] is used in any
2de60 20 6f 74 68 65 72 20 77 61 79 2c 20 69 6e 63 6c   other way, incl
2de70 75 64 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 74  uding calls.** t
2de80 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20  o routines like 
2de90 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69  [sqlite3_value_i
2dea0 6e 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  nt()], [sqlite3_
2deb0 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a  value_text()],.*
2dec0 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61  * or [sqlite3_va
2ded0 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 74 68  lue_bytes()], th
2dee0 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
2def0 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
2df00 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
2df10 65 73 20 61 74 74 65 6d 70 74 20 74 6f 20 63 6f  es attempt to co
2df20 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 20  nvert the value 
2df30 77 68 65 72 65 20 61 70 70 72 6f 70 72 69 61 74  where appropriat
2df40 65 2e 20 20 5e 46 6f 72 0a 2a 2a 20 65 78 61 6d  e.  ^For.** exam
2df50 70 6c 65 2c 20 69 66 20 74 68 65 20 69 6e 74 65  ple, if the inte
2df60 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74  rnal representat
2df70 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e 64  ion is FLOAT and
2df80 20 61 20 74 65 78 74 20 72 65 73 75 6c 74 0a 2a   a text result.*
2df90 2a 20 69 73 20 72 65 71 75 65 73 74 65 64 2c 20  * is requested, 
2dfa0 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  [sqlite3_snprint
2dfb0 66 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 74  f()] is used int
2dfc0 65 72 6e 61 6c 6c 79 20 74 6f 20 70 65 72 66 6f  ernally to perfo
2dfd0 72 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e 76 65 72  rm the.** conver
2dfe0 73 69 6f 6e 20 61 75 74 6f 6d 61 74 69 63 61 6c  sion automatical
2dff0 6c 79 2e 20 20 5e 28 54 68 65 20 66 6f 6c 6c 6f  ly.  ^(The follo
2e000 77 69 6e 67 20 74 61 62 6c 65 20 64 65 74 61 69  wing table detai
2e010 6c 73 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f  ls the conversio
2e020 6e 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 61  ns.** that are a
2e030 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62  pplied:.**.** <b
2e040 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74  lockquote>.** <t
2e050 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e  able border="1">
2e060 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74  .** <tr><th> Int
2e070 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74  ernal<br>Type <t
2e080 68 3e 20 52 65 71 75 65 73 74 65 64 3c 62 72 3e  h> Requested<br>
2e090 54 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65  Type <th>  Conve
2e0a0 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e  rsion.**.** <tr>
2e0b0 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74  <td>  NULL    <t
2e0c0 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64  d> INTEGER   <td
2e0d0 3e 20 52 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a  > Result is 0.**
2e0e0 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20   <tr><td>  NULL 
2e0f0 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20     <td>  FLOAT  
2e100 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73    <td> Result is
2e110 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e   0.0.** <tr><td>
2e120 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20    NULL    <td>  
2e130 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 52 65   TEXT    <td> Re
2e140 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69  sult is NULL poi
2e150 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  nter.** <tr><td>
2e160 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20    NULL    <td>  
2e170 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52 65   BLOB    <td> Re
2e180 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69  sult is NULL poi
2e190 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  nter.** <tr><td>
2e1a0 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20   INTEGER  <td>  
2e1b0 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f  FLOAT    <td> Co
2e1c0 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e 74 65 67  nvert from integ
2e1d0 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c  er to float.** <
2e1e0 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20  tr><td> INTEGER 
2e1f0 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
2e200 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65  <td> ASCII rende
2e210 72 69 6e 67 20 6f 66 20 74 68 65 20 69 6e 74 65  ring of the inte
2e220 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ger.** <tr><td> 
2e230 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20  INTEGER  <td>   
2e240 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d  BLOB    <td> Sam
2e250 65 20 61 73 20 49 4e 54 45 47 45 52 2d 3e 54 45  e as INTEGER->TE
2e260 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  XT.** <tr><td>  
2e270 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e 54  FLOAT   <td> INT
2e280 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76  EGER   <td> Conv
2e290 65 72 74 20 66 72 6f 6d 20 66 6c 6f 61 74 20 74  ert from float t
2e2a0 6f 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72  o integer.** <tr
2e2b0 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c  ><td>  FLOAT   <
2e2c0 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
2e2d0 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69  d> ASCII renderi
2e2e0 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a  ng of the float.
2e2f0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f  ** <tr><td>  FLO
2e300 41 54 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42  AT   <td>   BLOB
2e310 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73      <td> Same as
2e320 20 46 4c 4f 41 54 2d 3e 54 45 58 54 0a 2a 2a 20   FLOAT->TEXT.** 
2e330 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20  <tr><td>  TEXT  
2e340 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20    <td> INTEGER  
2e350 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 69 28 29   <td> Use atoi()
2e360 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45  .** <tr><td>  TE
2e370 58 54 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41  XT    <td>  FLOA
2e380 54 20 20 20 20 3c 74 64 3e 20 55 73 65 20 61 74  T    <td> Use at
2e390 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  of().** <tr><td>
2e3a0 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20    TEXT    <td>  
2e3b0 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f   BLOB    <td> No
2e3c0 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c   change.** <tr><
2e3d0 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  td>  BLOB    <td
2e3e0 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e  > INTEGER   <td>
2e3f0 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 54   Convert to TEXT
2e400 20 74 68 65 6e 20 75 73 65 20 61 74 6f 69 28 29   then use atoi()
2e410 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c  .** <tr><td>  BL
2e420 4f 42 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41  OB    <td>  FLOA
2e430 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72  T    <td> Conver
2e440 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20 75  t to TEXT then u
2e450 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72  se atof().** <tr
2e460 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c  ><td>  BLOB    <
2e470 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
2e480 64 3e 20 41 64 64 20 61 20 7a 65 72 6f 20 74 65  d> Add a zero te
2e490 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65 65 64  rminator if need
2e4a0 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a  ed.** </table>.*
2e4b0 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29  * </blockquote>)
2e4c0 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c  ^.**.** The tabl
2e4d0 65 20 61 62 6f 76 65 20 6d 61 6b 65 73 20 72 65  e above makes re
2e4e0 66 65 72 65 6e 63 65 20 74 6f 20 73 74 61 6e 64  ference to stand
2e4f0 61 72 64 20 43 20 6c 69 62 72 61 72 79 20 66 75  ard C library fu
2e500 6e 63 74 69 6f 6e 73 20 61 74 6f 69 28 29 0a 2a  nctions atoi().*
2e510 2a 20 61 6e 64 20 61 74 6f 66 28 29 2e 20 20 53  * and atof().  S
2e520 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f 74 20 72  QLite does not r
2e530 65 61 6c 6c 79 20 75 73 65 20 74 68 65 73 65 20  eally use these 
2e540 66 75 6e 63 74 69 6f 6e 73 2e 20 20 49 74 20 68  functions.  It h
2e550 61 73 20 69 74 73 0a 2a 2a 20 6f 77 6e 20 65 71  as its.** own eq
2e560 75 69 76 61 6c 65 6e 74 20 69 6e 74 65 72 6e 61  uivalent interna
2e570 6c 20 72 6f 75 74 69 6e 65 73 2e 20 20 54 68 65  l routines.  The
2e580 20 61 74 6f 69 28 29 20 61 6e 64 20 61 74 6f 66   atoi() and atof
2e590 28 29 20 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20  () names are.** 
2e5a0 75 73 65 64 20 69 6e 20 74 68 65 20 74 61 62 6c  used in the tabl
2e5b0 65 20 66 6f 72 20 62 72 65 76 69 74 79 20 61 6e  e for brevity an
2e5c0 64 20 62 65 63 61 75 73 65 20 74 68 65 79 20 61  d because they a
2e5d0 72 65 20 66 61 6d 69 6c 69 61 72 20 74 6f 20 6d  re familiar to m
2e5e0 6f 73 74 0a 2a 2a 20 43 20 70 72 6f 67 72 61 6d  ost.** C program
2e5f0 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  mers..**.** Note
2e600 20 74 68 61 74 20 77 68 65 6e 20 74 79 70 65 20   that when type 
2e610 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63 75  conversions occu
2e620 72 2c 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75  r, pointers retu
2e630 72 6e 65 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a  rned by prior.**
2e640 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
2e650 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c  3_column_blob(),
2e660 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2e670 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a  text(), and/or.*
2e680 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
2e690 5f 74 65 78 74 31 36 28 29 20 6d 61 79 20 62 65  _text16() may be
2e6a0 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a   invalidated..**
2e6b0 20 54 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   Type conversion
2e6c0 73 20 61 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e  s and pointer in
2e6d0 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67 68  validations migh
2e6e0 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68  t occur.** in th
2e6f0 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65  e following case
2e700 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
2e710 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61   <li> The initia
2e720 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 61 20 42  l content is a B
2e730 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  LOB and sqlite3_
2e740 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72  column_text() or
2e750 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33  .**      sqlite3
2e760 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
2e770 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a   is called.  A z
2e780 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d  ero-terminator m
2e790 69 67 68 74 0a 2a 2a 20 20 20 20 20 20 6e 65 65  ight.**      nee
2e7a0 64 20 74 6f 20 62 65 20 61 64 64 65 64 20 74 6f  d to be added to
2e7b0 20 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f 6c 69   the string.</li
2e7c0 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e  >.** <li> The in
2e7d0 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73  itial content is
2e7e0 20 55 54 46 2d 38 20 74 65 78 74 20 61 6e 64 20   UTF-8 text and 
2e7f0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2e800 79 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20  ytes16() or.**  
2e810 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75      sqlite3_colu
2e820 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63  mn_text16() is c
2e830 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74  alled.  The cont
2e840 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76  ent must be conv
2e850 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f  erted.**      to
2e860 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a   UTF-16.</li>.**
2e870 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61   <li> The initia
2e880 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46  l content is UTF
2e890 2d 31 36 20 74 65 78 74 20 61 6e 64 20 73 71 6c  -16 text and sql
2e8a0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2e8b0 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73  s() or.**      s
2e8c0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2e8d0 78 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20  xt() is called. 
2e8e0 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73   The content mus
2e8f0 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a  t be converted.*
2e900 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d 38 2e  *      to UTF-8.
2e910 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  </li>.** </ul>.*
2e920 2a 0a 2a 2a 20 5e 43 6f 6e 76 65 72 73 69 6f 6e  *.** ^Conversion
2e930 73 20 62 65 74 77 65 65 6e 20 55 54 46 2d 31 36  s between UTF-16
2e940 62 65 20 61 6e 64 20 55 54 46 2d 31 36 6c 65 20  be and UTF-16le 
2e950 61 72 65 20 61 6c 77 61 79 73 20 64 6f 6e 65 20  are always done 
2e960 69 6e 20 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a  in place and do.
2e970 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74  ** not invalidat
2e980 65 20 61 20 70 72 69 6f 72 20 70 6f 69 6e 74 65  e a prior pointe
2e990 72 2c 20 74 68 6f 75 67 68 20 6f 66 20 63 6f 75  r, though of cou
2e9a0 72 73 65 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  rse the content 
2e9b0 6f 66 20 74 68 65 20 62 75 66 66 65 72 0a 2a 2a  of the buffer.**
2e9c0 20 74 68 61 74 20 74 68 65 20 70 72 69 6f 72 20   that the prior 
2e9d0 70 6f 69 6e 74 65 72 20 72 65 66 65 72 65 6e 63  pointer referenc
2e9e0 65 73 20 77 69 6c 6c 20 68 61 76 65 20 62 65 65  es will have bee
2e9f0 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74 68  n modified.  Oth
2ea00 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63  er kinds.** of c
2ea10 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65 20 64 6f  onversion are do
2ea20 6e 65 20 69 6e 20 70 6c 61 63 65 20 77 68 65 6e  ne in place when
2ea30 20 69 74 20 69 73 20 70 6f 73 73 69 62 6c 65 2c   it is possible,
2ea40 20 62 75 74 20 73 6f 6d 65 74 69 6d 65 73 20 74   but sometimes t
2ea50 68 65 79 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 70  hey.** are not p
2ea60 6f 73 73 69 62 6c 65 20 61 6e 64 20 69 6e 20 74  ossible and in t
2ea70 68 6f 73 65 20 63 61 73 65 73 20 70 72 69 6f 72  hose cases prior
2ea80 20 70 6f 69 6e 74 65 72 73 20 61 72 65 20 69 6e   pointers are in
2ea90 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a  validated..**.**
2eaa0 20 54 68 65 20 73 61 66 65 73 74 20 61 6e 64 20   The safest and 
2eab0 65 61 73 69 65 73 74 20 74 6f 20 72 65 6d 65 6d  easiest to remem
2eac0 62 65 72 20 70 6f 6c 69 63 79 20 69 73 20 74 6f  ber policy is to
2ead0 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 20 72 6f   invoke these ro
2eae0 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65  utines.** in one
2eaf0 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   of the followin
2eb00 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  g ways:.**.** <u
2eb10 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74  l>.**  <li>sqlit
2eb20 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
2eb30 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c   followed by sql
2eb40 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2eb50 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69  s()</li>.**  <li
2eb60 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  >sqlite3_column_
2eb70 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20  blob() followed 
2eb80 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
2eb90 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a  n_bytes()</li>.*
2eba0 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63  *  <li>sqlite3_c
2ebb0 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66  olumn_text16() f
2ebc0 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74  ollowed by sqlit
2ebd0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
2ebe0 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c  6()</li>.** </ul
2ebf0 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72  >.**.** In other
2ec00 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f 75   words, you shou
2ec10 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f  ld call sqlite3_
2ec20 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a  column_text(),.*
2ec30 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
2ec40 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c 69  _blob(), or sqli
2ec50 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
2ec60 36 28 29 20 66 69 72 73 74 20 74 6f 20 66 6f 72  6() first to for
2ec70 63 65 20 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a  ce the result.**
2ec80 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69 72 65   into the desire
2ec90 64 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69  d format, then i
2eca0 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f  nvoke sqlite3_co
2ecb0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a  lumn_bytes() or.
2ecc0 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
2ecd0 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f 20 66  n_bytes16() to f
2ece0 69 6e 64 20 74 68 65 20 73 69 7a 65 20 6f 66 20  ind the size of 
2ecf0 74 68 65 20 72 65 73 75 6c 74 2e 20 20 44 6f 20  the result.  Do 
2ed00 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a  not mix calls.**
2ed10 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
2ed20 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c  mn_text() or sql
2ed30 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
2ed40 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f  () with calls to
2ed50 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
2ed60 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c 20 61 6e  mn_bytes16(), an
2ed70 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c  d do not mix cal
2ed80 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ls to sqlite3_co
2ed90 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a  lumn_text16().**
2eda0 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 20 73   with calls to s
2edb0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2edc0 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  tes()..**.** ^Th
2edd0 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72  e pointers retur
2ede0 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20 75 6e  ned are valid un
2edf0 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e 76 65  til a type conve
2ee00 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a  rsion occurs as.
2ee10 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61 62 6f  ** described abo
2ee20 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71  ve, or until [sq
2ee30 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72  lite3_step()] or
2ee40 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2ee50 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
2ee60 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73  3_finalize()] is
2ee70 20 63 61 6c 6c 65 64 2e 20 20 5e 54 68 65 20 6d   called.  ^The m
2ee80 65 6d 6f 72 79 20 73 70 61 63 65 20 75 73 65 64  emory space used
2ee90 20 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67 73   to hold strings
2eea0 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69 73  .** and BLOBs is
2eeb0 20 66 72 65 65 64 20 61 75 74 6f 6d 61 74 69 63   freed automatic
2eec0 61 6c 6c 79 2e 20 20 44 6f 20 3c 62 3e 6e 6f 74  ally.  Do <b>not
2eed0 3c 2f 62 3e 20 70 61 73 73 20 74 68 65 20 70 6f  </b> pass the po
2eee0 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 0a  inters returned.
2eef0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
2ef00 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c  mn_blob()], [sql
2ef10 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2ef20 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 0a 2a  ()], etc. into.*
2ef30 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  * [sqlite3_free(
2ef40 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61  )]..**.** ^(If a
2ef50 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
2ef60 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  on error occurs 
2ef70 64 75 72 69 6e 67 20 74 68 65 20 65 76 61 6c 75  during the evalu
2ef80 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20  ation of any.** 
2ef90 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
2efa0 73 2c 20 61 20 64 65 66 61 75 6c 74 20 76 61 6c  s, a default val
2efb0 75 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  ue is returned. 
2efc0 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c   The default val
2efd0 75 65 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20  ue.** is either 
2efe0 74 68 65 20 69 6e 74 65 67 65 72 20 30 2c 20 74  the integer 0, t
2eff0 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  he floating poin
2f000 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72  t number 0.0, or
2f010 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74   a NULL.** point
2f020 65 72 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20  er.  Subsequent 
2f030 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
2f040 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 77 69 6c  3_errcode()] wil
2f050 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c  l return.** [SQL
2f060 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f  ITE_NOMEM].)^.*/
2f070 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
2f080 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
2f090 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69  column_blob(sqli
2f0a0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
2f0b0 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  Col);.SQLITE_API
2f0c0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c   int sqlite3_col
2f0d0 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 74 65  umn_bytes(sqlite
2f0e0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
2f0f0 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  l);.SQLITE_API i
2f100 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
2f110 6e 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65  n_bytes16(sqlite
2f120 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
2f130 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 64  l);.SQLITE_API d
2f140 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f  ouble sqlite3_co
2f150 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69  lumn_double(sqli
2f160 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
2f170 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  Col);.SQLITE_API
2f180 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c   int sqlite3_col
2f190 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f  umn_int(sqlite3_
2f1a0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
2f1b0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c  ;.SQLITE_API sql
2f1c0 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
2f1d0 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28  e3_column_int64(
2f1e0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2f1f0 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45  nt iCol);.SQLITE
2f200 5f 41 50 49 20 63 6f 6e 73 74 20 75 6e 73 69 67  _API const unsig
2f210 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65  ned char *sqlite
2f220 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71  3_column_text(sq
2f230 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2f240 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41   iCol);.SQLITE_A
2f250 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  PI const void *s
2f260 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2f270 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  xt16(sqlite3_stm
2f280 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53  t*, int iCol);.S
2f290 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
2f2a0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
2f2b0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
2f2c0 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49   int iCol);.SQLI
2f2d0 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 76  TE_API sqlite3_v
2f2e0 61 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f 63 6f  alue *sqlite3_co
2f2f0 6c 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74  lumn_value(sqlit
2f300 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
2f310 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ol);../*.** CAPI
2f320 33 52 45 46 3a 20 44 65 73 74 72 6f 79 20 41 20  3REF: Destroy A 
2f330 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
2f340 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20  nt Object.**.** 
2f350 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e  ^The sqlite3_fin
2f360 61 6c 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e  alize() function
2f370 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 64 65   is called to de
2f380 6c 65 74 65 20 61 20 5b 70 72 65 70 61 72 65 64  lete a [prepared
2f390 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20   statement]..** 
2f3a0 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63  ^If the most rec
2f3b0 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f  ent evaluation o
2f3c0 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
2f3d0 65 6e 63 6f 75 6e 74 65 72 65 64 20 6e 6f 20 65  encountered no e
2f3e0 72 72 6f 72 73 0a 2a 2a 20 6f 72 20 69 66 20 74  rrors.** or if t
2f3f0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
2f400 6e 65 76 65 72 20 62 65 65 6e 20 65 76 61 6c 75  never been evalu
2f410 61 74 65 64 2c 20 74 68 65 6e 20 73 71 6c 69 74  ated, then sqlit
2f420 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 72 65  e3_finalize() re
2f430 74 75 72 6e 73 0a 2a 2a 20 53 51 4c 49 54 45 5f  turns.** SQLITE_
2f440 4f 4b 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 73  OK.  ^If the mos
2f450 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74  t recent evaluat
2f460 69 6f 6e 20 6f 66 20 73 74 61 74 65 6d 65 6e 74  ion of statement
2f470 20 53 20 66 61 69 6c 65 64 2c 20 74 68 65 6e 0a   S failed, then.
2f480 2a 2a 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  ** sqlite3_final
2f490 69 7a 65 28 53 29 20 72 65 74 75 72 6e 73 20 74  ize(S) returns t
2f4a0 68 65 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b  he appropriate [
2f4b0 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 0a 2a  error code] or.*
2f4c0 2a 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f  * [extended erro
2f4d0 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  r code]..**.** ^
2f4e0 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  The sqlite3_fina
2f4f0 6c 69 7a 65 28 53 29 20 72 6f 75 74 69 6e 65 20  lize(S) routine 
2f500 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 74  can be called at
2f510 20 61 6e 79 20 70 6f 69 6e 74 20 64 75 72 69 6e   any point durin
2f520 67 0a 2a 2a 20 74 68 65 20 6c 69 66 65 20 63 79  g.** the life cy
2f530 63 6c 65 20 6f 66 20 5b 70 72 65 70 61 72 65 64  cle of [prepared
2f540 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 3a 0a 2a   statement] S:.*
2f550 2a 20 62 65 66 6f 72 65 20 73 74 61 74 65 6d 65  * before stateme
2f560 6e 74 20 53 20 69 73 20 65 76 65 72 20 65 76 61  nt S is ever eva
2f570 6c 75 61 74 65 64 2c 20 61 66 74 65 72 0a 2a 2a  luated, after.**
2f580 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 63 61 6c   one or more cal
2f590 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  ls to [sqlite3_r
2f5a0 65 73 65 74 28 29 5d 2c 20 6f 72 20 61 66 74 65  eset()], or afte
2f5b0 72 20 61 6e 79 20 63 61 6c 6c 0a 2a 2a 20 74 6f  r any call.** to
2f5c0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2f5d0 5d 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20  ] regardless of 
2f5e0 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
2f5f0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73  he statement has
2f600 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65 78  .** completed ex
2f610 65 63 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  ecution..**.** ^
2f620 49 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33  Invoking sqlite3
2f630 5f 66 69 6e 61 6c 69 7a 65 28 29 20 6f 6e 20 61  _finalize() on a
2f640 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73   NULL pointer is
2f650 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f   a harmless no-o
2f660 70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70  p..**.** The app
2f670 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 66 69  lication must fi
2f680 6e 61 6c 69 7a 65 20 65 76 65 72 79 20 5b 70 72  nalize every [pr
2f690 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2f6a0 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 61 76  ] in order to av
2f6b0 6f 69 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 20  oid.** resource 
2f6c0 6c 65 61 6b 73 2e 20 20 49 74 20 69 73 20 61 20  leaks.  It is a 
2f6d0 67 72 69 65 76 6f 75 73 20 65 72 72 6f 72 20 66  grievous error f
2f6e0 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  or the applicati
2f6f0 6f 6e 20 74 6f 20 74 72 79 20 74 6f 20 75 73 65  on to try to use
2f700 0a 2a 2a 20 61 20 70 72 65 70 61 72 65 64 20 73  .** a prepared s
2f710 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69  tatement after i
2f720 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c  t has been final
2f730 69 7a 65 64 2e 20 20 41 6e 79 20 75 73 65 20 6f  ized.  Any use o
2f740 66 20 61 20 70 72 65 70 61 72 65 64 0a 2a 2a 20  f a prepared.** 
2f750 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20  statement after 
2f760 69 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61  it has been fina
2f770 6c 69 7a 65 64 20 63 61 6e 20 72 65 73 75 6c 74  lized can result
2f780 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 61 6e   in undefined an
2f790 64 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65  d.** undesirable
2f7a0 20 62 65 68 61 76 69 6f 72 20 73 75 63 68 20 61   behavior such a
2f7b0 73 20 73 65 67 66 61 75 6c 74 73 20 61 6e 64 20  s segfaults and 
2f7c0 68 65 61 70 20 63 6f 72 72 75 70 74 69 6f 6e 2e  heap corruption.
2f7d0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
2f7e0 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  nt sqlite3_final
2f7f0 69 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ize(sqlite3_stmt
2f800 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
2f810 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74   CAPI3REF: Reset
2f820 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74   A Prepared Stat
2f830 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a  ement Object.**.
2f840 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
2f850 65 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20  eset() function 
2f860 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73  is called to res
2f870 65 74 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  et a [prepared s
2f880 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a  tatement].** obj
2f890 65 63 74 20 62 61 63 6b 20 74 6f 20 69 74 73 20  ect back to its 
2f8a0 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72  initial state, r
2f8b0 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78  eady to be re-ex
2f8c0 65 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20  ecuted..** ^Any 
2f8d0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61  SQL statement va
2f8e0 72 69 61 62 6c 65 73 20 74 68 61 74 20 68 61 64  riables that had
2f8f0 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f   values bound to
2f900 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74   them using.** t
2f910 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  he [sqlite3_bind
2f920 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f  _blob | sqlite3_
2f930 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65  bind_*() API] re
2f940 74 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65  tain their value
2f950 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74  s..** Use [sqlit
2f960 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67  e3_clear_binding
2f970 73 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68  s()] to reset th
2f980 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a  e bindings..**.*
2f990 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  * ^The [sqlite3_
2f9a0 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66  reset(S)] interf
2f9b0 61 63 65 20 72 65 73 65 74 73 20 74 68 65 20 5b  ace resets the [
2f9c0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2f9d0 6e 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74 6f  nt] S.** back to
2f9e0 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f   the beginning o
2f9f0 66 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a  f its program..*
2fa00 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73  *.** ^If the mos
2fa10 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f  t recent call to
2fa20 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
2fa30 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70  )] for the.** [p
2fa40 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2fa50 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b 53  t] S returned [S
2fa60 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53  QLITE_ROW] or [S
2fa70 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20  QLITE_DONE],.** 
2fa80 6f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 73  or if [sqlite3_s
2fa90 74 65 70 28 53 29 5d 20 68 61 73 20 6e 65 76 65  tep(S)] has neve
2faa0 72 20 62 65 66 6f 72 65 20 62 65 65 6e 20 63 61  r before been ca
2fab0 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68  lled on S,.** th
2fac0 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  en [sqlite3_rese
2fad0 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b 53  t(S)] returns [S
2fae0 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a  QLITE_OK]..**.**
2faf0 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65   ^If the most re
2fb00 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  cent call to [sq
2fb10 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66  lite3_step(S)] f
2fb20 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  or the.** [prepa
2fb30 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
2fb40 20 69 6e 64 69 63 61 74 65 64 20 61 6e 20 65 72   indicated an er
2fb50 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 71  ror, then.** [sq
2fb60 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20  lite3_reset(S)] 
2fb70 72 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f  returns an appro
2fb80 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f  priate [error co
2fb90 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  de]..**.** ^The 
2fba0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
2fbb0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65  )] interface doe
2fbc0 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65  s not change the
2fbd0 20 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 6e   values.** of an
2fbe0 79 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  y [sqlite3_bind_
2fbf0 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f  blob|bindings] o
2fc00 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  n the [prepared 
2fc10 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f  statement] S..*/
2fc20 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2fc30 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73 71  sqlite3_reset(sq
2fc40 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
2fc50 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
2fc60 52 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20 52  REF: Create Or R
2fc70 65 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e 63  edefine SQL Func
2fc80 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  tions.** KEYWORD
2fc90 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65  S: {function cre
2fca0 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a  ation routines}.
2fcb0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70  ** KEYWORDS: {ap
2fcc0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2fcd0 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a  d SQL function}.
2fce0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70  ** KEYWORDS: {ap
2fcf0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2fd00 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d  d SQL functions}
2fd10 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75  .**.** ^These fu
2fd20 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 63 74  nctions (collect
2fd30 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 22  ively known as "
2fd40 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f  function creatio
2fd50 6e 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a 2a 20  n routines").** 
2fd60 61 72 65 20 75 73 65 64 20 74 6f 20 61 64 64 20  are used to add 
2fd70 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72  SQL functions or
2fd80 20 61 67 67 72 65 67 61 74 65 73 20 6f 72 20 74   aggregates or t
2fd90 6f 20 72 65 64 65 66 69 6e 65 20 74 68 65 20 62  o redefine the b
2fda0 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 65 78  ehavior.** of ex
2fdb0 69 73 74 69 6e 67 20 53 51 4c 20 66 75 6e 63 74  isting SQL funct
2fdc0 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74  ions or aggregat
2fdd0 65 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 64 69  es.  The only di
2fde0 66 66 65 72 65 6e 63 65 73 20 62 65 74 77 65 65  fferences betwee
2fdf0 6e 0a 2a 2a 20 74 68 65 73 65 20 72 6f 75 74 69  n.** these routi
2fe00 6e 65 73 20 61 72 65 20 74 68 65 20 74 65 78 74  nes are the text
2fe10 20 65 6e 63 6f 64 69 6e 67 20 65 78 70 65 63 74   encoding expect
2fe20 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 73 65  ed for.** the se
2fe30 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 28  cond parameter (
2fe40 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
2fe50 66 75 6e 63 74 69 6f 6e 20 62 65 69 6e 67 20 63  function being c
2fe60 72 65 61 74 65 64 29 0a 2a 2a 20 61 6e 64 20 74  reated).** and t
2fe70 68 65 20 70 72 65 73 65 6e 63 65 20 6f 72 20 61  he presence or a
2fe80 62 73 65 6e 63 65 20 6f 66 20 61 20 64 65 73 74  bsence of a dest
2fe90 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20  ructor callback 
2fea0 66 6f 72 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69  for.** the appli
2feb0 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e  cation data poin
2fec0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ter..**.** ^The 
2fed0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
2fee0 69 73 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  is the [database
2fef0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20   connection] to 
2ff00 77 68 69 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a  which the SQL.**
2ff10 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20   function is to 
2ff20 62 65 20 61 64 64 65 64 2e 20 20 5e 49 66 20 61  be added.  ^If a
2ff30 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73  n application us
2ff40 65 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65  es more than one
2ff50 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e   database.** con
2ff60 6e 65 63 74 69 6f 6e 20 74 68 65 6e 20 61 70 70  nection then app
2ff70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
2ff80 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6d   SQL functions m
2ff90 75 73 74 20 62 65 20 61 64 64 65 64 0a 2a 2a 20  ust be added.** 
2ffa0 74 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 65  to each database
2ffb0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 65 70 61   connection sepa
2ffc0 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54  rately..**.** ^T
2ffd0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
2ffe0 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20  ter is the name 
2fff0 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  of the SQL funct
30000 69 6f 6e 20 74 6f 20 62 65 20 63 72 65 61 74 65  ion to be create
30010 64 20 6f 72 0a 2a 2a 20 72 65 64 65 66 69 6e 65  d or.** redefine
30020 64 2e 20 20 5e 54 68 65 20 6c 65 6e 67 74 68 20  d.  ^The length 
30030 6f 66 20 74 68 65 20 6e 61 6d 65 20 69 73 20 6c  of the name is l
30040 69 6d 69 74 65 64 20 74 6f 20 32 35 35 20 62 79  imited to 255 by
30050 74 65 73 20 69 6e 20 61 20 55 54 46 2d 38 0a 2a  tes in a UTF-8.*
30060 2a 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e  * representation
30070 2c 20 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74  , exclusive of t
30080 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  he zero-terminat
30090 6f 72 2e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20  or.  ^Note that 
300a0 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 6c 65 6e 67  the name.** leng
300b0 74 68 20 6c 69 6d 69 74 20 69 73 20 69 6e 20 55  th limit is in U
300c0 54 46 2d 38 20 62 79 74 65 73 2c 20 6e 6f 74 20  TF-8 bytes, not 
300d0 63 68 61 72 61 63 74 65 72 73 20 6e 6f 72 20 55  characters nor U
300e0 54 46 2d 31 36 20 62 79 74 65 73 2e 20 20 0a 2a  TF-16 bytes.  .*
300f0 2a 20 5e 41 6e 79 20 61 74 74 65 6d 70 74 20 74  * ^Any attempt t
30100 6f 20 63 72 65 61 74 65 20 61 20 66 75 6e 63 74  o create a funct
30110 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67 65  ion with a longe
30120 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72  r name.** will r
30130 65 73 75 6c 74 20 69 6e 20 5b 53 51 4c 49 54 45  esult in [SQLITE
30140 5f 4d 49 53 55 53 45 5d 20 62 65 69 6e 67 20 72  _MISUSE] being r
30150 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  eturned..**.** ^
30160 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  The third parame
30170 74 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20 69 73  ter (nArg).** is
30180 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61   the number of a
30190 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 74 68  rguments that th
301a0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f  e SQL function o
301b0 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 74  r.** aggregate t
301c0 61 6b 65 73 2e 20 5e 49 66 20 74 68 69 73 20 70  akes. ^If this p
301d0 61 72 61 6d 65 74 65 72 20 69 73 20 2d 31 2c 20  arameter is -1, 
301e0 74 68 65 6e 20 74 68 65 20 53 51 4c 20 66 75 6e  then the SQL fun
301f0 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72  ction or.** aggr
30200 65 67 61 74 65 20 6d 61 79 20 74 61 6b 65 20 61  egate may take a
30210 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67  ny number of arg
30220 75 6d 65 6e 74 73 20 62 65 74 77 65 65 6e 20 30  uments between 0
30230 20 61 6e 64 20 74 68 65 20 6c 69 6d 69 74 0a 2a   and the limit.*
30240 2a 20 73 65 74 20 62 79 20 5b 73 71 6c 69 74 65  * set by [sqlite
30250 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45  3_limit]([SQLITE
30260 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f  _LIMIT_FUNCTION_
30270 41 52 47 5d 29 2e 20 20 49 66 20 74 68 65 20 74  ARG]).  If the t
30280 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65  hird.** paramete
30290 72 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 2d  r is less than -
302a0 31 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61  1 or greater tha
302b0 6e 20 31 32 37 20 74 68 65 6e 20 74 68 65 20 62  n 127 then the b
302c0 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75 6e  ehavior is.** un
302d0 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  defined..**.** ^
302e0 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  The fourth param
302f0 65 74 65 72 2c 20 65 54 65 78 74 52 65 70 2c 20  eter, eTextRep, 
30300 73 70 65 63 69 66 69 65 73 20 77 68 61 74 0a 2a  specifies what.*
30310 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c  * [SQLITE_UTF8 |
30320 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20   text encoding] 
30330 74 68 69 73 20 53 51 4c 20 66 75 6e 63 74 69 6f  this SQL functio
30340 6e 20 70 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a  n prefers for.**
30350 20 69 74 73 20 70 61 72 61 6d 65 74 65 72 73 2e   its parameters.
30360 20 20 45 76 65 72 79 20 53 51 4c 20 66 75 6e 63    Every SQL func
30370 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  tion implementat
30380 69 6f 6e 20 6d 75 73 74 20 62 65 20 61 62 6c 65  ion must be able
30390 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69 74 68   to work.** with
303a0 20 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 6c 65   UTF-8, UTF-16le
303b0 2c 20 6f 72 20 55 54 46 2d 31 36 62 65 2e 20 20  , or UTF-16be.  
303c0 42 75 74 20 73 6f 6d 65 20 69 6d 70 6c 65 6d 65  But some impleme
303d0 6e 74 61 74 69 6f 6e 73 20 6d 61 79 20 62 65 0a  ntations may be.
303e0 2a 2a 20 6d 6f 72 65 20 65 66 66 69 63 69 65 6e  ** more efficien
303f0 74 20 77 69 74 68 20 6f 6e 65 20 65 6e 63 6f 64  t with one encod
30400 69 6e 67 20 74 68 61 6e 20 61 6e 6f 74 68 65 72  ing than another
30410 2e 20 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69  .  ^An applicati
30420 6f 6e 20 6d 61 79 0a 2a 2a 20 69 6e 76 6f 6b 65  on may.** invoke
30430 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
30440 66 75 6e 63 74 69 6f 6e 28 29 20 6f 72 20 73 71  function() or sq
30450 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
30460 63 74 69 6f 6e 31 36 28 29 20 6d 75 6c 74 69 70  ction16() multip
30470 6c 65 0a 2a 2a 20 74 69 6d 65 73 20 77 69 74 68  le.** times with
30480 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69   the same functi
30490 6f 6e 20 62 75 74 20 77 69 74 68 20 64 69 66 66  on but with diff
304a0 65 72 65 6e 74 20 76 61 6c 75 65 73 20 6f 66 20  erent values of 
304b0 65 54 65 78 74 52 65 70 2e 0a 2a 2a 20 5e 57 68  eTextRep..** ^Wh
304c0 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c  en multiple impl
304d0 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74  ementations of t
304e0 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e  he same function
304f0 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65 2c 20   are available, 
30500 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70  SQLite.** will p
30510 69 63 6b 20 74 68 65 20 6f 6e 65 20 74 68 61 74  ick the one that
30520 20 69 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c 65   involves the le
30530 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61  ast amount of da
30540 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a  ta conversion..*
30550 2a 20 49 66 20 74 68 65 72 65 20 69 73 20 6f 6e  * If there is on
30560 6c 79 20 61 20 73 69 6e 67 6c 65 20 69 6d 70 6c  ly a single impl
30570 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 69 63 68  ementation which
30580 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 77   does not care w
30590 68 61 74 20 74 65 78 74 0a 2a 2a 20 65 6e 63 6f  hat text.** enco
305a0 64 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68  ding is used, th
305b0 65 6e 20 74 68 65 20 66 6f 75 72 74 68 20 61 72  en the fourth ar
305c0 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65  gument should be
305d0 20 5b 53 51 4c 49 54 45 5f 41 4e 59 5d 2e 0a 2a   [SQLITE_ANY]..*
305e0 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 66 74 68  *.** ^(The fifth
305f0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e   parameter is an
30600 20 61 72 62 69 74 72 61 72 79 20 70 6f 69 6e 74   arbitrary point
30610 65 72 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d 65  er.  The impleme
30620 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a  ntation of the.*
30630 2a 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67  * function can g
30640 61 69 6e 20 61 63 63 65 73 73 20 74 6f 20 74 68  ain access to th
30650 69 73 20 70 6f 69 6e 74 65 72 20 75 73 69 6e 67  is pointer using
30660 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64   [sqlite3_user_d
30670 61 74 61 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20  ata()].)^.**.** 
30680 5e 54 68 65 20 73 69 78 74 68 2c 20 73 65 76 65  ^The sixth, seve
30690 6e 74 68 20 61 6e 64 20 65 69 67 68 74 68 20 70  nth and eighth p
306a0 61 72 61 6d 65 74 65 72 73 2c 20 78 46 75 6e 63  arameters, xFunc
306b0 2c 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e  , xStep and xFin
306c0 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74  al, are.** point
306d0 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67  ers to C-languag
306e0 65 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74  e functions that
306f0 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53   implement the S
30700 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a  QL function or.*
30710 2a 20 61 67 67 72 65 67 61 74 65 2e 20 5e 41 20  * aggregate. ^A 
30720 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74  scalar SQL funct
30730 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20  ion requires an 
30740 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
30750 66 20 74 68 65 20 78 46 75 6e 63 0a 2a 2a 20 63  f the xFunc.** c
30760 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 3b 20 4e 55  allback only; NU
30770 4c 4c 20 70 6f 69 6e 74 65 72 73 20 6d 75 73 74  LL pointers must
30780 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68   be passed as th
30790 65 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e  e xStep and xFin
307a0 61 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73  al.** parameters
307b0 2e 20 5e 41 6e 20 61 67 67 72 65 67 61 74 65 20  . ^An aggregate 
307c0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71  SQL function req
307d0 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65  uires an impleme
307e0 6e 74 61 74 69 6f 6e 20 6f 66 20 78 53 74 65 70  ntation of xStep
307f0 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20 61  .** and xFinal a
30800 6e 64 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20  nd NULL pointer 
30810 6d 75 73 74 20 62 65 20 70 61 73 73 65 64 20 66  must be passed f
30820 6f 72 20 78 46 75 6e 63 2e 20 5e 54 6f 20 64 65  or xFunc. ^To de
30830 6c 65 74 65 20 61 6e 20 65 78 69 73 74 69 6e 67  lete an existing
30840 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  .** SQL function
30850 20 6f 72 20 61 67 67 72 65 67 61 74 65 2c 20 70   or aggregate, p
30860 61 73 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  ass NULL pointer
30870 73 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 65 20  s for all three 
30880 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c  function.** call
30890 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49  backs..**.** ^(I
308a0 66 20 74 68 65 20 6e 69 6e 74 68 20 70 61 72 61  f the ninth para
308b0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
308c0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
308d0 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c  _v2() is not NUL
308e0 4c 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73  L,.** then it is
308f0 20 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20   destructor for 
30900 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
30910 64 61 74 61 20 70 6f 69 6e 74 65 72 2e 20 0a 2a  data pointer. .*
30920 2a 20 54 68 65 20 64 65 73 74 72 75 63 74 6f 72  * The destructor
30930 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   is invoked when
30940 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73   the function is
30950 20 64 65 6c 65 74 65 64 2c 20 65 69 74 68 65 72   deleted, either
30960 20 62 79 20 62 65 69 6e 67 0a 2a 2a 20 6f 76 65   by being.** ove
30970 72 6c 6f 61 64 65 64 20 6f 72 20 77 68 65 6e 20  rloaded or when 
30980 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
30990 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 29  nection closes.)
309a0 5e 0a 2a 2a 20 5e 54 68 65 20 64 65 73 74 72 75  ^.** ^The destru
309b0 63 74 6f 72 20 69 73 20 61 6c 73 6f 20 69 6e 76  ctor is also inv
309c0 6f 6b 65 64 20 69 66 20 74 68 65 20 63 61 6c 6c  oked if the call
309d0 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   to.** sqlite3_c
309e0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76  reate_function_v
309f0 32 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 57  2() fails..** ^W
30a00 68 65 6e 20 74 68 65 20 64 65 73 74 72 75 63 74  hen the destruct
30a10 6f 72 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74  or callback of t
30a20 68 65 20 74 65 6e 74 68 20 70 61 72 61 6d 65 74  he tenth paramet
30a30 65 72 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 69  er is invoked, i
30a40 74 0a 2a 2a 20 69 73 20 70 61 73 73 65 64 20 61  t.** is passed a
30a50 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
30a60 20 77 68 69 63 68 20 69 73 20 61 20 63 6f 70 79   which is a copy
30a70 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
30a80 69 6f 6e 20 64 61 74 61 20 0a 2a 2a 20 70 6f 69  ion data .** poi
30a90 6e 74 65 72 20 77 68 69 63 68 20 77 61 73 20 74  nter which was t
30aa0 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74  he fifth paramet
30ab0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72  er to sqlite3_cr
30ac0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32  eate_function_v2
30ad0 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73  ()..**.** ^It is
30ae0 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 72 65   permitted to re
30af0 67 69 73 74 65 72 20 6d 75 6c 74 69 70 6c 65 20  gister multiple 
30b00 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
30b10 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66  of the same.** f
30b20 75 6e 63 74 69 6f 6e 73 20 77 69 74 68 20 74 68  unctions with th
30b30 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 20  e same name but 
30b40 77 69 74 68 20 65 69 74 68 65 72 20 64 69 66 66  with either diff
30b50 65 72 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66  ering numbers of
30b60 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f 72  .** arguments or
30b70 20 64 69 66 66 65 72 69 6e 67 20 70 72 65 66 65   differing prefe
30b80 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69  rred text encodi
30b90 6e 67 73 2e 20 20 5e 53 51 4c 69 74 65 20 77 69  ngs.  ^SQLite wi
30ba0 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d  ll use.** the im
30bb0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61  plementation tha
30bc0 74 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20 6d  t most closely m
30bd0 61 74 63 68 65 73 20 74 68 65 20 77 61 79 20 69  atches the way i
30be0 6e 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 53  n which the.** S
30bf0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75  QL function is u
30c00 73 65 64 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f  sed.  ^A functio
30c10 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
30c20 20 77 69 74 68 20 61 20 6e 6f 6e 2d 6e 65 67 61   with a non-nega
30c30 74 69 76 65 0a 2a 2a 20 6e 41 72 67 20 70 61 72  tive.** nArg par
30c40 61 6d 65 74 65 72 20 69 73 20 61 20 62 65 74 74  ameter is a bett
30c50 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20  er match than a 
30c60 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65  function impleme
30c70 6e 74 61 74 69 6f 6e 20 77 69 74 68 0a 2a 2a 20  ntation with.** 
30c80 61 20 6e 65 67 61 74 69 76 65 20 6e 41 72 67 2e  a negative nArg.
30c90 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68    ^A function wh
30ca0 65 72 65 20 74 68 65 20 70 72 65 66 65 72 72 65  ere the preferre
30cb0 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 0a  d text encoding.
30cc0 2a 2a 20 6d 61 74 63 68 65 73 20 74 68 65 20 64  ** matches the d
30cd0 61 74 61 62 61 73 65 20 65 6e 63 6f 64 69 6e 67  atabase encoding
30ce0 20 69 73 20 61 20 62 65 74 74 65 72 0a 2a 2a 20   is a better.** 
30cf0 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e  match than a fun
30d00 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20  ction where the 
30d10 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66 66  encoding is diff
30d20 65 72 65 6e 74 2e 20 20 0a 2a 2a 20 5e 41 20 66  erent.  .** ^A f
30d30 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68  unction where th
30d40 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65  e encoding diffe
30d50 72 65 6e 63 65 20 69 73 20 62 65 74 77 65 65 6e  rence is between
30d60 20 55 54 46 31 36 6c 65 20 61 6e 64 20 55 54 46   UTF16le and UTF
30d70 31 36 62 65 0a 2a 2a 20 69 73 20 61 20 63 6c 6f  16be.** is a clo
30d80 73 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61  ser match than a
30d90 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20   function where 
30da0 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66  the encoding dif
30db0 66 65 72 65 6e 63 65 20 69 73 0a 2a 2a 20 62 65  ference is.** be
30dc0 74 77 65 65 6e 20 55 54 46 38 20 61 6e 64 20 55  tween UTF8 and U
30dd0 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75 69  TF16..**.** ^Bui
30de0 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20  lt-in functions 
30df0 6d 61 79 20 62 65 20 6f 76 65 72 6c 6f 61 64 65  may be overloade
30e00 64 20 62 79 20 6e 65 77 20 61 70 70 6c 69 63 61  d by new applica
30e10 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
30e20 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41  ctions..**.** ^A
30e30 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
30e40 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69  fined function i
30e50 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 63  s permitted to c
30e60 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c  all other.** SQL
30e70 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 2e 20  ite interfaces. 
30e80 20 48 6f 77 65 76 65 72 2c 20 73 75 63 68 20 63   However, such c
30e90 61 6c 6c 73 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a  alls must not.**
30ea0 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62   close the datab
30eb0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e  ase connection n
30ec0 6f 72 20 66 69 6e 61 6c 69 7a 65 20 6f 72 20 72  or finalize or r
30ed0 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65  eset the prepare
30ee0 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69  d.** statement i
30ef0 6e 20 77 68 69 63 68 20 74 68 65 20 66 75 6e 63  n which the func
30f00 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e  tion is running.
30f10 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
30f20 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
30f30 65 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71  e_function(.  sq
30f40 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e  lite3 *db,.  con
30f50 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69  st char *zFuncti
30f60 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41  onName,.  int nA
30f70 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52  rg,.  int eTextR
30f80 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70  ep,.  void *pApp
30f90 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63  ,.  void (*xFunc
30fa0 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
30fb0 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
30fc0 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
30fd0 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33  (*xStep)(sqlite3
30fe0 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
30ff0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
31000 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29    void (*xFinal)
31010 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
31020 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  *).);.SQLITE_API
31030 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65   int sqlite3_cre
31040 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a  ate_function16(.
31050 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20    sqlite3 *db,. 
31060 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75   const void *zFu
31070 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e  nctionName,.  in
31080 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54  t nArg,.  int eT
31090 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a  extRep,.  void *
310a0 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78  pApp,.  void (*x
310b0 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f  Func)(sqlite3_co
310c0 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
310d0 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
310e0 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c  oid (*xStep)(sql
310f0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
31100 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
31110 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69  *),.  void (*xFi
31120 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  nal)(sqlite3_con
31130 74 65 78 74 2a 29 0a 29 3b 0a 53 51 4c 49 54 45  text*).);.SQLITE
31140 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
31150 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
31160 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  _v2(.  sqlite3 *
31170 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  db,.  const char
31180 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c   *zFunctionName,
31190 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69  .  int nArg,.  i
311a0 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76  nt eTextRep,.  v
311b0 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69  oid *pApp,.  voi
311c0 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74  d (*xFunc)(sqlit
311d0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
311e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
311f0 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70  ,.  void (*xStep
31200 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
31210 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
31220 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
31230 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65  (*xFinal)(sqlite
31240 33 5f 63 6f 6e 74 65 78 74 2a 29 2c 0a 20 20 76  3_context*),.  v
31250 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76  oid(*xDestroy)(v
31260 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  oid*).);../*.** 
31270 43 41 50 49 33 52 45 46 3a 20 54 65 78 74 20 45  CAPI3REF: Text E
31280 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54  ncodings.**.** T
31290 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 20 64 65  hese constant de
312a0 66 69 6e 65 20 69 6e 74 65 67 65 72 20 63 6f 64  fine integer cod
312b0 65 73 20 74 68 61 74 20 72 65 70 72 65 73 65 6e  es that represen
312c0 74 20 74 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a  t the various.**
312d0 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 20   text encodings 
312e0 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c  supported by SQL
312f0 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ite..*/.#define 
31300 53 51 4c 49 54 45 5f 55 54 46 38 20 20 20 20 20  SQLITE_UTF8     
31310 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
31320 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 20 20  SQLITE_UTF16LE  
31330 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
31340 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 20 20  SQLITE_UTF16BE  
31350 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20        3.#define 
31360 53 51 4c 49 54 45 5f 55 54 46 31 36 20 20 20 20  SQLITE_UTF16    
31370 20 20 20 20 20 20 34 20 20 20 20 2f 2a 20 55 73        4    /* Us
31380 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  e native byte or
31390 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  der */.#define S
313a0 51 4c 49 54 45 5f 41 4e 59 20 20 20 20 20 20 20  QLITE_ANY       
313b0 20 20 20 20 20 35 20 20 20 20 2f 2a 20 73 71 6c       5    /* sql
313c0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
313d0 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65  tion only */.#de
313e0 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31  fine SQLITE_UTF1
313f0 36 5f 41 4c 49 47 4e 45 44 20 20 38 20 20 20 20  6_ALIGNED  8    
31400 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  /* sqlite3_creat
31410 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79  e_collation only
31420 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
31430 52 45 46 3a 20 44 65 70 72 65 63 61 74 65 64 20  REF: Deprecated 
31440 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 45 50  Functions.** DEP
31450 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68  RECATED.**.** Th
31460 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72  ese functions ar
31470 65 20 5b 64 65 70 72 65 63 61 74 65 64 5d 2e 20  e [deprecated]. 
31480 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61 69   In order to mai
31490 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72  ntain.** backwar
314a0 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
314b0 20 77 69 74 68 20 6f 6c 64 65 72 20 63 6f 64 65   with older code
314c0 2c 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  , these function
314d0 73 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20 74  s continue .** t
314e0 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 20  o be supported. 
314f0 20 48 6f 77 65 76 65 72 2c 20 6e 65 77 20 61 70   However, new ap
31500 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c  plications shoul
31510 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75  d avoid.** the u
31520 73 65 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63  se of these func
31530 74 69 6f 6e 73 2e 20 20 54 6f 20 68 65 6c 70 20  tions.  To help 
31540 65 6e 63 6f 75 72 61 67 65 20 70 65 6f 70 6c 65  encourage people
31550 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 75 73 69   to avoid.** usi
31560 6e 67 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  ng these functio
31570 6e 73 2c 20 77 65 20 61 72 65 20 6e 6f 74 20 67  ns, we are not g
31580 6f 69 6e 67 20 74 6f 20 74 65 6c 6c 20 79 6f 75  oing to tell you
31590 20 77 68 61 74 20 74 68 65 79 20 64 6f 2e 0a 2a   what they do..*
315a0 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45  /.#ifndef SQLITE
315b0 5f 4f 4d 49 54 5f 44 45 50 52 45 43 41 54 45 44  _OMIT_DEPRECATED
315c0 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49  .SQLITE_API SQLI
315d0 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e  TE_DEPRECATED in
315e0 74 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  t sqlite3_aggreg
315f0 61 74 65 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65  ate_count(sqlite
31600 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c  3_context*);.SQL
31610 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44  ITE_API SQLITE_D
31620 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71  EPRECATED int sq
31630 6c 69 74 65 33 5f 65 78 70 69 72 65 64 28 73 71  lite3_expired(sq
31640 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51  lite3_stmt*);.SQ
31650 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f  LITE_API SQLITE_
31660 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73  DEPRECATED int s
31670 71 6c 69 74 65 33 5f 74 72 61 6e 73 66 65 72 5f  qlite3_transfer_
31680 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33  bindings(sqlite3
31690 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f  _stmt*, sqlite3_
316a0 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41  stmt*);.SQLITE_A
316b0 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43  PI SQLITE_DEPREC
316c0 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33  ATED int sqlite3
316d0 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 65 72 28  _global_recover(
316e0 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50  void);.SQLITE_AP
316f0 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  I SQLITE_DEPRECA
31700 54 45 44 20 76 6f 69 64 20 73 71 6c 69 74 65 33  TED void sqlite3
31710 5f 74 68 72 65 61 64 5f 63 6c 65 61 6e 75 70 28  _thread_cleanup(
31720 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50  void);.SQLITE_AP
31730 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  I SQLITE_DEPRECA
31740 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TED int sqlite3_
31750 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69  memory_alarm(voi
31760 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74  d(*)(void*,sqlit
31770 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 0a 20  e3_int64,int),. 
31780 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
31790 20 20 20 20 20 76 6f 69 64 2a 2c 73 71 6c 69 74       void*,sqlit
317a0 65 33 5f 69 6e 74 36 34 29 3b 0a 23 65 6e 64 69  e3_int64);.#endi
317b0 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  f../*.** CAPI3RE
317c0 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53 51 4c  F: Obtaining SQL
317d0 20 46 75 6e 63 74 69 6f 6e 20 50 61 72 61 6d 65   Function Parame
317e0 74 65 72 20 56 61 6c 75 65 73 0a 2a 2a 0a 2a 2a  ter Values.**.**
317f0 20 54 68 65 20 43 2d 6c 61 6e 67 75 61 67 65 20   The C-language 
31800 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
31810 66 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  f SQL functions 
31820 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 20 75  and aggregates u
31830 73 65 73 0a 2a 2a 20 74 68 69 73 20 73 65 74 20  ses.** this set 
31840 6f 66 20 69 6e 74 65 72 66 61 63 65 20 72 6f 75  of interface rou
31850 74 69 6e 65 73 20 74 6f 20 61 63 63 65 73 73 20  tines to access 
31860 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 76 61  the parameter va
31870 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74 68 65 20 66  lues on.** the f
31880 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65  unction or aggre
31890 67 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  gate..**.** The 
318a0 78 46 75 6e 63 20 28 66 6f 72 20 73 63 61 6c 61  xFunc (for scala
318b0 72 20 66 75 6e 63 74 69 6f 6e 73 29 20 6f 72 20  r functions) or 
318c0 78 53 74 65 70 20 28 66 6f 72 20 61 67 67 72 65  xStep (for aggre
318d0 67 61 74 65 73 29 20 70 61 72 61 6d 65 74 65 72  gates) parameter
318e0 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33  s.** to [sqlite3
318f0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
31900 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
31910 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
31920 31 36 28 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 20  16()].** define 
31930 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 20 69  callbacks that i
31940 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c  mplement the SQL
31950 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61   functions and a
31960 67 67 72 65 67 61 74 65 73 2e 0a 2a 2a 20 54 68  ggregates..** Th
31970 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  e 3rd parameter 
31980 74 6f 20 74 68 65 73 65 20 63 61 6c 6c 62 61 63  to these callbac
31990 6b 73 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f  ks is an array o
319a0 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 0a 2a 2a  f pointers to.**
319b0 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
319c0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
319d0 74 73 2e 20 20 54 68 65 72 65 20 69 73 20 6f 6e  ts.  There is on
319e0 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
319f0 5d 20 6f 62 6a 65 63 74 20 66 6f 72 0a 2a 2a 20  ] object for.** 
31a00 65 61 63 68 20 70 61 72 61 6d 65 74 65 72 20 74  each parameter t
31a10 6f 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  o the SQL functi
31a20 6f 6e 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69  on.  These routi
31a30 6e 65 73 20 61 72 65 20 75 73 65 64 20 74 6f 0a  nes are used to.
31a40 2a 2a 20 65 78 74 72 61 63 74 20 76 61 6c 75 65  ** extract value
31a50 73 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69  s from the [sqli
31a60 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
31a70 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ts..**.** These 
31a80 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6f 6e  routines work on
31a90 6c 79 20 77 69 74 68 20 5b 70 72 6f 74 65 63 74  ly with [protect
31aa0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
31ab0 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e  ] objects..** An
31ac0 79 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65  y attempt to use
31ad0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
31ae0 6f 6e 20 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74  on an [unprotect
31af0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
31b00 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 73 75  ].** object resu
31b10 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64  lts in undefined
31b20 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a   behavior..**.**
31b30 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
31b40 20 77 6f 72 6b 20 6a 75 73 74 20 6c 69 6b 65 20   work just like 
31b50 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
31b60 67 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73  g [column access
31b70 20 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65   functions].** e
31b80 78 63 65 70 74 20 74 68 61 74 20 20 74 68 65 73  xcept that  thes
31b90 65 20 72 6f 75 74 69 6e 65 73 20 74 61 6b 65 20  e routines take 
31ba0 61 20 73 69 6e 67 6c 65 20 5b 70 72 6f 74 65 63  a single [protec
31bb0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
31bc0 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 6f 69  e] object.** poi
31bd0 6e 74 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20  nter instead of 
31be0 61 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  a [sqlite3_stmt*
31bf0 5d 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 61 6e  ] pointer and an
31c00 20 69 6e 74 65 67 65 72 20 63 6f 6c 75 6d 6e 20   integer column 
31c10 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  number..**.** ^T
31c20 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
31c30 5f 74 65 78 74 31 36 28 29 20 69 6e 74 65 72 66  _text16() interf
31c40 61 63 65 20 65 78 74 72 61 63 74 73 20 61 20 55  ace extracts a U
31c50 54 46 2d 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20  TF-16 string.** 
31c60 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79  in the native by
31c70 74 65 2d 6f 72 64 65 72 20 6f 66 20 74 68 65 20  te-order of the 
31c80 68 6f 73 74 20 6d 61 63 68 69 6e 65 2e 20 20 5e  host machine.  ^
31c90 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  The.** sqlite3_v
31ca0 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 29 20  alue_text16be() 
31cb0 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  and sqlite3_valu
31cc0 65 5f 74 65 78 74 31 36 6c 65 28 29 20 69 6e 74  e_text16le() int
31cd0 65 72 66 61 63 65 73 0a 2a 2a 20 65 78 74 72 61  erfaces.** extra
31ce0 63 74 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67  ct UTF-16 string
31cf0 73 20 61 73 20 62 69 67 2d 65 6e 64 69 61 6e 20  s as big-endian 
31d00 61 6e 64 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61  and little-endia
31d10 6e 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a  n respectively..
31d20 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69  **.** ^(The sqli
31d30 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69  te3_value_numeri
31d40 63 5f 74 79 70 65 28 29 20 69 6e 74 65 72 66 61  c_type() interfa
31d50 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 61  ce attempts to a
31d60 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 20  pply.** numeric 
31d70 61 66 66 69 6e 69 74 79 20 74 6f 20 74 68 65 20  affinity to the 
31d80 76 61 6c 75 65 2e 20 20 54 68 69 73 20 6d 65 61  value.  This mea
31d90 6e 73 20 74 68 61 74 20 61 6e 20 61 74 74 65 6d  ns that an attem
31da0 70 74 20 69 73 0a 2a 2a 20 6d 61 64 65 20 74 6f  pt is.** made to
31db0 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c   convert the val
31dc0 75 65 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  ue to an integer
31dd0 20 6f 72 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69   or floating poi
31de0 6e 74 2e 20 20 49 66 0a 2a 2a 20 73 75 63 68 20  nt.  If.** such 
31df0 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20  a conversion is 
31e00 70 6f 73 73 69 62 6c 65 20 77 69 74 68 6f 75 74  possible without
31e10 20 6c 6f 73 73 20 6f 66 20 69 6e 66 6f 72 6d 61   loss of informa
31e20 74 69 6f 6e 20 28 69 6e 20 6f 74 68 65 72 0a 2a  tion (in other.*
31e30 2a 20 77 6f 72 64 73 2c 20 69 66 20 74 68 65 20  * words, if the 
31e40 76 61 6c 75 65 20 69 73 20 61 20 73 74 72 69 6e  value is a strin
31e50 67 20 74 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b  g that looks lik
31e60 65 20 61 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 74  e a number).** t
31e70 68 65 6e 20 74 68 65 20 63 6f 6e 76 65 72 73 69  hen the conversi
31e80 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d 65 64 2e  on is performed.
31e90 20 20 4f 74 68 65 72 77 69 73 65 20 6e 6f 20 63    Otherwise no c
31ea0 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73  onversion occurs
31eb0 2e 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ..** The [SQLITE
31ec0 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74  _INTEGER | datat
31ed0 79 70 65 5d 20 61 66 74 65 72 20 63 6f 6e 76 65  ype] after conve
31ee0 72 73 69 6f 6e 20 69 73 20 72 65 74 75 72 6e 65  rsion is returne
31ef0 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73  d.)^.**.** Pleas
31f00 65 20 70 61 79 20 70 61 72 74 69 63 75 6c 61 72  e pay particular
31f10 20 61 74 74 65 6e 74 69 6f 6e 20 74 6f 20 74 68   attention to th
31f20 65 20 66 61 63 74 20 74 68 61 74 20 74 68 65 20  e fact that the 
31f30 70 6f 69 6e 74 65 72 20 72 65 74 75 72 6e 65 64  pointer returned
31f40 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  .** from [sqlite
31f50 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c  3_value_blob()],
31f60 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
31f70 74 65 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b  text()], or.** [
31f80 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
31f90 78 74 31 36 28 29 5d 20 63 61 6e 20 62 65 20 69  xt16()] can be i
31fa0 6e 76 61 6c 69 64 61 74 65 64 20 62 79 20 61 20  nvalidated by a 
31fb0 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20  subsequent call 
31fc0 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  to.** [sqlite3_v
31fd0 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b  alue_bytes()], [
31fe0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
31ff0 74 65 73 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74  tes16()], [sqlit
32000 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d  e3_value_text()]
32010 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33  ,.** or [sqlite3
32020 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d  _value_text16()]
32030 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
32040 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63  utines must be c
32050 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73  alled from the s
32060 61 6d 65 20 74 68 72 65 61 64 20 61 73 0a 2a 2a  ame thread as.**
32070 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
32080 6e 20 74 68 61 74 20 73 75 70 70 6c 69 65 64 20  n that supplied 
32090 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  the [sqlite3_val
320a0 75 65 2a 5d 20 70 61 72 61 6d 65 74 65 72 73 2e  ue*] parameters.
320b0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  .*/.SQLITE_API c
320c0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
320d0 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71  e3_value_blob(sq
320e0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53  lite3_value*);.S
320f0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
32100 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
32110 73 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  s(sqlite3_value*
32120 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
32130 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  t sqlite3_value_
32140 62 79 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f  bytes16(sqlite3_
32150 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f  value*);.SQLITE_
32160 41 50 49 20 64 6f 75 62 6c 65 20 73 71 6c 69 74  API double sqlit
32170 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28  e3_value_double(
32180 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
32190 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
321a0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e  sqlite3_value_in
321b0 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t(sqlite3_value*
321c0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71  );.SQLITE_API sq
321d0 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
321e0 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28  te3_value_int64(
321f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
32200 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
32210 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20  t unsigned char 
32220 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  *sqlite3_value_t
32230 65 78 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  ext(sqlite3_valu
32240 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  e*);.SQLITE_API 
32250 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
32260 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
32270 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
32280 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  ;.SQLITE_API con
32290 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
322a0 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28  _value_text16le(
322b0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
322c0 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
322d0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
322e0 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 73  value_text16be(s
322f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
32300 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
32310 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70  qlite3_value_typ
32320 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
32330 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
32340 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  t sqlite3_value_
32350 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 73 71 6c  numeric_type(sql
32360 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f  ite3_value*);../
32370 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
32380 62 74 61 69 6e 20 41 67 67 72 65 67 61 74 65 20  btain Aggregate 
32390 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74  Function Context
323a0 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c 65 6d 65 6e 74  .**.** Implement
323b0 61 74 69 6f 6e 73 20 6f 66 20 61 67 67 72 65 67  ations of aggreg
323c0 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ate SQL function
323d0 73 20 75 73 65 20 74 68 69 73 0a 2a 2a 20 72 6f  s use this.** ro
323e0 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74  utine to allocat
323f0 65 20 6d 65 6d 6f 72 79 20 66 6f 72 20 73 74 6f  e memory for sto
32400 72 69 6e 67 20 74 68 65 69 72 20 73 74 61 74 65  ring their state
32410 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
32420 73 74 20 74 69 6d 65 20 74 68 65 20 73 71 6c 69  st time the sqli
32430 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
32440 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69  ntext(C,N) routi
32450 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 0a 2a 2a  ne is called .**
32460 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61   for a particula
32470 72 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63  r aggregate func
32480 74 69 6f 6e 2c 20 53 51 4c 69 74 65 0a 2a 2a 20  tion, SQLite.** 
32490 61 6c 6c 6f 63 61 74 65 73 20 4e 20 6f 66 20 6d  allocates N of m
324a0 65 6d 6f 72 79 2c 20 7a 65 72 6f 65 73 20 6f 75  emory, zeroes ou
324b0 74 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c 20 61  t that memory, a
324c0 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  nd returns a poi
324d0 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 6e  nter.** to the n
324e0 65 77 20 6d 65 6d 6f 72 79 2e 20 5e 4f 6e 20 73  ew memory. ^On s
324f0 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71  econd and subseq
32500 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  uent calls to.**
32510 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
32520 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 66 6f 72  te_context() for
32530 20 74 68 65 20 73 61 6d 65 20 61 67 67 72 65 67   the same aggreg
32540 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73  ate function ins
32550 74 61 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 73 61  tance,.** the sa
32560 6d 65 20 62 75 66 66 65 72 20 69 73 20 72 65 74  me buffer is ret
32570 75 72 6e 65 64 2e 20 20 53 71 6c 69 74 65 33 5f  urned.  Sqlite3_
32580 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
32590 74 28 29 20 69 73 20 6e 6f 72 6d 61 6c 6c 79 0a  t() is normally.
325a0 2a 2a 20 63 61 6c 6c 65 64 20 6f 6e 63 65 20 66  ** called once f
325b0 6f 72 20 65 61 63 68 20 69 6e 76 6f 63 61 74 69  or each invocati
325c0 6f 6e 20 6f 66 20 74 68 65 20 78 53 74 65 70 20  on of the xStep 
325d0 63 61 6c 6c 62 61 63 6b 20 61 6e 64 20 74 68 65  callback and the
325e0 6e 20 6f 6e 65 0a 2a 2a 20 6c 61 73 74 20 74 69  n one.** last ti
325f0 6d 65 20 77 68 65 6e 20 74 68 65 20 78 46 69 6e  me when the xFin
32600 61 6c 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  al callback is i
32610 6e 76 6f 6b 65 64 2e 20 20 5e 28 57 68 65 6e 20  nvoked.  ^(When 
32620 6e 6f 20 72 6f 77 73 20 6d 61 74 63 68 0a 2a 2a  no rows match.**
32630 20 61 6e 20 61 67 67 72 65 67 61 74 65 20 71 75   an aggregate qu
32640 65 72 79 2c 20 74 68 65 20 78 53 74 65 70 28 29  ery, the xStep()
32650 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65   callback of the
32660 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74   aggregate funct
32670 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  ion.** implement
32680 61 74 69 6f 6e 20 69 73 20 6e 65 76 65 72 20 63  ation is never c
32690 61 6c 6c 65 64 20 61 6e 64 20 78 46 69 6e 61 6c  alled and xFinal
326a0 28 29 20 69 73 20 63 61 6c 6c 65 64 20 65 78 61  () is called exa
326b0 63 74 6c 79 20 6f 6e 63 65 2e 0a 2a 2a 20 49 6e  ctly once..** In
326c0 20 74 68 6f 73 65 20 63 61 73 65 73 2c 20 73 71   those cases, sq
326d0 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
326e0 63 6f 6e 74 65 78 74 28 29 20 6d 69 67 68 74 20  context() might 
326f0 62 65 20 63 61 6c 6c 65 64 20 66 6f 72 20 74 68  be called for th
32700 65 0a 2a 2a 20 66 69 72 73 74 20 74 69 6d 65 20  e.** first time 
32710 66 72 6f 6d 20 77 69 74 68 69 6e 20 78 46 69 6e  from within xFin
32720 61 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  al().)^.**.** ^T
32730 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  he sqlite3_aggre
32740 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e  gate_context(C,N
32750 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
32760 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
32770 20 0a 2a 2a 20 77 68 65 6e 20 66 69 72 73 74 20   .** when first 
32780 63 61 6c 6c 65 64 20 69 66 20 4e 20 69 73 20 6c  called if N is l
32790 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61  ess than or equa
327a0 6c 20 74 6f 20 7a 65 72 6f 20 6f 72 20 69 66 20  l to zero or if 
327b0 61 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  a memory.** allo
327c0 63 61 74 65 20 65 72 72 6f 72 20 6f 63 63 75 72  cate error occur
327d0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 61  s..**.** ^(The a
327e0 6d 6f 75 6e 74 20 6f 66 20 73 70 61 63 65 20 61  mount of space a
327f0 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69  llocated by sqli
32800 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
32810 6e 74 65 78 74 28 43 2c 4e 29 20 69 73 0a 2a 2a  ntext(C,N) is.**
32820 20 64 65 74 65 72 6d 69 6e 65 64 20 62 79 20 74   determined by t
32830 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 6f  he N parameter o
32840 6e 20 66 69 72 73 74 20 73 75 63 63 65 73 73 66  n first successf
32850 75 6c 20 63 61 6c 6c 2e 20 20 43 68 61 6e 67 69  ul call.  Changi
32860 6e 67 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20  ng the.** value 
32870 6f 66 20 4e 20 69 6e 20 73 75 62 73 65 71 75 65  of N in subseque
32880 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  nt call to sqlit
32890 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
328a0 74 65 78 74 28 29 20 77 69 74 68 69 6e 0a 2a 2a  text() within.**
328b0 20 74 68 65 20 73 61 6d 65 20 61 67 67 72 65 67   the same aggreg
328c0 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73  ate function ins
328d0 74 61 6e 63 65 20 77 69 6c 6c 20 6e 6f 74 20 72  tance will not r
328e0 65 73 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79  esize the memory
328f0 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e 29  .** allocation.)
32900 5e 20 20 57 69 74 68 69 6e 20 74 68 65 20 78 46  ^  Within the xF
32910 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 2c 20 69  inal callback, i
32920 74 20 69 73 20 63 75 73 74 6f 6d 61 72 79 20 74  t is customary t
32930 6f 20 73 65 74 0a 2a 2a 20 4e 3d 30 20 69 6e 20  o set.** N=0 in 
32940 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
32950 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
32960 78 74 28 43 2c 4e 29 20 73 6f 20 74 68 61 74 20  xt(C,N) so that 
32970 6e 6f 20 0a 2a 2a 20 70 6f 69 6e 74 6c 65 73 73  no .** pointless
32980 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
32990 6f 6e 73 20 6f 63 63 75 72 2e 0a 2a 2a 0a 2a 2a  ons occur..**.**
329a0 20 5e 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74   ^SQLite automat
329b0 69 63 61 6c 6c 79 20 66 72 65 65 73 20 74 68 65  ically frees the
329c0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65   memory allocate
329d0 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74 65 33  d by .** sqlite3
329e0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
329f0 78 74 28 29 20 77 68 65 6e 20 74 68 65 20 61 67  xt() when the ag
32a00 67 72 65 67 61 74 65 20 71 75 65 72 79 20 63 6f  gregate query co
32a10 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  ncludes..**.** T
32a20 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
32a30 65 72 20 6d 75 73 74 20 62 65 20 61 20 63 6f 70  er must be a cop
32a40 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  y of the.** [sql
32a50 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c 20 53  ite3_context | S
32a60 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f 6e 74  QL function cont
32a70 65 78 74 5d 20 74 68 61 74 20 69 73 20 74 68 65  ext] that is the
32a80 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
32a90 0a 2a 2a 20 74 6f 20 74 68 65 20 78 53 74 65 70  .** to the xStep
32aa0 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62   or xFinal callb
32ab0 61 63 6b 20 72 6f 75 74 69 6e 65 20 74 68 61 74  ack routine that
32ac0 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20   implements the 
32ad0 61 67 67 72 65 67 61 74 65 0a 2a 2a 20 66 75 6e  aggregate.** fun
32ae0 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  ction..**.** Thi
32af0 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62  s routine must b
32b00 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  e called from th
32b10 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e  e same thread in
32b20 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 67   which.** the ag
32b30 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63  gregate SQL func
32b40 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e  tion is running.
32b50 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  .*/.SQLITE_API v
32b60 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 61 67 67  oid *sqlite3_agg
32b70 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 73  regate_context(s
32b80 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
32b90 20 69 6e 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f   int nBytes);../
32ba0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 55  *.** CAPI3REF: U
32bb0 73 65 72 20 44 61 74 61 20 46 6f 72 20 46 75 6e  ser Data For Fun
32bc0 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  ctions.**.** ^Th
32bd0 65 20 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64  e sqlite3_user_d
32be0 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20  ata() interface 
32bf0 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f  returns a copy o
32c00 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72  f.** the pointer
32c10 20 74 68 61 74 20 77 61 73 20 74 68 65 20 70 55   that was the pU
32c20 73 65 72 44 61 74 61 20 70 61 72 61 6d 65 74 65  serData paramete
32c30 72 20 28 74 68 65 20 35 74 68 20 70 61 72 61 6d  r (the 5th param
32c40 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20  eter).** of the 
32c50 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
32c60 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61  function()].** a
32c70 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  nd [sqlite3_crea
32c80 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d  te_function16()]
32c90 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f   routines that o
32ca0 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67  riginally.** reg
32cb0 69 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c  istered the appl
32cc0 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20  ication defined 
32cd0 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  function..**.** 
32ce0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73  This routine mus
32cf0 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  t be called from
32d00 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
32d10 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65   in which.** the
32d20 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
32d30 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73  ined function is
32d40 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c   running..*/.SQL
32d50 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71  ITE_API void *sq
32d60 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28  lite3_user_data(
32d70 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
32d80 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
32d90 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
32da0 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46 75 6e 63  nection For Func
32db0 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  tions.**.** ^The
32dc0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
32dd0 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20 69 6e 74  _db_handle() int
32de0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
32df0 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20   copy of.** the 
32e00 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b  pointer to the [
32e10 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
32e20 69 6f 6e 5d 20 28 74 68 65 20 31 73 74 20 70 61  ion] (the 1st pa
32e30 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74  rameter).** of t
32e40 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  he [sqlite3_crea
32e50 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a  te_function()].*
32e60 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  * and [sqlite3_c
32e70 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
32e80 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61  ()] routines tha
32e90 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20  t originally.** 
32ea0 72 65 67 69 73 74 65 72 65 64 20 74 68 65 20 61  registered the a
32eb0 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e  pplication defin
32ec0 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a  ed function..*/.
32ed0 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74  SQLITE_API sqlit
32ee0 65 33 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6e 74  e3 *sqlite3_cont
32ef0 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71  ext_db_handle(sq
32f00 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
32f10 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
32f20 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c  : Function Auxil
32f30 69 61 72 79 20 44 61 74 61 0a 2a 2a 0a 2a 2a 20  iary Data.**.** 
32f40 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
32f50 6d 61 79 20 62 65 20 75 73 65 64 20 62 79 20 28  may be used by (
32f60 6e 6f 6e 2d 61 67 67 72 65 67 61 74 65 29 20 53  non-aggregate) S
32f70 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 0a  QL functions to.
32f80 2a 2a 20 61 73 73 6f 63 69 61 74 65 20 6d 65 74  ** associate met
32f90 61 64 61 74 61 20 77 69 74 68 20 61 72 67 75 6d  adata with argum
32fa0 65 6e 74 20 76 61 6c 75 65 73 2e 20 49 66 20 74  ent values. If t
32fb0 68 65 20 73 61 6d 65 20 76 61 6c 75 65 20 69 73  he same value is
32fc0 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 6d 75   passed to.** mu
32fd0 6c 74 69 70 6c 65 20 69 6e 76 6f 63 61 74 69 6f  ltiple invocatio
32fe0 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 53  ns of the same S
32ff0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 64 75 72 69  QL function duri
33000 6e 67 20 71 75 65 72 79 20 65 78 65 63 75 74 69  ng query executi
33010 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d  on, under.** som
33020 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 20  e circumstances 
33030 74 68 65 20 61 73 73 6f 63 69 61 74 65 64 20 6d  the associated m
33040 65 74 61 64 61 74 61 20 6d 61 79 20 62 65 20 70  etadata may be p
33050 72 65 73 65 72 76 65 64 2e 20 20 41 6e 20 65 78  reserved.  An ex
33060 61 6d 70 6c 65 0a 2a 2a 20 6f 66 20 77 68 65 72  ample.** of wher
33070 65 20 74 68 69 73 20 6d 69 67 68 74 20 62 65 20  e this might be 
33080 75 73 65 66 75 6c 20 69 73 20 69 6e 20 61 20 72  useful is in a r
33090 65 67 75 6c 61 72 2d 65 78 70 72 65 73 73 69 6f  egular-expressio
330a0 6e 20 6d 61 74 63 68 69 6e 67 0a 2a 2a 20 66 75  n matching.** fu
330b0 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f 6d 70  nction. The comp
330c0 69 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f 66 20  iled version of 
330d0 74 68 65 20 72 65 67 75 6c 61 72 20 65 78 70 72  the regular expr
330e0 65 73 73 69 6f 6e 20 63 61 6e 20 62 65 20 73 74  ession can be st
330f0 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61 64  ored as.** metad
33100 61 74 61 20 61 73 73 6f 63 69 61 74 65 64 20 77  ata associated w
33110 69 74 68 20 74 68 65 20 70 61 74 74 65 72 6e 20  ith the pattern 
33120 73 74 72 69 6e 67 2e 20 20 0a 2a 2a 20 54 68 65  string.  .** The
33130 6e 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65  n as long as the
33140 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67 20   pattern string 
33150 72 65 6d 61 69 6e 73 20 74 68 65 20 73 61 6d 65  remains the same
33160 2c 0a 2a 2a 20 74 68 65 20 63 6f 6d 70 69 6c 65  ,.** the compile
33170 64 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73  d regular expres
33180 73 69 6f 6e 20 63 61 6e 20 62 65 20 72 65 75 73  sion can be reus
33190 65 64 20 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a  ed on multiple.*
331a0 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66  * invocations of
331b0 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69   the same functi
331c0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  on..**.** ^The s
331d0 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61  qlite3_get_auxda
331e0 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ta() interface r
331f0 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
33200 20 74 6f 20 74 68 65 20 6d 65 74 61 64 61 74 61   to the metadata
33210 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 62  .** associated b
33220 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65  y the sqlite3_se
33230 74 5f 61 75 78 64 61 74 61 28 29 20 66 75 6e 63  t_auxdata() func
33240 74 69 6f 6e 20 77 69 74 68 20 74 68 65 20 4e 74  tion with the Nt
33250 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 61  h argument.** va
33260 6c 75 65 20 74 6f 20 74 68 65 20 61 70 70 6c 69  lue to the appli
33270 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
33280 75 6e 63 74 69 6f 6e 2e 20 5e 49 66 20 74 68 65  unction. ^If the
33290 72 65 20 69 73 20 6e 6f 20 6d 65 74 61 64 61 74  re is no metadat
332a0 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20  a.** associated 
332b0 77 69 74 68 20 74 68 65 20 66 75 6e 63 74 69 6f  with the functio
332c0 6e 20 61 72 67 75 6d 65 6e 74 2c 20 74 68 69 73  n argument, this
332d0 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78   sqlite3_get_aux
332e0 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65  data() interface
332f0 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 4e 55  .** returns a NU
33300 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
33310 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73  * ^The sqlite3_s
33320 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50  et_auxdata(C,N,P
33330 2c 58 29 20 69 6e 74 65 72 66 61 63 65 20 73 61  ,X) interface sa
33340 76 65 73 20 50 20 61 73 20 6d 65 74 61 64 61 74  ves P as metadat
33350 61 20 66 6f 72 20 74 68 65 20 4e 2d 74 68 0a 2a  a for the N-th.*
33360 2a 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68  * argument of th
33370 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
33380 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20  fined function. 
33390 20 5e 53 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20   ^Subsequent.** 
333a0 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
333b0 5f 67 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e  _get_auxdata(C,N
333c0 29 20 72 65 74 75 72 6e 20 50 20 66 72 6f 6d 20  ) return P from 
333d0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 0a  the most recent.
333e0 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  ** sqlite3_set_a
333f0 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20  uxdata(C,N,P,X) 
33400 63 61 6c 6c 20 69 66 20 74 68 65 20 6d 65 74 61  call if the meta
33410 64 61 74 61 20 69 73 20 73 74 69 6c 6c 20 76 61  data is still va
33420 6c 69 64 20 6f 72 0a 2a 2a 20 4e 55 4c 4c 20 69  lid or.** NULL i
33430 66 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 68  f the metadata h
33440 61 73 20 62 65 65 6e 20 64 69 73 63 61 72 64 65  as been discarde
33450 64 2e 0a 2a 2a 20 5e 41 66 74 65 72 20 65 61 63  d..** ^After eac
33460 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  h call to sqlite
33470 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c  3_set_auxdata(C,
33480 4e 2c 50 2c 58 29 20 77 68 65 72 65 20 58 20 69  N,P,X) where X i
33490 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 53  s not NULL,.** S
334a0 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b  QLite will invok
334b0 65 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  e the destructor
334c0 20 66 75 6e 63 74 69 6f 6e 20 58 20 77 69 74 68   function X with
334d0 20 70 61 72 61 6d 65 74 65 72 20 50 20 65 78 61   parameter P exa
334e0 63 74 6c 79 0a 2a 2a 20 6f 6e 63 65 2c 20 77 68  ctly.** once, wh
334f0 65 6e 20 74 68 65 20 6d 65 74 61 64 61 74 61 20  en the metadata 
33500 69 73 20 64 69 73 63 61 72 64 65 64 2e 0a 2a 2a  is discarded..**
33510 20 53 51 4c 69 74 65 20 69 73 20 66 72 65 65 20   SQLite is free 
33520 74 6f 20 64 69 73 63 61 72 64 20 74 68 65 20 6d  to discard the m
33530 65 74 61 64 61 74 61 20 61 74 20 61 6e 79 20 74  etadata at any t
33540 69 6d 65 2c 20 69 6e 63 6c 75 64 69 6e 67 3a 20  ime, including: 
33550 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 77 68 65  <ul>.** <li> whe
33560 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  n the correspond
33570 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70 61 72  ing function par
33580 61 6d 65 74 65 72 20 63 68 61 6e 67 65 73 2c 20  ameter changes, 
33590 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 77 68 65 6e 20  or.** <li> when 
335a0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
335b0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69  ] or [sqlite3_fi
335c0 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 61 6c  nalize()] is cal
335d0 6c 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20  led for the.**  
335e0 20 20 20 20 53 51 4c 20 73 74 61 74 65 6d 65 6e      SQL statemen
335f0 74 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 77 68  t, or.** <li> wh
33600 65 6e 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  en sqlite3_set_a
33610 75 78 64 61 74 61 28 29 20 69 73 20 69 6e 76 6f  uxdata() is invo
33620 6b 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 65  ked again on the
33630 20 73 61 6d 65 20 70 61 72 61 6d 65 74 65 72 2c   same parameter,
33640 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 64 75 72 69   or.** <li> duri
33650 6e 67 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  ng the original 
33660 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
33670 61 74 61 28 29 20 63 61 6c 6c 20 77 68 65 6e 20  ata() call when 
33680 61 20 6d 65 6d 6f 72 79 20 0a 2a 2a 20 20 20 20  a memory .**    
33690 20 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72    allocation err
336a0 6f 72 20 6f 63 63 75 72 73 2e 20 3c 2f 75 6c 3e  or occurs. </ul>
336b0 29 5e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  )^.**.** Note th
336c0 65 20 6c 61 73 74 20 62 75 6c 6c 65 74 20 69 6e  e last bullet in
336d0 20 70 61 72 74 69 63 75 6c 61 72 2e 20 20 54 68   particular.  Th
336e0 65 20 64 65 73 74 72 75 63 74 6f 72 20 58 20 69  e destructor X i
336f0 6e 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65  n .** sqlite3_se
33700 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c  t_auxdata(C,N,P,
33710 58 29 20 6d 69 67 68 74 20 62 65 20 63 61 6c 6c  X) might be call
33720 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20  ed immediately, 
33730 62 65 66 6f 72 65 20 74 68 65 0a 2a 2a 20 73 71  before the.** sq
33740 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
33750 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 65 76  a() interface ev
33760 65 6e 20 72 65 74 75 72 6e 73 2e 20 20 48 65 6e  en returns.  Hen
33770 63 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  ce sqlite3_set_a
33780 75 78 64 61 74 61 28 29 0a 2a 2a 20 73 68 6f 75  uxdata().** shou
33790 6c 64 20 62 65 20 63 61 6c 6c 65 64 20 6e 65 61  ld be called nea
337a0 72 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65  r the end of the
337b0 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
337c0 65 6e 74 61 74 69 6f 6e 20 61 6e 64 20 74 68 65  entation and the
337d0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70  .** function imp
337e0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75  lementation shou
337f0 6c 64 20 6e 6f 74 20 6d 61 6b 65 20 61 6e 79 20  ld not make any 
33800 75 73 65 20 6f 66 20 50 20 61 66 74 65 72 0a 2a  use of P after.*
33810 2a 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  * sqlite3_set_au
33820 78 64 61 74 61 28 29 20 68 61 73 20 62 65 65 6e  xdata() has been
33830 20 63 61 6c 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e   called..**.** ^
33840 28 49 6e 20 70 72 61 63 74 69 63 65 2c 20 6d 65  (In practice, me
33850 74 61 64 61 74 61 20 69 73 20 70 72 65 73 65 72  tadata is preser
33860 76 65 64 20 62 65 74 77 65 65 6e 20 66 75 6e 63  ved between func
33870 74 69 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a  tion calls for.*
33880 2a 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d  * function param
33890 65 74 65 72 73 20 74 68 61 74 20 61 72 65 20 63  eters that are c
338a0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 63 6f 6e 73  ompile-time cons
338b0 74 61 6e 74 73 2c 20 69 6e 63 6c 75 64 69 6e 67  tants, including
338c0 20 6c 69 74 65 72 61 6c 0a 2a 2a 20 76 61 6c 75   literal.** valu
338d0 65 73 20 61 6e 64 20 5b 70 61 72 61 6d 65 74 65  es and [paramete
338e0 72 73 5d 20 61 6e 64 20 65 78 70 72 65 73 73 69  rs] and expressi
338f0 6f 6e 73 20 63 6f 6d 70 6f 73 65 64 20 66 72 6f  ons composed fro
33900 6d 20 74 68 65 20 73 61 6d 65 2e 29 5e 0a 2a 2a  m the same.)^.**
33910 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
33920 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  es must be calle
33930 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20  d from the same 
33940 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a  thread in which.
33950 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  ** the SQL funct
33960 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  ion is running..
33970 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  */.SQLITE_API vo
33980 69 64 20 2a 73 71 6c 69 74 65 33 5f 67 65 74 5f  id *sqlite3_get_
33990 61 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f  auxdata(sqlite3_
339a0 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 29  context*, int N)
339b0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  ;.SQLITE_API voi
339c0 64 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  d sqlite3_set_au
339d0 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f  xdata(sqlite3_co
339e0 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 2c 20 76  ntext*, int N, v
339f0 6f 69 64 2a 2c 20 76 6f 69 64 20 28 2a 29 28 76  oid*, void (*)(v
33a00 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20  oid*));.../*.** 
33a10 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 73 74 61  CAPI3REF: Consta
33a20 6e 74 73 20 44 65 66 69 6e 69 6e 67 20 53 70 65  nts Defining Spe
33a30 63 69 61 6c 20 44 65 73 74 72 75 63 74 6f 72 20  cial Destructor 
33a40 42 65 68 61 76 69 6f 72 0a 2a 2a 0a 2a 2a 20 54  Behavior.**.** T
33a50 68 65 73 65 20 61 72 65 20 73 70 65 63 69 61 6c  hese are special
33a60 20 76 61 6c 75 65 73 20 66 6f 72 20 74 68 65 20   values for the 
33a70 64 65 73 74 72 75 63 74 6f 72 20 74 68 61 74 20  destructor that 
33a80 69 73 20 70 61 73 73 65 64 20 69 6e 20 61 73 20  is passed in as 
33a90 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67  the.** final arg
33aa0 75 6d 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65  ument to routine
33ab0 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f  s like [sqlite3_
33ac0 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20  result_blob()]. 
33ad0 20 5e 49 66 20 74 68 65 20 64 65 73 74 72 75 63   ^If the destruc
33ae0 74 6f 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  tor.** argument 
33af0 69 73 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43  is SQLITE_STATIC
33b00 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20  , it means that 
33b10 74 68 65 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e  the content poin
33b20 74 65 72 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a  ter is constant.
33b30 2a 2a 20 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65  ** and will neve
33b40 72 20 63 68 61 6e 67 65 2e 20 20 49 74 20 64 6f  r change.  It do
33b50 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62  es not need to b
33b60 65 20 64 65 73 74 72 6f 79 65 64 2e 20 20 5e 54  e destroyed.  ^T
33b70 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52 41  he.** SQLITE_TRA
33b80 4e 53 49 45 4e 54 20 76 61 6c 75 65 20 6d 65 61  NSIENT value mea
33b90 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74  ns that the cont
33ba0 65 6e 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20  ent will likely 
33bb0 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 65  change in.** the
33bc0 20 6e 65 61 72 20 66 75 74 75 72 65 20 61 6e 64   near future and
33bd0 20 74 68 61 74 20 53 51 4c 69 74 65 20 73 68 6f   that SQLite sho
33be0 75 6c 64 20 6d 61 6b 65 20 69 74 73 20 6f 77 6e  uld make its own
33bf0 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66   private copy of
33c00 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  .** the content 
33c10 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67  before returning
33c20 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65  ..**.** The type
33c30 64 65 66 20 69 73 20 6e 65 63 65 73 73 61 72 79  def is necessary
33c40 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20   to work around 
33c50 70 72 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72 74  problems in cert
33c60 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69  ain.** C++ compi
33c70 6c 65 72 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  lers..*/.typedef
33c80 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 33 5f   void (*sqlite3_
33c90 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29  destructor_type)
33ca0 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69 6e 65  (void*);.#define
33cb0 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 20 20   SQLITE_STATIC  
33cc0 20 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65      ((sqlite3_de
33cd0 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 30 29  structor_type)0)
33ce0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
33cf0 54 52 41 4e 53 49 45 4e 54 20 20 20 28 28 73 71  TRANSIENT   ((sq
33d00 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72  lite3_destructor
33d10 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a  _type)-1)../*.**
33d20 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 74 69   CAPI3REF: Setti
33d30 6e 67 20 54 68 65 20 52 65 73 75 6c 74 20 4f 66  ng The Result Of
33d40 20 41 6e 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e   An SQL Function
33d50 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
33d60 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 20 62  tines are used b
33d70 79 20 74 68 65 20 78 46 75 6e 63 20 6f 72 20 78  y the xFunc or x
33d80 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20  Final callbacks 
33d90 74 68 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  that.** implemen
33da0 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  t SQL functions 
33db0 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e 20  and aggregates. 
33dc0 20 53 65 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   See.** [sqlite3
33dd0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
33de0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
33df0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
33e00 31 36 28 29 5d 0a 2a 2a 20 66 6f 72 20 61 64 64  16()].** for add
33e10 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74  itional informat
33e20 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ion..**.** These
33e30 20 66 75 6e 63 74 69 6f 6e 73 20 77 6f 72 6b 20   functions work 
33e40 76 65 72 79 20 6d 75 63 68 20 6c 69 6b 65 20 74  very much like t
33e50 68 65 20 5b 70 61 72 61 6d 65 74 65 72 20 62 69  he [parameter bi
33e60 6e 64 69 6e 67 5d 20 66 61 6d 69 6c 79 20 6f 66  nding] family of
33e70 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 75 73  .** functions us
33e80 65 64 20 74 6f 20 62 69 6e 64 20 76 61 6c 75 65  ed to bind value
33e90 73 20 74 6f 20 68 6f 73 74 20 70 61 72 61 6d 65  s to host parame
33ea0 74 65 72 73 20 69 6e 20 70 72 65 70 61 72 65 64  ters in prepared
33eb0 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20   statements..** 
33ec0 52 65 66 65 72 20 74 6f 20 74 68 65 20 5b 53 51  Refer to the [SQ
33ed0 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 64 6f 63  L parameter] doc
33ee0 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61  umentation for a
33ef0 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
33f00 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ation..**.** ^Th
33f10 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
33f20 5f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63  _blob() interfac
33f30 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c  e sets the resul
33f40 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70  t from.** an app
33f50 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
33f60 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
33f70 74 68 65 20 42 4c 4f 42 20 77 68 6f 73 65 20 63  the BLOB whose c
33f80 6f 6e 74 65 6e 74 20 69 73 20 70 6f 69 6e 74 65  ontent is pointe
33f90 64 0a 2a 2a 20 74 6f 20 62 79 20 74 68 65 20 73  d.** to by the s
33fa0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
33fb0 61 6e 64 20 77 68 69 63 68 20 69 73 20 4e 20 62  and which is N b
33fc0 79 74 65 73 20 6c 6f 6e 67 20 77 68 65 72 65 20  ytes long where 
33fd0 4e 20 69 73 20 74 68 65 0a 2a 2a 20 74 68 69 72  N is the.** thir
33fe0 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  d parameter..**.
33ff0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
34000 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28  result_zeroblob(
34010 29 20 69 6e 74 65 72 66 61 63 65 73 20 73 65 74  ) interfaces set
34020 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a   the result of.*
34030 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * the applicatio
34040 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
34050 6f 6e 20 74 6f 20 62 65 20 61 20 42 4c 4f 42 20  on to be a BLOB 
34060 63 6f 6e 74 61 69 6e 69 6e 67 20 61 6c 6c 20 7a  containing all z
34070 65 72 6f 0a 2a 2a 20 62 79 74 65 73 20 61 6e 64  ero.** bytes and
34080 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65   N bytes in size
34090 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  , where N is the
340a0 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 32 6e   value of the 2n
340b0 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  d parameter..**.
340c0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
340d0 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 29 20  result_double() 
340e0 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
340f0 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a  he result from.*
34100 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  * an application
34110 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
34120 6e 20 74 6f 20 62 65 20 61 20 66 6c 6f 61 74 69  n to be a floati
34130 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 73  ng point value s
34140 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 69  pecified.** by i
34150 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e  ts 2nd argument.
34160 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
34170 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
34180 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72  () and sqlite3_r
34190 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20  esult_error16() 
341a0 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63 61 75  functions.** cau
341b0 73 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  se the implement
341c0 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ed SQL function 
341d0 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 78 63 65  to throw an exce
341e0 70 74 69 6f 6e 2e 0a 2a 2a 20 5e 53 51 4c 69 74  ption..** ^SQLit
341f0 65 20 75 73 65 73 20 74 68 65 20 73 74 72 69 6e  e uses the strin
34200 67 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20  g pointed to by 
34210 74 68 65 0a 2a 2a 20 32 6e 64 20 70 61 72 61 6d  the.** 2nd param
34220 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f  eter of sqlite3_
34230 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f  result_error() o
34240 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
34250 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 61 73  _error16().** as
34260 20 74 68 65 20 74 65 78 74 20 6f 66 20 61 6e 20   the text of an 
34270 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 20 20  error message.  
34280 5e 53 51 4c 69 74 65 20 69 6e 74 65 72 70 72 65  ^SQLite interpre
34290 74 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20  ts the error.** 
342a0 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 66  message string f
342b0 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75  rom sqlite3_resu
342c0 6c 74 5f 65 72 72 6f 72 28 29 20 61 73 20 55 54  lt_error() as UT
342d0 46 2d 38 2e 20 5e 53 51 4c 69 74 65 0a 2a 2a 20  F-8. ^SQLite.** 
342e0 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 73  interprets the s
342f0 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74  tring from sqlit
34300 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
34310 36 28 29 20 61 73 20 55 54 46 2d 31 36 20 69 6e  6() as UTF-16 in
34320 20 6e 61 74 69 76 65 0a 2a 2a 20 62 79 74 65 20   native.** byte 
34330 6f 72 64 65 72 2e 20 20 5e 49 66 20 74 68 65 20  order.  ^If the 
34340 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
34350 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  to sqlite3_resul
34360 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20  t_error().** or 
34370 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
34380 72 72 6f 72 31 36 28 29 20 69 73 20 6e 65 67 61  rror16() is nega
34390 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65  tive then SQLite
343a0 20 74 61 6b 65 73 20 61 73 20 74 68 65 20 65 72   takes as the er
343b0 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 61  ror.** message a
343c0 6c 6c 20 74 65 78 74 20 75 70 20 74 68 72 6f 75  ll text up throu
343d0 67 68 20 74 68 65 20 66 69 72 73 74 20 7a 65 72  gh the first zer
343e0 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20  o character..** 
343f0 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61  ^If the third pa
34400 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
34410 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
34420 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ) or.** sqlite3_
34430 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
34440 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
34450 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b   then SQLite tak
34460 65 73 20 74 68 61 74 20 6d 61 6e 79 0a 2a 2a 20  es that many.** 
34470 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61  bytes (not chara
34480 63 74 65 72 73 29 20 66 72 6f 6d 20 74 68 65 20  cters) from the 
34490 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 73  2nd parameter as
344a0 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
344b0 67 65 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  ge..** ^The sqli
344c0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
344d0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72  () and sqlite3_r
344e0 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a  esult_error16().
344f0 2a 2a 20 72 6f 75 74 69 6e 65 73 20 6d 61 6b 65  ** routines make
34500 20 61 20 70 72 69 76 61 74 65 20 63 6f 70 79 20   a private copy 
34510 6f 66 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  of the error mes
34520 73 61 67 65 20 74 65 78 74 20 62 65 66 6f 72 65  sage text before
34530 0a 2a 2a 20 74 68 65 79 20 72 65 74 75 72 6e 2e  .** they return.
34540 20 20 48 65 6e 63 65 2c 20 74 68 65 20 63 61 6c    Hence, the cal
34550 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61  ling function ca
34560 6e 20 64 65 61 6c 6c 6f 63 61 74 65 20 6f 72 0a  n deallocate or.
34570 2a 2a 20 6d 6f 64 69 66 79 20 74 68 65 20 74 65  ** modify the te
34580 78 74 20 61 66 74 65 72 20 74 68 65 79 20 72 65  xt after they re
34590 74 75 72 6e 20 77 69 74 68 6f 75 74 20 68 61 72  turn without har
345a0 6d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  m..** ^The sqlit
345b0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f  e3_result_error_
345c0 63 6f 64 65 28 29 20 66 75 6e 63 74 69 6f 6e 20  code() function 
345d0 63 68 61 6e 67 65 73 20 74 68 65 20 65 72 72 6f  changes the erro
345e0 72 20 63 6f 64 65 0a 2a 2a 20 72 65 74 75 72 6e  r code.** return
345f0 65 64 20 62 79 20 53 51 4c 69 74 65 20 61 73 20  ed by SQLite as 
34600 61 20 72 65 73 75 6c 74 20 6f 66 20 61 6e 20 65  a result of an e
34610 72 72 6f 72 20 69 6e 20 61 20 66 75 6e 63 74 69  rror in a functi
34620 6f 6e 2e 20 20 5e 42 79 20 64 65 66 61 75 6c 74  on.  ^By default
34630 2c 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 63  ,.** the error c
34640 6f 64 65 20 69 73 20 53 51 4c 49 54 45 5f 45 52  ode is SQLITE_ER
34650 52 4f 52 2e 20 20 5e 41 20 73 75 62 73 65 71 75  ROR.  ^A subsequ
34660 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  ent call to sqli
34670 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
34680 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  ().** or sqlite3
34690 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
346a0 29 20 72 65 73 65 74 73 20 74 68 65 20 65 72 72  ) resets the err
346b0 6f 72 20 63 6f 64 65 20 74 6f 20 53 51 4c 49 54  or code to SQLIT
346c0 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20 5e  E_ERROR..**.** ^
346d0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
346e0 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28  lt_error_toobig(
346f0 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73  ) interface caus
34700 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72  es SQLite to thr
34710 6f 77 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 69  ow an.** error i
34720 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 61  ndicating that a
34730 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20   string or BLOB 
34740 69 73 20 74 6f 6f 20 6c 6f 6e 67 20 74 6f 20 72  is too long to r
34750 65 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  epresent..**.** 
34760 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
34770 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28  ult_error_nomem(
34780 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73  ) interface caus
34790 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72  es SQLite to thr
347a0 6f 77 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 69  ow an.** error i
347b0 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 61  ndicating that a
347c0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
347d0 6f 6e 20 66 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a  on failed..**.**
347e0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
347f0 73 75 6c 74 5f 69 6e 74 28 29 20 69 6e 74 65 72  sult_int() inter
34800 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65  face sets the re
34810 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66  turn value.** of
34820 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
34830 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
34840 6e 20 74 6f 20 62 65 20 74 68 65 20 33 32 2d 62  n to be the 32-b
34850 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65  it signed intege
34860 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e  r.** value given
34870 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75   in the 2nd argu
34880 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  ment..** ^The sq
34890 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
348a0 36 34 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  64() interface s
348b0 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76  ets the return v
348c0 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61  alue.** of the a
348d0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
348e0 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
348f0 65 20 74 68 65 20 36 34 2d 62 69 74 20 73 69 67  e the 64-bit sig
34900 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76  ned integer.** v
34910 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68  alue given in th
34920 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a  e 2nd argument..
34930 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
34940 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 29  e3_result_null()
34950 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
34960 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
34970 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69  .** of the appli
34980 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
34990 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 4e 55  unction to be NU
349a0 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  LL..**.** ^The s
349b0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
349c0 78 74 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65  xt(), sqlite3_re
349d0 73 75 6c 74 5f 74 65 78 74 31 36 28 29 2c 0a 2a  sult_text16(),.*
349e0 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  * sqlite3_result
349f0 5f 74 65 78 74 31 36 6c 65 28 29 2c 20 61 6e 64  _text16le(), and
34a00 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
34a10 74 65 78 74 31 36 62 65 28 29 20 69 6e 74 65 72  text16be() inter
34a20 66 61 63 65 73 0a 2a 2a 20 73 65 74 20 74 68 65  faces.** set the
34a30 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
34a40 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
34a50 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
34a60 6e 20 74 6f 20 62 65 0a 2a 2a 20 61 20 74 65 78  n to be.** a tex
34a70 74 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 69  t string which i
34a80 73 20 72 65 70 72 65 73 65 6e 74 65 64 20 61 73  s represented as
34a90 20 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 20 6e   UTF-8, UTF-16 n
34aa0 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
34ab0 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74 74  ,.** UTF-16 litt
34ac0 6c 65 20 65 6e 64 69 61 6e 2c 20 6f 72 20 55 54  le endian, or UT
34ad0 46 2d 31 36 20 62 69 67 20 65 6e 64 69 61 6e 2c  F-16 big endian,
34ae0 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a   respectively..*
34af0 2a 20 5e 53 51 4c 69 74 65 20 74 61 6b 65 73 20  * ^SQLite takes 
34b00 74 68 65 20 74 65 78 74 20 72 65 73 75 6c 74 20  the text result 
34b10 66 72 6f 6d 20 74 68 65 20 61 70 70 6c 69 63 61  from the applica
34b20 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68 65  tion from.** the
34b30 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f   2nd parameter o
34b40 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  f the sqlite3_re
34b50 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
34b60 66 61 63 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68  faces..** ^If th
34b70 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  e 3rd parameter 
34b80 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72  to the sqlite3_r
34b90 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65  esult_text* inte
34ba0 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 65 67  rfaces.** is neg
34bb0 61 74 69 76 65 2c 20 74 68 65 6e 20 53 51 4c 69  ative, then SQLi
34bc0 74 65 20 74 61 6b 65 73 20 72 65 73 75 6c 74 20  te takes result 
34bd0 74 65 78 74 20 66 72 6f 6d 20 74 68 65 20 32 6e  text from the 2n
34be0 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74  d parameter.** t
34bf0 68 72 6f 75 67 68 20 74 68 65 20 66 69 72 73 74  hrough the first
34c00 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e   zero character.
34c10 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33 72 64 20  .** ^If the 3rd 
34c20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
34c30 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
34c40 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
34c50 0a 2a 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  .** is non-negat
34c60 69 76 65 2c 20 74 68 65 6e 20 61 73 20 6d 61 6e  ive, then as man
34c70 79 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61  y bytes (not cha
34c80 72 61 63 74 65 72 73 29 20 6f 66 20 74 68 65 20  racters) of the 
34c90 74 65 78 74 0a 2a 2a 20 70 6f 69 6e 74 65 64 20  text.** pointed 
34ca0 74 6f 20 62 79 20 74 68 65 20 32 6e 64 20 70 61  to by the 2nd pa
34cb0 72 61 6d 65 74 65 72 20 61 72 65 20 74 61 6b 65  rameter are take
34cc0 6e 20 61 73 20 74 68 65 20 61 70 70 6c 69 63 61  n as the applica
34cd0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a 20  tion-defined.** 
34ce0 66 75 6e 63 74 69 6f 6e 20 72 65 73 75 6c 74 2e  function result.
34cf0 20 20 49 66 20 74 68 65 20 33 72 64 20 70 61 72    If the 3rd par
34d00 61 6d 65 74 65 72 20 69 73 20 6e 6f 6e 2d 6e 65  ameter is non-ne
34d10 67 61 74 69 76 65 2c 20 74 68 65 6e 20 69 74 0a  gative, then it.
34d20 2a 2a 20 6d 75 73 74 20 62 65 20 74 68 65 20 62  ** must be the b
34d30 79 74 65 20 6f 66 66 73 65 74 20 69 6e 74 6f 20  yte offset into 
34d40 74 68 65 20 73 74 72 69 6e 67 20 77 68 65 72 65  the string where
34d50 20 74 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61   the NUL termina
34d60 74 6f 72 20 77 6f 75 6c 64 0a 2a 2a 20 61 70 70  tor would.** app
34d70 65 61 72 20 69 66 20 74 68 65 20 73 74 72 69 6e  ear if the strin
34d80 67 20 77 68 65 72 65 20 4e 55 4c 20 74 65 72 6d  g where NUL term
34d90 69 6e 61 74 65 64 2e 20 20 49 66 20 61 6e 79 20  inated.  If any 
34da0 4e 55 4c 20 63 68 61 72 61 63 74 65 72 73 20 6f  NUL characters o
34db0 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 73  ccur.** in the s
34dc0 74 72 69 6e 67 20 61 74 20 61 20 62 79 74 65 20  tring at a byte 
34dd0 6f 66 66 73 65 74 20 74 68 61 74 20 69 73 20 6c  offset that is l
34de0 65 73 73 20 74 68 61 6e 20 74 68 65 20 76 61 6c  ess than the val
34df0 75 65 20 6f 66 20 74 68 65 20 33 72 64 0a 2a 2a  ue of the 3rd.**
34e00 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e   parameter, then
34e10 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73   the resulting s
34e20 74 72 69 6e 67 20 77 69 6c 6c 20 63 6f 6e 74 61  tring will conta
34e30 69 6e 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73  in embedded NULs
34e40 20 61 6e 64 20 74 68 65 0a 2a 2a 20 72 65 73 75   and the.** resu
34e50 6c 74 20 6f 66 20 65 78 70 72 65 73 73 69 6f 6e  lt of expression
34e60 73 20 6f 70 65 72 61 74 69 6e 67 20 6f 6e 20 73  s operating on s
34e70 74 72 69 6e 67 73 20 77 69 74 68 20 65 6d 62 65  trings with embe
34e80 64 64 65 64 20 4e 55 4c 73 20 69 73 20 75 6e 64  dded NULs is und
34e90 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20 74  efined..** ^If t
34ea0 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  he 4th parameter
34eb0 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
34ec0 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74  result_text* int
34ed0 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71  erfaces.** or sq
34ee0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
34ef0 62 20 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20  b is a non-NULL 
34f00 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51  pointer, then SQ
34f10 4c 69 74 65 20 63 61 6c 6c 73 20 74 68 61 74 0a  Lite calls that.
34f20 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 61 73 20 74  ** function as t
34f30 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e  he destructor on
34f40 20 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f   the text or BLO
34f50 42 20 72 65 73 75 6c 74 20 77 68 65 6e 20 69 74  B result when it
34f60 20 68 61 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64   has.** finished
34f70 20 75 73 69 6e 67 20 74 68 61 74 20 72 65 73 75   using that resu
34f80 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34  lt..** ^If the 4
34f90 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
34fa0 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
34fb0 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
34fc0 63 65 73 20 6f 72 20 74 6f 0a 2a 2a 20 73 71 6c  ces or to.** sql
34fd0 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
34fe0 20 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 20   is the special 
34ff0 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f  constant SQLITE_
35000 53 54 41 54 49 43 2c 20 74 68 65 6e 20 53 51 4c  STATIC, then SQL
35010 69 74 65 0a 2a 2a 20 61 73 73 75 6d 65 73 20 74  ite.** assumes t
35020 68 61 74 20 74 68 65 20 74 65 78 74 20 6f 72 20  hat the text or 
35030 42 4c 4f 42 20 72 65 73 75 6c 74 20 69 73 20 69  BLOB result is i
35040 6e 20 63 6f 6e 73 74 61 6e 74 20 73 70 61 63 65  n constant space
35050 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a   and does not.**
35060 20 63 6f 70 79 20 74 68 65 20 63 6f 6e 74 65 6e   copy the conten
35070 74 20 6f 66 20 74 68 65 20 70 61 72 61 6d 65 74  t of the paramet
35080 65 72 20 6e 6f 72 20 63 61 6c 6c 20 61 20 64 65  er nor call a de
35090 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20  structor on the 
350a0 63 6f 6e 74 65 6e 74 0a 2a 2a 20 77 68 65 6e 20  content.** when 
350b0 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  it has finished 
350c0 75 73 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c  using that resul
350d0 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74  t..** ^If the 4t
350e0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
350f0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
35100 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
35110 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  es.** or sqlite3
35120 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20  _result_blob is 
35130 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73  the special cons
35140 74 61 6e 74 20 53 51 4c 49 54 45 5f 54 52 41 4e  tant SQLITE_TRAN
35150 53 49 45 4e 54 0a 2a 2a 20 74 68 65 6e 20 53 51  SIENT.** then SQ
35160 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70  Lite makes a cop
35170 79 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  y of the result 
35180 69 6e 74 6f 20 73 70 61 63 65 20 6f 62 74 61 69  into space obtai
35190 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f 6d  ned from.** from
351a0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
351b0 28 29 5d 20 62 65 66 6f 72 65 20 69 74 20 72 65  ()] before it re
351c0 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  turns..**.** ^Th
351d0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
351e0 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61  _value() interfa
351f0 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75  ce sets the resu
35200 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70  lt of.** the app
35210 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
35220 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
35230 61 20 63 6f 70 79 20 74 68 65 0a 2a 2a 20 5b 75  a copy the.** [u
35240 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
35250 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
35260 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68   specified by th
35270 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e  e 2nd parameter.
35280 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65    ^The.** sqlite
35290 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29  3_result_value()
352a0 20 69 6e 74 65 72 66 61 63 65 20 6d 61 6b 65 73   interface makes
352b0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b   a copy of the [
352c0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a  sqlite3_value].*
352d0 2a 20 73 6f 20 74 68 61 74 20 74 68 65 20 5b 73  * so that the [s
352e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 73 70  qlite3_value] sp
352f0 65 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 70  ecified in the p
35300 61 72 61 6d 65 74 65 72 20 6d 61 79 20 63 68 61  arameter may cha
35310 6e 67 65 20 6f 72 0a 2a 2a 20 62 65 20 64 65 61  nge or.** be dea
35320 6c 6c 6f 63 61 74 65 64 20 61 66 74 65 72 20 73  llocated after s
35330 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
35340 6c 75 65 28 29 20 72 65 74 75 72 6e 73 20 77 69  lue() returns wi
35350 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e  thout harm..** ^
35360 41 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  A [protected sql
35370 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
35380 63 74 20 6d 61 79 20 61 6c 77 61 79 73 20 62 65  ct may always be
35390 20 75 73 65 64 20 77 68 65 72 65 20 61 6e 0a 2a   used where an.*
353a0 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  * [unprotected s
353b0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
353c0 6a 65 63 74 20 69 73 20 72 65 71 75 69 72 65 64  ject is required
353d0 2c 20 73 6f 20 65 69 74 68 65 72 0a 2a 2a 20 6b  , so either.** k
353e0 69 6e 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ind of [sqlite3_
353f0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 63 61  value] object ca
35400 6e 20 62 65 20 75 73 65 64 20 77 69 74 68 20 74  n be used with t
35410 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  his interface..*
35420 2a 0a 2a 2a 20 49 66 20 74 68 65 73 65 20 72 6f  *.** If these ro
35430 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65  utines are calle
35440 64 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 74 68  d from within th
35450 65 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65  e different thre
35460 61 64 0a 2a 2a 20 74 68 61 6e 20 74 68 65 20 6f  ad.** than the o
35470 6e 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  ne containing th
35480 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
35490 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
354a0 68 61 74 20 72 65 63 65 69 76 65 64 0a 2a 2a 20  hat received.** 
354b0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  the [sqlite3_con
354c0 74 65 78 74 5d 20 70 6f 69 6e 74 65 72 2c 20 74  text] pointer, t
354d0 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75  he results are u
354e0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 53 51 4c  ndefined..*/.SQL
354f0 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c  ITE_API void sql
35500 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
35510 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
35520 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
35530 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  int, void(*)(voi
35540 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  d*));.SQLITE_API
35550 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65   void sqlite3_re
35560 73 75 6c 74 5f 64 6f 75 62 6c 65 28 73 71 6c 69  sult_double(sqli
35570 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 64 6f  te3_context*, do
35580 75 62 6c 65 29 3b 0a 53 51 4c 49 54 45 5f 41 50  uble);.SQLITE_AP
35590 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  I void sqlite3_r
355a0 65 73 75 6c 74 5f 65 72 72 6f 72 28 73 71 6c 69  esult_error(sqli
355b0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
355c0 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 29 3b  nst char*, int);
355d0 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
355e0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
355f0 65 72 72 6f 72 31 36 28 73 71 6c 69 74 65 33 5f  error16(sqlite3_
35600 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
35610 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c  void*, int);.SQL
35620 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c  ITE_API void sql
35630 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
35640 72 5f 74 6f 6f 62 69 67 28 73 71 6c 69 74 65 33  r_toobig(sqlite3
35650 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49  _context*);.SQLI
35660 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69  TE_API void sqli
35670 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
35680 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74 65 33 5f 63  _nomem(sqlite3_c
35690 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45  ontext*);.SQLITE
356a0 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65  _API void sqlite
356b0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63  3_result_error_c
356c0 6f 64 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ode(sqlite3_cont
356d0 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49  ext*, int);.SQLI
356e0 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69  TE_API void sqli
356f0 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73  te3_result_int(s
35700 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
35710 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50   int);.SQLITE_AP
35720 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  I void sqlite3_r
35730 65 73 75 6c 74 5f 69 6e 74 36 34 28 73 71 6c 69  esult_int64(sqli
35740 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71  te3_context*, sq
35750 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 53 51  lite3_int64);.SQ
35760 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71  LITE_API void sq
35770 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c  lite3_result_nul
35780 6c 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  l(sqlite3_contex
35790 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  t*);.SQLITE_API 
357a0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
357b0 75 6c 74 5f 74 65 78 74 28 73 71 6c 69 74 65 33  ult_text(sqlite3
357c0 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
357d0 20 63 68 61 72 2a 2c 20 69 6e 74 2c 20 76 6f 69   char*, int, voi
357e0 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51  d(*)(void*));.SQ
357f0 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71  LITE_API void sq
35800 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
35810 74 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  t16(sqlite3_cont
35820 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ext*, const void
35830 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28  *, int, void(*)(
35840 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f  void*));.SQLITE_
35850 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33  API void sqlite3
35860 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65  _result_text16le
35870 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
35880 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
35890 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64  int,void(*)(void
358a0 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  *));.SQLITE_API 
358b0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
358c0 75 6c 74 5f 74 65 78 74 31 36 62 65 28 73 71 6c  ult_text16be(sql
358d0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
358e0 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c  onst void*, int,
358f0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
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 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 63 6f  value(sqlite3_co
35930 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f  ntext*, sqlite3_
35940 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f  value*);.SQLITE_
35950 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33  API void sqlite3
35960 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62  _result_zeroblob
35970 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
35980 2a 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a  *, int n);../*.*
35990 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 66 69  * CAPI3REF: Defi
359a0 6e 65 20 4e 65 77 20 43 6f 6c 6c 61 74 69 6e 67  ne New Collating
359b0 20 53 65 71 75 65 6e 63 65 73 0a 2a 2a 0a 2a 2a   Sequences.**.**
359c0 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e   ^These function
359d0 73 20 61 64 64 2c 20 72 65 6d 6f 76 65 2c 20 6f  s add, remove, o
359e0 72 20 6d 6f 64 69 66 79 20 61 20 5b 63 6f 6c 6c  r modify a [coll
359f0 61 74 69 6f 6e 5d 20 61 73 73 6f 63 69 61 74 65  ation] associate
35a00 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 64  d.** with the [d
35a10 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
35a20 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 61 73  on] specified as
35a30 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
35a40 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ent..**.** ^The 
35a50 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 6c  name of the coll
35a60 61 74 69 6f 6e 20 69 73 20 61 20 55 54 46 2d 38  ation is a UTF-8
35a70 20 73 74 72 69 6e 67 0a 2a 2a 20 66 6f 72 20 73   string.** for s
35a80 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
35a90 6c 6c 61 74 69 6f 6e 28 29 20 61 6e 64 20 73 71  llation() and sq
35aa0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
35ab0 6c 61 74 69 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61  lation_v2().** a
35ac0 6e 64 20 61 20 55 54 46 2d 31 36 20 73 74 72 69  nd a UTF-16 stri
35ad0 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74  ng in native byt
35ae0 65 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69  e order for sqli
35af0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
35b00 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a 20 5e 43 6f  tion16()..** ^Co
35b10 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65 73 20 74 68  llation names th
35b20 61 74 20 63 6f 6d 70 61 72 65 20 65 71 75 61 6c  at compare equal
35b30 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 5b 73   according to [s
35b40 71 6c 69 74 65 33 5f 73 74 72 6e 69 63 6d 70 28  qlite3_strnicmp(
35b50 29 5d 20 61 72 65 0a 2a 2a 20 63 6f 6e 73 69 64  )] are.** consid
35b60 65 72 65 64 20 74 6f 20 62 65 20 74 68 65 20 73  ered to be the s
35b70 61 6d 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20  ame name..**.** 
35b80 5e 28 54 68 65 20 74 68 69 72 64 20 61 72 67 75  ^(The third argu
35b90 6d 65 6e 74 20 28 65 54 65 78 74 52 65 70 29 20  ment (eTextRep) 
35ba0 6d 75 73 74 20 62 65 20 6f 6e 65 20 6f 66 20 74  must be one of t
35bb0 68 65 20 63 6f 6e 73 74 61 6e 74 73 3a 0a 2a 2a  he constants:.**
35bc0 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53   <ul>.** <li> [S
35bd0 51 4c 49 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20  QLITE_UTF8],.** 
35be0 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46  <li> [SQLITE_UTF
35bf0 31 36 4c 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  16LE],.** <li> [
35c00 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c  SQLITE_UTF16BE],
35c10 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
35c20 5f 55 54 46 31 36 5d 2c 20 6f 72 0a 2a 2a 20 3c  _UTF16], or.** <
35c30 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  li> [SQLITE_UTF1
35c40 36 5f 41 4c 49 47 4e 45 44 5d 2e 0a 2a 2a 20 3c  6_ALIGNED]..** <
35c50 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 54 68 65 20 65  /ul>)^.** ^The e
35c60 54 65 78 74 52 65 70 20 61 72 67 75 6d 65 6e 74  TextRep argument
35c70 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 65 20   determines the 
35c80 65 6e 63 6f 64 69 6e 67 20 6f 66 20 73 74 72 69  encoding of stri
35c90 6e 67 73 20 70 61 73 73 65 64 0a 2a 2a 20 74 6f  ngs passed.** to
35ca0 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66   the collating f
35cb0 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b  unction callback
35cc0 2c 20 78 43 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20  , xCallback..** 
35cd0 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 55 54 46  ^The [SQLITE_UTF
35ce0 31 36 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  16] and [SQLITE_
35cf0 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20 76  UTF16_ALIGNED] v
35d00 61 6c 75 65 73 20 66 6f 72 20 65 54 65 78 74 52  alues for eTextR
35d10 65 70 0a 2a 2a 20 66 6f 72 63 65 20 73 74 72 69  ep.** force stri
35d20 6e 67 73 20 74 6f 20 62 65 20 55 54 46 31 36 20  ngs to be UTF16 
35d30 77 69 74 68 20 6e 61 74 69 76 65 20 62 79 74 65  with native byte
35d40 20 6f 72 64 65 72 2e 0a 2a 2a 20 5e 54 68 65 20   order..** ^The 
35d50 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c  [SQLITE_UTF16_AL
35d60 49 47 4e 45 44 5d 20 76 61 6c 75 65 20 66 6f 72  IGNED] value for
35d70 20 65 54 65 78 74 52 65 70 20 66 6f 72 63 65 73   eTextRep forces
35d80 20 73 74 72 69 6e 67 73 20 74 6f 20 62 65 67 69   strings to begi
35d90 6e 0a 2a 2a 20 6f 6e 20 61 6e 20 65 76 65 6e 20  n.** on an even 
35da0 62 79 74 65 20 61 64 64 72 65 73 73 2e 0a 2a 2a  byte address..**
35db0 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20  .** ^The fourth 
35dc0 61 72 67 75 6d 65 6e 74 2c 20 70 41 72 67 2c 20  argument, pArg, 
35dd0 69 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  is an applicatio
35de0 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 20 74  n data pointer t
35df0 68 61 74 20 69 73 20 70 61 73 73 65 64 0a 2a 2a  hat is passed.**
35e00 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20   through as the 
35e10 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
35e20 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20  o the collating 
35e30 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63  function callbac
35e40 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  k..**.** ^The fi
35e50 66 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 78 43  fth argument, xC
35e60 61 6c 6c 62 61 63 6b 2c 20 69 73 20 61 20 70 6f  allback, is a po
35e70 69 6e 74 65 72 20 74 6f 20 74 68 65 20 63 6f 6c  inter to the col
35e80 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 2e  lating function.
35e90 0a 2a 2a 20 5e 4d 75 6c 74 69 70 6c 65 20 63 6f  .** ^Multiple co
35ea0 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
35eb0 73 20 63 61 6e 20 62 65 20 72 65 67 69 73 74 65  s can be registe
35ec0 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 73 61  red using the sa
35ed0 6d 65 20 6e 61 6d 65 20 62 75 74 0a 2a 2a 20 77  me name but.** w
35ee0 69 74 68 20 64 69 66 66 65 72 65 6e 74 20 65 54  ith different eT
35ef0 65 78 74 52 65 70 20 70 61 72 61 6d 65 74 65 72  extRep parameter
35f00 73 20 61 6e 64 20 53 51 4c 69 74 65 20 77 69 6c  s and SQLite wil
35f10 6c 20 75 73 65 20 77 68 69 63 68 65 76 65 72 0a  l use whichever.
35f20 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75  ** function requ
35f30 69 72 65 73 20 74 68 65 20 6c 65 61 73 74 20 61  ires the least a
35f40 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20 74 72  mount of data tr
35f50 61 6e 73 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a  ansformation..**
35f60 20 5e 49 66 20 74 68 65 20 78 43 61 6c 6c 62 61   ^If the xCallba
35f70 63 6b 20 61 72 67 75 6d 65 6e 74 20 69 73 20 4e  ck argument is N
35f80 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 63 6f 6c  ULL then the col
35f90 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  lating function 
35fa0 69 73 0a 2a 2a 20 64 65 6c 65 74 65 64 2e 20 20  is.** deleted.  
35fb0 5e 57 68 65 6e 20 61 6c 6c 20 63 6f 6c 6c 61 74  ^When all collat
35fc0 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 68 61  ing functions ha
35fd0 76 69 6e 67 20 74 68 65 20 73 61 6d 65 20 6e 61  ving the same na
35fe0 6d 65 20 61 72 65 20 64 65 6c 65 74 65 64 2c 0a  me are deleted,.
35ff0 2a 2a 20 74 68 61 74 20 63 6f 6c 6c 61 74 69 6f  ** that collatio
36000 6e 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 75  n is no longer u
36010 73 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  sable..**.** ^Th
36020 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  e collating func
36030 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 20 69 73  tion callback is
36040 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 20   invoked with a 
36050 63 6f 70 79 20 6f 66 20 74 68 65 20 70 41 72 67  copy of the pArg
36060 20 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e   .** application
36070 20 64 61 74 61 20 70 6f 69 6e 74 65 72 20 61 6e   data pointer an
36080 64 20 77 69 74 68 20 74 77 6f 20 73 74 72 69 6e  d with two strin
36090 67 73 20 69 6e 20 74 68 65 20 65 6e 63 6f 64 69  gs in the encodi
360a0 6e 67 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20  ng specified.** 
360b0 62 79 20 74 68 65 20 65 54 65 78 74 52 65 70 20  by the eTextRep 
360c0 61 72 67 75 6d 65 6e 74 2e 20 20 54 68 65 20 63  argument.  The c
360d0 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
360e0 6e 20 6d 75 73 74 20 72 65 74 75 72 6e 20 61 6e  n must return an
360f0 0a 2a 2a 20 69 6e 74 65 67 65 72 20 74 68 61 74  .** integer that
36100 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 7a 65   is negative, ze
36110 72 6f 2c 20 6f 72 20 70 6f 73 69 74 69 76 65 0a  ro, or positive.
36120 2a 2a 20 69 66 20 74 68 65 20 66 69 72 73 74 20  ** if the first 
36130 73 74 72 69 6e 67 20 69 73 20 6c 65 73 73 20 74  string is less t
36140 68 61 6e 2c 20 65 71 75 61 6c 20 74 6f 2c 20 6f  han, equal to, o
36150 72 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 74  r greater than t
36160 68 65 20 73 65 63 6f 6e 64 2c 0a 2a 2a 20 72 65  he second,.** re
36170 73 70 65 63 74 69 76 65 6c 79 2e 20 20 41 20 63  spectively.  A c
36180 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
36190 6e 20 6d 75 73 74 20 61 6c 77 61 79 73 20 72 65  n must always re
361a0 74 75 72 6e 20 74 68 65 20 73 61 6d 65 20 61 6e  turn the same an
361b0 73 77 65 72 0a 2a 2a 20 67 69 76 65 6e 20 74 68  swer.** given th
361c0 65 20 73 61 6d 65 20 69 6e 70 75 74 73 2e 20 20  e same inputs.  
361d0 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 63  If two or more c
361e0 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
361f0 6e 73 20 61 72 65 20 72 65 67 69 73 74 65 72 65  ns are registere
36200 64 0a 2a 2a 20 74 6f 20 74 68 65 20 73 61 6d 65  d.** to the same
36210 20 63 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65 20   collation name 
36220 28 75 73 69 6e 67 20 64 69 66 66 65 72 65 6e 74  (using different
36230 20 65 54 65 78 74 52 65 70 20 76 61 6c 75 65 73   eTextRep values
36240 29 20 74 68 65 6e 20 61 6c 6c 0a 2a 2a 20 6d 75  ) then all.** mu
36250 73 74 20 67 69 76 65 20 61 6e 20 65 71 75 69 76  st give an equiv
36260 61 6c 65 6e 74 20 61 6e 73 77 65 72 20 77 68 65  alent answer whe
36270 6e 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 65  n invoked with e
36280 71 75 69 76 61 6c 65 6e 74 20 73 74 72 69 6e 67  quivalent string
36290 73 2e 0a 2a 2a 20 54 68 65 20 63 6f 6c 6c 61 74  s..** The collat
362a0 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73  ing function mus
362b0 74 20 6f 62 65 79 20 74 68 65 20 66 6f 6c 6c 6f  t obey the follo
362c0 77 69 6e 67 20 70 72 6f 70 65 72 74 69 65 73 20  wing properties 
362d0 66 6f 72 20 61 6c 6c 0a 2a 2a 20 73 74 72 69 6e  for all.** strin
362e0 67 73 20 41 2c 20 42 2c 20 61 6e 64 20 43 3a 0a  gs A, B, and C:.
362f0 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c  **.** <ol>.** <l
36300 69 3e 20 49 66 20 41 3d 3d 42 20 74 68 65 6e 20  i> If A==B then 
36310 42 3d 3d 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66  B==A..** <li> If
36320 20 41 3d 3d 42 20 61 6e 64 20 42 3d 3d 43 20 74   A==B and B==C t
36330 68 65 6e 20 41 3d 3d 43 2e 0a 2a 2a 20 3c 6c 69  hen A==C..** <li
36340 3e 20 49 66 20 41 26 6c 74 3b 42 20 54 48 45 4e  > If A&lt;B THEN
36350 20 42 26 67 74 3b 41 2e 0a 2a 2a 20 3c 6c 69 3e   B&gt;A..** <li>
36360 20 49 66 20 41 26 6c 74 3b 42 20 61 6e 64 20 42   If A&lt;B and B
36370 26 6c 74 3b 43 20 74 68 65 6e 20 41 26 6c 74 3b  &lt;C then A&lt;
36380 43 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a  C..** </ol>.**.*
36390 2a 20 49 66 20 61 20 63 6f 6c 6c 61 74 69 6e 67  * If a collating
363a0 20 66 75 6e 63 74 69 6f 6e 20 66 61 69 6c 73 20   function fails 
363b0 61 6e 79 20 6f 66 20 74 68 65 20 61 62 6f 76 65  any of the above
363c0 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 61 6e 64   constraints and
363d0 20 74 68 61 74 0a 2a 2a 20 63 6f 6c 6c 61 74 69   that.** collati
363e0 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 20  ng function is  
363f0 72 65 67 69 73 74 65 72 65 64 20 61 6e 64 20 75  registered and u
36400 73 65 64 2c 20 74 68 65 6e 20 74 68 65 20 62 65  sed, then the be
36410 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65  havior of SQLite
36420 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64  .** is undefined
36430 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
36440 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
36450 61 74 69 6f 6e 5f 76 32 28 29 20 77 6f 72 6b 73  ation_v2() works
36460 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 63 72   like sqlite3_cr
36470 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29  eate_collation()
36480 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 61 64 64  .** with the add
36490 69 74 69 6f 6e 20 74 68 61 74 20 74 68 65 20 78  ition that the x
364a0 44 65 73 74 72 6f 79 20 63 61 6c 6c 62 61 63 6b  Destroy callback
364b0 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 70   is invoked on p
364c0 41 72 67 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20  Arg when.** the 
364d0 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
364e0 6f 6e 20 69 73 20 64 65 6c 65 74 65 64 2e 0a 2a  on is deleted..*
364f0 2a 20 5e 43 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  * ^Collating fun
36500 63 74 69 6f 6e 73 20 61 72 65 20 64 65 6c 65 74  ctions are delet
36510 65 64 20 77 68 65 6e 20 74 68 65 79 20 61 72 65  ed when they are
36520 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79 20 6c   overridden by l
36530 61 74 65 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f  ater.** calls to
36540 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 63   the collation c
36550 72 65 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e  reation function
36560 73 20 6f 72 20 77 68 65 6e 20 74 68 65 0a 2a 2a  s or when the.**
36570 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
36580 63 74 69 6f 6e 5d 20 69 73 20 63 6c 6f 73 65 64  ction] is closed
36590 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
365a0 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  close()]..**.** 
365b0 5e 54 68 65 20 78 44 65 73 74 72 6f 79 20 63 61  ^The xDestroy ca
365c0 6c 6c 62 61 63 6b 20 69 73 20 3c 75 3e 6e 6f 74  llback is <u>not
365d0 3c 2f 75 3e 20 63 61 6c 6c 65 64 20 69 66 20 74  </u> called if t
365e0 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  he .** sqlite3_c
365f0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
36600 76 32 28 29 20 66 75 6e 63 74 69 6f 6e 20 66 61  v2() function fa
36610 69 6c 73 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ils.  Applicatio
36620 6e 73 20 74 68 61 74 20 69 6e 76 6f 6b 65 0a 2a  ns that invoke.*
36630 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  * sqlite3_create
36640 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20  _collation_v2() 
36650 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20  with a non-NULL 
36660 78 44 65 73 74 72 6f 79 20 61 72 67 75 6d 65 6e  xDestroy argumen
36670 74 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 63 68 65  t should .** che
36680 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f  ck the return co
36690 64 65 20 61 6e 64 20 64 69 73 70 6f 73 65 20 6f  de and dispose o
366a0 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
366b0 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 0a 2a  n data pointer.*
366c0 2a 20 74 68 65 6d 73 65 6c 76 65 73 20 72 61 74  * themselves rat
366d0 68 65 72 20 74 68 61 6e 20 65 78 70 65 63 74 69  her than expecti
366e0 6e 67 20 53 51 4c 69 74 65 20 74 6f 20 64 65 61  ng SQLite to dea
366f0 6c 20 77 69 74 68 20 69 74 20 66 6f 72 20 74 68  l with it for th
36700 65 6d 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 64  em..** This is d
36710 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 65 76  ifferent from ev
36720 65 72 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65  ery other SQLite
36730 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68 65   interface.  The
36740 20 69 6e 63 6f 6e 73 69 73 74 65 6e 63 79 20 0a   inconsistency .
36750 2a 2a 20 69 73 20 75 6e 66 6f 72 74 75 6e 61 74  ** is unfortunat
36760 65 20 62 75 74 20 63 61 6e 6e 6f 74 20 62 65 20  e but cannot be 
36770 63 68 61 6e 67 65 64 20 77 69 74 68 6f 75 74 20  changed without 
36780 62 72 65 61 6b 69 6e 67 20 62 61 63 6b 77 61 72  breaking backwar
36790 64 73 20 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69  ds .** compatibi
367a0 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  lity..**.** See 
367b0 61 6c 73 6f 3a 20 20 5b 73 71 6c 69 74 65 33 5f  also:  [sqlite3_
367c0 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
367d0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
367e0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
367f0 64 31 36 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54  d16()]..*/.SQLIT
36800 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
36810 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
36820 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  on(.  sqlite3*, 
36830 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
36840 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65  Name, .  int eTe
36850 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a  xtRep, .  void *
36860 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f  pArg,.  int(*xCo
36870 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74  mpare)(void*,int
36880 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74  ,const void*,int
36890 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b  ,const void*).);
368a0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
368b0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
368c0 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a 20 20 73  ollation_v2(.  s
368d0 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73  qlite3*, .  cons
368e0 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a  t char *zName, .
368f0 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20    int eTextRep, 
36900 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20  .  void *pArg,. 
36910 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28   int(*xCompare)(
36920 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
36930 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
36940 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64 28 2a  void*),.  void(*
36950 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29  xDestroy)(void*)
36960 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .);.SQLITE_API i
36970 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
36980 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 0a 20  e_collation16(. 
36990 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f   sqlite3*, .  co
369a0 6e 73 74 20 76 6f 69 64 20 2a 7a 4e 61 6d 65 2c  nst void *zName,
369b0 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
369c0 20 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a   .  void *pArg,.
369d0 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29    int(*xCompare)
369e0 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74  (void*,int,const
369f0 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74   void*,int,const
36a00 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a   void*).);../*.*
36a10 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 6c  * CAPI3REF: Coll
36a20 61 74 69 6f 6e 20 4e 65 65 64 65 64 20 43 61 6c  ation Needed Cal
36a30 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 6f  lbacks.**.** ^To
36a40 20 61 76 6f 69 64 20 68 61 76 69 6e 67 20 74 6f   avoid having to
36a50 20 72 65 67 69 73 74 65 72 20 61 6c 6c 20 63 6f   register all co
36a60 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
36a70 73 20 62 65 66 6f 72 65 20 61 20 64 61 74 61 62  s before a datab
36a80 61 73 65 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73  ase.** can be us
36a90 65 64 2c 20 61 20 73 69 6e 67 6c 65 20 63 61 6c  ed, a single cal
36aa0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6d  lback function m
36ab0 61 79 20 62 65 20 72 65 67 69 73 74 65 72 65 64  ay be registered
36ac0 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 64 61   with the.** [da
36ad0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
36ae0 6e 5d 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64  n] to be invoked
36af0 20 77 68 65 6e 65 76 65 72 20 61 6e 20 75 6e 64   whenever an und
36b00 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e  efined collation
36b10 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 69 73 20  .** sequence is 
36b20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  required..**.** 
36b30 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  ^If the function
36b40 20 69 73 20 72 65 67 69 73 74 65 72 65 64 20 75   is registered u
36b50 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33  sing the sqlite3
36b60 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
36b70 64 28 29 20 41 50 49 2c 0a 2a 2a 20 74 68 65 6e  d() API,.** then
36b80 20 69 74 20 69 73 20 70 61 73 73 65 64 20 74 68   it is passed th
36b90 65 20 6e 61 6d 65 73 20 6f 66 20 75 6e 64 65 66  e names of undef
36ba0 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73  ined collation s
36bb0 65 71 75 65 6e 63 65 73 20 61 73 20 73 74 72 69  equences as stri
36bc0 6e 67 73 0a 2a 2a 20 65 6e 63 6f 64 65 64 20 69  ngs.** encoded i
36bd0 6e 20 55 54 46 2d 38 2e 20 5e 49 66 20 73 71 6c  n UTF-8. ^If sql
36be0 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
36bf0 65 65 64 65 64 31 36 28 29 20 69 73 20 75 73 65  eeded16() is use
36c00 64 2c 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 73 20  d,.** the names 
36c10 61 72 65 20 70 61 73 73 65 64 20 61 73 20 55 54  are passed as UT
36c20 46 2d 31 36 20 69 6e 20 6d 61 63 68 69 6e 65 20  F-16 in machine 
36c30 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
36c40 72 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f  r..** ^A call to
36c50 20 65 69 74 68 65 72 20 66 75 6e 63 74 69 6f 6e   either function
36c60 20 72 65 70 6c 61 63 65 73 20 74 68 65 20 65 78   replaces the ex
36c70 69 73 74 69 6e 67 20 63 6f 6c 6c 61 74 69 6f 6e  isting collation
36c80 2d 6e 65 65 64 65 64 20 63 61 6c 6c 62 61 63 6b  -needed callback
36c90 2e 0a 2a 2a 0a 2a 2a 20 5e 28 57 68 65 6e 20 74  ..**.** ^(When t
36ca0 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  he callback is i
36cb0 6e 76 6f 6b 65 64 2c 20 74 68 65 20 66 69 72 73  nvoked, the firs
36cc0 74 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65  t argument passe
36cd0 64 20 69 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f  d is a copy.** o
36ce0 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  f the second arg
36cf0 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
36d00 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
36d10 64 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  d() or.** sqlite
36d20 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
36d30 65 64 31 36 28 29 2e 20 20 54 68 65 20 73 65 63  ed16().  The sec
36d40 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
36d50 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
36d60 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68 65  connection.  The
36d70 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
36d80 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  is one of [SQLIT
36d90 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45  E_UTF8], [SQLITE
36da0 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 6f 72  _UTF16BE],.** or
36db0 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45   [SQLITE_UTF16LE
36dc0 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68  ], indicating th
36dd0 65 20 6d 6f 73 74 20 64 65 73 69 72 61 62 6c 65  e most desirable
36de0 20 66 6f 72 6d 20 6f 66 20 74 68 65 20 63 6f 6c   form of the col
36df0 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e  lation.** sequen
36e00 63 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75  ce function requ
36e10 69 72 65 64 2e 20 20 54 68 65 20 66 6f 75 72 74  ired.  The fourt
36e20 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  h parameter is t
36e30 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a  he name of the.*
36e40 2a 20 72 65 71 75 69 72 65 64 20 63 6f 6c 6c 61  * required colla
36e50 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 2e 29 5e  tion sequence.)^
36e60 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62  .**.** The callb
36e70 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f  ack function sho
36e80 75 6c 64 20 72 65 67 69 73 74 65 72 20 74 68 65  uld register the
36e90 20 64 65 73 69 72 65 64 20 63 6f 6c 6c 61 74 69   desired collati
36ea0 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  on using.** [sql
36eb0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
36ec0 61 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  ation()], [sqlit
36ed0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
36ee0 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20  ion16()], or.** 
36ef0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
36f00 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 5d 2e  collation_v2()].
36f10 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
36f20 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  nt sqlite3_colla
36f30 74 69 6f 6e 5f 6e 65 65 64 65 64 28 0a 20 20 73  tion_needed(.  s
36f40 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64  qlite3*, .  void
36f50 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f  *, .  void(*)(vo
36f60 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74  id*,sqlite3*,int
36f70 20 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20   eTextRep,const 
36f80 63 68 61 72 2a 29 0a 29 3b 0a 53 51 4c 49 54 45  char*).);.SQLITE
36f90 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
36fa0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
36fb0 64 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  d16(.  sqlite3*,
36fc0 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 76 6f 69   .  void*,.  voi
36fd0 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74  d(*)(void*,sqlit
36fe0 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70  e3*,int eTextRep
36ff0 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b  ,const void*).);
37000 0a 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f  ..#ifdef SQLITE_
37010 48 41 53 5f 43 4f 44 45 43 0a 2f 2a 0a 2a 2a 20  HAS_CODEC./*.** 
37020 53 70 65 63 69 66 79 20 74 68 65 20 6b 65 79 20  Specify the key 
37030 66 6f 72 20 61 6e 20 65 6e 63 72 79 70 74 65 64  for an encrypted
37040 20 64 61 74 61 62 61 73 65 2e 20 20 54 68 69 73   database.  This
37050 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 20   routine should 
37060 62 65 0a 2a 2a 20 63 61 6c 6c 65 64 20 72 69 67  be.** called rig
37070 68 74 20 61 66 74 65 72 20 73 71 6c 69 74 65 33  ht after sqlite3
37080 5f 6f 70 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 54  _open()..**.** T
37090 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65  he code to imple
370a0 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20 69 73  ment this API is
370b0 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69   not available i
370c0 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c  n the public rel
370d0 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74  ease.** of SQLit
370e0 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  e..*/.SQLITE_API
370f0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6b 65 79   int sqlite3_key
37100 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
37110 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
37120 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74     /* Database t
37130 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a  o be rekeyed */.
37140 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b    const void *pK
37150 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20  ey, int nKey    
37160 20 2f 2a 20 54 68 65 20 6b 65 79 20 2a 2f 0a 29   /* The key */.)
37170 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
37180 20 73 71 6c 69 74 65 33 5f 6b 65 79 5f 76 32 28   sqlite3_key_v2(
37190 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
371a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
371b0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f    /* Database to
371c0 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20   be rekeyed */. 
371d0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62   const char *zDb
371e0 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 20 20 20  Name,           
371f0 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 64  /* Name of the d
37200 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e  atabase */.  con
37210 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69  st void *pKey, i
37220 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54  nt nKey     /* T
37230 68 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a  he key */.);../*
37240 0a 2a 2a 20 43 68 61 6e 67 65 20 74 68 65 20 6b  .** Change the k
37250 65 79 20 6f 6e 20 61 6e 20 6f 70 65 6e 20 64 61  ey on an open da
37260 74 61 62 61 73 65 2e 20 20 49 66 20 74 68 65 20  tabase.  If the 
37270 63 75 72 72 65 6e 74 20 64 61 74 61 62 61 73 65  current database
37280 20 69 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63 72 79   is not.** encry
37290 70 74 65 64 2c 20 74 68 69 73 20 72 6f 75 74 69  pted, this routi
372a0 6e 65 20 77 69 6c 6c 20 65 6e 63 72 79 70 74 20  ne will encrypt 
372b0 69 74 2e 20 20 49 66 20 70 4e 65 77 3d 3d 30 20  it.  If pNew==0 
372c0 6f 72 20 6e 4e 65 77 3d 3d 30 2c 20 74 68 65 0a  or nNew==0, the.
372d0 2a 2a 20 64 61 74 61 62 61 73 65 20 69 73 20 64  ** database is d
372e0 65 63 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  ecrypted..**.** 
372f0 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c  The code to impl
37300 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20 69  ement this API i
37310 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20  s not available 
37320 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72 65  in the public re
37330 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69  lease.** of SQLi
37340 74 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  te..*/.SQLITE_AP
37350 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65  I int sqlite3_re
37360 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  key(.  sqlite3 *
37370 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  db,             
37380 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
37390 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20  e to be rekeyed 
373a0 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
373b0 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20  *pKey, int nKey 
373c0 20 20 20 20 2f 2a 20 54 68 65 20 6e 65 77 20 6b      /* The new k
373d0 65 79 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f  ey */.);.SQLITE_
373e0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
373f0 72 65 6b 65 79 5f 76 32 28 0a 20 20 73 71 6c 69  rekey_v2(.  sqli
37400 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
37410 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
37420 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b  tabase to be rek
37430 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  eyed */.  const 
37440 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65 2c 20 20  char *zDbName,  
37450 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65           /* Name
37460 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
37470 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
37480 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79   *pKey, int nKey
37490 20 20 20 20 20 2f 2a 20 54 68 65 20 6e 65 77 20       /* The new 
374a0 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  key */.);../*.**
374b0 20 53 70 65 63 69 66 79 20 74 68 65 20 61 63 74   Specify the act
374c0 69 76 61 74 69 6f 6e 20 6b 65 79 20 66 6f 72 20  ivation key for 
374d0 61 20 53 45 45 20 64 61 74 61 62 61 73 65 2e 20  a SEE database. 
374e0 20 55 6e 6c 65 73 73 20 0a 2a 2a 20 61 63 74 69   Unless .** acti
374f0 76 61 74 65 64 2c 20 6e 6f 6e 65 20 6f 66 20 74  vated, none of t
37500 68 65 20 53 45 45 20 72 6f 75 74 69 6e 65 73 20  he SEE routines 
37510 77 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 53 51  will work..*/.SQ
37520 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71  LITE_API void sq
37530 6c 69 74 65 33 5f 61 63 74 69 76 61 74 65 5f 73  lite3_activate_s
37540 65 65 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  ee(.  const char
37550 20 2a 7a 50 61 73 73 50 68 72 61 73 65 20 20 20   *zPassPhrase   
37560 20 20 20 20 20 2f 2a 20 41 63 74 69 76 61 74 69       /* Activati
37570 6f 6e 20 70 68 72 61 73 65 20 2a 2f 0a 29 3b 0a  on phrase */.);.
37580 23 65 6e 64 69 66 0a 0a 23 69 66 64 65 66 20 53  #endif..#ifdef S
37590 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 45 52  QLITE_ENABLE_CER
375a0 4f 44 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79  OD./*.** Specify
375b0 20 74 68 65 20 61 63 74 69 76 61 74 69 6f 6e 20   the activation 
375c0 6b 65 79 20 66 6f 72 20 61 20 43 45 52 4f 44 20  key for a CEROD 
375d0 64 61 74 61 62 61 73 65 2e 20 20 55 6e 6c 65 73  database.  Unles
375e0 73 20 0a 2a 2a 20 61 63 74 69 76 61 74 65 64 2c  s .** activated,
375f0 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20 43 45 52   none of the CER
37600 4f 44 20 72 6f 75 74 69 6e 65 73 20 77 69 6c 6c  OD routines will
37610 20 77 6f 72 6b 2e 0a 2a 2f 0a 53 51 4c 49 54 45   work..*/.SQLITE
37620 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65  _API void sqlite
37630 33 5f 61 63 74 69 76 61 74 65 5f 63 65 72 6f 64  3_activate_cerod
37640 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  (.  const char *
37650 7a 50 61 73 73 50 68 72 61 73 65 20 20 20 20 20  zPassPhrase     
37660 20 20 20 2f 2a 20 41 63 74 69 76 61 74 69 6f 6e     /* Activation
37670 20 70 68 72 61 73 65 20 2a 2f 0a 29 3b 0a 23 65   phrase */.);.#e
37680 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
37690 33 52 45 46 3a 20 53 75 73 70 65 6e 64 20 45 78  3REF: Suspend Ex
376a0 65 63 75 74 69 6f 6e 20 46 6f 72 20 41 20 53 68  ecution For A Sh
376b0 6f 72 74 20 54 69 6d 65 0a 2a 2a 0a 2a 2a 20 54  ort Time.**.** T
376c0 68 65 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70  he sqlite3_sleep
376d0 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73  () function caus
376e0 65 73 20 74 68 65 20 63 75 72 72 65 6e 74 20 74  es the current t
376f0 68 72 65 61 64 20 74 6f 20 73 75 73 70 65 6e 64  hread to suspend
37700 20 65 78 65 63 75 74 69 6f 6e 0a 2a 2a 20 66 6f   execution.** fo
37710 72 20 61 74 20 6c 65 61 73 74 20 61 20 6e 75 6d  r at least a num
37720 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f  ber of milliseco
37730 6e 64 73 20 73 70 65 63 69 66 69 65 64 20 69 6e  nds specified in
37740 20 69 74 73 20 70 61 72 61 6d 65 74 65 72 2e 0a   its parameter..
37750 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6f 70 65  **.** If the ope
37760 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 64 6f  rating system do
37770 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 20 73  es not support s
37780 6c 65 65 70 20 72 65 71 75 65 73 74 73 20 77 69  leep requests wi
37790 74 68 0a 2a 2a 20 6d 69 6c 6c 69 73 65 63 6f 6e  th.** millisecon
377a0 64 20 74 69 6d 65 20 72 65 73 6f 6c 75 74 69 6f  d time resolutio
377b0 6e 2c 20 74 68 65 6e 20 74 68 65 20 74 69 6d 65  n, then the time
377c0 20 77 69 6c 6c 20 62 65 20 72 6f 75 6e 64 65 64   will be rounded
377d0 20 75 70 20 74 6f 0a 2a 2a 20 74 68 65 20 6e 65   up to.** the ne
377e0 61 72 65 73 74 20 73 65 63 6f 6e 64 2e 20 54 68  arest second. Th
377f0 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c  e number of mill
37800 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65  iseconds of slee
37810 70 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 72 65  p actually.** re
37820 71 75 65 73 74 65 64 20 66 72 6f 6d 20 74 68 65  quested from the
37830 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
37840 6d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  m is returned..*
37850 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 69 6d 70  *.** ^SQLite imp
37860 6c 65 6d 65 6e 74 73 20 74 68 69 73 20 69 6e 74  lements this int
37870 65 72 66 61 63 65 20 62 79 20 63 61 6c 6c 69 6e  erface by callin
37880 67 20 74 68 65 20 78 53 6c 65 65 70 28 29 0a 2a  g the xSleep().*
37890 2a 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20  * method of the 
378a0 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
378b0 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20 20 49  _vfs] object.  I
378c0 66 20 74 68 65 20 78 53 6c 65 65 70 28 29 20 6d  f the xSleep() m
378d0 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20  ethod.** of the 
378e0 64 65 66 61 75 6c 74 20 56 46 53 20 69 73 20 6e  default VFS is n
378f0 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 63  ot implemented c
37900 6f 72 72 65 63 74 6c 79 2c 20 6f 72 20 6e 6f 74  orrectly, or not
37910 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 74 0a   implemented at.
37920 2a 2a 20 61 6c 6c 2c 20 74 68 65 6e 20 74 68 65  ** all, then the
37930 20 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c   behavior of sql
37940 69 74 65 33 5f 73 6c 65 65 70 28 29 20 6d 61 79  ite3_sleep() may
37950 20 64 65 76 69 61 74 65 20 66 72 6f 6d 20 74 68   deviate from th
37960 65 20 64 65 73 63 72 69 70 74 69 6f 6e 0a 2a 2a  e description.**
37970 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73   in the previous
37980 20 70 61 72 61 67 72 61 70 68 73 2e 0a 2a 2f 0a   paragraphs..*/.
37990 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
379a0 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 69 6e 74  qlite3_sleep(int
379b0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
379c0 45 46 3a 20 4e 61 6d 65 20 4f 66 20 54 68 65 20  EF: Name Of The 
379d0 46 6f 6c 64 65 72 20 48 6f 6c 64 69 6e 67 20 54  Folder Holding T
379e0 65 6d 70 6f 72 61 72 79 20 46 69 6c 65 73 0a 2a  emporary Files.*
379f0 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 69 73 20 67  *.** ^(If this g
37a00 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 20 69  lobal variable i
37a10 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20  s made to point 
37a20 74 6f 20 61 20 73 74 72 69 6e 67 20 77 68 69 63  to a string whic
37a30 68 20 69 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65  h is.** the name
37a40 20 6f 66 20 61 20 66 6f 6c 64 65 72 20 28 61 2e   of a folder (a.
37a50 6b 2e 61 2e 20 64 69 72 65 63 74 6f 72 79 29 2c  k.a. directory),
37a60 20 74 68 65 6e 20 61 6c 6c 20 74 65 6d 70 6f 72   then all tempor
37a70 61 72 79 20 66 69 6c 65 73 0a 2a 2a 20 63 72 65  ary files.** cre
37a80 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 20 77  ated by SQLite w
37a90 68 65 6e 20 75 73 69 6e 67 20 61 20 62 75 69 6c  hen using a buil
37aa0 74 2d 69 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66  t-in [sqlite3_vf
37ab0 73 20 7c 20 56 46 53 5d 0a 2a 2a 20 77 69 6c 6c  s | VFS].** will
37ac0 20 62 65 20 70 6c 61 63 65 64 20 69 6e 20 74 68   be placed in th
37ad0 61 74 20 64 69 72 65 63 74 6f 72 79 2e 29 5e 20  at directory.)^ 
37ae0 20 5e 49 66 20 74 68 69 73 20 76 61 72 69 61 62   ^If this variab
37af0 6c 65 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20  le.** is a NULL 
37b00 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51  pointer, then SQ
37b10 4c 69 74 65 20 70 65 72 66 6f 72 6d 73 20 61 20  Lite performs a 
37b20 73 65 61 72 63 68 20 66 6f 72 20 61 6e 20 61 70  search for an ap
37b30 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 74 65 6d  propriate.** tem
37b40 70 6f 72 61 72 79 20 66 69 6c 65 20 64 69 72 65  porary file dire
37b50 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20  ctory..**.** It 
37b60 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 72  is not safe to r
37b70 65 61 64 20 6f 72 20 6d 6f 64 69 66 79 20 74 68  ead or modify th
37b80 69 73 20 76 61 72 69 61 62 6c 65 20 69 6e 20 6d  is variable in m
37b90 6f 72 65 20 74 68 61 6e 20 6f 6e 65 0a 2a 2a 20  ore than one.** 
37ba0 74 68 72 65 61 64 20 61 74 20 61 20 74 69 6d 65  thread at a time
37bb0 2e 20 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66  .  It is not saf
37bc0 65 20 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64  e to read or mod
37bd0 69 66 79 20 74 68 69 73 20 76 61 72 69 61 62 6c  ify this variabl
37be0 65 0a 2a 2a 20 69 66 20 61 20 5b 64 61 74 61 62  e.** if a [datab
37bf0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
37c00 69 73 20 62 65 69 6e 67 20 75 73 65 64 20 61 74  is being used at
37c10 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 69   the same time i
37c20 6e 20 61 20 73 65 70 61 72 61 74 65 0a 2a 2a 20  n a separate.** 
37c30 74 68 72 65 61 64 2e 0a 2a 2a 20 49 74 20 69 73  thread..** It is
37c40 20 69 6e 74 65 6e 64 65 64 20 74 68 61 74 20 74   intended that t
37c50 68 69 73 20 76 61 72 69 61 62 6c 65 20 62 65 20  his variable be 
37c60 73 65 74 20 6f 6e 63 65 0a 2a 2a 20 61 73 20 70  set once.** as p
37c70 61 72 74 20 6f 66 20 70 72 6f 63 65 73 73 20 69  art of process i
37c80 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e  nitialization an
37c90 64 20 62 65 66 6f 72 65 20 61 6e 79 20 53 51 4c  d before any SQL
37ca0 69 74 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  ite interface.**
37cb0 20 72 6f 75 74 69 6e 65 73 20 68 61 76 65 20 62   routines have b
37cc0 65 65 6e 20 63 61 6c 6c 65 64 20 61 6e 64 20 74  een called and t
37cd0 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62 6c  hat this variabl
37ce0 65 20 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67  e remain unchang
37cf0 65 64 0a 2a 2a 20 74 68 65 72 65 61 66 74 65 72  ed.** thereafter
37d00 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 74 65  ..**.** ^The [te
37d10 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f  mp_store_directo
37d20 72 79 20 70 72 61 67 6d 61 5d 20 6d 61 79 20 6d  ry pragma] may m
37d30 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61  odify this varia
37d40 62 6c 65 20 61 6e 64 20 63 61 75 73 65 0a 2a 2a  ble and cause.**
37d50 20 69 74 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20   it to point to 
37d60 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20  memory obtained 
37d70 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
37d80 6c 6c 6f 63 5d 2e 20 20 5e 46 75 72 74 68 65 72  lloc].  ^Further
37d90 6d 6f 72 65 2c 0a 2a 2a 20 74 68 65 20 5b 74 65  more,.** the [te
37da0 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f  mp_store_directo
37db0 72 79 20 70 72 61 67 6d 61 5d 20 61 6c 77 61 79  ry pragma] alway
37dc0 73 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 61  s assumes that a
37dd0 6e 79 20 73 74 72 69 6e 67 0a 2a 2a 20 74 68 61  ny string.** tha
37de0 74 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20  t this variable 
37df0 70 6f 69 6e 74 73 20 74 6f 20 69 73 20 68 65 6c  points to is hel
37e00 64 20 69 6e 20 6d 65 6d 6f 72 79 20 6f 62 74 61  d in memory obta
37e10 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73  ined from .** [s
37e20 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 20 61  qlite3_malloc] a
37e30 6e 64 20 74 68 65 20 70 72 61 67 6d 61 20 6d 61  nd the pragma ma
37e40 79 20 61 74 74 65 6d 70 74 20 74 6f 20 66 72 65  y attempt to fre
37e50 65 20 74 68 61 74 20 6d 65 6d 6f 72 79 0a 2a 2a  e that memory.**
37e60 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
37e70 66 72 65 65 5d 2e 0a 2a 2a 20 48 65 6e 63 65 2c  free]..** Hence,
37e80 20 69 66 20 74 68 69 73 20 76 61 72 69 61 62 6c   if this variabl
37e90 65 20 69 73 20 6d 6f 64 69 66 69 65 64 20 64 69  e is modified di
37ea0 72 65 63 74 6c 79 2c 20 65 69 74 68 65 72 20 69  rectly, either i
37eb0 74 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 6d  t should be.** m
37ec0 61 64 65 20 4e 55 4c 4c 20 6f 72 20 6d 61 64 65  ade NULL or made
37ed0 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d   to point to mem
37ee0 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
37ef0 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
37f00 63 5d 0a 2a 2a 20 6f 72 20 65 6c 73 65 20 74 68  c].** or else th
37f10 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b 74 65  e use of the [te
37f20 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f  mp_store_directo
37f30 72 79 20 70 72 61 67 6d 61 5d 20 73 68 6f 75 6c  ry pragma] shoul
37f40 64 20 62 65 20 61 76 6f 69 64 65 64 2e 0a 2a 2a  d be avoided..**
37f50 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57  .** <b>Note to W
37f60 69 6e 64 6f 77 73 20 52 75 6e 74 69 6d 65 20 75  indows Runtime u
37f70 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 74  sers:</b>  The t
37f80 65 6d 70 6f 72 61 72 79 20 64 69 72 65 63 74 6f  emporary directo
37f90 72 79 20 6d 75 73 74 20 62 65 20 73 65 74 0a 2a  ry must be set.*
37fa0 2a 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69  * prior to calli
37fb0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ng [sqlite3_open
37fc0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ] or [sqlite3_op
37fd0 65 6e 5f 76 32 5d 2e 20 20 4f 74 68 65 72 77 69  en_v2].  Otherwi
37fe0 73 65 2c 20 76 61 72 69 6f 75 73 0a 2a 2a 20 66  se, various.** f
37ff0 65 61 74 75 72 65 73 20 74 68 61 74 20 72 65 71  eatures that req
38000 75 69 72 65 20 74 68 65 20 75 73 65 20 6f 66 20  uire the use of 
38010 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 20  temporary files 
38020 6d 61 79 20 66 61 69 6c 2e 20 20 48 65 72 65 20  may fail.  Here 
38030 69 73 20 61 6e 0a 2a 2a 20 65 78 61 6d 70 6c 65  is an.** example
38040 20 6f 66 20 68 6f 77 20 74 6f 20 64 6f 20 74 68   of how to do th
38050 69 73 20 75 73 69 6e 67 20 43 2b 2b 20 77 69 74  is using C++ wit
38060 68 20 74 68 65 20 57 69 6e 64 6f 77 73 20 52 75  h the Windows Ru
38070 6e 74 69 6d 65 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  ntime:.**.** <bl
38080 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
38090 2a 20 4c 50 43 57 53 54 52 20 7a 50 61 74 68 20  * LPCWSTR zPath 
380a0 3d 20 57 69 6e 64 6f 77 73 3a 3a 53 74 6f 72 61  = Windows::Stora
380b0 67 65 3a 3a 41 70 70 6c 69 63 61 74 69 6f 6e 44  ge::ApplicationD
380c0 61 74 61 3a 3a 43 75 72 72 65 6e 74 2d 3e 0a 2a  ata::Current->.*
380d0 2a 20 26 6e 62 73 70 3b 20 20 20 20 20 54 65 6d  * &nbsp;     Tem
380e0 70 6f 72 61 72 79 46 6f 6c 64 65 72 2d 3e 50 61  poraryFolder->Pa
380f0 74 68 2d 3e 44 61 74 61 28 29 3b 0a 2a 2a 20 63  th->Data();.** c
38100 68 61 72 20 7a 50 61 74 68 42 75 66 26 23 39 31  har zPathBuf&#91
38110 3b 4d 41 58 5f 50 41 54 48 20 2b 20 31 26 23 39  ;MAX_PATH + 1&#9
38120 33 3b 3b 0a 2a 2a 20 6d 65 6d 73 65 74 28 7a 50  3;;.** memset(zP
38130 61 74 68 42 75 66 2c 20 30 2c 20 73 69 7a 65 6f  athBuf, 0, sizeo
38140 66 28 7a 50 61 74 68 42 75 66 29 29 3b 0a 2a 2a  f(zPathBuf));.**
38150 20 57 69 64 65 43 68 61 72 54 6f 4d 75 6c 74 69   WideCharToMulti
38160 42 79 74 65 28 43 50 5f 55 54 46 38 2c 20 30 2c  Byte(CP_UTF8, 0,
38170 20 7a 50 61 74 68 2c 20 2d 31 2c 20 7a 50 61 74   zPath, -1, zPat
38180 68 42 75 66 2c 20 73 69 7a 65 6f 66 28 7a 50 61  hBuf, sizeof(zPa
38190 74 68 42 75 66 29 2c 0a 2a 2a 20 26 6e 62 73 70  thBuf),.** &nbsp
381a0 3b 20 20 20 20 20 4e 55 4c 4c 2c 20 4e 55 4c 4c  ;     NULL, NULL
381b0 29 3b 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 74 65  );.** sqlite3_te
381c0 6d 70 5f 64 69 72 65 63 74 6f 72 79 20 3d 20 73  mp_directory = s
381d0 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22  qlite3_mprintf("
381e0 25 73 22 2c 20 7a 50 61 74 68 42 75 66 29 3b 0a  %s", zPathBuf);.
381f0 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
38200 71 75 6f 74 65 3e 0a 2a 2f 0a 53 51 4c 49 54 45  quote>.*/.SQLITE
38210 5f 41 50 49 20 63 68 61 72 20 2a 73 71 6c 69 74  _API char *sqlit
38220 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72  e3_temp_director
38230 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  y;../*.** CAPI3R
38240 45 46 3a 20 4e 61 6d 65 20 4f 66 20 54 68 65 20  EF: Name Of The 
38250 46 6f 6c 64 65 72 20 48 6f 6c 64 69 6e 67 20 44  Folder Holding D
38260 61 74 61 62 61 73 65 20 46 69 6c 65 73 0a 2a 2a  atabase Files.**
38270 0a 2a 2a 20 5e 28 49 66 20 74 68 69 73 20 67 6c  .** ^(If this gl
38280 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 20 69 73  obal variable is
38290 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74   made to point t
382a0 6f 20 61 20 73 74 72 69 6e 67 20 77 68 69 63 68  o a string which
382b0 20 69 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20   is.** the name 
382c0 6f 66 20 61 20 66 6f 6c 64 65 72 20 28 61 2e 6b  of a folder (a.k
382d0 2e 61 2e 20 64 69 72 65 63 74 6f 72 79 29 2c 20  .a. directory), 
382e0 74 68 65 6e 20 61 6c 6c 20 64 61 74 61 62 61 73  then all databas
382f0 65 20 66 69 6c 65 73 0a 2a 2a 20 73 70 65 63 69  e files.** speci
38300 66 69 65 64 20 77 69 74 68 20 61 20 72 65 6c 61  fied with a rela
38310 74 69 76 65 20 70 61 74 68 6e 61 6d 65 20 61 6e  tive pathname an
38320 64 20 63 72 65 61 74 65 64 20 6f 72 20 61 63 63  d created or acc
38330 65 73 73 65 64 20 62 79 0a 2a 2a 20 53 51 4c 69  essed by.** SQLi
38340 74 65 20 77 68 65 6e 20 75 73 69 6e 67 20 61 20  te when using a 
38350 62 75 69 6c 74 2d 69 6e 20 77 69 6e 64 6f 77 73  built-in windows
38360 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20   [sqlite3_vfs | 
38370 56 46 53 5d 20 77 69 6c 6c 20 62 65 20 61 73 73  VFS] will be ass
38380 75 6d 65 64 0a 2a 2a 20 74 6f 20 62 65 20 72 65  umed.** to be re
38390 6c 61 74 69 76 65 20 74 6f 20 74 68 61 74 20 64  lative to that d
383a0 69 72 65 63 74 6f 72 79 2e 29 5e 20 5e 49 66 20  irectory.)^ ^If 
383b0 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 69 73  this variable is
383c0 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74   a NULL.** point
383d0 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  er, then SQLite 
383e0 61 73 73 75 6d 65 73 20 74 68 61 74 20 61 6c 6c  assumes that all
383f0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 73 20   database files 
38400 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 77 69 74  specified.** wit
38410 68 20 61 20 72 65 6c 61 74 69 76 65 20 70 61 74  h a relative pat
38420 68 6e 61 6d 65 20 61 72 65 20 72 65 6c 61 74 69  hname are relati
38430 76 65 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e  ve to the curren
38440 74 20 64 69 72 65 63 74 6f 72 79 0a 2a 2a 20 66  t directory.** f
38450 6f 72 20 74 68 65 20 70 72 6f 63 65 73 73 2e 20  or the process. 
38460 20 4f 6e 6c 79 20 74 68 65 20 77 69 6e 64 6f 77   Only the window
38470 73 20 56 46 53 20 6d 61 6b 65 73 20 75 73 65 20  s VFS makes use 
38480 6f 66 20 74 68 69 73 20 67 6c 6f 62 61 6c 0a 2a  of this global.*
38490 2a 20 76 61 72 69 61 62 6c 65 3b 20 69 74 20 69  * variable; it i
384a0 73 20 69 67 6e 6f 72 65 64 20 62 79 20 74 68 65  s ignored by the
384b0 20 75 6e 69 78 20 56 46 53 2e 0a 2a 2a 0a 2a 2a   unix VFS..**.**
384c0 20 43 68 61 6e 67 69 6e 67 20 74 68 65 20 76 61   Changing the va
384d0 6c 75 65 20 6f 66 20 74 68 69 73 20 76 61 72 69  lue of this vari
384e0 61 62 6c 65 20 77 68 69 6c 65 20 61 20 64 61 74  able while a dat
384f0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
38500 20 69 73 0a 2a 2a 20 6f 70 65 6e 20 63 61 6e 20   is.** open can 
38510 72 65 73 75 6c 74 20 69 6e 20 61 20 63 6f 72 72  result in a corr
38520 75 70 74 20 64 61 74 61 62 61 73 65 2e 0a 2a 2a  upt database..**
38530 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61  .** It is not sa
38540 66 65 20 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f  fe to read or mo
38550 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61 62  dify this variab
38560 6c 65 20 69 6e 20 6d 6f 72 65 20 74 68 61 6e 20  le in more than 
38570 6f 6e 65 0a 2a 2a 20 74 68 72 65 61 64 20 61 74  one.** thread at
38580 20 61 20 74 69 6d 65 2e 20 20 49 74 20 69 73 20   a time.  It is 
38590 6e 6f 74 20 73 61 66 65 20 74 6f 20 72 65 61 64  not safe to read
385a0 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20   or modify this 
385b0 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69 66 20 61  variable.** if a
385c0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
385d0 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20  ction] is being 
385e0 75 73 65 64 20 61 74 20 74 68 65 20 73 61 6d 65  used at the same
385f0 20 74 69 6d 65 20 69 6e 20 61 20 73 65 70 61 72   time in a separ
38600 61 74 65 0a 2a 2a 20 74 68 72 65 61 64 2e 0a 2a  ate.** thread..*
38610 2a 20 49 74 20 69 73 20 69 6e 74 65 6e 64 65 64  * It is intended
38620 20 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61   that this varia
38630 62 6c 65 20 62 65 20 73 65 74 20 6f 6e 63 65 0a  ble be set once.
38640 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 20 70 72  ** as part of pr
38650 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61  ocess initializa
38660 74 69 6f 6e 20 61 6e 64 20 62 65 66 6f 72 65 20  tion and before 
38670 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72  any SQLite inter
38680 66 61 63 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  face.** routines
38690 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65   have been calle
386a0 64 20 61 6e 64 20 74 68 61 74 20 74 68 69 73 20  d and that this 
386b0 76 61 72 69 61 62 6c 65 20 72 65 6d 61 69 6e 20  variable remain 
386c0 75 6e 63 68 61 6e 67 65 64 0a 2a 2a 20 74 68 65  unchanged.** the
386d0 72 65 61 66 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  reafter..**.** ^
386e0 54 68 65 20 5b 64 61 74 61 5f 73 74 6f 72 65 5f  The [data_store_
386f0 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61  directory pragma
38700 5d 20 6d 61 79 20 6d 6f 64 69 66 79 20 74 68 69  ] may modify thi
38710 73 20 76 61 72 69 61 62 6c 65 20 61 6e 64 20 63  s variable and c
38720 61 75 73 65 0a 2a 2a 20 69 74 20 74 6f 20 70 6f  ause.** it to po
38730 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  int to memory ob
38740 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
38750 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 2e 20 20 5e  ite3_malloc].  ^
38760 46 75 72 74 68 65 72 6d 6f 72 65 2c 0a 2a 2a 20  Furthermore,.** 
38770 74 68 65 20 5b 64 61 74 61 5f 73 74 6f 72 65 5f  the [data_store_
38780 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61  directory pragma
38790 5d 20 61 6