System.Data.SQLite
Hex Artifact Content
Not logged in

Artifact 4fb1bc049d96aecfc07b85051185c48ab2d3fef7:


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 38 2e 20 20 42  ersion 3.8.8.  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 49 6e 74 2e 68 20  ile sqliteInt.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 49 6e 74 65 72 6e 61 6c 20 69 6e 74 65  ** Internal inte
0750: 72 66 61 63 65 20 64 65 66 69 6e 69 74 69 6f 6e  rface definition
0760: 73 20 66 6f 72 20 53 51 4c 69 74 65 2e 0a 2a 2a  s for SQLite..**
0770: 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c  .*/.#ifndef _SQL
0780: 49 54 45 49 4e 54 5f 48 5f 0a 23 64 65 66 69 6e  ITEINT_H_.#defin
0790: 65 20 5f 53 51 4c 49 54 45 49 4e 54 5f 48 5f 0a  e _SQLITEINT_H_.
07a0: 0a 2f 2a 0a 2a 2a 20 49 6e 63 6c 75 64 65 20 74  ./*.** Include t
07b0: 68 65 20 68 65 61 64 65 72 20 66 69 6c 65 20 75  he header file u
07c0: 73 65 64 20 74 6f 20 63 75 73 74 6f 6d 69 7a 65  sed to customize
07d0: 20 74 68 65 20 63 6f 6d 70 69 6c 65 72 20 6f 70   the compiler op
07e0: 74 69 6f 6e 73 20 66 6f 72 20 4d 53 56 43 2e 0a  tions for MSVC..
07f0: 2a 2a 20 54 68 69 73 20 73 68 6f 75 6c 64 20 62  ** This should b
0800: 65 20 64 6f 6e 65 20 66 69 72 73 74 20 73 6f 20  e done first so 
0810: 74 68 61 74 20 69 74 20 63 61 6e 20 73 75 63 63  that it can succ
0820: 65 73 73 66 75 6c 6c 79 20 70 72 65 76 65 6e 74  essfully prevent
0830: 20 73 70 75 72 69 6f 75 73 0a 2a 2a 20 63 6f 6d   spurious.** com
0840: 70 69 6c 65 72 20 77 61 72 6e 69 6e 67 73 20 64  piler warnings d
0850: 75 65 20 74 6f 20 73 75 62 73 65 71 75 65 6e 74  ue to subsequent
0860: 20 63 6f 6e 74 65 6e 74 20 69 6e 20 74 68 69 73   content in this
0870: 20 66 69 6c 65 20 61 6e 64 20 6f 74 68 65 72 20   file and other 
0880: 66 69 6c 65 73 0a 2a 2a 20 74 68 61 74 20 61 72  files.** that ar
0890: 65 20 69 6e 63 6c 75 64 65 64 20 62 79 20 74 68  e included by th
08a0: 69 73 20 66 69 6c 65 2e 0a 2a 2f 0a 2f 2a 2a 2a  is file..*/./***
08b0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 49 6e 63 6c  *********** Incl
08c0: 75 64 65 20 6d 73 76 63 2e 68 20 69 6e 20 74 68  ude msvc.h in th
08d0: 65 20 6d 69 64 64 6c 65 20 6f 66 20 73 71 6c 69  e middle of sqli
08e0: 74 65 49 6e 74 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a  teInt.h ********
08f0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 2a 2a  **********/./***
0900: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 42 65 67 69  *********** Begi
0910: 6e 20 66 69 6c 65 20 6d 73 76 63 2e 68 20 2a 2a  n file msvc.h **
0920: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0930: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0940: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 0a 2a  **********/./*.*
0950: 2a 20 32 30 31 35 20 4a 61 6e 75 61 72 79 20 31  * 2015 January 1
0960: 32 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68  2.**.** The auth
0970: 6f 72 20 64 69 73 63 6c 61 69 6d 73 20 63 6f 70  or disclaims cop
0980: 79 72 69 67 68 74 20 74 6f 20 74 68 69 73 20 73  yright to this s
0990: 6f 75 72 63 65 20 63 6f 64 65 2e 20 20 49 6e 20  ource code.  In 
09a0: 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 61 20 6c 65  place of.** a le
09b0: 67 61 6c 20 6e 6f 74 69 63 65 2c 20 68 65 72 65  gal notice, here
09c0: 20 69 73 20 61 20 62 6c 65 73 73 69 6e 67 3a 0a   is a blessing:.
09d0: 2a 2a 0a 2a 2a 20 20 20 20 4d 61 79 20 79 6f 75  **.**    May you
09e0: 20 64 6f 20 67 6f 6f 64 20 61 6e 64 20 6e 6f 74   do good and not
09f0: 20 65 76 69 6c 2e 0a 2a 2a 20 20 20 20 4d 61 79   evil..**    May
0a00: 20 79 6f 75 20 66 69 6e 64 20 66 6f 72 67 69 76   you find forgiv
0a10: 65 6e 65 73 73 20 66 6f 72 20 79 6f 75 72 73 65  eness for yourse
0a20: 6c 66 20 61 6e 64 20 66 6f 72 67 69 76 65 20 6f  lf and forgive o
0a30: 74 68 65 72 73 2e 0a 2a 2a 20 20 20 20 4d 61 79  thers..**    May
0a40: 20 79 6f 75 20 73 68 61 72 65 20 66 72 65 65 6c   you share freel
0a50: 79 2c 20 6e 65 76 65 72 20 74 61 6b 69 6e 67 20  y, never taking 
0a60: 6d 6f 72 65 20 74 68 61 6e 20 79 6f 75 20 67 69  more than you gi
0a70: 76 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ve..**.*********
0a80: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0a90: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0aa0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0ab0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0ac0: 2a 2a 2a 2a 2a 0a 2a 2a 0a 2a 2a 20 54 68 69 73  *****.**.** This
0ad0: 20 66 69 6c 65 20 63 6f 6e 74 61 69 6e 73 20 63   file contains c
0ae0: 6f 64 65 20 74 68 61 74 20 69 73 20 73 70 65 63  ode that is spec
0af0: 69 66 69 63 20 74 6f 20 4d 53 56 43 2e 0a 2a 2f  ific to MSVC..*/
0b00: 0a 23 69 66 6e 64 65 66 20 5f 4d 53 56 43 5f 48  .#ifndef _MSVC_H
0b10: 5f 0a 23 64 65 66 69 6e 65 20 5f 4d 53 56 43 5f  _.#define _MSVC_
0b20: 48 5f 0a 0a 23 69 66 20 64 65 66 69 6e 65 64 28  H_..#if defined(
0b30: 5f 4d 53 43 5f 56 45 52 29 0a 23 70 72 61 67 6d  _MSC_VER).#pragm
0b40: 61 20 77 61 72 6e 69 6e 67 28 64 69 73 61 62 6c  a warning(disabl
0b50: 65 20 3a 20 34 30 35 34 29 0a 23 70 72 61 67 6d  e : 4054).#pragm
0b60: 61 20 77 61 72 6e 69 6e 67 28 64 69 73 61 62 6c  a warning(disabl
0b70: 65 20 3a 20 34 30 35 35 29 0a 23 70 72 61 67 6d  e : 4055).#pragm
0b80: 61 20 77 61 72 6e 69 6e 67 28 64 69 73 61 62 6c  a warning(disabl
0b90: 65 20 3a 20 34 31 30 30 29 0a 23 70 72 61 67 6d  e : 4100).#pragm
0ba0: 61 20 77 61 72 6e 69 6e 67 28 64 69 73 61 62 6c  a warning(disabl
0bb0: 65 20 3a 20 34 31 32 37 29 0a 23 70 72 61 67 6d  e : 4127).#pragm
0bc0: 61 20 77 61 72 6e 69 6e 67 28 64 69 73 61 62 6c  a warning(disabl
0bd0: 65 20 3a 20 34 31 35 32 29 0a 23 70 72 61 67 6d  e : 4152).#pragm
0be0: 61 20 77 61 72 6e 69 6e 67 28 64 69 73 61 62 6c  a warning(disabl
0bf0: 65 20 3a 20 34 31 38 39 29 0a 23 70 72 61 67 6d  e : 4189).#pragm
0c00: 61 20 77 61 72 6e 69 6e 67 28 64 69 73 61 62 6c  a warning(disabl
0c10: 65 20 3a 20 34 32 30 36 29 0a 23 70 72 61 67 6d  e : 4206).#pragm
0c20: 61 20 77 61 72 6e 69 6e 67 28 64 69 73 61 62 6c  a warning(disabl
0c30: 65 20 3a 20 34 32 31 30 29 0a 23 70 72 61 67 6d  e : 4210).#pragm
0c40: 61 20 77 61 72 6e 69 6e 67 28 64 69 73 61 62 6c  a warning(disabl
0c50: 65 20 3a 20 34 32 33 32 29 0a 23 70 72 61 67 6d  e : 4232).#pragm
0c60: 61 20 77 61 72 6e 69 6e 67 28 64 69 73 61 62 6c  a warning(disabl
0c70: 65 20 3a 20 34 32 34 34 29 0a 23 70 72 61 67 6d  e : 4244).#pragm
0c80: 61 20 77 61 72 6e 69 6e 67 28 64 69 73 61 62 6c  a warning(disabl
0c90: 65 20 3a 20 34 33 30 35 29 0a 23 70 72 61 67 6d  e : 4305).#pragm
0ca0: 61 20 77 61 72 6e 69 6e 67 28 64 69 73 61 62 6c  a warning(disabl
0cb0: 65 20 3a 20 34 33 30 36 29 0a 23 70 72 61 67 6d  e : 4306).#pragm
0cc0: 61 20 77 61 72 6e 69 6e 67 28 64 69 73 61 62 6c  a warning(disabl
0cd0: 65 20 3a 20 34 37 30 32 29 0a 23 70 72 61 67 6d  e : 4702).#pragm
0ce0: 61 20 77 61 72 6e 69 6e 67 28 64 69 73 61 62 6c  a warning(disabl
0cf0: 65 20 3a 20 34 37 30 36 29 0a 23 65 6e 64 69 66  e : 4706).#endif
0d00: 20 2f 2a 20 64 65 66 69 6e 65 64 28 5f 4d 53 43   /* defined(_MSC
0d10: 5f 56 45 52 29 20 2a 2f 0a 0a 23 65 6e 64 69 66  _VER) */..#endif
0d20: 20 2f 2a 20 5f 4d 53 56 43 5f 48 5f 20 2a 2f 0a   /* _MSVC_H_ */.
0d30: 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ./**************
0d40: 20 45 6e 64 20 6f 66 20 6d 73 76 63 2e 68 20 2a   End of msvc.h *
0d50: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0d60: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0d70: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f  ***************/
0d80: 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ./**************
0d90: 20 43 6f 6e 74 69 6e 75 69 6e 67 20 77 68 65 72   Continuing wher
0da0: 65 20 77 65 20 6c 65 66 74 20 6f 66 66 20 69 6e  e we left off in
0db0: 20 73 71 6c 69 74 65 49 6e 74 2e 68 20 2a 2a 2a   sqliteInt.h ***
0dc0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f  ***************/
0dd0: 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73 65 20 23 64  ../*.** These #d
0de0: 65 66 69 6e 65 73 20 73 68 6f 75 6c 64 20 65 6e  efines should en
0df0: 61 62 6c 65 20 3e 32 47 42 20 66 69 6c 65 20 73  able >2GB file s
0e00: 75 70 70 6f 72 74 20 6f 6e 20 50 4f 53 49 58 20  upport on POSIX 
0e10: 69 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c  if the.** underl
0e20: 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73  ying operating s
0e30: 79 73 74 65 6d 20 73 75 70 70 6f 72 74 73 20 69  ystem supports i
0e40: 74 2e 20 20 49 66 20 74 68 65 20 4f 53 20 6c 61  t.  If the OS la
0e50: 63 6b 73 0a 2a 2a 20 6c 61 72 67 65 20 66 69 6c  cks.** large fil
0e60: 65 20 73 75 70 70 6f 72 74 2c 20 6f 72 20 69 66  e support, or if
0e70: 20 74 68 65 20 4f 53 20 69 73 20 77 69 6e 64 6f   the OS is windo
0e80: 77 73 2c 20 74 68 65 73 65 20 73 68 6f 75 6c 64  ws, these should
0e90: 20 62 65 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a 2a   be no-ops..**.*
0ea0: 2a 20 54 69 63 6b 65 74 20 23 32 37 33 39 3a 20  * Ticket #2739: 
0eb0: 20 54 68 65 20 5f 4c 41 52 47 45 46 49 4c 45 5f   The _LARGEFILE_
0ec0: 53 4f 55 52 43 45 20 6d 61 63 72 6f 20 6d 75 73  SOURCE macro mus
0ed0: 74 20 61 70 70 65 61 72 20 62 65 66 6f 72 65 20  t appear before 
0ee0: 61 6e 79 0a 2a 2a 20 73 79 73 74 65 6d 20 23 69  any.** system #i
0ef0: 6e 63 6c 75 64 65 73 2e 20 20 48 65 6e 63 65 2c  ncludes.  Hence,
0f00: 20 74 68 69 73 20 62 6c 6f 63 6b 20 6f 66 20 63   this block of c
0f10: 6f 64 65 20 6d 75 73 74 20 62 65 20 74 68 65 20  ode must be the 
0f20: 76 65 72 79 20 66 69 72 73 74 0a 2a 2a 20 63 6f  very first.** co
0f30: 64 65 20 69 6e 20 61 6c 6c 20 73 6f 75 72 63 65  de in all source
0f40: 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 4c 61   files..**.** La
0f50: 72 67 65 20 66 69 6c 65 20 73 75 70 70 6f 72 74  rge file support
0f60: 20 63 61 6e 20 62 65 20 64 69 73 61 62 6c 65 64   can be disabled
0f70: 20 75 73 69 6e 67 20 74 68 65 20 2d 44 53 51 4c   using the -DSQL
0f80: 49 54 45 5f 44 49 53 41 42 4c 45 5f 4c 46 53 20  ITE_DISABLE_LFS 
0f90: 73 77 69 74 63 68 0a 2a 2a 20 6f 6e 20 74 68 65  switch.** on the
0fa0: 20 63 6f 6d 70 69 6c 65 72 20 63 6f 6d 6d 61 6e   compiler comman
0fb0: 64 20 6c 69 6e 65 2e 20 20 54 68 69 73 20 69 73  d line.  This is
0fc0: 20 6e 65 63 65 73 73 61 72 79 20 69 66 20 79 6f   necessary if yo
0fd0: 75 20 61 72 65 20 63 6f 6d 70 69 6c 69 6e 67 0a  u are compiling.
0fe0: 2a 2a 20 6f 6e 20 61 20 72 65 63 65 6e 74 20 6d  ** on a recent m
0ff0: 61 63 68 69 6e 65 20 28 65 78 3a 20 52 65 64 20  achine (ex: Red 
1000: 48 61 74 20 37 2e 32 29 20 62 75 74 20 79 6f 75  Hat 7.2) but you
1010: 20 77 61 6e 74 20 79 6f 75 72 20 63 6f 64 65 20   want your code 
1020: 74 6f 20 77 6f 72 6b 0a 2a 2a 20 6f 6e 20 61 6e  to work.** on an
1030: 20 6f 6c 64 65 72 20 6d 61 63 68 69 6e 65 20 28   older machine (
1040: 65 78 3a 20 52 65 64 20 48 61 74 20 36 2e 30 29  ex: Red Hat 6.0)
1050: 2e 20 20 49 66 20 79 6f 75 20 63 6f 6d 70 69 6c  .  If you compil
1060: 65 20 6f 6e 20 52 65 64 20 48 61 74 20 37 2e 32  e on Red Hat 7.2
1070: 0a 2a 2a 20 77 69 74 68 6f 75 74 20 74 68 69 73  .** without this
1080: 20 6f 70 74 69 6f 6e 2c 20 4c 46 53 20 69 73 20   option, LFS is 
1090: 65 6e 61 62 6c 65 2e 20 20 42 75 74 20 4c 46 53  enable.  But LFS
10a0: 20 64 6f 65 73 20 6e 6f 74 20 65 78 69 73 74 20   does not exist 
10b0: 69 6e 20 74 68 65 20 6b 65 72 6e 65 6c 0a 2a 2a  in the kernel.**
10c0: 20 69 6e 20 52 65 64 20 48 61 74 20 36 2e 30 2c   in Red Hat 6.0,
10d0: 20 73 6f 20 74 68 65 20 63 6f 64 65 20 77 6f 6e   so the code won
10e0: 27 74 20 77 6f 72 6b 2e 20 20 48 65 6e 63 65 2c  't work.  Hence,
10f0: 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 62 69 6e   for maximum bin
1100: 61 72 79 0a 2a 2a 20 70 6f 72 74 61 62 69 6c 69  ary.** portabili
1110: 74 79 20 79 6f 75 20 73 68 6f 75 6c 64 20 6f 6d  ty you should om
1120: 69 74 20 4c 46 53 2e 0a 2a 2a 0a 2a 2a 20 54 68  it LFS..**.** Th
1130: 65 20 70 72 65 76 69 6f 75 73 20 70 61 72 61 67  e previous parag
1140: 72 61 70 68 20 77 61 73 20 77 72 69 74 74 65 6e  raph was written
1150: 20 69 6e 20 32 30 30 35 2e 20 20 28 54 68 69 73   in 2005.  (This
1160: 20 70 61 72 61 67 72 61 70 68 20 69 73 20 77 72   paragraph is wr
1170: 69 74 74 65 6e 0a 2a 2a 20 6f 6e 20 32 30 30 38  itten.** on 2008
1180: 2d 31 31 2d 32 38 2e 29 20 54 68 65 73 65 20 64  -11-28.) These d
1190: 61 79 73 2c 20 61 6c 6c 20 4c 69 6e 75 78 20 6b  ays, all Linux k
11a0: 65 72 6e 65 6c 73 20 73 75 70 70 6f 72 74 20 6c  ernels support l
11b0: 61 72 67 65 20 66 69 6c 65 73 2c 20 73 6f 0a 2a  arge files, so.*
11c0: 2a 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 72 6f  * you should pro
11d0: 62 61 62 6c 79 20 6c 65 61 76 65 20 4c 46 53 20  bably leave LFS 
11e0: 65 6e 61 62 6c 65 64 2e 20 20 42 75 74 20 73 6f  enabled.  But so
11f0: 6d 65 20 65 6d 62 65 64 64 65 64 20 70 6c 61 74  me embedded plat
1200: 66 6f 72 6d 73 20 6d 69 67 68 74 0a 2a 2a 20 6c  forms might.** l
1210: 61 63 6b 20 4c 46 53 20 69 6e 20 77 68 69 63 68  ack LFS in which
1220: 20 63 61 73 65 20 74 68 65 20 53 51 4c 49 54 45   case the SQLITE
1230: 5f 44 49 53 41 42 4c 45 5f 4c 46 53 20 6d 61 63  _DISABLE_LFS mac
1240: 72 6f 20 6d 69 67 68 74 20 73 74 69 6c 6c 20 62  ro might still b
1250: 65 20 75 73 65 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20  e useful..**.** 
1260: 53 69 6d 69 6c 61 72 20 69 73 20 74 72 75 65 20  Similar is true 
1270: 66 6f 72 20 4d 61 63 20 4f 53 20 58 2e 20 20 4c  for Mac OS X.  L
1280: 46 53 20 69 73 20 6f 6e 6c 79 20 73 75 70 70 6f  FS is only suppo
1290: 72 74 65 64 20 6f 6e 20 4d 61 63 20 4f 53 20 58  rted on Mac OS X
12a0: 20 39 20 61 6e 64 20 6c 61 74 65 72 2e 0a 2a 2f   9 and later..*/
12b0: 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f  .#ifndef SQLITE_
12c0: 44 49 53 41 42 4c 45 5f 4c 46 53 0a 23 20 64 65  DISABLE_LFS.# de
12d0: 66 69 6e 65 20 5f 4c 41 52 47 45 5f 46 49 4c 45  fine _LARGE_FILE
12e0: 20 20 20 20 20 20 20 31 0a 23 20 69 66 6e 64 65         1.# ifnde
12f0: 66 20 5f 46 49 4c 45 5f 4f 46 46 53 45 54 5f 42  f _FILE_OFFSET_B
1300: 49 54 53 0a 23 20 20 20 64 65 66 69 6e 65 20 5f  ITS.#   define _
1310: 46 49 4c 45 5f 4f 46 46 53 45 54 5f 42 49 54 53  FILE_OFFSET_BITS
1320: 20 36 34 0a 23 20 65 6e 64 69 66 0a 23 20 64 65   64.# endif.# de
1330: 66 69 6e 65 20 5f 4c 41 52 47 45 46 49 4c 45 5f  fine _LARGEFILE_
1340: 53 4f 55 52 43 45 20 31 0a 23 65 6e 64 69 66 0a  SOURCE 1.#endif.
1350: 0a 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72 20 76  ./* Needed for v
1360: 61 72 69 6f 75 73 20 64 65 66 69 6e 69 74 69 6f  arious definitio
1370: 6e 73 2e 2e 2e 20 2a 2f 0a 23 69 66 20 64 65 66  ns... */.#if def
1380: 69 6e 65 64 28 5f 5f 47 4e 55 43 5f 5f 29 20 26  ined(__GNUC__) &
1390: 26 20 21 64 65 66 69 6e 65 64 28 5f 47 4e 55 5f  & !defined(_GNU_
13a0: 53 4f 55 52 43 45 29 0a 23 20 64 65 66 69 6e 65  SOURCE).# define
13b0: 20 5f 47 4e 55 5f 53 4f 55 52 43 45 0a 23 65 6e   _GNU_SOURCE.#en
13c0: 64 69 66 0a 0a 23 69 66 20 64 65 66 69 6e 65 64  dif..#if defined
13d0: 28 5f 5f 4f 70 65 6e 42 53 44 5f 5f 29 20 26 26  (__OpenBSD__) &&
13e0: 20 21 64 65 66 69 6e 65 64 28 5f 42 53 44 5f 53   !defined(_BSD_S
13f0: 4f 55 52 43 45 29 0a 23 20 64 65 66 69 6e 65 20  OURCE).# define 
1400: 5f 42 53 44 5f 53 4f 55 52 43 45 0a 23 65 6e 64  _BSD_SOURCE.#end
1410: 69 66 0a 0a 2f 2a 0a 2a 2a 20 46 6f 72 20 4d 69  if../*.** For Mi
1420: 6e 47 57 2c 20 63 68 65 63 6b 20 74 6f 20 73 65  nGW, check to se
1430: 65 20 69 66 20 77 65 20 63 61 6e 20 69 6e 63 6c  e if we can incl
1440: 75 64 65 20 74 68 65 20 68 65 61 64 65 72 20 66  ude the header f
1450: 69 6c 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69  ile containing i
1460: 74 73 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 69 6e  ts.** version in
1470: 66 6f 72 6d 61 74 69 6f 6e 2c 20 61 6d 6f 6e 67  formation, among
1480: 20 6f 74 68 65 72 20 74 68 69 6e 67 73 2e 20 20   other things.  
1490: 4e 6f 72 6d 61 6c 6c 79 2c 20 74 68 69 73 20 69  Normally, this i
14a0: 6e 74 65 72 6e 61 6c 20 4d 69 6e 47 57 0a 2a 2a  nternal MinGW.**
14b0: 20 68 65 61 64 65 72 20 66 69 6c 65 20 77 6f 75   header file wou
14c0: 6c 64 20 5b 6f 6e 6c 79 5d 20 62 65 20 69 6e 63  ld [only] be inc
14d0: 6c 75 64 65 64 20 61 75 74 6f 6d 61 74 69 63 61  luded automatica
14e0: 6c 6c 79 20 62 79 20 6f 74 68 65 72 20 4d 69 6e  lly by other Min
14f0: 47 57 20 68 65 61 64 65 72 0a 2a 2a 20 66 69 6c  GW header.** fil
1500: 65 73 3b 20 68 6f 77 65 76 65 72 2c 20 74 68 65  es; however, the
1510: 20 63 6f 6e 74 61 69 6e 65 64 20 76 65 72 73 69   contained versi
1520: 6f 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  on information i
1530: 73 20 6e 6f 77 20 72 65 71 75 69 72 65 64 20 62  s now required b
1540: 79 20 74 68 69 73 0a 2a 2a 20 68 65 61 64 65 72  y this.** header
1550: 20 66 69 6c 65 20 74 6f 20 77 6f 72 6b 20 61 72   file to work ar
1560: 6f 75 6e 64 20 62 69 6e 61 72 79 20 63 6f 6d 70  ound binary comp
1570: 61 74 69 62 69 6c 69 74 79 20 69 73 73 75 65 73  atibility issues
1580: 20 28 73 65 65 20 62 65 6c 6f 77 29 20 61 6e 64   (see below) and
1590: 0a 2a 2a 20 74 68 69 73 20 69 73 20 74 68 65 20  .** this is the 
15a0: 6f 6e 6c 79 20 6b 6e 6f 77 6e 20 77 61 79 20 74  only known way t
15b0: 6f 20 72 65 6c 69 61 62 6c 79 20 6f 62 74 61 69  o reliably obtai
15c0: 6e 20 69 74 2e 20 20 54 68 69 73 20 65 6e 74 69  n it.  This enti
15d0: 72 65 20 23 69 66 20 62 6c 6f 63 6b 0a 2a 2a 20  re #if block.** 
15e0: 77 6f 75 6c 64 20 62 65 20 63 6f 6d 70 6c 65 74  would be complet
15f0: 65 6c 79 20 75 6e 6e 65 63 65 73 73 61 72 79 20  ely unnecessary 
1600: 69 66 20 74 68 65 72 65 20 77 61 73 20 61 6e 79  if there was any
1610: 20 6f 74 68 65 72 20 77 61 79 20 6f 66 20 64 65   other way of de
1620: 74 65 63 74 69 6e 67 0a 2a 2a 20 4d 69 6e 47 57  tecting.** MinGW
1630: 20 76 69 61 20 74 68 65 69 72 20 70 72 65 70 72   via their prepr
1640: 6f 63 65 73 73 6f 72 20 28 65 2e 67 2e 20 69 66  ocessor (e.g. if
1650: 20 74 68 65 79 20 63 75 73 74 6f 6d 69 7a 65 64   they customized
1660: 20 74 68 65 69 72 20 47 43 43 20 74 6f 20 64 65   their GCC to de
1670: 66 69 6e 65 0a 2a 2a 20 73 6f 6d 65 20 4d 69 6e  fine.** some Min
1680: 47 57 2d 73 70 65 63 69 66 69 63 20 6d 61 63 72  GW-specific macr
1690: 6f 73 29 2e 20 20 57 68 65 6e 20 63 6f 6d 70 69  os).  When compi
16a0: 6c 69 6e 67 20 66 6f 72 20 4d 69 6e 47 57 2c 20  ling for MinGW, 
16b0: 65 69 74 68 65 72 20 74 68 65 0a 2a 2a 20 5f 48  either the.** _H
16c0: 41 56 45 5f 4d 49 4e 47 57 5f 48 20 6f 72 20 5f  AVE_MINGW_H or _
16d0: 48 41 56 45 5f 5f 4d 49 4e 47 57 5f 48 20 28 6e  HAVE__MINGW_H (n
16e0: 6f 74 65 20 74 68 65 20 65 78 74 72 61 20 75 6e  ote the extra un
16f0: 64 65 72 73 63 6f 72 65 29 20 6d 61 63 72 6f 20  derscore) macro 
1700: 6d 75 73 74 20 62 65 0a 2a 2a 20 64 65 66 69 6e  must be.** defin
1710: 65 64 3b 20 6f 74 68 65 72 77 69 73 65 2c 20 64  ed; otherwise, d
1720: 65 74 65 63 74 69 6f 6e 20 6f 66 20 63 6f 6e 64  etection of cond
1730: 69 74 69 6f 6e 73 20 73 70 65 63 69 66 69 63 20  itions specific 
1740: 74 6f 20 4d 69 6e 47 57 20 77 69 6c 6c 20 62 65  to MinGW will be
1750: 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2f  .** disabled..*/
1760: 0a 23 69 66 20 64 65 66 69 6e 65 64 28 5f 48 41  .#if defined(_HA
1770: 56 45 5f 4d 49 4e 47 57 5f 48 29 0a 23 20 69 6e  VE_MINGW_H).# in
1780: 63 6c 75 64 65 20 22 6d 69 6e 67 77 2e 68 22 0a  clude "mingw.h".
1790: 23 65 6c 69 66 20 64 65 66 69 6e 65 64 28 5f 48  #elif defined(_H
17a0: 41 56 45 5f 5f 4d 49 4e 47 57 5f 48 29 0a 23 20  AVE__MINGW_H).# 
17b0: 69 6e 63 6c 75 64 65 20 22 5f 6d 69 6e 67 77 2e  include "_mingw.
17c0: 68 22 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  h".#endif../*.**
17d0: 20 46 6f 72 20 4d 69 6e 47 57 20 76 65 72 73 69   For MinGW versi
17e0: 6f 6e 20 34 2e 78 20 28 61 6e 64 20 68 69 67 68  on 4.x (and high
17f0: 65 72 29 2c 20 63 68 65 63 6b 20 74 6f 20 73 65  er), check to se
1800: 65 20 69 66 20 74 68 65 20 5f 55 53 45 5f 33 32  e if the _USE_32
1810: 42 49 54 5f 54 49 4d 45 5f 54 0a 2a 2a 20 64 65  BIT_TIME_T.** de
1820: 66 69 6e 65 20 69 73 20 72 65 71 75 69 72 65 64  fine is required
1830: 20 74 6f 20 6d 61 69 6e 74 61 69 6e 20 62 69 6e   to maintain bin
1840: 61 72 79 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  ary compatibilit
1850: 79 20 77 69 74 68 20 74 68 65 20 4d 53 56 43 20  y with the MSVC 
1860: 72 75 6e 74 69 6d 65 0a 2a 2a 20 6c 69 62 72 61  runtime.** libra
1870: 72 79 20 69 6e 20 75 73 65 20 28 65 2e 67 2e 20  ry in use (e.g. 
1880: 66 6f 72 20 57 69 6e 64 6f 77 73 20 58 50 29 2e  for Windows XP).
1890: 0a 2a 2f 0a 23 69 66 20 21 64 65 66 69 6e 65 64  .*/.#if !defined
18a0: 28 5f 55 53 45 5f 33 32 42 49 54 5f 54 49 4d 45  (_USE_32BIT_TIME
18b0: 5f 54 29 20 26 26 20 21 64 65 66 69 6e 65 64 28  _T) && !defined(
18c0: 5f 55 53 45 5f 36 34 42 49 54 5f 54 49 4d 45 5f  _USE_64BIT_TIME_
18d0: 54 29 20 26 26 20 5c 0a 20 20 20 20 64 65 66 69  T) && \.    defi
18e0: 6e 65 64 28 5f 57 49 4e 33 32 29 20 26 26 20 21  ned(_WIN32) && !
18f0: 64 65 66 69 6e 65 64 28 5f 57 49 4e 36 34 29 20  defined(_WIN64) 
1900: 26 26 20 5c 0a 20 20 20 20 64 65 66 69 6e 65 64  && \.    defined
1910: 28 5f 5f 4d 49 4e 47 57 5f 4d 41 4a 4f 52 5f 56  (__MINGW_MAJOR_V
1920: 45 52 53 49 4f 4e 29 20 26 26 20 5f 5f 4d 49 4e  ERSION) && __MIN
1930: 47 57 5f 4d 41 4a 4f 52 5f 56 45 52 53 49 4f 4e  GW_MAJOR_VERSION
1940: 20 3e 3d 20 34 20 26 26 20 5c 0a 20 20 20 20 64   >= 4 && \.    d
1950: 65 66 69 6e 65 64 28 5f 5f 4d 53 56 43 52 54 5f  efined(__MSVCRT_
1960: 5f 29 0a 23 20 64 65 66 69 6e 65 20 5f 55 53 45  _).# define _USE
1970: 5f 33 32 42 49 54 5f 54 49 4d 45 5f 54 0a 23 65  _32BIT_TIME_T.#e
1980: 6e 64 69 66 0a 0a 2f 2a 20 54 68 65 20 70 75 62  ndif../* The pub
1990: 6c 69 63 20 53 51 4c 69 74 65 20 69 6e 74 65 72  lic SQLite inter
19a0: 66 61 63 65 2e 20 20 54 68 65 20 5f 46 49 4c 45  face.  The _FILE
19b0: 5f 4f 46 46 53 45 54 5f 42 49 54 53 20 6d 61 63  _OFFSET_BITS mac
19c0: 72 6f 20 6d 75 73 74 20 61 70 70 65 61 72 0a 2a  ro must appear.*
19d0: 2a 20 66 69 72 73 74 20 69 6e 20 51 4e 58 2e 20  * first in QNX. 
19e0: 20 41 6c 73 6f 2c 20 74 68 65 20 5f 55 53 45 5f   Also, the _USE_
19f0: 33 32 42 49 54 5f 54 49 4d 45 5f 54 20 6d 61 63  32BIT_TIME_T mac
1a00: 72 6f 20 6d 75 73 74 20 61 70 70 65 61 72 20 66  ro must appear f
1a10: 69 72 73 74 20 66 6f 72 0a 2a 2a 20 4d 69 6e 47  irst for.** MinG
1a20: 57 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a  W..*/./*********
1a30: 2a 2a 2a 2a 2a 20 49 6e 63 6c 75 64 65 20 73 71  ***** Include sq
1a40: 6c 69 74 65 33 2e 68 20 69 6e 20 74 68 65 20 6d  lite3.h in the m
1a50: 69 64 64 6c 65 20 6f 66 20 73 71 6c 69 74 65 49  iddle of sqliteI
1a60: 6e 74 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  nt.h ***********
1a70: 2a 2a 2a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****/./*********
1a80: 2a 2a 2a 2a 2a 20 42 65 67 69 6e 20 66 69 6c 65  ***** Begin file
1a90: 20 73 71 6c 69 74 65 33 2e 68 20 2a 2a 2a 2a 2a   sqlite3.h *****
1aa0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1ab0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1ac0: 2a 2a 2a 2a 2f 0a 2f 2a 0a 2a 2a 20 32 30 30 31  ****/./*.** 2001
1ad0: 20 53 65 70 74 65 6d 62 65 72 20 31 35 0a 2a 2a   September 15.**
1ae0: 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 20 64  .** The author d
1af0: 69 73 63 6c 61 69 6d 73 20 63 6f 70 79 72 69 67  isclaims copyrig
1b00: 68 74 20 74 6f 20 74 68 69 73 20 73 6f 75 72 63  ht to this sourc
1b10: 65 20 63 6f 64 65 2e 20 20 49 6e 20 70 6c 61 63  e code.  In plac
1b20: 65 20 6f 66 0a 2a 2a 20 61 20 6c 65 67 61 6c 20  e of.** a legal 
1b30: 6e 6f 74 69 63 65 2c 20 68 65 72 65 20 69 73 20  notice, here is 
1b40: 61 20 62 6c 65 73 73 69 6e 67 3a 0a 2a 2a 0a 2a  a blessing:.**.*
1b50: 2a 20 20 20 20 4d 61 79 20 79 6f 75 20 64 6f 20  *    May you do 
1b60: 67 6f 6f 64 20 61 6e 64 20 6e 6f 74 20 65 76 69  good and not evi
1b70: 6c 2e 0a 2a 2a 20 20 20 20 4d 61 79 20 79 6f 75  l..**    May you
1b80: 20 66 69 6e 64 20 66 6f 72 67 69 76 65 6e 65 73   find forgivenes
1b90: 73 20 66 6f 72 20 79 6f 75 72 73 65 6c 66 20 61  s for yourself a
1ba0: 6e 64 20 66 6f 72 67 69 76 65 20 6f 74 68 65 72  nd forgive other
1bb0: 73 2e 0a 2a 2a 20 20 20 20 4d 61 79 20 79 6f 75  s..**    May you
1bc0: 20 73 68 61 72 65 20 66 72 65 65 6c 79 2c 20 6e   share freely, n
1bd0: 65 76 65 72 20 74 61 6b 69 6e 67 20 6d 6f 72 65  ever taking more
1be0: 20 74 68 61 6e 20 79 6f 75 20 67 69 76 65 2e 0a   than you give..
1bf0: 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  **.*************
1c00: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1c10: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1c20: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1c30: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a 2a 20  ************.** 
1c40: 54 68 69 73 20 68 65 61 64 65 72 20 66 69 6c 65  This header file
1c50: 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74   defines the int
1c60: 65 72 66 61 63 65 20 74 68 61 74 20 74 68 65 20  erface that the 
1c70: 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 0a 2a  SQLite library.*
1c80: 2a 20 70 72 65 73 65 6e 74 73 20 74 6f 20 63 6c  * presents to cl
1c90: 69 65 6e 74 20 70 72 6f 67 72 61 6d 73 2e 20 20  ient programs.  
1ca0: 49 66 20 61 20 43 2d 66 75 6e 63 74 69 6f 6e 2c  If a C-function,
1cb0: 20 73 74 72 75 63 74 75 72 65 2c 20 64 61 74 61   structure, data
1cc0: 74 79 70 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6e 73  type,.** or cons
1cd0: 74 61 6e 74 20 64 65 66 69 6e 69 74 69 6f 6e 20  tant definition 
1ce0: 64 6f 65 73 20 6e 6f 74 20 61 70 70 65 61 72 20  does not appear 
1cf0: 69 6e 20 74 68 69 73 20 66 69 6c 65 2c 20 74 68  in this file, th
1d00: 65 6e 20 69 74 20 69 73 0a 2a 2a 20 6e 6f 74 20  en it is.** not 
1d10: 61 20 70 75 62 6c 69 73 68 65 64 20 41 50 49 20  a published API 
1d20: 6f 66 20 53 51 4c 69 74 65 2c 20 69 73 20 73 75  of SQLite, is su
1d30: 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20  bject to change 
1d40: 77 69 74 68 6f 75 74 0a 2a 2a 20 6e 6f 74 69 63  without.** notic
1d50: 65 2c 20 61 6e 64 20 73 68 6f 75 6c 64 20 6e 6f  e, and should no
1d60: 74 20 62 65 20 72 65 66 65 72 65 6e 63 65 64 20  t be referenced 
1d70: 62 79 20 70 72 6f 67 72 61 6d 73 20 74 68 61 74  by programs that
1d80: 20 75 73 65 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a   use SQLite..**.
1d90: 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68 65 20 64  ** Some of the d
1da0: 65 66 69 6e 69 74 69 6f 6e 73 20 74 68 61 74 20  efinitions that 
1db0: 61 72 65 20 69 6e 20 74 68 69 73 20 66 69 6c 65  are in this file
1dc0: 20 61 72 65 20 6d 61 72 6b 65 64 20 61 73 0a 2a   are marked as.*
1dd0: 2a 20 22 65 78 70 65 72 69 6d 65 6e 74 61 6c 22  * "experimental"
1de0: 2e 20 20 45 78 70 65 72 69 6d 65 6e 74 61 6c 20  .  Experimental 
1df0: 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 6e  interfaces are n
1e00: 6f 72 6d 61 6c 6c 79 20 6e 65 77 0a 2a 2a 20 66  ormally new.** f
1e10: 65 61 74 75 72 65 73 20 72 65 63 65 6e 74 6c 79  eatures recently
1e20: 20 61 64 64 65 64 20 74 6f 20 53 51 4c 69 74 65   added to SQLite
1e30: 2e 20 20 57 65 20 64 6f 20 6e 6f 74 20 61 6e 74  .  We do not ant
1e40: 69 63 69 70 61 74 65 20 63 68 61 6e 67 65 73 0a  icipate changes.
1e50: 2a 2a 20 74 6f 20 65 78 70 65 72 69 6d 65 6e 74  ** to experiment
1e60: 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 62 75  al interfaces bu
1e70: 74 20 72 65 73 65 72 76 65 20 74 68 65 20 72 69  t reserve the ri
1e80: 67 68 74 20 74 6f 20 6d 61 6b 65 20 6d 69 6e 6f  ght to make mino
1e90: 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20 69 66 20  r changes.** if 
1ea0: 65 78 70 65 72 69 65 6e 63 65 20 66 72 6f 6d 20  experience from 
1eb0: 75 73 65 20 22 69 6e 20 74 68 65 20 77 69 6c 64  use "in the wild
1ec0: 22 20 73 75 67 67 65 73 74 20 73 75 63 68 20 63  " suggest such c
1ed0: 68 61 6e 67 65 73 20 61 72 65 20 70 72 75 64 65  hanges are prude
1ee0: 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 66  nt..**.** The of
1ef0: 66 69 63 69 61 6c 20 43 2d 6c 61 6e 67 75 61 67  ficial C-languag
1f00: 65 20 41 50 49 20 64 6f 63 75 6d 65 6e 74 61 74  e API documentat
1f10: 69 6f 6e 20 66 6f 72 20 53 51 4c 69 74 65 20 69  ion for SQLite i
1f20: 73 20 64 65 72 69 76 65 64 0a 2a 2a 20 66 72 6f  s derived.** fro
1f30: 6d 20 63 6f 6d 6d 65 6e 74 73 20 69 6e 20 74 68  m comments in th
1f40: 69 73 20 66 69 6c 65 2e 20 20 54 68 69 73 20 66  is file.  This f
1f50: 69 6c 65 20 69 73 20 74 68 65 20 61 75 74 68 6f  ile is the autho
1f60: 72 69 74 61 74 69 76 65 20 73 6f 75 72 63 65 0a  ritative source.
1f70: 2a 2a 20 6f 6e 20 68 6f 77 20 53 51 4c 69 74 65  ** on how SQLite
1f80: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
1f90: 73 75 70 70 6f 73 65 20 74 6f 20 6f 70 65 72 61  suppose to opera
1fa0: 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61  te..**.** The na
1fb0: 6d 65 20 6f 66 20 74 68 69 73 20 66 69 6c 65 20  me of this file 
1fc0: 75 6e 64 65 72 20 63 6f 6e 66 69 67 75 72 61 74  under configurat
1fd0: 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 20 69  ion management i
1fe0: 73 20 22 73 71 6c 69 74 65 2e 68 2e 69 6e 22 2e  s "sqlite.h.in".
1ff0: 0a 2a 2a 20 54 68 65 20 6d 61 6b 65 66 69 6c 65  .** The makefile
2000: 20 6d 61 6b 65 73 20 73 6f 6d 65 20 6d 69 6e 6f   makes some mino
2010: 72 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 69  r changes to thi
2020: 73 20 66 69 6c 65 20 28 73 75 63 68 20 61 73 20  s file (such as 
2030: 69 6e 73 65 72 74 69 6e 67 0a 2a 2a 20 74 68 65  inserting.** the
2040: 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 29   version number)
2050: 20 61 6e 64 20 63 68 61 6e 67 65 73 20 69 74 73   and changes its
2060: 20 6e 61 6d 65 20 74 6f 20 22 73 71 6c 69 74 65   name to "sqlite
2070: 33 2e 68 22 20 61 73 0a 2a 2a 20 70 61 72 74 20  3.h" as.** part 
2080: 6f 66 20 74 68 65 20 62 75 69 6c 64 20 70 72 6f  of the build pro
2090: 63 65 73 73 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66  cess..*/.#ifndef
20a0: 20 5f 53 51 4c 49 54 45 33 5f 48 5f 0a 23 64 65   _SQLITE3_H_.#de
20b0: 66 69 6e 65 20 5f 53 51 4c 49 54 45 33 5f 48 5f  fine _SQLITE3_H_
20c0: 0a 23 69 6e 63 6c 75 64 65 20 3c 73 74 64 61 72  .#include <stdar
20d0: 67 2e 68 3e 20 20 20 20 20 2f 2a 20 4e 65 65 64  g.h>     /* Need
20e0: 65 64 20 66 6f 72 20 74 68 65 20 64 65 66 69 6e  ed for the defin
20f0: 69 74 69 6f 6e 20 6f 66 20 76 61 5f 6c 69 73 74  ition of va_list
2100: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 4d 61 6b 65 20   */../*.** Make 
2110: 73 75 72 65 20 77 65 20 63 61 6e 20 63 61 6c 6c  sure we can call
2120: 20 74 68 69 73 20 73 74 75 66 66 20 66 72 6f 6d   this stuff from
2130: 20 43 2b 2b 2e 0a 2a 2f 0a 23 69 66 20 30 0a 65   C++..*/.#if 0.e
2140: 78 74 65 72 6e 20 22 43 22 20 7b 0a 23 65 6e 64  xtern "C" {.#end
2150: 69 66 0a 0a 0a 2f 2a 0a 2a 2a 20 41 64 64 20 74  if.../*.** Add t
2160: 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20 6f 76  he ability to ov
2170: 65 72 72 69 64 65 20 27 65 78 74 65 72 6e 27 0a  erride 'extern'.
2180: 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54  */.#ifndef SQLIT
2190: 45 5f 45 58 54 45 52 4e 0a 23 20 64 65 66 69 6e  E_EXTERN.# defin
21a0: 65 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20  e SQLITE_EXTERN 
21b0: 65 78 74 65 72 6e 0a 23 65 6e 64 69 66 0a 0a 23  extern.#endif..#
21c0: 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 41 50  ifndef SQLITE_AP
21d0: 49 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54  I.# define SQLIT
21e0: 45 5f 41 50 49 0a 23 65 6e 64 69 66 0a 0a 0a 2f  E_API.#endif.../
21f0: 2a 0a 2a 2a 20 54 68 65 73 65 20 6e 6f 2d 6f 70  *.** These no-op
2200: 20 6d 61 63 72 6f 73 20 61 72 65 20 75 73 65 64   macros are used
2210: 20 69 6e 20 66 72 6f 6e 74 20 6f 66 20 69 6e 74   in front of int
2220: 65 72 66 61 63 65 73 20 74 6f 20 6d 61 72 6b 20  erfaces to mark 
2230: 74 68 6f 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61  those.** interfa
2240: 63 65 73 20 61 73 20 65 69 74 68 65 72 20 64 65  ces as either de
2250: 70 72 65 63 61 74 65 64 20 6f 72 20 65 78 70 65  precated or expe
2260: 72 69 6d 65 6e 74 61 6c 2e 20 20 4e 65 77 20 61  rimental.  New a
2270: 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73  pplications.** s
2280: 68 6f 75 6c 64 20 6e 6f 74 20 75 73 65 20 64 65  hould not use de
2290: 70 72 65 63 61 74 65 64 20 69 6e 74 65 72 66 61  precated interfa
22a0: 63 65 73 20 2d 20 74 68 65 79 20 61 72 65 20 73  ces - they are s
22b0: 75 70 70 6f 72 74 65 64 20 66 6f 72 20 62 61 63  upported for bac
22c0: 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74  kwards.** compat
22d0: 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 20 20 41  ibility only.  A
22e0: 70 70 6c 69 63 61 74 69 6f 6e 20 77 72 69 74 65  pplication write
22f0: 72 73 20 73 68 6f 75 6c 64 20 62 65 20 61 77 61  rs should be awa
2300: 72 65 20 74 68 61 74 0a 2a 2a 20 65 78 70 65 72  re that.** exper
2310: 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66 61 63  imental interfac
2320: 65 73 20 61 72 65 20 73 75 62 6a 65 63 74 20 74  es are subject t
2330: 6f 20 63 68 61 6e 67 65 20 69 6e 20 70 6f 69 6e  o change in poin
2340: 74 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a  t releases..**.*
2350: 2a 20 54 68 65 73 65 20 6d 61 63 72 6f 73 20 75  * These macros u
2360: 73 65 64 20 74 6f 20 72 65 73 6f 6c 76 65 20 74  sed to resolve t
2370: 6f 20 76 61 72 69 6f 75 73 20 6b 69 6e 64 73 20  o various kinds 
2380: 6f 66 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69  of compiler magi
2390: 63 20 74 68 61 74 0a 2a 2a 20 77 6f 75 6c 64 20  c that.** would 
23a0: 67 65 6e 65 72 61 74 65 20 77 61 72 6e 69 6e 67  generate warning
23b0: 20 6d 65 73 73 61 67 65 73 20 77 68 65 6e 20 74   messages when t
23c0: 68 65 79 20 77 65 72 65 20 75 73 65 64 2e 20 20  hey were used.  
23d0: 42 75 74 20 74 68 61 74 0a 2a 2a 20 63 6f 6d 70  But that.** comp
23e0: 69 6c 65 72 20 6d 61 67 69 63 20 65 6e 64 65 64  iler magic ended
23f0: 20 75 70 20 67 65 6e 65 72 61 74 69 6e 67 20 73   up generating s
2400: 75 63 68 20 61 20 66 6c 75 72 72 79 20 6f 66 20  uch a flurry of 
2410: 62 75 67 20 72 65 70 6f 72 74 73 0a 2a 2a 20 74  bug reports.** t
2420: 68 61 74 20 77 65 20 68 61 76 65 20 74 61 6b 65  hat we have take
2430: 6e 20 69 74 20 61 6c 6c 20 6f 75 74 20 61 6e 64  n it all out and
2440: 20 67 6f 6e 65 20 62 61 63 6b 20 74 6f 20 75 73   gone back to us
2450: 69 6e 67 20 73 69 6d 70 6c 65 0a 2a 2a 20 6e 6f  ing simple.** no
2460: 6f 70 20 6d 61 63 72 6f 73 2e 0a 2a 2f 0a 23 64  op macros..*/.#d
2470: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 50  efine SQLITE_DEP
2480: 52 45 43 41 54 45 44 0a 23 64 65 66 69 6e 65 20  RECATED.#define 
2490: 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e  SQLITE_EXPERIMEN
24a0: 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20 45 6e 73 75 72  TAL../*.** Ensur
24b0: 65 20 74 68 65 73 65 20 73 79 6d 62 6f 6c 73 20  e these symbols 
24c0: 77 65 72 65 20 6e 6f 74 20 64 65 66 69 6e 65 64  were not defined
24d0: 20 62 79 20 73 6f 6d 65 20 70 72 65 76 69 6f 75   by some previou
24e0: 73 20 68 65 61 64 65 72 20 66 69 6c 65 2e 0a 2a  s header file..*
24f0: 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f  /.#ifdef SQLITE_
2500: 56 45 52 53 49 4f 4e 0a 23 20 75 6e 64 65 66 20  VERSION.# undef 
2510: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23  SQLITE_VERSION.#
2520: 65 6e 64 69 66 0a 23 69 66 64 65 66 20 53 51 4c  endif.#ifdef SQL
2530: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
2540: 45 52 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54  ER.# undef SQLIT
2550: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
2560: 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43  .#endif../*.** C
2570: 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65  API3REF: Compile
2580: 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20 56 65  -Time Library Ve
2590: 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a  rsion Numbers.**
25a0: 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49 54  .** ^(The [SQLIT
25b0: 45 5f 56 45 52 53 49 4f 4e 5d 20 43 20 70 72 65  E_VERSION] C pre
25c0: 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20  processor macro 
25d0: 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 2e 68  in the sqlite3.h
25e0: 20 68 65 61 64 65 72 0a 2a 2a 20 65 76 61 6c 75   header.** evalu
25f0: 61 74 65 73 20 74 6f 20 61 20 73 74 72 69 6e 67  ates to a string
2600: 20 6c 69 74 65 72 61 6c 20 74 68 61 74 20 69 73   literal that is
2610: 20 74 68 65 20 53 51 4c 69 74 65 20 76 65 72 73   the SQLite vers
2620: 69 6f 6e 20 69 6e 20 74 68 65 0a 2a 2a 20 66 6f  ion in the.** fo
2630: 72 6d 61 74 20 22 58 2e 59 2e 5a 22 20 77 68 65  rmat "X.Y.Z" whe
2640: 72 65 20 58 20 69 73 20 74 68 65 20 6d 61 6a 6f  re X is the majo
2650: 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72  r version number
2660: 20 28 61 6c 77 61 79 73 20 33 20 66 6f 72 0a 2a   (always 3 for.*
2670: 2a 20 53 51 4c 69 74 65 33 29 20 61 6e 64 20 59  * SQLite3) and Y
2680: 20 69 73 20 74 68 65 20 6d 69 6e 6f 72 20 76 65   is the minor ve
2690: 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 61 6e 64  rsion number and
26a0: 20 5a 20 69 73 20 74 68 65 20 72 65 6c 65 61 73   Z is the releas
26b0: 65 20 6e 75 6d 62 65 72 2e 29 5e 0a 2a 2a 20 5e  e number.)^.** ^
26c0: 28 54 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52  (The [SQLITE_VER
26d0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 20 43 20 70  SION_NUMBER] C p
26e0: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
26f0: 6f 20 72 65 73 6f 6c 76 65 73 20 74 6f 20 61 6e  o resolves to an
2700: 20 69 6e 74 65 67 65 72 0a 2a 2a 20 77 69 74 68   integer.** with
2710: 20 74 68 65 20 76 61 6c 75 65 20 28 58 2a 31 30   the value (X*10
2720: 30 30 30 30 30 20 2b 20 59 2a 31 30 30 30 20 2b  00000 + Y*1000 +
2730: 20 5a 29 20 77 68 65 72 65 20 58 2c 20 59 2c 20   Z) where X, Y, 
2740: 61 6e 64 20 5a 20 61 72 65 20 74 68 65 20 73 61  and Z are the sa
2750: 6d 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 75 73  me.** numbers us
2760: 65 64 20 69 6e 20 5b 53 51 4c 49 54 45 5f 56 45  ed in [SQLITE_VE
2770: 52 53 49 4f 4e 5d 2e 29 5e 0a 2a 2a 20 54 68 65  RSION].)^.** The
2780: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f   SQLITE_VERSION_
2790: 4e 55 4d 42 45 52 20 66 6f 72 20 61 6e 79 20 67  NUMBER for any g
27a0: 69 76 65 6e 20 72 65 6c 65 61 73 65 20 6f 66 20  iven release of 
27b0: 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f  SQLite will also
27c0: 0a 2a 2a 20 62 65 20 6c 61 72 67 65 72 20 74 68  .** be larger th
27d0: 61 6e 20 74 68 65 20 72 65 6c 65 61 73 65 20 66  an the release f
27e0: 72 6f 6d 20 77 68 69 63 68 20 69 74 20 69 73 20  rom which it is 
27f0: 64 65 72 69 76 65 64 2e 20 20 45 69 74 68 65 72  derived.  Either
2800: 20 59 20 77 69 6c 6c 0a 2a 2a 20 62 65 20 68 65   Y will.** be he
2810: 6c 64 20 63 6f 6e 73 74 61 6e 74 20 61 6e 64 20  ld constant and 
2820: 5a 20 77 69 6c 6c 20 62 65 20 69 6e 63 72 65 6d  Z will be increm
2830: 65 6e 74 65 64 20 6f 72 20 65 6c 73 65 20 59 20  ented or else Y 
2840: 77 69 6c 6c 20 62 65 20 69 6e 63 72 65 6d 65 6e  will be incremen
2850: 74 65 64 0a 2a 2a 20 61 6e 64 20 5a 20 77 69 6c  ted.** and Z wil
2860: 6c 20 62 65 20 72 65 73 65 74 20 74 6f 20 7a 65  l be reset to ze
2870: 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 69 6e 63 65 20  ro..**.** Since 
2880: 76 65 72 73 69 6f 6e 20 33 2e 36 2e 31 38 2c 20  version 3.6.18, 
2890: 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20 63 6f  SQLite source co
28a0: 64 65 20 68 61 73 20 62 65 65 6e 20 73 74 6f 72  de has been stor
28b0: 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20 3c 61 20  ed in the.** <a 
28c0: 68 72 65 66 3d 22 68 74 74 70 3a 2f 2f 77 77 77  href="http://www
28d0: 2e 66 6f 73 73 69 6c 2d 73 63 6d 2e 6f 72 67 2f  .fossil-scm.org/
28e0: 22 3e 46 6f 73 73 69 6c 20 63 6f 6e 66 69 67 75  ">Fossil configu
28f0: 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e  ration managemen
2900: 74 0a 2a 2a 20 73 79 73 74 65 6d 3c 2f 61 3e 2e  t.** system</a>.
2910: 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 53 4f    ^The SQLITE_SO
2920: 55 52 43 45 5f 49 44 20 6d 61 63 72 6f 20 65 76  URCE_ID macro ev
2930: 61 6c 75 61 74 65 73 20 74 6f 0a 2a 2a 20 61 20  aluates to.** a 
2940: 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 64 65  string which ide
2950: 6e 74 69 66 69 65 73 20 61 20 70 61 72 74 69 63  ntifies a partic
2960: 75 6c 61 72 20 63 68 65 63 6b 2d 69 6e 20 6f 66  ular check-in of
2970: 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 74 68 69   SQLite.** withi
2980: 6e 20 69 74 73 20 63 6f 6e 66 69 67 75 72 61 74  n its configurat
2990: 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 20 73  ion management s
29a0: 79 73 74 65 6d 2e 20 20 5e 54 68 65 20 53 51 4c  ystem.  ^The SQL
29b0: 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 0a 2a 2a  ITE_SOURCE_ID.**
29c0: 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 73   string contains
29d0: 20 74 68 65 20 64 61 74 65 20 61 6e 64 20 74 69   the date and ti
29e0: 6d 65 20 6f 66 20 74 68 65 20 63 68 65 63 6b 2d  me of the check-
29f0: 69 6e 20 28 55 54 43 29 20 61 6e 64 20 61 6e 20  in (UTC) and an 
2a00: 53 48 41 31 0a 2a 2a 20 68 61 73 68 20 6f 66 20  SHA1.** hash of 
2a10: 74 68 65 20 65 6e 74 69 72 65 20 73 6f 75 72 63  the entire sourc
2a20: 65 20 74 72 65 65 2e 0a 2a 2a 0a 2a 2a 20 53 65  e tree..**.** Se
2a30: 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
2a40: 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 5d 2c 0a  _libversion()],.
2a50: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76  ** [sqlite3_libv
2a60: 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 5d  ersion_number()]
2a70: 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  , [sqlite3_sourc
2a80: 65 69 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  eid()],.** [sqli
2a90: 74 65 5f 76 65 72 73 69 6f 6e 28 29 5d 20 61 6e  te_version()] an
2aa0: 64 20 5b 73 71 6c 69 74 65 5f 73 6f 75 72 63 65  d [sqlite_source
2ab0: 5f 69 64 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69  _id()]..*/.#defi
2ac0: 6e 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  ne SQLITE_VERSIO
2ad0: 4e 20 20 20 20 20 20 20 20 22 33 2e 38 2e 38 22  N        "3.8.8"
2ae0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2af0: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 33  VERSION_NUMBER 3
2b00: 30 30 38 30 30 38 0a 23 64 65 66 69 6e 65 20 53  008008.#define S
2b10: 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 20  QLITE_SOURCE_ID 
2b20: 20 20 20 20 20 22 32 30 31 35 2d 30 31 2d 31 33       "2015-01-13
2b30: 20 32 31 3a 32 36 3a 31 37 20 38 38 32 31 38 31   21:26:17 882181
2b40: 66 66 39 64 64 37 35 66 33 32 64 62 32 36 36 64  ff9dd75f32db266d
2b50: 62 36 65 34 37 36 36 37 31 30 32 31 66 63 35 36  b6e476671021fc56
2b60: 37 62 22 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  7b"../*.** CAPI3
2b70: 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69  REF: Run-Time Li
2b80: 62 72 61 72 79 20 56 65 72 73 69 6f 6e 20 4e 75  brary Version Nu
2b90: 6d 62 65 72 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  mbers.** KEYWORD
2ba0: 53 3a 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69  S: sqlite3_versi
2bb0: 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 73 6f 75 72  on, sqlite3_sour
2bc0: 63 65 69 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ceid.**.** These
2bd0: 20 69 6e 74 65 72 66 61 63 65 73 20 70 72 6f 76   interfaces prov
2be0: 69 64 65 20 74 68 65 20 73 61 6d 65 20 69 6e 66  ide the same inf
2bf0: 6f 72 6d 61 74 69 6f 6e 20 61 73 20 74 68 65 20  ormation as the 
2c00: 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d  [SQLITE_VERSION]
2c10: 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52  ,.** [SQLITE_VER
2c20: 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2c 20 61 6e  SION_NUMBER], an
2c30: 64 20 5b 53 51 4c 49 54 45 5f 53 4f 55 52 43 45  d [SQLITE_SOURCE
2c40: 5f 49 44 5d 20 43 20 70 72 65 70 72 6f 63 65 73  _ID] C preproces
2c50: 73 6f 72 20 6d 61 63 72 6f 73 0a 2a 2a 20 62 75  sor macros.** bu
2c60: 74 20 61 72 65 20 61 73 73 6f 63 69 61 74 65 64  t are associated
2c70: 20 77 69 74 68 20 74 68 65 20 6c 69 62 72 61 72   with the librar
2c80: 79 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65  y instead of the
2c90: 20 68 65 61 64 65 72 20 66 69 6c 65 2e 20 20 5e   header file.  ^
2ca0: 28 43 61 75 74 69 6f 75 73 0a 2a 2a 20 70 72 6f  (Cautious.** pro
2cb0: 67 72 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 69  grammers might i
2cc0: 6e 63 6c 75 64 65 20 61 73 73 65 72 74 28 29 20  nclude assert() 
2cd0: 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68  statements in th
2ce0: 65 69 72 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  eir application 
2cf0: 74 6f 0a 2a 2a 20 76 65 72 69 66 79 20 74 68 61  to.** verify tha
2d00: 74 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65  t values returne
2d10: 64 20 62 79 20 74 68 65 73 65 20 69 6e 74 65 72  d by these inter
2d20: 66 61 63 65 73 20 6d 61 74 63 68 20 74 68 65 20  faces match the 
2d30: 6d 61 63 72 6f 73 20 69 6e 0a 2a 2a 20 74 68 65  macros in.** the
2d40: 20 68 65 61 64 65 72 2c 20 61 6e 64 20 74 68 75   header, and thu
2d50: 73 20 69 6e 73 75 72 65 20 74 68 61 74 20 74 68  s insure that th
2d60: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73  e application is
2d70: 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 74  .** compiled wit
2d80: 68 20 6d 61 74 63 68 69 6e 67 20 6c 69 62 72 61  h matching libra
2d90: 72 79 20 61 6e 64 20 68 65 61 64 65 72 20 66 69  ry and header fi
2da0: 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  les..**.** <bloc
2db0: 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
2dc0: 61 73 73 65 72 74 28 20 73 71 6c 69 74 65 33 5f  assert( sqlite3_
2dd0: 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65  libversion_numbe
2de0: 72 28 29 3d 3d 53 51 4c 49 54 45 5f 56 45 52 53  r()==SQLITE_VERS
2df0: 49 4f 4e 5f 4e 55 4d 42 45 52 20 29 3b 0a 2a 2a  ION_NUMBER );.**
2e00: 20 61 73 73 65 72 74 28 20 73 74 72 63 6d 70 28   assert( strcmp(
2e10: 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64  sqlite3_sourceid
2e20: 28 29 2c 53 51 4c 49 54 45 5f 53 4f 55 52 43 45  (),SQLITE_SOURCE
2e30: 5f 49 44 29 3d 3d 30 20 29 3b 0a 2a 2a 20 61 73  _ID)==0 );.** as
2e40: 73 65 72 74 28 20 73 74 72 63 6d 70 28 73 71 6c  sert( strcmp(sql
2e50: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28  ite3_libversion(
2e60: 29 2c 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  ),SQLITE_VERSION
2e70: 29 3d 3d 30 20 29 3b 0a 2a 2a 20 3c 2f 70 72 65  )==0 );.** </pre
2e80: 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e  ></blockquote>)^
2e90: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2ea0: 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74  te3_version[] st
2eb0: 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 20 63 6f  ring constant co
2ec0: 6e 74 61 69 6e 73 20 74 68 65 20 74 65 78 74 20  ntains the text 
2ed0: 6f 66 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49  of [SQLITE_VERSI
2ee0: 4f 4e 5d 0a 2a 2a 20 6d 61 63 72 6f 2e 20 20 5e  ON].** macro.  ^
2ef0: 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 69 62 76  The sqlite3_libv
2f00: 65 72 73 69 6f 6e 28 29 20 66 75 6e 63 74 69 6f  ersion() functio
2f10: 6e 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  n returns a poin
2f20: 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 74 6f  ter to the.** to
2f30: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 65 72   the sqlite3_ver
2f40: 73 69 6f 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f  sion[] string co
2f50: 6e 73 74 61 6e 74 2e 20 20 54 68 65 20 73 71 6c  nstant.  The sql
2f60: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28  ite3_libversion(
2f70: 29 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73  ).** function is
2f80: 20 70 72 6f 76 69 64 65 64 20 66 6f 72 20 75 73   provided for us
2f90: 65 20 69 6e 20 44 4c 4c 73 20 73 69 6e 63 65 20  e in DLLs since 
2fa0: 44 4c 4c 20 75 73 65 72 73 20 75 73 75 61 6c 6c  DLL users usuall
2fb0: 79 20 64 6f 20 6e 6f 74 20 68 61 76 65 0a 2a 2a  y do not have.**
2fc0: 20 64 69 72 65 63 74 20 61 63 63 65 73 73 20 74   direct access t
2fd0: 6f 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e  o string constan
2fe0: 74 73 20 77 69 74 68 69 6e 20 74 68 65 20 44 4c  ts within the DL
2ff0: 4c 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69  L.  ^The.** sqli
3000: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e  te3_libversion_n
3010: 75 6d 62 65 72 28 29 20 66 75 6e 63 74 69 6f 6e  umber() function
3020: 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65   returns an inte
3030: 67 65 72 20 65 71 75 61 6c 20 74 6f 0a 2a 2a 20  ger equal to.** 
3040: 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f  [SQLITE_VERSION_
3050: 4e 55 4d 42 45 52 5d 2e 20 20 5e 54 68 65 20 73  NUMBER].  ^The s
3060: 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28  qlite3_sourceid(
3070: 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  ) function retur
3080: 6e 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72  ns .** a pointer
3090: 20 74 6f 20 61 20 73 74 72 69 6e 67 20 63 6f 6e   to a string con
30a0: 73 74 61 6e 74 20 77 68 6f 73 65 20 76 61 6c 75  stant whose valu
30b0: 65 20 69 73 20 74 68 65 20 73 61 6d 65 20 61 73  e is the same as
30c0: 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45   the .** [SQLITE
30d0: 5f 53 4f 55 52 43 45 5f 49 44 5d 20 43 20 70 72  _SOURCE_ID] C pr
30e0: 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  eprocessor macro
30f0: 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
3100: 3a 20 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f  : [sqlite_versio
3110: 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  n()] and [sqlite
3120: 5f 73 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a  _source_id()]..*
3130: 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  /.SQLITE_API con
3140: 73 74 20 63 68 61 72 20 73 71 6c 69 74 65 33 5f  st char sqlite3_
3150: 76 65 72 73 69 6f 6e 5b 5d 20 3d 20 53 51 4c 49  version[] = SQLI
3160: 54 45 5f 56 45 52 53 49 4f 4e 3b 0a 53 51 4c 49  TE_VERSION;.SQLI
3170: 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61  TE_API const cha
3180: 72 20 2a 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  r *sqlite3_libve
3190: 72 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 53 51 4c  rsion(void);.SQL
31a0: 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68  ITE_API const ch
31b0: 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72  ar *sqlite3_sour
31c0: 63 65 69 64 28 76 6f 69 64 29 3b 0a 53 51 4c 49  ceid(void);.SQLI
31d0: 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
31e0: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75  e3_libversion_nu
31f0: 6d 62 65 72 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a  mber(void);../*.
3200: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e  ** CAPI3REF: Run
3210: 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20 43 6f  -Time Library Co
3220: 6d 70 69 6c 61 74 69 6f 6e 20 4f 70 74 69 6f 6e  mpilation Option
3230: 73 20 44 69 61 67 6e 6f 73 74 69 63 73 0a 2a 2a  s Diagnostics.**
3240: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
3250: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75  _compileoption_u
3260: 73 65 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 72  sed() function r
3270: 65 74 75 72 6e 73 20 30 20 6f 72 20 31 20 0a 2a  eturns 0 or 1 .*
3280: 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 77 68 65  * indicating whe
3290: 74 68 65 72 20 74 68 65 20 73 70 65 63 69 66 69  ther the specifi
32a0: 65 64 20 6f 70 74 69 6f 6e 20 77 61 73 20 64 65  ed option was de
32b0: 66 69 6e 65 64 20 61 74 20 0a 2a 2a 20 63 6f 6d  fined at .** com
32c0: 70 69 6c 65 20 74 69 6d 65 2e 20 20 5e 54 68 65  pile time.  ^The
32d0: 20 53 51 4c 49 54 45 5f 20 70 72 65 66 69 78 20   SQLITE_ prefix 
32e0: 6d 61 79 20 62 65 20 6f 6d 69 74 74 65 64 20 66  may be omitted f
32f0: 72 6f 6d 20 74 68 65 20 0a 2a 2a 20 6f 70 74 69  rom the .** opti
3300: 6f 6e 20 6e 61 6d 65 20 70 61 73 73 65 64 20 74  on name passed t
3310: 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c  o sqlite3_compil
3320: 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 2e 20  eoption_used(). 
3330: 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c   .**.** ^The sql
3340: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
3350: 6f 6e 5f 67 65 74 28 29 20 66 75 6e 63 74 69 6f  on_get() functio
3360: 6e 20 61 6c 6c 6f 77 73 20 69 74 65 72 61 74 69  n allows iterati
3370: 6e 67 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6c  ng.** over the l
3380: 69 73 74 20 6f 66 20 6f 70 74 69 6f 6e 73 20 74  ist of options t
3390: 68 61 74 20 77 65 72 65 20 64 65 66 69 6e 65 64  hat were defined
33a0: 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65   at compile time
33b0: 20 62 79 0a 2a 2a 20 72 65 74 75 72 6e 69 6e 67   by.** returning
33c0: 20 74 68 65 20 4e 2d 74 68 20 63 6f 6d 70 69 6c   the N-th compil
33d0: 65 20 74 69 6d 65 20 6f 70 74 69 6f 6e 20 73 74  e time option st
33e0: 72 69 6e 67 2e 20 20 5e 49 66 20 4e 20 69 73 20  ring.  ^If N is 
33f0: 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 0a 2a 2a  out of range,.**
3400: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
3410: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 72 65 74  option_get() ret
3420: 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  urns a NULL poin
3430: 74 65 72 2e 20 20 5e 54 68 65 20 53 51 4c 49 54  ter.  ^The SQLIT
3440: 45 5f 20 0a 2a 2a 20 70 72 65 66 69 78 20 69 73  E_ .** prefix is
3450: 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 61 6e   omitted from an
3460: 79 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e  y strings return
3470: 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74 65  ed by .** sqlite
3480: 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  3_compileoption_
3490: 67 65 74 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 53 75  get()..**.** ^Su
34a0: 70 70 6f 72 74 20 66 6f 72 20 74 68 65 20 64 69  pport for the di
34b0: 61 67 6e 6f 73 74 69 63 20 66 75 6e 63 74 69 6f  agnostic functio
34c0: 6e 73 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69  ns sqlite3_compi
34d0: 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 0a  leoption_used().
34e0: 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  ** and sqlite3_c
34f0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74  ompileoption_get
3500: 28 29 20 6d 61 79 20 62 65 20 6f 6d 69 74 74 65  () may be omitte
3510: 64 20 62 79 20 73 70 65 63 69 66 79 69 6e 67 20  d by specifying 
3520: 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  the .** [SQLITE_
3530: 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45 4f 50 54 49  OMIT_COMPILEOPTI
3540: 4f 4e 5f 44 49 41 47 53 5d 20 6f 70 74 69 6f 6e  ON_DIAGS] option
3550: 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65   at compile time
3560: 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
3570: 3a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  : SQL functions 
3580: 5b 73 71 6c 69 74 65 5f 63 6f 6d 70 69 6c 65 6f  [sqlite_compileo
3590: 70 74 69 6f 6e 5f 75 73 65 64 28 29 5d 20 61 6e  ption_used()] an
35a0: 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 63 6f 6d  d.** [sqlite_com
35b0: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29  pileoption_get()
35c0: 5d 20 61 6e 64 20 74 68 65 20 5b 63 6f 6d 70 69  ] and the [compi
35d0: 6c 65 5f 6f 70 74 69 6f 6e 73 20 70 72 61 67 6d  le_options pragm
35e0: 61 5d 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53  a]..*/.#ifndef S
35f0: 51 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49  QLITE_OMIT_COMPI
3600: 4c 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53 0a 53  LEOPTION_DIAGS.S
3610: 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
3620: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
3630: 69 6f 6e 5f 75 73 65 64 28 63 6f 6e 73 74 20 63  ion_used(const c
3640: 68 61 72 20 2a 7a 4f 70 74 4e 61 6d 65 29 3b 0a  har *zOptName);.
3650: 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
3660: 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
3670: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74  ompileoption_get
3680: 28 69 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66 0a  (int N);.#endif.
3690: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
36a0: 20 54 65 73 74 20 54 6f 20 53 65 65 20 49 66 20   Test To See If 
36b0: 54 68 65 20 4c 69 62 72 61 72 79 20 49 73 20 54  The Library Is T
36c0: 68 72 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20  hreadsafe.**.** 
36d0: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72  ^The sqlite3_thr
36e0: 65 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69  eadsafe() functi
36f0: 6f 6e 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20  on returns zero 
3700: 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a  if and only if.*
3710: 2a 20 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d  * SQLite was com
3720: 70 69 6c 65 64 20 77 69 74 68 20 6d 75 74 65 78  piled with mutex
3730: 69 6e 67 20 63 6f 64 65 20 6f 6d 69 74 74 65 64  ing code omitted
3740: 20 64 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20 5b   due to the.** [
3750: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
3760: 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  E] compile-time 
3770: 6f 70 74 69 6f 6e 20 62 65 69 6e 67 20 73 65 74  option being set
3780: 20 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c   to 0..**.** SQL
3790: 69 74 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69  ite can be compi
37a0: 6c 65 64 20 77 69 74 68 20 6f 72 20 77 69 74 68  led with or with
37b0: 6f 75 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68  out mutexes.  Wh
37c0: 65 6e 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54  en.** the [SQLIT
37d0: 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 43 20  E_THREADSAFE] C 
37e0: 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63  preprocessor mac
37f0: 72 6f 20 69 73 20 31 20 6f 72 20 32 2c 20 6d 75  ro is 1 or 2, mu
3800: 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61  texes.** are ena
3810: 62 6c 65 64 20 61 6e 64 20 53 51 4c 69 74 65 20  bled and SQLite 
3820: 69 73 20 74 68 72 65 61 64 73 61 66 65 2e 20 20  is threadsafe.  
3830: 57 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  When the.** [SQL
3840: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20  ITE_THREADSAFE] 
3850: 6d 61 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20  macro is 0, .** 
3860: 74 68 65 20 6d 75 74 65 78 65 73 20 61 72 65 20  the mutexes are 
3870: 6f 6d 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75  omitted.  Withou
3880: 74 20 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69  t the mutexes, i
3890: 74 20 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a  t is not safe.**
38a0: 20 74 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63   to use SQLite c
38b0: 6f 6e 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d  oncurrently from
38c0: 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74   more than one t
38d0: 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61  hread..**.** Ena
38e0: 62 6c 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e  bling mutexes in
38f0: 63 75 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c  curs a measurabl
3900: 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65  e performance pe
3910: 6e 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20  nalty..** So if 
3920: 73 70 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f  speed is of utmo
3930: 73 74 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69  st importance, i
3940: 74 20 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f  t makes sense to
3950: 20 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20   disable.** the 
3960: 6d 75 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f  mutexes.  But fo
3970: 72 20 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79  r maximum safety
3980: 2c 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64  , mutexes should
3990: 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20   be enabled..** 
39a0: 5e 54 68 65 20 64 65 66 61 75 6c 74 20 62 65 68  ^The default beh
39b0: 61 76 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 74  avior is for mut
39c0: 65 78 65 73 20 74 6f 20 62 65 20 65 6e 61 62 6c  exes to be enabl
39d0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  ed..**.** This i
39e0: 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20  nterface can be 
39f0: 75 73 65 64 20 62 79 20 61 6e 20 61 70 70 6c 69  used by an appli
3a00: 63 61 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20 73  cation to make s
3a10: 75 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  ure that the.** 
3a20: 76 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74  version of SQLit
3a30: 65 20 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e  e that it is lin
3a40: 6b 69 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73  king against was
3a50: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
3a60: 2a 20 74 68 65 20 64 65 73 69 72 65 64 20 73 65  * the desired se
3a70: 74 74 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 51  tting of the [SQ
3a80: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d  LITE_THREADSAFE]
3a90: 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68   macro..**.** Th
3aa0: 69 73 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c  is interface onl
3ab0: 79 20 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 65  y reports on the
3ac0: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75   compile-time mu
3ad0: 74 65 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f  tex setting.** o
3ae0: 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  f the [SQLITE_TH
3af0: 52 45 41 44 53 41 46 45 5d 20 66 6c 61 67 2e 20  READSAFE] flag. 
3b00: 20 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f   If SQLite is co
3b10: 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53  mpiled with.** S
3b20: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
3b30: 3d 31 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d 75  =1 or =2 then mu
3b40: 74 65 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65  texes are enable
3b50: 64 20 62 79 20 64 65 66 61 75 6c 74 20 62 75 74  d by default but
3b60: 0a 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79  .** can be fully
3b70: 20 6f 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69   or partially di
3b80: 73 61 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63  sabled using a c
3b90: 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
3ba0: 63 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74  config()].** wit
3bb0: 68 20 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c  h the verbs [SQL
3bc0: 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
3bd0: 45 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54  ETHREAD], [SQLIT
3be0: 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48  E_CONFIG_MULTITH
3bf0: 52 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51  READ],.** or [SQ
3c00: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49  LITE_CONFIG_SERI
3c10: 41 4c 49 5a 45 44 5d 2e 20 20 5e 28 54 68 65 20  ALIZED].  ^(The 
3c20: 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
3c30: 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 74  the.** sqlite3_t
3c40: 68 72 65 61 64 73 61 66 65 28 29 20 66 75 6e 63  hreadsafe() func
3c50: 74 69 6f 6e 20 73 68 6f 77 73 20 6f 6e 6c 79 20  tion shows only 
3c60: 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  the compile-time
3c70: 20 73 65 74 74 69 6e 67 20 6f 66 0a 2a 2a 20 74   setting of.** t
3c80: 68 72 65 61 64 20 73 61 66 65 74 79 2c 20 6e 6f  hread safety, no
3c90: 74 20 61 6e 79 20 72 75 6e 2d 74 69 6d 65 20 63  t any run-time c
3ca0: 68 61 6e 67 65 73 20 74 6f 20 74 68 61 74 20 73  hanges to that s
3cb0: 65 74 74 69 6e 67 20 6d 61 64 65 20 62 79 0a 2a  etting made by.*
3cc0: 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  * sqlite3_config
3cd0: 28 29 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  (). In other wor
3ce0: 64 73 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76  ds, the return v
3cf0: 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65  alue from sqlite
3d00: 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 0a 2a  3_threadsafe().*
3d10: 2a 20 69 73 20 75 6e 63 68 61 6e 67 65 64 20 62  * is unchanged b
3d20: 79 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  y calls to sqlit
3d30: 65 33 5f 63 6f 6e 66 69 67 28 29 2e 29 5e 0a 2a  e3_config().)^.*
3d40: 2a 0a 2a 2a 20 53 65 65 20 74 68 65 20 5b 74 68  *.** See the [th
3d50: 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 64 6f  reading mode] do
3d60: 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20  cumentation for 
3d70: 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  additional infor
3d80: 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54  mation..*/.SQLIT
3d90: 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
3da0: 33 5f 74 68 72 65 61 64 73 61 66 65 28 76 6f 69  3_threadsafe(voi
3db0: 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  d);../*.** CAPI3
3dc0: 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f  REF: Database Co
3dd0: 6e 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 0a  nnection Handle.
3de0: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64 61  ** KEYWORDS: {da
3df0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
3e00: 6e 7d 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e  n} {database con
3e10: 6e 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20  nections}.**.** 
3e20: 45 61 63 68 20 6f 70 65 6e 20 53 51 4c 69 74 65  Each open SQLite
3e30: 20 64 61 74 61 62 61 73 65 20 69 73 20 72 65 70   database is rep
3e40: 72 65 73 65 6e 74 65 64 20 62 79 20 61 20 70 6f  resented by a po
3e50: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74  inter to an inst
3e60: 61 6e 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f  ance of.** the o
3e70: 70 61 71 75 65 20 73 74 72 75 63 74 75 72 65 20  paque structure 
3e80: 6e 61 6d 65 64 20 22 73 71 6c 69 74 65 33 22 2e  named "sqlite3".
3e90: 20 20 49 74 20 69 73 20 75 73 65 66 75 6c 20 74    It is useful t
3ea0: 6f 20 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73 71  o think of an sq
3eb0: 6c 69 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65 72  lite3.** pointer
3ec0: 20 61 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20 20   as an object.  
3ed0: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  The [sqlite3_ope
3ee0: 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f  n()], [sqlite3_o
3ef0: 70 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a  pen16()], and.**
3f00: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
3f10: 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20  2()] interfaces 
3f20: 61 72 65 20 69 74 73 20 63 6f 6e 73 74 72 75 63  are its construc
3f30: 74 6f 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69 74  tors, and [sqlit
3f40: 65 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 61  e3_close()].** a
3f50: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73  nd [sqlite3_clos
3f60: 65 5f 76 32 28 29 5d 20 61 72 65 20 69 74 73 20  e_v2()] are its 
3f70: 64 65 73 74 72 75 63 74 6f 72 73 2e 20 20 54 68  destructors.  Th
3f80: 65 72 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68  ere are many oth
3f90: 65 72 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  er.** interfaces
3fa0: 20 28 73 75 63 68 20 61 73 0a 2a 2a 20 5b 73 71   (such as.** [sq
3fb0: 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
3fc0: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72  ()], [sqlite3_cr
3fd0: 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
3fe0: 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  , and.** [sqlite
3ff0: 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29  3_busy_timeout()
4000: 5d 20 74 6f 20 6e 61 6d 65 20 62 75 74 20 74 68  ] to name but th
4010: 72 65 65 29 20 74 68 61 74 20 61 72 65 20 6d 65  ree) that are me
4020: 74 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73  thods on an.** s
4030: 71 6c 69 74 65 33 20 6f 62 6a 65 63 74 2e 0a 2a  qlite3 object..*
4040: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
4050: 20 73 71 6c 69 74 65 33 20 73 71 6c 69 74 65 33   sqlite3 sqlite3
4060: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
4070: 46 3a 20 36 34 2d 42 69 74 20 49 6e 74 65 67 65  F: 64-Bit Intege
4080: 72 20 54 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f  r Types.** KEYWO
4090: 52 44 53 3a 20 73 71 6c 69 74 65 5f 69 6e 74 36  RDS: sqlite_int6
40a0: 34 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 0a  4 sqlite_uint64.
40b0: 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68  **.** Because th
40c0: 65 72 65 20 69 73 20 6e 6f 20 63 72 6f 73 73 2d  ere is no cross-
40d0: 70 6c 61 74 66 6f 72 6d 20 77 61 79 20 74 6f 20  platform way to 
40e0: 73 70 65 63 69 66 79 20 36 34 2d 62 69 74 20 69  specify 64-bit i
40f0: 6e 74 65 67 65 72 20 74 79 70 65 73 0a 2a 2a 20  nteger types.** 
4100: 53 51 4c 69 74 65 20 69 6e 63 6c 75 64 65 73 20  SQLite includes 
4110: 74 79 70 65 64 65 66 73 20 66 6f 72 20 36 34 2d  typedefs for 64-
4120: 62 69 74 20 73 69 67 6e 65 64 20 61 6e 64 20 75  bit signed and u
4130: 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 73  nsigned integers
4140: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
4150: 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71  te3_int64 and sq
4160: 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 61 72 65  lite3_uint64 are
4170: 20 74 68 65 20 70 72 65 66 65 72 72 65 64 20 74   the preferred t
4180: 79 70 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 2e  ype definitions.
4190: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 5f 69  .** The sqlite_i
41a0: 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f  nt64 and sqlite_
41b0: 75 69 6e 74 36 34 20 74 79 70 65 73 20 61 72 65  uint64 types are
41c0: 20 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20 62   supported for b
41d0: 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70  ackwards.** comp
41e0: 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a  atibility only..
41f0: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
4200: 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c  e3_int64 and sql
4210: 69 74 65 5f 69 6e 74 36 34 20 74 79 70 65 73 20  ite_int64 types 
4220: 63 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65  can store intege
4230: 72 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77  r values.** betw
4240: 65 65 6e 20 2d 39 32 32 33 33 37 32 30 33 36 38  een -92233720368
4250: 35 34 37 37 35 38 30 38 20 61 6e 64 20 2b 39 32  54775808 and +92
4260: 32 33 33 37 32 30 33 36 38 35 34 37 37 35 38 30  2337203685477580
4270: 37 20 69 6e 63 6c 75 73 69 76 65 2e 20 20 5e 54  7 inclusive.  ^T
4280: 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 69  he.** sqlite3_ui
4290: 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f  nt64 and sqlite_
42a0: 75 69 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e  uint64 types can
42b0: 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76   store integer v
42c0: 61 6c 75 65 73 20 0a 2a 2a 20 62 65 74 77 65 65  alues .** betwee
42d0: 6e 20 30 20 61 6e 64 20 2b 31 38 34 34 36 37 34  n 0 and +1844674
42e0: 34 30 37 33 37 30 39 35 35 31 36 31 35 20 69 6e  4073709551615 in
42f0: 63 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23 69 66 64  clusive..*/.#ifd
4300: 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f  ef SQLITE_INT64_
4310: 54 59 50 45 0a 20 20 74 79 70 65 64 65 66 20 53  TYPE.  typedef S
4320: 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45  QLITE_INT64_TYPE
4330: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20   sqlite_int64;. 
4340: 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65   typedef unsigne
4350: 64 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54  d SQLITE_INT64_T
4360: 59 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 36  YPE sqlite_uint6
4370: 34 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64  4;.#elif defined
4380: 28 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65  (_MSC_VER) || de
4390: 66 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43  fined(__BORLANDC
43a0: 5f 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f  __).  typedef __
43b0: 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74  int64 sqlite_int
43c0: 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e  64;.  typedef un
43d0: 73 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73  signed __int64 s
43e0: 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65  qlite_uint64;.#e
43f0: 6c 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f  lse.  typedef lo
4400: 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69  ng long int sqli
4410: 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65  te_int64;.  type
4420: 64 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e  def unsigned lon
4430: 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74  g long int sqlit
4440: 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66  e_uint64;.#endif
4450: 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f  .typedef sqlite_
4460: 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e  int64 sqlite3_in
4470: 74 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c  t64;.typedef sql
4480: 69 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74  ite_uint64 sqlit
4490: 65 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a  e3_uint64;../*.*
44a0: 2a 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66  * If compiling f
44b0: 6f 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74  or a processor t
44c0: 68 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69  hat lacks floati
44d0: 6e 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74  ng point support
44e0: 2c 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20  ,.** substitute 
44f0: 69 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61  integer for floa
4500: 74 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23  ting-point..*/.#
4510: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49  ifdef SQLITE_OMI
4520: 54 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54  T_FLOATING_POINT
4530: 0a 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65  .# define double
4540: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23   sqlite3_int64.#
4550: 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  endif../*.** CAP
4560: 49 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41  I3REF: Closing A
4570: 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63   Database Connec
4580: 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  tion.**.** ^The 
4590: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20  sqlite3_close() 
45a0: 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  and sqlite3_clos
45b0: 65 5f 76 32 28 29 20 72 6f 75 74 69 6e 65 73 20  e_v2() routines 
45c0: 61 72 65 20 64 65 73 74 72 75 63 74 6f 72 73 0a  are destructors.
45d0: 2a 2a 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69  ** for the [sqli
45e0: 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20  te3] object..** 
45f0: 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65  ^Calls to sqlite
4600: 33 5f 63 6c 6f 73 65 28 29 20 61 6e 64 20 73 71  3_close() and sq
4610: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29  lite3_close_v2()
4620: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
4630: 4f 4b 5d 20 69 66 0a 2a 2a 20 74 68 65 20 5b 73  OK] if.** the [s
4640: 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 69  qlite3] object i
4650: 73 20 73 75 63 63 65 73 73 66 75 6c 6c 79 20 64  s successfully d
4660: 65 73 74 72 6f 79 65 64 20 61 6e 64 20 61 6c 6c  estroyed and all
4670: 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 72   associated.** r
4680: 65 73 6f 75 72 63 65 73 20 61 72 65 20 64 65 61  esources are dea
4690: 6c 6c 6f 63 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  llocated..**.** 
46a0: 5e 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65  ^If the database
46b0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 61   connection is a
46c0: 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 75  ssociated with u
46d0: 6e 66 69 6e 61 6c 69 7a 65 64 20 70 72 65 70 61  nfinalized prepa
46e0: 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  red.** statement
46f0: 73 20 6f 72 20 75 6e 66 69 6e 69 73 68 65 64 20  s or unfinished 
4700: 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 20 6f  sqlite3_backup o
4710: 62 6a 65 63 74 73 20 74 68 65 6e 20 73 71 6c 69  bjects then sqli
4720: 74 65 33 5f 63 6c 6f 73 65 28 29 0a 2a 2a 20 77  te3_close().** w
4730: 69 6c 6c 20 6c 65 61 76 65 20 74 68 65 20 64 61  ill leave the da
4740: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
4750: 6e 20 6f 70 65 6e 20 61 6e 64 20 72 65 74 75 72  n open and retur
4760: 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e  n [SQLITE_BUSY].
4770: 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  .** ^If sqlite3_
4780: 63 6c 6f 73 65 5f 76 32 28 29 20 69 73 20 63 61  close_v2() is ca
4790: 6c 6c 65 64 20 77 69 74 68 20 75 6e 66 69 6e 61  lled with unfina
47a0: 6c 69 7a 65 64 20 70 72 65 70 61 72 65 64 20 73  lized prepared s
47b0: 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 61 6e 64  tatements.** and
47c0: 2f 6f 72 20 75 6e 66 69 6e 69 73 68 65 64 20 73  /or unfinished s
47d0: 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 73 2c 20  qlite3_backups, 
47e0: 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  then the databas
47f0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 65 63  e connection bec
4800: 6f 6d 65 73 0a 2a 2a 20 61 6e 20 75 6e 75 73 61  omes.** an unusa
4810: 62 6c 65 20 22 7a 6f 6d 62 69 65 22 20 77 68 69  ble "zombie" whi
4820: 63 68 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69  ch will automati
4830: 63 61 6c 6c 79 20 62 65 20 64 65 61 6c 6c 6f 63  cally be dealloc
4840: 61 74 65 64 20 77 68 65 6e 20 74 68 65 0a 2a 2a  ated when the.**
4850: 20 6c 61 73 74 20 70 72 65 70 61 72 65 64 20 73   last prepared s
4860: 74 61 74 65 6d 65 6e 74 20 69 73 20 66 69 6e 61  tatement is fina
4870: 6c 69 7a 65 64 20 6f 72 20 74 68 65 20 6c 61 73  lized or the las
4880: 74 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70  t sqlite3_backup
4890: 20 69 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 2e   is.** finished.
48a0: 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6c    The sqlite3_cl
48b0: 6f 73 65 5f 76 32 28 29 20 69 6e 74 65 72 66 61  ose_v2() interfa
48c0: 63 65 20 69 73 20 69 6e 74 65 6e 64 65 64 20 66  ce is intended f
48d0: 6f 72 20 75 73 65 20 77 69 74 68 0a 2a 2a 20 68  or use with.** h
48e0: 6f 73 74 20 6c 61 6e 67 75 61 67 65 73 20 74 68  ost languages th
48f0: 61 74 20 61 72 65 20 67 61 72 62 61 67 65 20 63  at are garbage c
4900: 6f 6c 6c 65 63 74 65 64 2c 20 61 6e 64 20 77 68  ollected, and wh
4910: 65 72 65 20 74 68 65 20 6f 72 64 65 72 20 69 6e  ere the order in
4920: 20 77 68 69 63 68 0a 2a 2a 20 64 65 73 74 72 75   which.** destru
4930: 63 74 6f 72 73 20 61 72 65 20 63 61 6c 6c 65 64  ctors are called
4940: 20 69 73 20 61 72 62 69 74 72 61 72 79 2e 0a 2a   is arbitrary..*
4950: 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e  *.** Application
4960: 73 20 73 68 6f 75 6c 64 20 5b 73 71 6c 69 74 65  s should [sqlite
4970: 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e  3_finalize | fin
4980: 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72 65 70  alize] all [prep
4990: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d  ared statements]
49a0: 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c  ,.** [sqlite3_bl
49b0: 6f 62 5f 63 6c 6f 73 65 20 7c 20 63 6c 6f 73 65  ob_close | close
49c0: 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20 68 61 6e 64  ] all [BLOB hand
49d0: 6c 65 73 5d 2c 20 61 6e 64 20 0a 2a 2a 20 5b 73  les], and .** [s
49e0: 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 66 69  qlite3_backup_fi
49f0: 6e 69 73 68 20 7c 20 66 69 6e 69 73 68 5d 20 61  nish | finish] a
4a00: 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b  ll [sqlite3_back
4a10: 75 70 5d 20 6f 62 6a 65 63 74 73 20 61 73 73 6f  up] objects asso
4a20: 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 20 74  ciated.** with t
4a30: 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a  he [sqlite3] obj
4a40: 65 63 74 20 70 72 69 6f 72 20 74 6f 20 61 74 74  ect prior to att
4a50: 65 6d 70 74 69 6e 67 20 74 6f 20 63 6c 6f 73 65  empting to close
4a60: 20 74 68 65 20 6f 62 6a 65 63 74 2e 20 20 5e 49   the object.  ^I
4a70: 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6c 6f  f.** sqlite3_clo
4a80: 73 65 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65  se_v2() is calle
4a90: 64 20 6f 6e 20 61 20 5b 64 61 74 61 62 61 73 65  d on a [database
4aa0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61   connection] tha
4ab0: 74 20 73 74 69 6c 6c 20 68 61 73 0a 2a 2a 20 6f  t still has.** o
4ac0: 75 74 73 74 61 6e 64 69 6e 67 20 5b 70 72 65 70  utstanding [prep
4ad0: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d  ared statements]
4ae0: 2c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d  , [BLOB handles]
4af0: 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 5b 73 71 6c  , and/or.** [sql
4b00: 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a  ite3_backup] obj
4b10: 65 63 74 73 20 74 68 65 6e 20 69 74 20 72 65 74  ects then it ret
4b20: 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
4b30: 20 61 6e 64 20 74 68 65 20 64 65 61 6c 6c 6f 63   and the dealloc
4b40: 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 72 65 73 6f  ation.** of reso
4b50: 75 72 63 65 73 20 69 73 20 64 65 66 65 72 72 65  urces is deferre
4b60: 64 20 75 6e 74 69 6c 20 61 6c 6c 20 5b 70 72 65  d until all [pre
4b70: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
4b80: 5d 2c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73  ], [BLOB handles
4b90: 5d 2c 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74  ],.** and [sqlit
4ba0: 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63  e3_backup] objec
4bb0: 74 73 20 61 72 65 20 61 6c 73 6f 20 64 65 73 74  ts are also dest
4bc0: 72 6f 79 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  royed..**.** ^If
4bd0: 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62   an [sqlite3] ob
4be0: 6a 65 63 74 20 69 73 20 64 65 73 74 72 6f 79 65  ject is destroye
4bf0: 64 20 77 68 69 6c 65 20 61 20 74 72 61 6e 73 61  d while a transa
4c00: 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 2c 0a 2a  ction is open,.*
4c10: 2a 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f  * the transactio
4c20: 6e 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c  n is automatical
4c30: 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a  ly rolled back..
4c40: 2a 2a 0a 2a 2a 20 54 68 65 20 43 20 70 61 72 61  **.** The C para
4c50: 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
4c60: 33 5f 63 6c 6f 73 65 28 43 29 5d 20 61 6e 64 20  3_close(C)] and 
4c70: 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76  [sqlite3_close_v
4c80: 32 28 43 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65  2(C)].** must be
4c90: 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 0a 2a   either a NULL.*
4ca0: 2a 20 70 6f 69 6e 74 65 72 20 6f 72 20 61 6e 20  * pointer or an 
4cb0: 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74  [sqlite3] object
4cc0: 20 70 6f 69 6e 74 65 72 20 6f 62 74 61 69 6e 65   pointer obtaine
4cd0: 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74  d.** from [sqlit
4ce0: 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c  e3_open()], [sql
4cf0: 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20  ite3_open16()], 
4d00: 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f  or.** [sqlite3_o
4d10: 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20 6e  pen_v2()], and n
4d20: 6f 74 20 70 72 65 76 69 6f 75 73 6c 79 20 63 6c  ot previously cl
4d30: 6f 73 65 64 2e 0a 2a 2a 20 5e 43 61 6c 6c 69 6e  osed..** ^Callin
4d40: 67 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28  g sqlite3_close(
4d50: 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6c 6f  ) or sqlite3_clo
4d60: 73 65 5f 76 32 28 29 20 77 69 74 68 20 61 20 4e  se_v2() with a N
4d70: 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 61  ULL pointer.** a
4d80: 72 67 75 6d 65 6e 74 20 69 73 20 61 20 68 61 72  rgument is a har
4d90: 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a  mless no-op..*/.
4da0: 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
4db0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 73 71 6c  qlite3_close(sql
4dc0: 69 74 65 33 2a 29 3b 0a 53 51 4c 49 54 45 5f 41  ite3*);.SQLITE_A
4dd0: 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  PI int sqlite3_c
4de0: 6c 6f 73 65 5f 76 32 28 73 71 6c 69 74 65 33 2a  lose_v2(sqlite3*
4df0: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 79  );../*.** The ty
4e00: 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 61 63  pe for a callbac
4e10: 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54  k function..** T
4e20: 68 69 73 20 69 73 20 6c 65 67 61 63 79 20 61 6e  his is legacy an
4e30: 64 20 64 65 70 72 65 63 61 74 65 64 2e 20 20 49  d deprecated.  I
4e40: 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20 66 6f  t is included fo
4e50: 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20  r historical.** 
4e60: 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 61 6e  compatibility an
4e70: 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65 6e  d is not documen
4e80: 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ted..*/.typedef 
4e90: 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f 63 61  int (*sqlite3_ca
4ea0: 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e  llback)(void*,in
4eb0: 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a 2a  t,char**, char**
4ec0: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
4ed0: 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75 65  EF: One-Step Que
4ee0: 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49 6e 74  ry Execution Int
4ef0: 65 72 66 61 63 65 0a 2a 2a 0a 2a 2a 20 54 68 65  erface.**.** The
4f00: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
4f10: 69 6e 74 65 72 66 61 63 65 20 69 73 20 61 20 63  interface is a c
4f20: 6f 6e 76 65 6e 69 65 6e 63 65 20 77 72 61 70 70  onvenience wrapp
4f30: 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71  er around.** [sq
4f40: 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
4f50: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74  ()], [sqlite3_st
4f60: 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69  ep()], and [sqli
4f70: 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2c  te3_finalize()],
4f80: 0a 2a 2a 20 74 68 61 74 20 61 6c 6c 6f 77 73 20  .** that allows 
4f90: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74  an application t
4fa0: 6f 20 72 75 6e 20 6d 75 6c 74 69 70 6c 65 20 73  o run multiple s
4fb0: 74 61 74 65 6d 65 6e 74 73 20 6f 66 20 53 51 4c  tatements of SQL
4fc0: 0a 2a 2a 20 77 69 74 68 6f 75 74 20 68 61 76 69  .** without havi
4fd0: 6e 67 20 74 6f 20 75 73 65 20 61 20 6c 6f 74 20  ng to use a lot 
4fe0: 6f 66 20 43 20 63 6f 64 65 2e 20 0a 2a 2a 0a 2a  of C code. .**.*
4ff0: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
5000: 78 65 63 28 29 20 69 6e 74 65 72 66 61 63 65 20  xec() interface 
5010: 72 75 6e 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72  runs zero or mor
5020: 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2c  e UTF-8 encoded,
5030: 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65  .** semicolon-se
5040: 70 61 72 61 74 65 20 53 51 4c 20 73 74 61 74 65  parate SQL state
5050: 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74  ments passed int
5060: 6f 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65  o its 2nd argume
5070: 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68 65 20 63 6f  nt,.** in the co
5080: 6e 74 65 78 74 20 6f 66 20 74 68 65 20 5b 64 61  ntext of the [da
5090: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
50a0: 6e 5d 20 70 61 73 73 65 64 20 69 6e 20 61 73 20  n] passed in as 
50b0: 69 74 73 20 31 73 74 0a 2a 2a 20 61 72 67 75 6d  its 1st.** argum
50c0: 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 20 63 61  ent.  ^If the ca
50d0: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
50e0: 6f 66 20 74 68 65 20 33 72 64 20 61 72 67 75 6d  of the 3rd argum
50f0: 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  ent to.** sqlite
5100: 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20  3_exec() is not 
5110: 4e 55 4c 4c 2c 20 74 68 65 6e 20 69 74 20 69 73  NULL, then it is
5120: 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 65 61 63   invoked for eac
5130: 68 20 72 65 73 75 6c 74 20 72 6f 77 0a 2a 2a 20  h result row.** 
5140: 63 6f 6d 69 6e 67 20 6f 75 74 20 6f 66 20 74 68  coming out of th
5150: 65 20 65 76 61 6c 75 61 74 65 64 20 53 51 4c 20  e evaluated SQL 
5160: 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 5e 54 68  statements.  ^Th
5170: 65 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74  e 4th argument t
5180: 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65  o.** sqlite3_exe
5190: 63 28 29 20 69 73 20 72 65 6c 61 79 65 64 20 74  c() is relayed t
51a0: 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20 31 73  hrough to the 1s
51b0: 74 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 65 61  t argument of ea
51c0: 63 68 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69  ch.** callback i
51d0: 6e 76 6f 63 61 74 69 6f 6e 2e 20 20 5e 49 66 20  nvocation.  ^If 
51e0: 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 70 6f 69  the callback poi
51f0: 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  nter to sqlite3_
5200: 65 78 65 63 28 29 0a 2a 2a 20 69 73 20 4e 55 4c  exec().** is NUL
5210: 4c 2c 20 74 68 65 6e 20 6e 6f 20 63 61 6c 6c 62  L, then no callb
5220: 61 63 6b 20 69 73 20 65 76 65 72 20 69 6e 76 6f  ack is ever invo
5230: 6b 65 64 20 61 6e 64 20 72 65 73 75 6c 74 20 72  ked and result r
5240: 6f 77 73 20 61 72 65 0a 2a 2a 20 69 67 6e 6f 72  ows are.** ignor
5250: 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e  ed..**.** ^If an
5260: 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68   error occurs wh
5270: 69 6c 65 20 65 76 61 6c 75 61 74 69 6e 67 20 74  ile evaluating t
5280: 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
5290: 73 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a  s passed into.**
52a0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 2c   sqlite3_exec(),
52b0: 20 74 68 65 6e 20 65 78 65 63 75 74 69 6f 6e 20   then execution 
52c0: 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 73  of the current s
52d0: 74 61 74 65 6d 65 6e 74 20 73 74 6f 70 73 20 61  tatement stops a
52e0: 6e 64 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74  nd.** subsequent
52f0: 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20   statements are 
5300: 73 6b 69 70 70 65 64 2e 20 20 5e 49 66 20 74 68  skipped.  ^If th
5310: 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 5th parameter 
5320: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
5330: 29 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  ).** is not NULL
5340: 20 74 68 65 6e 20 61 6e 79 20 65 72 72 6f 72 20   then any error 
5350: 6d 65 73 73 61 67 65 20 69 73 20 77 72 69 74 74  message is writt
5360: 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f  en into memory o
5370: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
5380: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
5390: 29 5d 20 61 6e 64 20 70 61 73 73 65 64 20 62 61  )] and passed ba
53a0: 63 6b 20 74 68 72 6f 75 67 68 20 74 68 65 20 35  ck through the 5
53b0: 74 68 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  th parameter..**
53c0: 20 54 6f 20 61 76 6f 69 64 20 6d 65 6d 6f 72 79   To avoid memory
53d0: 20 6c 65 61 6b 73 2c 20 74 68 65 20 61 70 70 6c   leaks, the appl
53e0: 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 69  ication should i
53f0: 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66  nvoke [sqlite3_f
5400: 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72  ree()].** on err
5410: 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e  or message strin
5420: 67 73 20 72 65 74 75 72 6e 65 64 20 74 68 72 6f  gs returned thro
5430: 75 67 68 20 74 68 65 20 35 74 68 20 70 61 72 61  ugh the 5th para
5440: 6d 65 74 65 72 20 6f 66 0a 2a 2a 20 6f 66 20 73  meter of.** of s
5450: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 61 66  qlite3_exec() af
5460: 74 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65  ter the error me
5470: 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20  ssage string is 
5480: 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64  no longer needed
5490: 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35 74 68  ..** ^If the 5th
54a0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
54b0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
54c0: 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20  not NULL and no 
54d0: 65 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c  errors.** occur,
54e0: 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 65 78   then sqlite3_ex
54f0: 65 63 28 29 20 73 65 74 73 20 74 68 65 20 70 6f  ec() sets the po
5500: 69 6e 74 65 72 20 69 6e 20 69 74 73 20 35 74 68  inter in its 5th
5510: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
5520: 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72 65 74   NULL before ret
5530: 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49  urning..**.** ^I
5540: 66 20 61 6e 20 73 71 6c 69 74 65 33 5f 65 78 65  f an sqlite3_exe
5550: 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  c() callback ret
5560: 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
5570: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  he sqlite3_exec(
5580: 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74  ).** routine ret
5590: 75 72 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f 52  urns SQLITE_ABOR
55a0: 54 20 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69  T without invoki
55b0: 6e 67 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  ng the callback 
55c0: 61 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74  again and.** wit
55d0: 68 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79  hout running any
55e0: 20 73 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20   subsequent SQL 
55f0: 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
5600: 2a 20 5e 54 68 65 20 32 6e 64 20 61 72 67 75 6d  * ^The 2nd argum
5610: 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ent to the sqlit
5620: 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61  e3_exec() callba
5630: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74  ck function is t
5640: 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
5650: 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72  columns in the r
5660: 65 73 75 6c 74 2e 20 20 5e 54 68 65 20 33 72 64  esult.  ^The 3rd
5670: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
5680: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
5690: 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  ** callback is a
56a0: 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
56b0: 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 6f  ers to strings o
56c0: 62 74 61 69 6e 65 64 20 61 73 20 69 66 20 66 72  btained as if fr
56d0: 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  om.** [sqlite3_c
56e0: 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f  olumn_text()], o
56f0: 6e 65 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75  ne for each colu
5700: 6d 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d  mn.  ^If an elem
5710: 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75  ent of a.** resu
5720: 6c 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74  lt row is NULL t
5730: 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f  hen the correspo
5740: 6e 64 69 6e 67 20 73 74 72 69 6e 67 20 70 6f 69  nding string poi
5750: 6e 74 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20  nter for the.** 
5760: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63  sqlite3_exec() c
5770: 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e 55 4c  allback is a NUL
5780: 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65  L pointer.  ^The
5790: 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f   4th argument to
57a0: 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   the.** sqlite3_
57b0: 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20  exec() callback 
57c0: 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
57d0: 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e  ointers to strin
57e0: 67 73 20 77 68 65 72 65 20 65 61 63 68 0a 2a 2a  gs where each.**
57f0: 20 65 6e 74 72 79 20 72 65 70 72 65 73 65 6e 74   entry represent
5800: 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f  s the name of co
5810: 72 72 65 73 70 6f 6e 64 69 6e 67 20 72 65 73 75  rresponding resu
5820: 6c 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74  lt column as obt
5830: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73  ained.** from [s
5840: 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
5850: 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  me()]..**.** ^If
5860: 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
5870: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
5880: 65 63 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70  ec() is a NULL p
5890: 6f 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74 65  ointer, a pointe
58a0: 72 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79  r.** to an empty
58b0: 20 73 74 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f   string, or a po
58c0: 69 6e 74 65 72 20 74 68 61 74 20 63 6f 6e 74 61  inter that conta
58d0: 69 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65 73 70  ins only whitesp
58e0: 61 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53  ace and/or .** S
58f0: 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65  QL comments, the
5900: 6e 20 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d 65  n no SQL stateme
5910: 6e 74 73 20 61 72 65 20 65 76 61 6c 75 61 74 65  nts are evaluate
5920: 64 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 61  d and the databa
5930: 73 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61  se.** is not cha
5940: 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74  nged..**.** Rest
5950: 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20  rictions:.**.** 
5960: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  <ul>.** <li> The
5970: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
5980: 74 20 69 6e 73 75 72 65 20 74 68 61 74 20 74 68  t insure that th
5990: 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20  e 1st parameter 
59a0: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
59b0: 29 0a 2a 2a 20 20 20 20 20 20 69 73 20 61 20 76  ).**      is a v
59c0: 61 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64  alid and open [d
59d0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
59e0: 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  on]..** <li> The
59f0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
5a00: 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20  t not close the 
5a10: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
5a20: 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20  tion] specified 
5a30: 62 79 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 31  by.**      the 1
5a40: 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
5a50: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77  sqlite3_exec() w
5a60: 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65  hile sqlite3_exe
5a70: 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  c() is running..
5a80: 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c  ** <li> The appl
5a90: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ication must not
5aa0: 20 6d 6f 64 69 66 79 20 74 68 65 20 53 51 4c 20   modify the SQL 
5ab0: 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 70  statement text p
5ac0: 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 20 20  assed into.**   
5ad0: 20 20 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d     the 2nd param
5ae0: 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f  eter of sqlite3_
5af0: 65 78 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c  exec() while sql
5b00: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 72  ite3_exec() is r
5b10: 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e  unning..** </ul>
5b20: 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
5b30: 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  nt sqlite3_exec(
5b40: 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 20 20  .  sqlite3*,    
5b50: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
5b60: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
5b70: 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73   An open databas
5b80: 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
5b90: 72 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 20 20  r *sql,         
5ba0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
5bb0: 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65    /* SQL to be e
5bc0: 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69 6e  valuated */.  in
5bd0: 74 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f  t (*callback)(vo
5be0: 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63  id*,int,char**,c
5bf0: 68 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c  har**),  /* Call
5c00: 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f  back function */
5c10: 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20 20  .  void *,      
5c20: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
5c30: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
5c40: 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f   1st argument to
5c50: 20 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63   callback */.  c
5c60: 68 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 20  har **errmsg    
5c70: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
5c80: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72            /* Err
5c90: 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68  or msg written h
5ca0: 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  ere */.);../*.**
5cb0: 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c   CAPI3REF: Resul
5cc0: 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f  t Codes.** KEYWO
5cd0: 52 44 53 3a 20 7b 72 65 73 75 6c 74 20 63 6f 64  RDS: {result cod
5ce0: 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 7d 0a 2a  e definitions}.*
5cf0: 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51 4c 69 74 65  *.** Many SQLite
5d00: 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72   functions retur
5d10: 6e 20 61 6e 20 69 6e 74 65 67 65 72 20 72 65 73  n an integer res
5d20: 75 6c 74 20 63 6f 64 65 20 66 72 6f 6d 20 74 68  ult code from th
5d30: 65 20 73 65 74 20 73 68 6f 77 6e 0a 2a 2a 20 68  e set shown.** h
5d40: 65 72 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ere in order to 
5d50: 69 6e 64 69 63 61 74 65 20 73 75 63 63 65 73 73  indicate success
5d60: 20 6f 72 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a   or failure..**.
5d70: 2a 2a 20 4e 65 77 20 65 72 72 6f 72 20 63 6f 64  ** New error cod
5d80: 65 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  es may be added 
5d90: 69 6e 20 66 75 74 75 72 65 20 76 65 72 73 69 6f  in future versio
5da0: 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  ns of SQLite..**
5db0: 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 65  .** See also: [e
5dc0: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
5dd0: 6f 64 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 5d  ode definitions]
5de0: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
5df0: 54 45 5f 4f 4b 20 20 20 20 20 20 20 20 20 20 20  TE_OK           
5e00: 30 20 20 20 2f 2a 20 53 75 63 63 65 73 73 66 75  0   /* Successfu
5e10: 6c 20 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62  l result */./* b
5e20: 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f  eginning-of-erro
5e30: 72 2d 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66 69  r-codes */.#defi
5e40: 6e 65 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20  ne SQLITE_ERROR 
5e50: 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 53 51         1   /* SQ
5e60: 4c 20 65 72 72 6f 72 20 6f 72 20 6d 69 73 73 69  L error or missi
5e70: 6e 67 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23  ng database */.#
5e80: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
5e90: 54 45 52 4e 41 4c 20 20 20 20 20 32 20 20 20 2f  TERNAL     2   /
5ea0: 2a 20 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69 63  * Internal logic
5eb0: 20 65 72 72 6f 72 20 69 6e 20 53 51 4c 69 74 65   error in SQLite
5ec0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5ed0: 54 45 5f 50 45 52 4d 20 20 20 20 20 20 20 20 20  TE_PERM         
5ee0: 33 20 20 20 2f 2a 20 41 63 63 65 73 73 20 70 65  3   /* Access pe
5ef0: 72 6d 69 73 73 69 6f 6e 20 64 65 6e 69 65 64 20  rmission denied 
5f00: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5f10: 45 5f 41 42 4f 52 54 20 20 20 20 20 20 20 20 34  E_ABORT        4
5f20: 20 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 72     /* Callback r
5f30: 6f 75 74 69 6e 65 20 72 65 71 75 65 73 74 65 64  outine requested
5f40: 20 61 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64 65   an abort */.#de
5f50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59  fine SQLITE_BUSY
5f60: 20 20 20 20 20 20 20 20 20 35 20 20 20 2f 2a 20           5   /* 
5f70: 54 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  The database fil
5f80: 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23  e is locked */.#
5f90: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
5fa0: 43 4b 45 44 20 20 20 20 20 20 20 36 20 20 20 2f  CKED       6   /
5fb0: 2a 20 41 20 74 61 62 6c 65 20 69 6e 20 74 68 65  * A table in the
5fc0: 20 64 61 74 61 62 61 73 65 20 69 73 20 6c 6f 63   database is loc
5fd0: 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ked */.#define S
5fe0: 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20 20  QLITE_NOMEM     
5ff0: 20 20 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c 6c     7   /* A mall
6000: 6f 63 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a 23  oc() failed */.#
6010: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
6020: 41 44 4f 4e 4c 59 20 20 20 20 20 38 20 20 20 2f  ADONLY     8   /
6030: 2a 20 41 74 74 65 6d 70 74 20 74 6f 20 77 72 69  * Attempt to wri
6040: 74 65 20 61 20 72 65 61 64 6f 6e 6c 79 20 64 61  te a readonly da
6050: 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e  tabase */.#defin
6060: 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55  e SQLITE_INTERRU
6070: 50 54 20 20 20 20 39 20 20 20 2f 2a 20 4f 70 65  PT    9   /* Ope
6080: 72 61 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74 65  ration terminate
6090: 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 74  d by sqlite3_int
60a0: 65 72 72 75 70 74 28 29 2a 2f 0a 23 64 65 66 69  errupt()*/.#defi
60b0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 20  ne SQLITE_IOERR 
60c0: 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 53 6f        10   /* So
60d0: 6d 65 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b 20  me kind of disk 
60e0: 49 2f 4f 20 65 72 72 6f 72 20 6f 63 63 75 72 72  I/O error occurr
60f0: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
6100: 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 20 20 20  LITE_CORRUPT    
6110: 20 31 31 20 20 20 2f 2a 20 54 68 65 20 64 61 74   11   /* The dat
6120: 61 62 61 73 65 20 64 69 73 6b 20 69 6d 61 67 65  abase disk image
6130: 20 69 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f   is malformed */
6140: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6150: 4e 4f 54 46 4f 55 4e 44 20 20 20 20 31 32 20 20  NOTFOUND    12  
6160: 20 2f 2a 20 55 6e 6b 6e 6f 77 6e 20 6f 70 63 6f   /* Unknown opco
6170: 64 65 20 69 6e 20 73 71 6c 69 74 65 33 5f 66 69  de in sqlite3_fi
6180: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 20 2a 2f 0a  le_control() */.
6190: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
61a0: 55 4c 4c 20 20 20 20 20 20 20 20 31 33 20 20 20  ULL        13   
61b0: 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 20 66 61 69  /* Insertion fai
61c0: 6c 65 64 20 62 65 63 61 75 73 65 20 64 61 74 61  led because data
61d0: 62 61 73 65 20 69 73 20 66 75 6c 6c 20 2a 2f 0a  base is full */.
61e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
61f0: 41 4e 54 4f 50 45 4e 20 20 20 20 31 34 20 20 20  ANTOPEN    14   
6200: 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 20 6f 70 65  /* Unable to ope
6210: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  n the database f
6220: 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ile */.#define S
6230: 51 4c 49 54 45 5f 50 52 4f 54 4f 43 4f 4c 20 20  QLITE_PROTOCOL  
6240: 20 20 31 35 20 20 20 2f 2a 20 44 61 74 61 62 61    15   /* Databa
6250: 73 65 20 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c  se lock protocol
6260: 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e   error */.#defin
6270: 65 20 53 51 4c 49 54 45 5f 45 4d 50 54 59 20 20  e SQLITE_EMPTY  
6280: 20 20 20 20 20 31 36 20 20 20 2f 2a 20 44 61 74       16   /* Dat
6290: 61 62 61 73 65 20 69 73 20 65 6d 70 74 79 20 2a  abase is empty *
62a0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
62b0: 5f 53 43 48 45 4d 41 20 20 20 20 20 20 31 37 20  _SCHEMA      17 
62c0: 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73    /* The databas
62d0: 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 64  e schema changed
62e0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
62f0: 54 45 5f 54 4f 4f 42 49 47 20 20 20 20 20 20 31  TE_TOOBIG      1
6300: 38 20 20 20 2f 2a 20 53 74 72 69 6e 67 20 6f 72  8   /* String or
6310: 20 42 4c 4f 42 20 65 78 63 65 65 64 73 20 73 69   BLOB exceeds si
6320: 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a 23 64 65 66  ze limit */.#def
6330: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
6340: 52 41 49 4e 54 20 20 31 39 20 20 20 2f 2a 20 41  RAINT  19   /* A
6350: 62 6f 72 74 20 64 75 65 20 74 6f 20 63 6f 6e 73  bort due to cons
6360: 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e  traint violation
6370: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6380: 54 45 5f 4d 49 53 4d 41 54 43 48 20 20 20 20 32  TE_MISMATCH    2
6390: 30 20 20 20 2f 2a 20 44 61 74 61 20 74 79 70 65  0   /* Data type
63a0: 20 6d 69 73 6d 61 74 63 68 20 2a 2f 0a 23 64 65   mismatch */.#de
63b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 55  fine SQLITE_MISU
63c0: 53 45 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20  SE      21   /* 
63d0: 4c 69 62 72 61 72 79 20 75 73 65 64 20 69 6e 63  Library used inc
63e0: 6f 72 72 65 63 74 6c 79 20 2a 2f 0a 23 64 65 66  orrectly */.#def
63f0: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4c 46 53  ine SQLITE_NOLFS
6400: 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 55         22   /* U
6410: 73 65 73 20 4f 53 20 66 65 61 74 75 72 65 73 20  ses OS features 
6420: 6e 6f 74 20 73 75 70 70 6f 72 74 65 64 20 6f 6e  not supported on
6430: 20 68 6f 73 74 20 2a 2f 0a 23 64 65 66 69 6e 65   host */.#define
6440: 20 53 51 4c 49 54 45 5f 41 55 54 48 20 20 20 20   SQLITE_AUTH    
6450: 20 20 20 20 32 33 20 20 20 2f 2a 20 41 75 74 68      23   /* Auth
6460: 6f 72 69 7a 61 74 69 6f 6e 20 64 65 6e 69 65 64  orization denied
6470: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6480: 54 45 5f 46 4f 52 4d 41 54 20 20 20 20 20 20 32  TE_FORMAT      2
6490: 34 20 20 20 2f 2a 20 41 75 78 69 6c 69 61 72 79  4   /* Auxiliary
64a0: 20 64 61 74 61 62 61 73 65 20 66 6f 72 6d 61 74   database format
64b0: 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e   error */.#defin
64c0: 65 20 53 51 4c 49 54 45 5f 52 41 4e 47 45 20 20  e SQLITE_RANGE  
64d0: 20 20 20 20 20 32 35 20 20 20 2f 2a 20 32 6e 64       25   /* 2nd
64e0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
64f0: 6c 69 74 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f  lite3_bind out o
6500: 66 20 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69  f range */.#defi
6510: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42  ne SQLITE_NOTADB
6520: 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 46 69        26   /* Fi
6530: 6c 65 20 6f 70 65 6e 65 64 20 74 68 61 74 20 69  le opened that i
6540: 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65  s not a database
6550: 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65   file */.#define
6560: 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 20   SQLITE_NOTICE  
6570: 20 20 20 20 32 37 20 20 20 2f 2a 20 4e 6f 74 69      27   /* Noti
6580: 66 69 63 61 74 69 6f 6e 73 20 66 72 6f 6d 20 73  fications from s
6590: 71 6c 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a  qlite3_log() */.
65a0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 57  #define SQLITE_W
65b0: 41 52 4e 49 4e 47 20 20 20 20 20 32 38 20 20 20  ARNING     28   
65c0: 2f 2a 20 57 61 72 6e 69 6e 67 73 20 66 72 6f 6d  /* Warnings from
65d0: 20 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 20 2a   sqlite3_log() *
65e0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
65f0: 5f 52 4f 57 20 20 20 20 20 20 20 20 20 31 30 30  _ROW         100
6600: 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65    /* sqlite3_ste
6610: 70 28 29 20 68 61 73 20 61 6e 6f 74 68 65 72 20  p() has another 
6620: 72 6f 77 20 72 65 61 64 79 20 2a 2f 0a 23 64 65  row ready */.#de
6630: 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45  fine SQLITE_DONE
6640: 20 20 20 20 20 20 20 20 31 30 31 20 20 2f 2a 20          101  /* 
6650: 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68  sqlite3_step() h
6660: 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 63  as finished exec
6670: 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d  uting */./* end-
6680: 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a  of-error-codes *
6690: 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
66a0: 46 3a 20 45 78 74 65 6e 64 65 64 20 52 65 73 75  F: Extended Resu
66b0: 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57  lt Codes.** KEYW
66c0: 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20  ORDS: {extended 
66d0: 72 65 73 75 6c 74 20 63 6f 64 65 20 64 65 66 69  result code defi
66e0: 6e 69 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 49  nitions}.**.** I
66f0: 6e 20 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f  n its default co
6700: 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c  nfiguration, SQL
6710: 69 74 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73  ite API routines
6720: 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 33   return one of 3
6730: 30 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 72 65  0 integer.** [re
6740: 73 75 6c 74 20 63 6f 64 65 73 5d 2e 20 20 48 6f  sult codes].  Ho
6750: 77 65 76 65 72 2c 20 65 78 70 65 72 69 65 6e 63  wever, experienc
6760: 65 20 68 61 73 20 73 68 6f 77 6e 20 74 68 61 74  e has shown that
6770: 20 6d 61 6e 79 20 6f 66 0a 2a 2a 20 74 68 65 73   many of.** thes
6780: 65 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61  e result codes a
6790: 72 65 20 74 6f 6f 20 63 6f 61 72 73 65 2d 67 72  re too coarse-gr
67a0: 61 69 6e 65 64 2e 20 20 54 68 65 79 20 64 6f 20  ained.  They do 
67b0: 6e 6f 74 20 70 72 6f 76 69 64 65 20 61 73 0a 2a  not provide as.*
67c0: 2a 20 6d 75 63 68 20 69 6e 66 6f 72 6d 61 74 69  * much informati
67d0: 6f 6e 20 61 62 6f 75 74 20 70 72 6f 62 6c 65 6d  on about problem
67e0: 73 20 61 73 20 70 72 6f 67 72 61 6d 6d 65 72 73  s as programmers
67f0: 20 6d 69 67 68 74 20 6c 69 6b 65 2e 20 20 49 6e   might like.  In
6800: 20 61 6e 20 65 66 66 6f 72 74 20 74 6f 0a 2a 2a   an effort to.**
6810: 20 61 64 64 72 65 73 73 20 74 68 69 73 2c 20 6e   address this, n
6820: 65 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66  ewer versions of
6830: 20 53 51 4c 69 74 65 20 28 76 65 72 73 69 6f 6e   SQLite (version
6840: 20 33 2e 33 2e 38 20 61 6e 64 20 6c 61 74 65 72   3.3.8 and later
6850: 29 20 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75 70  ) include.** sup
6860: 70 6f 72 74 20 66 6f 72 20 61 64 64 69 74 69 6f  port for additio
6870: 6e 61 6c 20 72 65 73 75 6c 74 20 63 6f 64 65 73  nal result codes
6880: 20 74 68 61 74 20 70 72 6f 76 69 64 65 20 6d 6f   that provide mo
6890: 72 65 20 64 65 74 61 69 6c 65 64 20 69 6e 66 6f  re detailed info
68a0: 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74  rmation.** about
68b0: 20 65 72 72 6f 72 73 2e 20 54 68 65 73 65 20 5b   errors. These [
68c0: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
68d0: 63 6f 64 65 73 5d 20 61 72 65 20 65 6e 61 62 6c  codes] are enabl
68e0: 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a  ed or disabled.*
68f0: 2a 20 6f 6e 20 61 20 70 65 72 20 64 61 74 61 62  * on a per datab
6900: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62  ase connection b
6910: 61 73 69 73 20 75 73 69 6e 67 20 74 68 65 0a 2a  asis using the.*
6920: 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  * [sqlite3_exten
6930: 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73  ded_result_codes
6940: 28 29 5d 20 41 50 49 2e 20 20 4f 72 2c 20 74 68  ()] API.  Or, th
6950: 65 20 65 78 74 65 6e 64 65 64 20 63 6f 64 65 20  e extended code 
6960: 66 6f 72 0a 2a 2a 20 74 68 65 20 6d 6f 73 74 20  for.** the most 
6970: 72 65 63 65 6e 74 20 65 72 72 6f 72 20 63 61 6e  recent error can
6980: 20 62 65 20 6f 62 74 61 69 6e 65 64 20 75 73 69   be obtained usi
6990: 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  ng.** [sqlite3_e
69a0: 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28  xtended_errcode(
69b0: 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  )]..*/.#define S
69c0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44  QLITE_IOERR_READ
69d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53                (S
69e0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31  QLITE_IOERR | (1
69f0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
6a00: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54  LITE_IOERR_SHORT
6a10: 5f 52 45 41 44 20 20 20 20 20 20 20 20 28 53 51  _READ        (SQ
6a20: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c  LITE_IOERR | (2<
6a30: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
6a40: 49 54 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20  ITE_IOERR_WRITE 
6a50: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
6a60: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c  ITE_IOERR | (3<<
6a70: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
6a80: 54 45 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20  TE_IOERR_FSYNC  
6a90: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
6aa0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38  TE_IOERR | (4<<8
6ab0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
6ac0: 45 5f 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e  E_IOERR_DIR_FSYN
6ad0: 43 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  C         (SQLIT
6ae0: 45 5f 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29  E_IOERR | (5<<8)
6af0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
6b00: 5f 49 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20  _IOERR_TRUNCATE 
6b10: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
6b20: 5f 49 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29  _IOERR | (6<<8))
6b30: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6b40: 49 4f 45 52 52 5f 46 53 54 41 54 20 20 20 20 20  IOERR_FSTAT     
6b50: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
6b60: 49 4f 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a  IOERR | (7<<8)).
6b70: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6b80: 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20  OERR_UNLOCK     
6b90: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
6ba0: 4f 45 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23  OERR | (8<<8)).#
6bb0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6bc0: 45 52 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20  ERR_RDLOCK      
6bd0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
6be0: 45 52 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64  ERR | (9<<8)).#d
6bf0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
6c00: 52 52 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20  RR_DELETE       
6c10: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
6c20: 52 52 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64  RR | (10<<8)).#d
6c30: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
6c40: 52 52 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20  RR_BLOCKED      
6c50: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
6c60: 52 52 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64  RR | (11<<8)).#d
6c70: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
6c80: 52 52 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20  RR_NOMEM        
6c90: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
6ca0: 52 52 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64  RR | (12<<8)).#d
6cb0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
6cc0: 52 52 5f 41 43 43 45 53 53 20 20 20 20 20 20 20  RR_ACCESS       
6cd0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
6ce0: 52 52 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64  RR | (13<<8)).#d
6cf0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
6d00: 52 52 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44  RR_CHECKRESERVED
6d10: 4c 4f 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45  LOCK (SQLITE_IOE
6d20: 52 52 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64  RR | (14<<8)).#d
6d30: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
6d40: 52 52 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  RR_LOCK         
6d50: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
6d60: 52 52 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64  RR | (15<<8)).#d
6d70: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
6d80: 52 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20  RR_CLOSE        
6d90: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
6da0: 52 52 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64  RR | (16<<8)).#d
6db0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
6dc0: 52 52 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20  RR_DIR_CLOSE    
6dd0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
6de0: 52 52 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64  RR | (17<<8)).#d
6df0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
6e00: 52 52 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20 20  RR_SHMOPEN      
6e10: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
6e20: 52 52 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64  RR | (18<<8)).#d
6e30: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
6e40: 52 52 5f 53 48 4d 53 49 5a 45 20 20 20 20 20 20  RR_SHMSIZE      
6e50: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
6e60: 52 52 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64  RR | (19<<8)).#d
6e70: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
6e80: 52 52 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20  RR_SHMLOCK      
6e90: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
6ea0: 52 52 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64  RR | (20<<8)).#d
6eb0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
6ec0: 52 52 5f 53 48 4d 4d 41 50 20 20 20 20 20 20 20  RR_SHMMAP       
6ed0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
6ee0: 52 52 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64  RR | (21<<8)).#d
6ef0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
6f00: 52 52 5f 53 45 45 4b 20 20 20 20 20 20 20 20 20  RR_SEEK         
6f10: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
6f20: 52 52 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64  RR | (22<<8)).#d
6f30: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
6f40: 52 52 5f 44 45 4c 45 54 45 5f 4e 4f 45 4e 54 20  RR_DELETE_NOENT 
6f50: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
6f60: 52 52 20 7c 20 28 32 33 3c 3c 38 29 29 0a 23 64  RR | (23<<8)).#d
6f70: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
6f80: 52 52 5f 4d 4d 41 50 20 20 20 20 20 20 20 20 20  RR_MMAP         
6f90: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
6fa0: 52 52 20 7c 20 28 32 34 3c 3c 38 29 29 0a 23 64  RR | (24<<8)).#d
6fb0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
6fc0: 52 52 5f 47 45 54 54 45 4d 50 50 41 54 48 20 20  RR_GETTEMPPATH  
6fd0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
6fe0: 52 52 20 7c 20 28 32 35 3c 3c 38 29 29 0a 23 64  RR | (25<<8)).#d
6ff0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
7000: 52 52 5f 43 4f 4e 56 50 41 54 48 20 20 20 20 20  RR_CONVPATH     
7010: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
7020: 52 52 20 7c 20 28 32 36 3c 3c 38 29 29 0a 23 64  RR | (26<<8)).#d
7030: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
7040: 4b 45 44 5f 53 48 41 52 45 44 43 41 43 48 45 20  KED_SHAREDCACHE 
7050: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43       (SQLITE_LOC
7060: 4b 45 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23  KED |  (1<<8)).#
7070: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55  define SQLITE_BU
7080: 53 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20  SY_RECOVERY     
7090: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55        (SQLITE_BU
70a0: 53 59 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a  SY   |  (1<<8)).
70b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42  #define SQLITE_B
70c0: 55 53 59 5f 53 4e 41 50 53 48 4f 54 20 20 20 20  USY_SNAPSHOT    
70d0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42         (SQLITE_B
70e0: 55 53 59 20 20 20 7c 20 20 28 32 3c 3c 38 29 29  USY   |  (2<<8))
70f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
7100: 43 41 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44  CANTOPEN_NOTEMPD
7110: 49 52 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  IR      (SQLITE_
7120: 43 41 4e 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38  CANTOPEN | (1<<8
7130: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
7140: 45 5f 43 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52  E_CANTOPEN_ISDIR
7150: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
7160: 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c  E_CANTOPEN | (2<
7170: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
7180: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c  ITE_CANTOPEN_FUL
7190: 4c 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c  LPATH       (SQL
71a0: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28  ITE_CANTOPEN | (
71b0: 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  3<<8)).#define S
71c0: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 43  QLITE_CANTOPEN_C
71d0: 4f 4e 56 50 41 54 48 20 20 20 20 20 20 20 28 53  ONVPATH       (S
71e0: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c  QLITE_CANTOPEN |
71f0: 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (4<<8)).#define
7200: 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f   SQLITE_CORRUPT_
7210: 56 54 41 42 20 20 20 20 20 20 20 20 20 20 20 20  VTAB            
7220: 28 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20  (SQLITE_CORRUPT 
7230: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
7240: 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c  e SQLITE_READONL
7250: 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20  Y_RECOVERY      
7260: 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c   (SQLITE_READONL
7270: 59 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  Y | (1<<8)).#def
7280: 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f  ine SQLITE_READO
7290: 4e 4c 59 5f 43 41 4e 54 4c 4f 43 4b 20 20 20 20  NLY_CANTLOCK    
72a0: 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f     (SQLITE_READO
72b0: 4e 4c 59 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64  NLY | (2<<8)).#d
72c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41  efine SQLITE_REA
72d0: 44 4f 4e 4c 59 5f 52 4f 4c 4c 42 41 43 4b 20 20  DONLY_ROLLBACK  
72e0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41       (SQLITE_REA
72f0: 44 4f 4e 4c 59 20 7c 20 28 33 3c 3c 38 29 29 0a  DONLY | (3<<8)).
7300: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
7310: 45 41 44 4f 4e 4c 59 5f 44 42 4d 4f 56 45 44 20  EADONLY_DBMOVED 
7320: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52         (SQLITE_R
7330: 45 41 44 4f 4e 4c 59 20 7c 20 28 34 3c 3c 38 29  EADONLY | (4<<8)
7340: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
7350: 5f 41 42 4f 52 54 5f 52 4f 4c 4c 42 41 43 4b 20  _ABORT_ROLLBACK 
7360: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
7370: 5f 41 42 4f 52 54 20 7c 20 28 32 3c 3c 38 29 29  _ABORT | (2<<8))
7380: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
7390: 43 4f 4e 53 54 52 41 49 4e 54 5f 43 48 45 43 4b  CONSTRAINT_CHECK
73a0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
73b0: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 31 3c  CONSTRAINT | (1<
73c0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
73d0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43  ITE_CONSTRAINT_C
73e0: 4f 4d 4d 49 54 48 4f 4f 4b 20 20 20 28 53 51 4c  OMMITHOOK   (SQL
73f0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
7400: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (2<<8)).#define
7410: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
7420: 4e 54 5f 46 4f 52 45 49 47 4e 4b 45 59 20 20 20  NT_FOREIGNKEY   
7430: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
7440: 4e 54 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65  NT | (3<<8)).#de
7450: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
7460: 54 52 41 49 4e 54 5f 46 55 4e 43 54 49 4f 4e 20  TRAINT_FUNCTION 
7470: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53      (SQLITE_CONS
7480: 54 52 41 49 4e 54 20 7c 20 28 34 3c 3c 38 29 29  TRAINT | (4<<8))
7490: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
74a0: 43 4f 4e 53 54 52 41 49 4e 54 5f 4e 4f 54 4e 55  CONSTRAINT_NOTNU
74b0: 4c 4c 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  LL      (SQLITE_
74c0: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 35 3c  CONSTRAINT | (5<
74d0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
74e0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 50  ITE_CONSTRAINT_P
74f0: 52 49 4d 41 52 59 4b 45 59 20 20 20 28 53 51 4c  RIMARYKEY   (SQL
7500: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
7510: 20 28 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (6<<8)).#define
7520: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
7530: 4e 54 5f 54 52 49 47 47 45 52 20 20 20 20 20 20  NT_TRIGGER      
7540: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
7550: 4e 54 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65  NT | (7<<8)).#de
7560: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
7570: 54 52 41 49 4e 54 5f 55 4e 49 51 55 45 20 20 20  TRAINT_UNIQUE   
7580: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53      (SQLITE_CONS
7590: 54 52 41 49 4e 54 20 7c 20 28 38 3c 3c 38 29 29  TRAINT | (8<<8))
75a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
75b0: 43 4f 4e 53 54 52 41 49 4e 54 5f 56 54 41 42 20  CONSTRAINT_VTAB 
75c0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
75d0: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 39 3c  CONSTRAINT | (9<
75e0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
75f0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 52  ITE_CONSTRAINT_R
7600: 4f 57 49 44 20 20 20 20 20 20 20 20 28 53 51 4c  OWID        (SQL
7610: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
7620: 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (10<<8)).#define
7630: 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52   SQLITE_NOTICE_R
7640: 45 43 4f 56 45 52 5f 57 41 4c 20 20 20 20 20 20  ECOVER_WAL      
7650: 28 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c  (SQLITE_NOTICE |
7660: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
7670: 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52   SQLITE_NOTICE_R
7680: 45 43 4f 56 45 52 5f 52 4f 4c 4c 42 41 43 4b 20  ECOVER_ROLLBACK 
7690: 28 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c  (SQLITE_NOTICE |
76a0: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (2<<8)).#define
76b0: 20 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 5f   SQLITE_WARNING_
76c0: 41 55 54 4f 49 4e 44 45 58 20 20 20 20 20 20 20  AUTOINDEX       
76d0: 28 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 20  (SQLITE_WARNING 
76e0: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
76f0: 65 20 53 51 4c 49 54 45 5f 41 55 54 48 5f 55 53  e SQLITE_AUTH_US
7700: 45 52 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ER              
7710: 20 28 53 51 4c 49 54 45 5f 41 55 54 48 20 7c 20   (SQLITE_AUTH | 
7720: 28 31 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43  (1<<8))../*.** C
7730: 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46  API3REF: Flags F
7740: 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65  or File Open Ope
7750: 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  rations.**.** Th
7760: 65 73 65 20 62 69 74 20 76 61 6c 75 65 73 20 61  ese bit values a
7770: 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  re intended for 
7780: 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72  use in the.** 3r
7790: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
77a0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
77b0: 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65  _v2()] interface
77c0: 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34   and.** in the 4
77d0: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
77e0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
77f0: 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a  .xOpen] method..
7800: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
7810: 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20  E_OPEN_READONLY 
7820: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
7830: 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  01  /* Ok for sq
7840: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
7850: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
7860: 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
7870: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
7880: 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  02  /* Ok for sq
7890: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
78a0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
78b0: 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20  E_OPEN_CREATE   
78c0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
78d0: 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  04  /* Ok for sq
78e0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
78f0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
7900: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
7910: 4c 4f 53 45 20 20 20 20 30 78 30 30 30 30 30 30  LOSE    0x000000
7920: 30 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  08  /* VFS only 
7930: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
7940: 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45  E_OPEN_EXCLUSIVE
7950: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
7960: 31 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  10  /* VFS only 
7970: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
7980: 45 5f 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58 59  E_OPEN_AUTOPROXY
7990: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
79a0: 32 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  20  /* VFS only 
79b0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
79c0: 45 5f 4f 50 45 4e 5f 55 52 49 20 20 20 20 20 20  E_OPEN_URI      
79d0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
79e0: 34 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  40  /* Ok for sq
79f0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
7a00: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
7a10: 45 5f 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20 20 20  E_OPEN_MEMORY   
7a20: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
7a30: 38 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  80  /* Ok for sq
7a40: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
7a50: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
7a60: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20  E_OPEN_MAIN_DB  
7a70: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31          0x000001
7a80: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
7a90: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
7aa0: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20  E_OPEN_TEMP_DB  
7ab0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32          0x000002
7ac0: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
7ad0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
7ae0: 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54  E_OPEN_TRANSIENT
7af0: 5f 44 42 20 20 20 20 20 30 78 30 30 30 30 30 34  _DB     0x000004
7b00: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
7b10: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
7b20: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52  E_OPEN_MAIN_JOUR
7b30: 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 30 38  NAL     0x000008
7b40: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
7b50: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
7b60: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52  E_OPEN_TEMP_JOUR
7b70: 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 31 30  NAL     0x000010
7b80: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
7b90: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
7ba0: 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41  E_OPEN_SUBJOURNA
7bb0: 4c 20 20 20 20 20 20 20 30 78 30 30 30 30 32 30  L       0x000020
7bc0: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
7bd0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
7be0: 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f  E_OPEN_MASTER_JO
7bf0: 55 52 4e 41 4c 20 20 20 30 78 30 30 30 30 34 30  URNAL   0x000040
7c00: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
7c10: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
7c20: 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20  E_OPEN_NOMUTEX  
7c30: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 38 30          0x000080
7c40: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
7c50: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
7c60: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
7c70: 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58  E_OPEN_FULLMUTEX
7c80: 20 20 20 20 20 20 20 20 30 78 30 30 30 31 30 30          0x000100
7c90: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
7ca0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
7cb0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
7cc0: 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
7cd0: 48 45 20 20 20 20 20 20 30 78 30 30 30 32 30 30  HE      0x000200
7ce0: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
7cf0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
7d00: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
7d10: 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41  E_OPEN_PRIVATECA
7d20: 43 48 45 20 20 20 20 20 30 78 30 30 30 34 30 30  CHE     0x000400
7d30: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
7d40: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
7d50: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
7d60: 45 5f 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20 20  E_OPEN_WAL      
7d70: 20 20 20 20 20 20 20 20 30 78 30 30 30 38 30 30          0x000800
7d80: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
7d90: 2a 2f 0a 0a 2f 2a 20 52 65 73 65 72 76 65 64 3a  */../* Reserved:
7da0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
7db0: 20 20 20 20 20 20 20 20 20 30 78 30 30 46 30 30           0x00F00
7dc0: 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  000 */../*.** CA
7dd0: 50 49 33 52 45 46 3a 20 44 65 76 69 63 65 20 43  PI3REF: Device C
7de0: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 0a 2a  haracteristics.*
7df0: 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65  *.** The xDevice
7e00: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20  Characteristics 
7e10: 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 73  method of the [s
7e20: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
7e30: 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74  s].** object ret
7e40: 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20  urns an integer 
7e50: 77 68 69 63 68 20 69 73 20 61 20 76 65 63 74 6f  which is a vecto
7e60: 72 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 62 69  r of these.** bi
7e70: 74 20 76 61 6c 75 65 73 20 65 78 70 72 65 73 73  t values express
7e80: 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 74 65  ing I/O characte
7e90: 72 69 73 74 69 63 73 20 6f 66 20 74 68 65 20 6d  ristics of the m
7ea0: 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64  ass storage.** d
7eb0: 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c 64 73  evice that holds
7ec0: 20 74 68 65 20 66 69 6c 65 20 74 68 61 74 20 74   the file that t
7ed0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  he [sqlite3_io_m
7ee0: 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72  ethods].** refer
7ef0: 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  s to..**.** The 
7f00: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
7f10: 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61  MIC property mea
7f20: 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74  ns that all writ
7f30: 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a  es of.** any siz
7f40: 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  e are atomic.  T
7f50: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
7f60: 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73  ATOMICnnn values
7f70: 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72  .** mean that wr
7f80: 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74  ites of blocks t
7f90: 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65  hat are nnn byte
7fa0: 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a  s in size and.**
7fb0: 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20   are aligned to 
7fc0: 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68  an address which
7fd0: 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d   is an integer m
7fe0: 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e  ultiple of.** nn
7ff0: 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  n are atomic.  T
8000: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
8010: 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75  SAFE_APPEND valu
8020: 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20  e means.** that 
8030: 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70  when data is app
8040: 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c  ended to a file,
8050: 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70   the data is app
8060: 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74  ended.** first t
8070: 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20  hen the size of 
8080: 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65  the file is exte
8090: 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20  nded, never the 
80a0: 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f  other.** way aro
80b0: 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45  und.  The SQLITE
80c0: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41  _IOCAP_SEQUENTIA
80d0: 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  L property means
80e0: 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61   that.** informa
80f0: 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20  tion is written 
8100: 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73  to disk in the s
8110: 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c  ame order as cal
8120: 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28  ls.** to xWrite(
8130: 29 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  ).  The SQLITE_I
8140: 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f  OCAP_POWERSAFE_O
8150: 56 45 52 57 52 49 54 45 20 70 72 6f 70 65 72 74  VERWRITE propert
8160: 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20  y means that.** 
8170: 61 66 74 65 72 20 72 65 62 6f 6f 74 20 66 6f 6c  after reboot fol
8180: 6c 6f 77 69 6e 67 20 61 20 63 72 61 73 68 20 6f  lowing a crash o
8190: 72 20 70 6f 77 65 72 20 6c 6f 73 73 2c 20 74 68  r power loss, th
81a0: 65 20 6f 6e 6c 79 20 62 79 74 65 73 20 69 6e 20  e only bytes in 
81b0: 61 0a 2a 2a 20 66 69 6c 65 20 74 68 61 74 20 77  a.** file that w
81c0: 65 72 65 20 77 72 69 74 74 65 6e 20 61 74 20 74  ere written at t
81d0: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6c  he application l
81e0: 65 76 65 6c 20 6d 69 67 68 74 20 68 61 76 65 20  evel might have 
81f0: 63 68 61 6e 67 65 64 0a 2a 2a 20 61 6e 64 20 74  changed.** and t
8200: 68 61 74 20 61 64 6a 61 63 65 6e 74 20 62 79 74  hat adjacent byt
8210: 65 73 2c 20 65 76 65 6e 20 62 79 74 65 73 20 77  es, even bytes w
8220: 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 73  ithin the same s
8230: 65 63 74 6f 72 20 61 72 65 0a 2a 2a 20 67 75 61  ector are.** gua
8240: 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20 75 6e  ranteed to be un
8250: 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20 53 51  changed.  The SQ
8260: 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c  LITE_IOCAP_UNDEL
8270: 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e  ETABLE_WHEN_OPEN
8280: 0a 2a 2a 20 66 6c 61 67 20 69 6e 64 69 63 61 74  .** flag indicat
8290: 65 20 74 68 61 74 20 61 20 66 69 6c 65 20 63 61  e that a file ca
82a0: 6e 6e 6f 74 20 62 65 20 64 65 6c 65 74 65 64 20  nnot be deleted 
82b0: 77 68 65 6e 20 6f 70 65 6e 2e 20 20 54 68 65 0a  when open.  The.
82c0: 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ** SQLITE_IOCAP_
82d0: 49 4d 4d 55 54 41 42 4c 45 20 66 6c 61 67 20 69  IMMUTABLE flag i
82e0: 6e 64 69 63 61 74 65 73 20 74 68 61 74 20 74 68  ndicates that th
82f0: 65 20 66 69 6c 65 20 69 73 20 6f 6e 0a 2a 2a 20  e file is on.** 
8300: 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 64 69 61 20  read-only media 
8310: 61 6e 64 20 63 61 6e 6e 6f 74 20 62 65 20 63 68  and cannot be ch
8320: 61 6e 67 65 64 20 65 76 65 6e 20 62 79 20 70 72  anged even by pr
8330: 6f 63 65 73 73 65 73 20 77 69 74 68 0a 2a 2a 20  ocesses with.** 
8340: 65 6c 65 76 61 74 65 64 20 70 72 69 76 69 6c 65  elevated privile
8350: 67 65 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ges..*/.#define 
8360: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
8370: 4d 49 43 20 20 20 20 20 20 20 20 20 20 20 20 20  MIC             
8380: 20 20 20 20 30 78 30 30 30 30 30 30 30 31 0a 23      0x00000001.#
8390: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
83a0: 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 20 20 20  CAP_ATOMIC512   
83b0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
83c0: 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51  00002.#define SQ
83d0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
83e0: 43 31 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  C1K             
83f0: 20 20 30 78 30 30 30 30 30 30 30 34 0a 23 64 65    0x00000004.#de
8400: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
8410: 50 5f 41 54 4f 4d 49 43 32 4b 20 20 20 20 20 20  P_ATOMIC2K      
8420: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
8430: 30 30 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  008.#define SQLI
8440: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34  TE_IOCAP_ATOMIC4
8450: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  K               
8460: 30 78 30 30 30 30 30 30 31 30 0a 23 64 65 66 69  0x00000010.#defi
8470: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
8480: 41 54 4f 4d 49 43 38 4b 20 20 20 20 20 20 20 20  ATOMIC8K        
8490: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32         0x0000002
84a0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
84b0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b  _IOCAP_ATOMIC16K
84c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
84d0: 30 30 30 30 30 30 34 30 0a 23 64 65 66 69 6e 65  00000040.#define
84e0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
84f0: 4f 4d 49 43 33 32 4b 20 20 20 20 20 20 20 20 20  OMIC32K         
8500: 20 20 20 20 20 30 78 30 30 30 30 30 30 38 30 0a       0x00000080.
8510: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
8520: 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 20 20  OCAP_ATOMIC64K  
8530: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
8540: 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53  000100.#define S
8550: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
8560: 5f 41 50 50 45 4e 44 20 20 20 20 20 20 20 20 20  _APPEND         
8570: 20 20 20 30 78 30 30 30 30 30 32 30 30 0a 23 64     0x00000200.#d
8580: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
8590: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 20 20  AP_SEQUENTIAL   
85a0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
85b0: 30 34 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0400.#define SQL
85c0: 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45  ITE_IOCAP_UNDELE
85d0: 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 20  TABLE_WHEN_OPEN 
85e0: 20 30 78 30 30 30 30 30 38 30 30 0a 23 64 65 66   0x00000800.#def
85f0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
8600: 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57  _POWERSAFE_OVERW
8610: 52 49 54 45 20 20 20 20 30 78 30 30 30 30 31 30  RITE    0x000010
8620: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  00.#define SQLIT
8630: 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c  E_IOCAP_IMMUTABL
8640: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30  E              0
8650: 78 30 30 30 30 32 30 30 30 0a 0a 2f 2a 0a 2a 2a  x00002000../*.**
8660: 20 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20   CAPI3REF: File 
8670: 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a  Locking Levels.*
8680: 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73  *.** SQLite uses
8690: 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e   one of these in
86a0: 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 20  teger values as 
86b0: 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72  the second.** ar
86c0: 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20  gument to calls 
86d0: 69 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20  it makes to the 
86e0: 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c  xLock() and xUnl
86f0: 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a  ock() methods.**
8700: 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   of an [sqlite3_
8710: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
8720: 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ct..*/.#define S
8730: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20  QLITE_LOCK_NONE 
8740: 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69           0.#defi
8750: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53  ne SQLITE_LOCK_S
8760: 48 41 52 45 44 20 20 20 20 20 20 20 20 31 0a 23  HARED        1.#
8770: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
8780: 43 4b 5f 52 45 53 45 52 56 45 44 20 20 20 20 20  CK_RESERVED     
8790: 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
87a0: 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20  E_LOCK_PENDING  
87b0: 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53       3.#define S
87c0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55  QLITE_LOCK_EXCLU
87d0: 53 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a  SIVE     4../*.*
87e0: 2a 20 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63  * CAPI3REF: Sync
87f0: 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65  hronization Type
8800: 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65   Flags.**.** Whe
8810: 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73  n SQLite invokes
8820: 20 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74   the xSync() met
8830: 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71  hod of an.** [sq
8840: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
8850: 5d 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73  ] object it uses
8860: 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f   a combination o
8870: 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 67  f.** these integ
8880: 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65  er values as the
8890: 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
88a0: 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65  ..**.** When the
88b0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54   SQLITE_SYNC_DAT
88c0: 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 73  AONLY flag is us
88d0: 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61  ed, it means tha
88e0: 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70  t the.** sync op
88f0: 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65  eration only nee
8900: 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61  ds to flush data
8910: 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 65   to mass storage
8920: 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f  .  Inode.** info
8930: 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74  rmation need not
8940: 20 62 65 20 66 6c 75 73 68 65 64 2e 20 49 66 20   be flushed. If 
8950: 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62  the lower four b
8960: 69 74 73 20 6f 66 20 74 68 65 20 66 6c 61 67 0a  its of the flag.
8970: 2a 2a 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f  ** equal SQLITE_
8980: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61  SYNC_NORMAL, tha
8990: 74 20 6d 65 61 6e 73 20 74 6f 20 75 73 65 20 6e  t means to use n
89a0: 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 65  ormal fsync() se
89b0: 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74  mantics..** If t
89c0: 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69  he lower four bi
89d0: 74 73 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f  ts equal SQLITE_
89e0: 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20  SYNC_FULL, that 
89f0: 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20  means.** to use 
8a00: 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66  Mac OS X style f
8a10: 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20  ullsync instead 
8a20: 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a  of fsync()..**.*
8a30: 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65  * Do not confuse
8a40: 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43   the SQLITE_SYNC
8a50: 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49  _NORMAL and SQLI
8a60: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61  TE_SYNC_FULL fla
8a70: 67 73 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b  gs.** with the [
8a80: 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f  PRAGMA synchrono
8a90: 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b  us]=NORMAL and [
8aa0: 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f  PRAGMA synchrono
8ab0: 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74  us]=FULL.** sett
8ac0: 69 6e 67 73 2e 20 20 54 68 65 20 5b 73 79 6e 63  ings.  The [sync
8ad0: 68 72 6f 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20  hronous pragma] 
8ae0: 64 65 74 65 72 6d 69 6e 65 73 20 77 68 65 6e 20  determines when 
8af0: 63 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20  calls to the.** 
8b00: 78 53 79 6e 63 20 56 46 53 20 6d 65 74 68 6f 64  xSync VFS method
8b10: 20 6f 63 63 75 72 20 61 6e 64 20 61 70 70 6c 69   occur and appli
8b20: 65 73 20 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72  es uniformly acr
8b30: 6f 73 73 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d  oss all platform
8b40: 73 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  s..** The SQLITE
8b50: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64  _SYNC_NORMAL and
8b60: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c   SQLITE_SYNC_FUL
8b70: 4c 20 66 6c 61 67 73 20 64 65 74 65 72 6d 69 6e  L flags determin
8b80: 65 20 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74  e how.** energet
8b90: 69 63 20 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f  ic or rigorous o
8ba0: 72 20 66 6f 72 63 65 66 75 6c 20 74 68 65 20 73  r forceful the s
8bb0: 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 73 20 61  ync operations a
8bc0: 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d  re and.** only m
8bd0: 61 6b 65 20 61 20 64 69 66 66 65 72 65 6e 63 65  ake a difference
8be0: 20 6f 6e 20 4d 61 63 20 4f 53 58 20 66 6f 72 20   on Mac OSX for 
8bf0: 74 68 65 20 64 65 66 61 75 6c 74 20 53 51 4c 69  the default SQLi
8c00: 74 65 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69  te code..** (Thi
8c10: 72 64 2d 70 61 72 74 79 20 56 46 53 20 69 6d 70  rd-party VFS imp
8c20: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67  lementations mig
8c30: 68 74 20 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65  ht also make the
8c40: 20 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20   distinction.** 
8c50: 62 65 74 77 65 65 6e 20 53 51 4c 49 54 45 5f 53  between SQLITE_S
8c60: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53  YNC_NORMAL and S
8c70: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c  QLITE_SYNC_FULL,
8c80: 20 62 75 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a   but among the.*
8c90: 2a 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  * operating syst
8ca0: 65 6d 73 20 6e 61 74 69 76 65 6c 79 20 73 75 70  ems natively sup
8cb0: 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65  ported by SQLite
8cc0: 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a  , only Mac OSX.*
8cd0: 2a 20 63 61 72 65 73 20 61 62 6f 75 74 20 74 68  * cares about th
8ce0: 65 20 64 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a  e difference.).*
8cf0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
8d00: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20  _SYNC_NORMAL    
8d10: 20 20 20 20 30 78 30 30 30 30 32 0a 23 64 65 66      0x00002.#def
8d20: 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ine SQLITE_SYNC_
8d30: 46 55 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78  FULL          0x
8d40: 30 30 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51  00003.#define SQ
8d50: 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e  LITE_SYNC_DATAON
8d60: 4c 59 20 20 20 20 20 20 30 78 30 30 30 31 30 0a  LY      0x00010.
8d70: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
8d80: 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70   OS Interface Op
8d90: 65 6e 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a  en File Handle.*
8da0: 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33  *.** An [sqlite3
8db0: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65  _file] object re
8dc0: 70 72 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e  presents an open
8dd0: 20 66 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a   file in the .**
8de0: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20   [sqlite3_vfs | 
8df0: 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79  OS interface lay
8e00: 65 72 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c  er].  Individual
8e10: 20 4f 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a   OS interface.**
8e20: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
8e30: 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f   will.** want to
8e40: 20 73 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f   subclass this o
8e50: 62 6a 65 63 74 20 62 79 20 61 70 70 65 6e 64 69  bject by appendi
8e60: 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69  ng additional fi
8e70: 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69  elds.** for thei
8e80: 72 20 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20  r own use.  The 
8e90: 70 4d 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69  pMethods entry i
8ea0: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
8eb0: 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f  n.** [sqlite3_io
8ec0: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
8ed0: 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65   that defines me
8ee0: 74 68 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72  thods for perfor
8ef0: 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72  ming.** I/O oper
8f00: 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70  ations on the op
8f10: 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65  en file..*/.type
8f20: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
8f30: 65 33 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f  e3_file sqlite3_
8f40: 66 69 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c  file;.struct sql
8f50: 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f  ite3_file {.  co
8f60: 6e 73 74 20 73 74 72 75 63 74 20 73 71 6c 69 74  nst struct sqlit
8f70: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70  e3_io_methods *p
8f80: 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74  Methods;  /* Met
8f90: 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e  hods for an open
8fa0: 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a   file */.};../*.
8fb0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20  ** CAPI3REF: OS 
8fc0: 49 6e 74 65 72 66 61 63 65 20 46 69 6c 65 20 56  Interface File V
8fd0: 69 72 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f  irtual Methods O
8fe0: 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72  bject.**.** Ever
8ff0: 79 20 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79  y file opened by
9000: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
9010: 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20  s.xOpen] method 
9020: 70 6f 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20  populates an.** 
9030: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
9040: 62 6a 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20  bject (or, more 
9050: 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63  commonly, a subc
9060: 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b  lass of the.** [
9070: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
9080: 6a 65 63 74 29 20 77 69 74 68 20 61 20 70 6f 69  ject) with a poi
9090: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
90a0: 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
90b0: 63 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65  ct..** This obje
90c0: 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d  ct defines the m
90d0: 65 74 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70  ethods used to p
90e0: 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f  erform various o
90f0: 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61  perations.** aga
9100: 69 6e 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69  inst the open fi
9110: 6c 65 20 72 65 70 72 65 73 65 6e 74 65 64 20 62  le represented b
9120: 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66  y the [sqlite3_f
9130: 69 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a  ile] object..**.
9140: 2a 2a 20 49 66 20 74 68 65 20 5b 73 71 6c 69 74  ** If the [sqlit
9150: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65  e3_vfs.xOpen] me
9160: 74 68 6f 64 20 73 65 74 73 20 74 68 65 20 73 71  thod sets the sq
9170: 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68  lite3_file.pMeth
9180: 6f 64 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20  ods element .** 
9190: 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f  to a non-NULL po
91a0: 69 6e 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20  inter, then the 
91b0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
91c0: 64 73 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64  ds.xClose method
91d0: 0a 2a 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b  .** may be invok
91e0: 65 64 20 65 76 65 6e 20 69 66 20 74 68 65 20 5b  ed even if the [
91f0: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65  sqlite3_vfs.xOpe
9200: 6e 5d 20 72 65 70 6f 72 74 65 64 20 74 68 61 74  n] reported that
9210: 20 69 74 20 66 61 69 6c 65 64 2e 20 20 54 68 65   it failed.  The
9220: 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20  .** only way to 
9230: 70 72 65 76 65 6e 74 20 61 20 63 61 6c 6c 20 74  prevent a call t
9240: 6f 20 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69  o xClose followi
9250: 6e 67 20 61 20 66 61 69 6c 65 64 20 5b 73 71 6c  ng a failed [sql
9260: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a  ite3_vfs.xOpen].
9270: 2a 2a 20 69 73 20 66 6f 72 20 74 68 65 20 5b 73  ** is for the [s
9280: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
9290: 5d 20 74 6f 20 73 65 74 20 74 68 65 20 73 71 6c  ] to set the sql
92a0: 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f  ite3_file.pMetho
92b0: 64 73 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f  ds element.** to
92c0: 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   NULL..**.** The
92d0: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20   flags argument 
92e0: 74 6f 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20  to xSync may be 
92f0: 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53  one of [SQLITE_S
9300: 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a  YNC_NORMAL] or.*
9310: 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  * [SQLITE_SYNC_F
9320: 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74  ULL].  The first
9330: 20 63 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e   choice is the n
9340: 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a  ormal fsync()..*
9350: 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f  * The second cho
9360: 69 63 65 20 69 73 20 61 20 4d 61 63 20 4f 53 20  ice is a Mac OS 
9370: 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63  X style fullsync
9380: 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 53  .  The [SQLITE_S
9390: 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a  YNC_DATAONLY].**
93a0: 20 66 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65   flag may be ORe
93b0: 64 20 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 65  d in to indicate
93c0: 20 74 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64   that only the d
93d0: 61 74 61 20 6f 66 20 74 68 65 20 66 69 6c 65 0a  ata of the file.
93e0: 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69  ** and not its i
93f0: 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65  node needs to be
9400: 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54   synced..**.** T
9410: 68 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65  he integer value
9420: 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64  s to xLock() and
9430: 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f   xUnlock() are o
9440: 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  ne of.** <ul>.**
9450: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
9460: 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69  CK_NONE],.** <li
9470: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53  > [SQLITE_LOCK_S
9480: 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  HARED],.** <li> 
9490: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53  [SQLITE_LOCK_RES
94a0: 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  ERVED],.** <li> 
94b0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e  [SQLITE_LOCK_PEN
94c0: 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69  DING], or.** <li
94d0: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45  > [SQLITE_LOCK_E
94e0: 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f  XCLUSIVE]..** </
94f0: 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69  ul>.** xLock() i
9500: 6e 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63  ncreases the loc
9510: 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63  k. xUnlock() dec
9520: 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e  reases the lock.
9530: 0a 2a 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65  .** The xCheckRe
9540: 73 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74  servedLock() met
9550: 68 6f 64 20 63 68 65 63 6b 73 20 77 68 65 74 68  hod checks wheth
9560: 65 72 20 61 6e 79 20 64 61 74 61 62 61 73 65 20  er any database 
9570: 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65  connection,.** e
9580: 69 74 68 65 72 20 69 6e 20 74 68 69 73 20 70 72  ither in this pr
9590: 6f 63 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65  ocess or in some
95a0: 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20   other process, 
95b0: 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 53  is holding a RES
95c0: 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e  ERVED,.** PENDIN
95d0: 47 2c 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20  G, or EXCLUSIVE 
95e0: 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65  lock on the file
95f0: 2e 20 20 49 74 20 72 65 74 75 72 6e 73 20 74 72  .  It returns tr
9600: 75 65 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20  ue.** if such a 
9610: 6c 6f 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20  lock exists and 
9620: 66 61 6c 73 65 20 6f 74 68 65 72 77 69 73 65 2e  false otherwise.
9630: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65  .**.** The xFile
9640: 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64  Control() method
9650: 20 69 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e   is a generic in
9660: 74 65 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c  terface that all
9670: 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46  ows custom.** VF
9680: 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
9690: 73 20 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f  s to directly co
96a0: 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69  ntrol an open fi
96b0: 6c 65 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  le using the.** 
96c0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
96d0: 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61  ntrol()] interfa
96e0: 63 65 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ce.  The second 
96f0: 22 6f 70 22 20 61 72 67 75 6d 65 6e 74 20 69 73  "op" argument is
9700: 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f   an.** integer o
9710: 70 63 6f 64 65 2e 20 20 54 68 65 20 74 68 69 72  pcode.  The thir
9720: 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  d argument is a 
9730: 67 65 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20  generic pointer 
9740: 69 6e 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70  intended to.** p
9750: 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 75 63 74  oint to a struct
9760: 75 72 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e  ure that may con
9770: 74 61 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f  tain arguments o
9780: 72 20 73 70 61 63 65 20 69 6e 20 77 68 69 63 68  r space in which
9790: 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74   to.** write ret
97a0: 75 72 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74  urn values.  Pot
97b0: 65 6e 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20  ential uses for 
97c0: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d  xFileControl() m
97d0: 69 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74  ight be.** funct
97e0: 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62  ions to enable b
97f0: 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69  locking locks wi
9800: 74 68 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20  th timeouts, to 
9810: 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f  change the.** lo
9820: 63 6b 69 6e 67 20 73 74 72 61 74 65 67 79 20 28  cking strategy (
9830: 66 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75  for example to u
9840: 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b  se dot-file lock
9850: 73 29 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a  s), to inquire.*
9860: 2a 20 61 62 6f 75 74 20 74 68 65 20 73 74 61 74  * about the stat
9870: 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72  us of a lock, or
9880: 20 74 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20   to break stale 
9890: 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69  locks.  The SQLi
98a0: 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72  te.** core reser
98b0: 76 65 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20  ves all opcodes 
98c0: 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f  less than 100 fo
98d0: 72 20 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a  r its own use..*
98e0: 2a 20 41 20 5b 66 69 6c 65 20 63 6f 6e 74 72 6f  * A [file contro
98f0: 6c 20 6f 70 63 6f 64 65 73 20 7c 20 6c 69 73 74  l opcodes | list
9900: 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73   of opcodes] les
9910: 73 20 74 68 61 6e 20 31 30 30 20 69 73 20 61 76  s than 100 is av
9920: 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c  ailable..** Appl
9930: 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64 65  ications that de
9940: 66 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 46  fine a custom xF
9950: 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f  ileControl metho
9960: 64 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 63  d should use opc
9970: 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 72 20  odes.** greater 
9980: 74 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f 69  than 100 to avoi
9990: 64 20 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56 46  d conflicts.  VF
99a0: 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
99b0: 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75  s should.** retu
99c0: 72 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f  rn [SQLITE_NOTFO
99d0: 55 4e 44 5d 20 66 6f 72 20 66 69 6c 65 20 63 6f  UND] for file co
99e0: 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74 68  ntrol opcodes th
99f0: 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a  at they do not.*
9a00: 2a 20 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a  * recognize..**.
9a10: 2a 2a 20 54 68 65 20 78 53 65 63 74 6f 72 53 69  ** The xSectorSi
9a20: 7a 65 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75  ze() method retu
9a30: 72 6e 73 20 74 68 65 20 73 65 63 74 6f 72 20 73  rns the sector s
9a40: 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65  ize of the.** de
9a50: 76 69 63 65 20 74 68 61 74 20 75 6e 64 65 72 6c  vice that underl
9a60: 69 65 73 20 74 68 65 20 66 69 6c 65 2e 20 20 54  ies the file.  T
9a70: 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 69  he sector size i
9a80: 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d  s the.** minimum
9a90: 20 77 72 69 74 65 20 74 68 61 74 20 63 61 6e 20   write that can 
9aa0: 62 65 20 70 65 72 66 6f 72 6d 65 64 20 77 69 74  be performed wit
9ab0: 68 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67 0a  hout disturbing.
9ac0: 2a 2a 20 6f 74 68 65 72 20 62 79 74 65 73 20 69  ** other bytes i
9ad0: 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65  n the file.  The
9ae0: 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65   xDeviceCharacte
9af0: 72 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74  ristics().** met
9b00: 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 62 69  hod returns a bi
9b10: 74 20 76 65 63 74 6f 72 20 64 65 73 63 72 69 62  t vector describ
9b20: 69 6e 67 20 62 65 68 61 76 69 6f 72 73 20 6f 66  ing behaviors of
9b30: 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69   the.** underlyi
9b40: 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a  ng device:.**.**
9b50: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53   <ul>.** <li> [S
9b60: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
9b70: 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  IC].** <li> [SQL
9b80: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
9b90: 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  512].** <li> [SQ
9ba0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
9bb0: 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C1K].** <li> [SQ
9bc0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
9bd0: 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C2K].** <li> [SQ
9be0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
9bf0: 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C4K].** <li> [SQ
9c00: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
9c10: 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C8K].** <li> [SQ
9c20: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
9c30: 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C16K].** <li> [S
9c40: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
9c50: 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC32K].** <li> [
9c60: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
9c70: 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  MIC64K].** <li> 
9c80: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41  [SQLITE_IOCAP_SA
9c90: 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c  FE_APPEND].** <l
9ca0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
9cb0: 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20  _SEQUENTIAL].** 
9cc0: 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  </ul>.**.** The 
9cd0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
9ce0: 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61  MIC property mea
9cf0: 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74  ns that all writ
9d00: 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a  es of.** any siz
9d10: 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  e are atomic.  T
9d20: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
9d30: 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73  ATOMICnnn values
9d40: 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72  .** mean that wr
9d50: 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74  ites of blocks t
9d60: 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65  hat are nnn byte
9d70: 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a  s in size and.**
9d80: 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20   are aligned to 
9d90: 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68  an address which
9da0: 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d   is an integer m
9db0: 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e  ultiple of.** nn
9dc0: 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  n are atomic.  T
9dd0: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
9de0: 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75  SAFE_APPEND valu
9df0: 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20  e means.** that 
9e00: 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70  when data is app
9e10: 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c  ended to a file,
9e20: 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70   the data is app
9e30: 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74  ended.** first t
9e40: 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20  hen the size of 
9e50: 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65  the file is exte
9e60: 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20  nded, never the 
9e70: 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f  other.** way aro
9e80: 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45  und.  The SQLITE
9e90: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41  _IOCAP_SEQUENTIA
9ea0: 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  L property means
9eb0: 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61   that.** informa
9ec0: 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20  tion is written 
9ed0: 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73  to disk in the s
9ee0: 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c  ame order as cal
9ef0: 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28  ls.** to xWrite(
9f00: 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 65 61  )..**.** If xRea
9f10: 64 28 29 20 72 65 74 75 72 6e 73 20 53 51 4c 49  d() returns SQLI
9f20: 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52  TE_IOERR_SHORT_R
9f30: 45 41 44 20 69 74 20 6d 75 73 74 20 61 6c 73 6f  EAD it must also
9f40: 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65 20   fill.** in the 
9f50: 75 6e 72 65 61 64 20 70 6f 72 74 69 6f 6e 73 20  unread portions 
9f60: 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 77 69  of the buffer wi
9f70: 74 68 20 7a 65 72 6f 73 2e 20 20 41 20 56 46 53  th zeros.  A VFS
9f80: 20 74 68 61 74 0a 2a 2a 20 66 61 69 6c 73 20 74   that.** fails t
9f90: 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72  o zero-fill shor
9fa0: 74 20 72 65 61 64 73 20 6d 69 67 68 74 20 73 65  t reads might se
9fb0: 65 6d 20 74 6f 20 77 6f 72 6b 2e 20 20 48 6f 77  em to work.  How
9fc0: 65 76 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 72 65  ever,.** failure
9fd0: 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68   to zero-fill sh
9fe0: 6f 72 74 20 72 65 61 64 73 20 77 69 6c 6c 20 65  ort reads will e
9ff0: 76 65 6e 74 75 61 6c 6c 79 20 6c 65 61 64 20 74  ventually lead t
a000: 6f 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  o.** database co
a010: 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70  rruption..*/.typ
a020: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
a030: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73  te3_io_methods s
a040: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
a050: 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  s;.struct sqlite
a060: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20  3_io_methods {. 
a070: 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20   int iVersion;. 
a080: 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73   int (*xClose)(s
a090: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20  qlite3_file*);. 
a0a0: 20 69 6e 74 20 28 2a 78 52 65 61 64 29 28 73 71   int (*xRead)(sq
a0b0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69  lite3_file*, voi
a0c0: 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71  d*, int iAmt, sq
a0d0: 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73  lite3_int64 iOfs
a0e0: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72 69  t);.  int (*xWri
a0f0: 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  te)(sqlite3_file
a100: 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
a110: 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65  int iAmt, sqlite
a120: 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a  3_int64 iOfst);.
a130: 20 20 69 6e 74 20 28 2a 78 54 72 75 6e 63 61 74    int (*xTruncat
a140: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
a150: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
a160: 73 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78  size);.  int (*x
a170: 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 66 69  Sync)(sqlite3_fi
a180: 6c 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b  le*, int flags);
a190: 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 53 69  .  int (*xFileSi
a1a0: 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ze)(sqlite3_file
a1b0: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
a1c0: 20 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20   *pSize);.  int 
a1d0: 28 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33  (*xLock)(sqlite3
a1e0: 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20  _file*, int);.  
a1f0: 69 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73  int (*xUnlock)(s
a200: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
a210: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68 65  t);.  int (*xChe
a220: 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 29 28  ckReservedLock)(
a230: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
a240: 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20  nt *pResOut);.  
a250: 69 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72  int (*xFileContr
a260: 6f 6c 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ol)(sqlite3_file
a270: 2a 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20  *, int op, void 
a280: 2a 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a  *pArg);.  int (*
a290: 78 53 65 63 74 6f 72 53 69 7a 65 29 28 73 71 6c  xSectorSize)(sql
a2a0: 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69  ite3_file*);.  i
a2b0: 6e 74 20 28 2a 78 44 65 76 69 63 65 43 68 61 72  nt (*xDeviceChar
a2c0: 61 63 74 65 72 69 73 74 69 63 73 29 28 73 71 6c  acteristics)(sql
a2d0: 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f  ite3_file*);.  /
a2e0: 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  * Methods above 
a2f0: 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65  are valid for ve
a300: 72 73 69 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e 74  rsion 1 */.  int
a310: 20 28 2a 78 53 68 6d 4d 61 70 29 28 73 71 6c 69   (*xShmMap)(sqli
a320: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 69  te3_file*, int i
a330: 50 67 2c 20 69 6e 74 20 70 67 73 7a 2c 20 69 6e  Pg, int pgsz, in
a340: 74 2c 20 76 6f 69 64 20 76 6f 6c 61 74 69 6c 65  t, void volatile
a350: 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68  **);.  int (*xSh
a360: 6d 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66  mLock)(sqlite3_f
a370: 69 6c 65 2a 2c 20 69 6e 74 20 6f 66 66 73 65 74  ile*, int offset
a380: 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20 66 6c 61  , int n, int fla
a390: 67 73 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 53  gs);.  void (*xS
a3a0: 68 6d 42 61 72 72 69 65 72 29 28 73 71 6c 69 74  hmBarrier)(sqlit
a3b0: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74  e3_file*);.  int
a3c0: 20 28 2a 78 53 68 6d 55 6e 6d 61 70 29 28 73 71   (*xShmUnmap)(sq
a3d0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
a3e0: 20 64 65 6c 65 74 65 46 6c 61 67 29 3b 0a 20 20   deleteFlag);.  
a3f0: 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65  /* Methods above
a400: 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76   are valid for v
a410: 65 72 73 69 6f 6e 20 32 20 2a 2f 0a 20 20 69 6e  ersion 2 */.  in
a420: 74 20 28 2a 78 46 65 74 63 68 29 28 73 71 6c 69  t (*xFetch)(sqli
a430: 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74  te3_file*, sqlit
a440: 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c 20  e3_int64 iOfst, 
a450: 69 6e 74 20 69 41 6d 74 2c 20 76 6f 69 64 20 2a  int iAmt, void *
a460: 2a 70 70 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55  *pp);.  int (*xU
a470: 6e 66 65 74 63 68 29 28 73 71 6c 69 74 65 33 5f  nfetch)(sqlite3_
a480: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
a490: 6e 74 36 34 20 69 4f 66 73 74 2c 20 76 6f 69 64  nt64 iOfst, void
a4a0: 20 2a 70 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f   *p);.  /* Metho
a4b0: 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c  ds above are val
a4c0: 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33  id for version 3
a4d0: 20 2a 2f 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f   */.  /* Additio
a4e0: 6e 61 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79 20  nal methods may 
a4f0: 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
a500: 72 65 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d  re releases */.}
a510: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
a520: 46 3a 20 53 74 61 6e 64 61 72 64 20 46 69 6c 65  F: Standard File
a530: 20 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73   Control Opcodes
a540: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66  .** KEYWORDS: {f
a550: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f  ile control opco
a560: 64 65 73 7d 20 7b 66 69 6c 65 20 63 6f 6e 74 72  des} {file contr
a570: 6f 6c 20 6f 70 63 6f 64 65 7d 0a 2a 2a 0a 2a 2a  ol opcode}.**.**
a580: 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63   These integer c
a590: 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 6f 70 63  onstants are opc
a5a0: 6f 64 65 73 20 66 6f 72 20 74 68 65 20 78 46 69  odes for the xFi
a5b0: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
a5c0: 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  .** of the [sqli
a5d0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
a5e0: 6f 62 6a 65 63 74 20 61 6e 64 20 66 6f 72 20 74  object and for t
a5f0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
a600: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69  _control()].** i
a610: 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
a620: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
a630: 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63  L_LOCKSTATE] opc
a640: 6f 64 65 20 69 73 20 75 73 65 64 20 66 6f 72 20  ode is used for 
a650: 64 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73  debugging.  This
a660: 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65  .** opcode cause
a670: 73 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72  s the xFileContr
a680: 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 69  ol method to wri
a690: 74 65 20 74 68 65 20 63 75 72 72 65 6e 74 20 73  te the current s
a6a0: 74 61 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c  tate of.** the l
a6b0: 6f 63 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c  ock (one of [SQL
a6c0: 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20  ITE_LOCK_NONE], 
a6d0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41  [SQLITE_LOCK_SHA
a6e0: 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  RED],.** [SQLITE
a6f0: 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c  _LOCK_RESERVED],
a700: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45   [SQLITE_LOCK_PE
a710: 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49  NDING], or [SQLI
a720: 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56  TE_LOCK_EXCLUSIV
a730: 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69  E]).** into an i
a740: 6e 74 65 67 65 72 20 74 68 61 74 20 74 68 65 20  nteger that the 
a750: 70 41 72 67 20 61 72 67 75 6d 65 6e 74 20 70 6f  pArg argument po
a760: 69 6e 74 73 20 74 6f 2e 20 54 68 69 73 20 63 61  ints to. This ca
a770: 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75  pability.** is u
a780: 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69  sed during testi
a790: 6e 67 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64  ng and only need
a7a0: 73 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65  s to be supporte
a7b0: 64 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 54 45  d when SQLITE_TE
a7c0: 53 54 0a 2a 2a 20 69 73 20 64 65 66 69 6e 65 64  ST.** is defined
a7d0: 2e 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  ..** <ul>.** <li
a7e0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
a7f0: 53 49 5a 45 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 54  SIZE_HINT]].** T
a800: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
a810: 5f 53 49 5a 45 5f 48 49 4e 54 5d 20 6f 70 63 6f  _SIZE_HINT] opco
a820: 64 65 20 69 73 20 75 73 65 64 20 62 79 20 53 51  de is used by SQ
a830: 4c 69 74 65 20 74 6f 20 67 69 76 65 20 74 68 65  Lite to give the
a840: 20 56 46 53 0a 2a 2a 20 6c 61 79 65 72 20 61 20   VFS.** layer a 
a850: 68 69 6e 74 20 6f 66 20 68 6f 77 20 6c 61 72 67  hint of how larg
a860: 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  e the database f
a870: 69 6c 65 20 77 69 6c 6c 20 67 72 6f 77 20 74 6f  ile will grow to
a880: 20 62 65 20 64 75 72 69 6e 67 20 74 68 65 0a 2a   be during the.*
a890: 2a 20 63 75 72 72 65 6e 74 20 74 72 61 6e 73 61  * current transa
a8a0: 63 74 69 6f 6e 2e 20 20 54 68 69 73 20 68 69 6e  ction.  This hin
a8b0: 74 20 69 73 20 6e 6f 74 20 67 75 61 72 61 6e 74  t is not guarant
a8c0: 65 65 64 20 74 6f 20 62 65 20 61 63 63 75 72 61  eed to be accura
a8d0: 74 65 20 62 75 74 20 69 74 0a 2a 2a 20 69 73 20  te but it.** is 
a8e0: 6f 66 74 65 6e 20 63 6c 6f 73 65 2e 20 20 54 68  often close.  Th
a8f0: 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 56 46 53  e underlying VFS
a900: 20 6d 69 67 68 74 20 63 68 6f 6f 73 65 20 74 6f   might choose to
a910: 20 70 72 65 61 6c 6c 6f 63 61 74 65 20 64 61 74   preallocate dat
a920: 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 73 70  abase.** file sp
a930: 61 63 65 20 62 61 73 65 64 20 6f 6e 20 74 68 69  ace based on thi
a940: 73 20 68 69 6e 74 20 69 6e 20 6f 72 64 65 72 20  s hint in order 
a950: 74 6f 20 68 65 6c 70 20 77 72 69 74 65 73 20 74  to help writes t
a960: 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  o the database.*
a970: 2a 20 66 69 6c 65 20 72 75 6e 20 66 61 73 74 65  * file run faste
a980: 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  r..**.** <li>[[S
a990: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e  QLITE_FCNTL_CHUN
a9a0: 4b 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20  K_SIZE]].** The 
a9b0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48  [SQLITE_FCNTL_CH
a9c0: 55 4e 4b 5f 53 49 5a 45 5d 20 6f 70 63 6f 64 65  UNK_SIZE] opcode
a9d0: 20 69 73 20 75 73 65 64 20 74 6f 20 72 65 71 75   is used to requ
a9e0: 65 73 74 20 74 68 61 74 20 74 68 65 20 56 46 53  est that the VFS
a9f0: 0a 2a 2a 20 65 78 74 65 6e 64 73 20 61 6e 64 20  .** extends and 
aa00: 74 72 75 6e 63 61 74 65 73 20 74 68 65 20 64 61  truncates the da
aa10: 74 61 62 61 73 65 20 66 69 6c 65 20 69 6e 20 63  tabase file in c
aa20: 68 75 6e 6b 73 20 6f 66 20 61 20 73 69 7a 65 20  hunks of a size 
aa30: 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20  specified.** by 
aa40: 74 68 65 20 75 73 65 72 2e 20 54 68 65 20 66 6f  the user. The fo
aa50: 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f  urth argument to
aa60: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
aa70: 6f 6e 74 72 6f 6c 28 29 5d 20 73 68 6f 75 6c 64  ontrol()] should
aa80: 20 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 6e   .** point to an
aa90: 20 69 6e 74 65 67 65 72 20 28 74 79 70 65 20 69   integer (type i
aaa0: 6e 74 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  nt) containing t
aab0: 68 65 20 6e 65 77 20 63 68 75 6e 6b 2d 73 69 7a  he new chunk-siz
aac0: 65 20 74 6f 20 75 73 65 0a 2a 2a 20 66 6f 72 20  e to use.** for 
aad0: 74 68 65 20 6e 6f 6d 69 6e 61 74 65 64 20 64 61  the nominated da
aae0: 74 61 62 61 73 65 2e 20 41 6c 6c 6f 63 61 74 69  tabase. Allocati
aaf0: 6e 67 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  ng database file
ab00: 20 73 70 61 63 65 20 69 6e 20 6c 61 72 67 65 0a   space in large.
ab10: 2a 2a 20 63 68 75 6e 6b 73 20 28 73 61 79 20 31  ** chunks (say 1
ab20: 4d 42 20 61 74 20 61 20 74 69 6d 65 29 2c 20 6d  MB at a time), m
ab30: 61 79 20 72 65 64 75 63 65 20 66 69 6c 65 2d 73  ay reduce file-s
ab40: 79 73 74 65 6d 20 66 72 61 67 6d 65 6e 74 61 74  ystem fragmentat
ab50: 69 6f 6e 20 61 6e 64 0a 2a 2a 20 69 6d 70 72 6f  ion and.** impro
ab60: 76 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6f  ve performance o
ab70: 6e 20 73 6f 6d 65 20 73 79 73 74 65 6d 73 2e 0a  n some systems..
ab80: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
ab90: 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f  TE_FCNTL_FILE_PO
aba0: 49 4e 54 45 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b  INTER]].** The [
abb0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c  SQLITE_FCNTL_FIL
abc0: 45 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64  E_POINTER] opcod
abd0: 65 20 69 73 20 75 73 65 64 20 74 6f 20 6f 62 74  e is used to obt
abe0: 61 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a  ain a pointer.**
abf0: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
ac00: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73  _file] object as
ac10: 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20  sociated with a 
ac20: 70 61 72 74 69 63 75 6c 61 72 20 64 61 74 61 62  particular datab
ac30: 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
ac40: 6e 2e 20 20 53 65 65 20 74 68 65 20 5b 73 71 6c  n.  See the [sql
ac50: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
ac60: 6c 28 29 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69  l()] documentati
ac70: 6f 6e 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69  on for.** additi
ac80: 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
ac90: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
aca0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f  LITE_FCNTL_SYNC_
acb0: 4f 4d 49 54 54 45 44 5d 5d 0a 2a 2a 20 4e 6f 20  OMITTED]].** No 
acc0: 6c 6f 6e 67 65 72 20 69 6e 20 75 73 65 2e 0a 2a  longer in use..*
acd0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
ace0: 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d 5d 0a 2a  E_FCNTL_SYNC]].*
acf0: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
ad00: 4e 54 4c 5f 53 59 4e 43 5d 20 6f 70 63 6f 64 65  NTL_SYNC] opcode
ad10: 20 69 73 20 67 65 6e 65 72 61 74 65 64 20 69 6e   is generated in
ad20: 74 65 72 6e 61 6c 6c 79 20 62 79 20 53 51 4c 69  ternally by SQLi
ad30: 74 65 20 61 6e 64 0a 2a 2a 20 73 65 6e 74 20 74  te and.** sent t
ad40: 6f 20 74 68 65 20 56 46 53 20 69 6d 6d 65 64 69  o the VFS immedi
ad50: 61 74 65 6c 79 20 62 65 66 6f 72 65 20 74 68 65  ately before the
ad60: 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 20 69 73   xSync method is
ad70: 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 61 0a 2a 2a   invoked on a.**
ad80: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 64   database file d
ad90: 65 73 63 72 69 70 74 6f 72 2e 20 4f 72 2c 20 69  escriptor. Or, i
ada0: 66 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68  f the xSync meth
adb0: 6f 64 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65  od is not invoke
adc0: 64 20 0a 2a 2a 20 62 65 63 61 75 73 65 20 74 68  d .** because th
add0: 65 20 75 73 65 72 20 68 61 73 20 63 6f 6e 66 69  e user has confi
ade0: 67 75 72 65 64 20 53 51 4c 69 74 65 20 77 69 74  gured SQLite wit
adf0: 68 20 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 73 79  h .** [PRAGMA sy
ae00: 6e 63 68 72 6f 6e 6f 75 73 20 7c 20 50 52 41 47  nchronous | PRAG
ae10: 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 3d 4f  MA synchronous=O
ae20: 46 46 5d 20 69 74 20 69 73 20 69 6e 76 6f 6b 65  FF] it is invoke
ae30: 64 20 69 6e 20 70 6c 61 63 65 20 0a 2a 2a 20 6f  d in place .** o
ae40: 66 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68  f the xSync meth
ae50: 6f 64 2e 20 49 6e 20 6d 6f 73 74 20 63 61 73 65  od. In most case
ae60: 73 2c 20 74 68 65 20 70 6f 69 6e 74 65 72 20 61  s, the pointer a
ae70: 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 77  rgument passed w
ae80: 69 74 68 0a 2a 2a 20 74 68 69 73 20 66 69 6c 65  ith.** this file
ae90: 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 4e 55 4c 4c  -control is NULL
aea0: 2e 20 48 6f 77 65 76 65 72 2c 20 69 66 20 74 68  . However, if th
aeb0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
aec0: 69 73 20 62 65 69 6e 67 20 73 79 6e 63 65 64 0a  is being synced.
aed0: 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 20 61 20  ** as part of a 
aee0: 6d 75 6c 74 69 2d 64 61 74 61 62 61 73 65 20 63  multi-database c
aef0: 6f 6d 6d 69 74 2c 20 74 68 65 20 61 72 67 75 6d  ommit, the argum
af00: 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 20 61 20  ent points to a 
af10: 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  nul-terminated.*
af20: 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e  * string contain
af30: 69 6e 67 20 74 68 65 20 74 72 61 6e 73 61 63 74  ing the transact
af40: 69 6f 6e 73 20 6d 61 73 74 65 72 2d 6a 6f 75 72  ions master-jour
af50: 6e 61 6c 20 66 69 6c 65 20 6e 61 6d 65 2e 20 56  nal file name. V
af60: 46 53 65 73 20 74 68 61 74 20 0a 2a 2a 20 64 6f  FSes that .** do
af70: 20 6e 6f 74 20 6e 65 65 64 20 74 68 69 73 20 73   not need this s
af80: 69 67 6e 61 6c 20 73 68 6f 75 6c 64 20 73 69 6c  ignal should sil
af90: 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69  ently ignore thi
afa0: 73 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69 63  s opcode. Applic
afb0: 61 74 69 6f 6e 73 20 0a 2a 2a 20 73 68 6f 75 6c  ations .** shoul
afc0: 64 20 6e 6f 74 20 63 61 6c 6c 20 5b 73 71 6c 69  d not call [sqli
afd0: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
afe0: 28 29 5d 20 77 69 74 68 20 74 68 69 73 20 6f 70  ()] with this op
aff0: 63 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f  code as doing so
b000: 20 6d 61 79 20 0a 2a 2a 20 64 69 73 72 75 70 74   may .** disrupt
b010: 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 6f   the operation o
b020: 66 20 74 68 65 20 73 70 65 63 69 61 6c 69 7a 65  f the specialize
b030: 64 20 56 46 53 65 73 20 74 68 61 74 20 64 6f 20  d VFSes that do 
b040: 72 65 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a  require it.  .**
b050: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
b060: 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48  _FCNTL_COMMIT_PH
b070: 41 53 45 54 57 4f 5d 5d 0a 2a 2a 20 54 68 65 20  ASETWO]].** The 
b080: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f  [SQLITE_FCNTL_CO
b090: 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f 5d 20 6f  MMIT_PHASETWO] o
b0a0: 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61 74  pcode is generat
b0b0: 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79  ed internally by
b0c0: 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 73   SQLite.** and s
b0d0: 65 6e 74 20 74 6f 20 74 68 65 20 56 46 53 20 61  ent to the VFS a
b0e0: 66 74 65 72 20 61 20 74 72 61 6e 73 61 63 74 69  fter a transacti
b0f0: 6f 6e 20 68 61 73 20 62 65 65 6e 20 63 6f 6d 6d  on has been comm
b100: 69 74 74 65 64 20 69 6d 6d 65 64 69 61 74 65 6c  itted immediatel
b110: 79 0a 2a 2a 20 62 75 74 20 62 65 66 6f 72 65 20  y.** but before 
b120: 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  the database is 
b130: 75 6e 6c 6f 63 6b 65 64 2e 20 56 46 53 65 73 20  unlocked. VFSes 
b140: 74 68 61 74 20 64 6f 20 6e 6f 74 20 6e 65 65 64  that do not need
b150: 20 74 68 69 73 20 73 69 67 6e 61 6c 0a 2a 2a 20   this signal.** 
b160: 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20  should silently 
b170: 69 67 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 6f  ignore this opco
b180: 64 65 2e 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  de. Applications
b190: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c   should not call
b1a0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
b1b0: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74  e_control()] wit
b1c0: 68 20 74 68 69 73 20 6f 70 63 6f 64 65 20 61 73  h this opcode as
b1d0: 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20 64 69   doing so may di
b1e0: 73 72 75 70 74 20 74 68 65 20 0a 2a 2a 20 6f 70  srupt the .** op
b1f0: 65 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73  eration of the s
b200: 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73  pecialized VFSes
b210: 20 74 68 61 74 20 64 6f 20 72 65 71 75 69 72 65   that do require
b220: 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69   it.  .**.** <li
b230: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
b240: 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d 5d  WIN32_AV_RETRY]]
b250: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
b260: 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f  _FCNTL_WIN32_AV_
b270: 52 45 54 52 59 5d 20 6f 70 63 6f 64 65 20 69 73  RETRY] opcode is
b280: 20 75 73 65 64 20 74 6f 20 63 6f 6e 66 69 67 75   used to configu
b290: 72 65 20 61 75 74 6f 6d 61 74 69 63 0a 2a 2a 20  re automatic.** 
b2a0: 72 65 74 72 79 20 63 6f 75 6e 74 73 20 61 6e 64  retry counts and
b2b0: 20 69 6e 74 65 72 76 61 6c 73 20 66 6f 72 20 63   intervals for c
b2c0: 65 72 74 61 69 6e 20 64 69 73 6b 20 49 2f 4f 20  ertain disk I/O 
b2d0: 6f 70 65 72 61 74 69 6f 6e 73 20 66 6f 72 20 74  operations for t
b2e0: 68 65 0a 2a 2a 20 77 69 6e 64 6f 77 73 20 5b 56  he.** windows [V
b2f0: 46 53 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  FS] in order to 
b300: 70 72 6f 76 69 64 65 20 72 6f 62 75 73 74 6e 65  provide robustne
b310: 73 73 20 69 6e 20 74 68 65 20 70 72 65 73 65 6e  ss in the presen
b320: 63 65 20 6f 66 0a 2a 2a 20 61 6e 74 69 2d 76 69  ce of.** anti-vi
b330: 72 75 73 20 70 72 6f 67 72 61 6d 73 2e 20 20 42  rus programs.  B
b340: 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20 77  y default, the w
b350: 69 6e 64 6f 77 73 20 56 46 53 20 77 69 6c 6c 20  indows VFS will 
b360: 72 65 74 72 79 20 66 69 6c 65 20 72 65 61 64 2c  retry file read,
b370: 0a 2a 2a 20 66 69 6c 65 20 77 72 69 74 65 2c 20  .** file write, 
b380: 61 6e 64 20 66 69 6c 65 20 64 65 6c 65 74 65 20  and file delete 
b390: 6f 70 65 72 61 74 69 6f 6e 73 20 75 70 20 74 6f  operations up to
b3a0: 20 31 30 20 74 69 6d 65 73 2c 20 77 69 74 68 20   10 times, with 
b3b0: 61 20 64 65 6c 61 79 0a 2a 2a 20 6f 66 20 32 35  a delay.** of 25
b3c0: 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 62 65   milliseconds be
b3d0: 66 6f 72 65 20 74 68 65 20 66 69 72 73 74 20 72  fore the first r
b3e0: 65 74 72 79 20 61 6e 64 20 77 69 74 68 20 74 68  etry and with th
b3f0: 65 20 64 65 6c 61 79 20 69 6e 63 72 65 61 73 69  e delay increasi
b400: 6e 67 0a 2a 2a 20 62 79 20 61 6e 20 61 64 64 69  ng.** by an addi
b410: 74 69 6f 6e 61 6c 20 32 35 20 6d 69 6c 6c 69 73  tional 25 millis
b420: 65 63 6f 6e 64 73 20 77 69 74 68 20 65 61 63 68  econds with each
b430: 20 73 75 62 73 65 71 75 65 6e 74 20 72 65 74 72   subsequent retr
b440: 79 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f  y.  This.** opco
b450: 64 65 20 61 6c 6c 6f 77 73 20 74 68 65 73 65 20  de allows these 
b460: 74 77 6f 20 76 61 6c 75 65 73 20 28 31 30 20 72  two values (10 r
b470: 65 74 72 69 65 73 20 61 6e 64 20 32 35 20 6d 69  etries and 25 mi
b480: 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 64 65  lliseconds of de
b490: 6c 61 79 29 0a 2a 2a 20 74 6f 20 62 65 20 61 64  lay).** to be ad
b4a0: 6a 75 73 74 65 64 2e 20 20 54 68 65 20 76 61 6c  justed.  The val
b4b0: 75 65 73 20 61 72 65 20 63 68 61 6e 67 65 64 20  ues are changed 
b4c0: 66 6f 72 20 61 6c 6c 20 64 61 74 61 62 61 73 65  for all database
b4d0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20   connections.** 
b4e0: 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20  within the same 
b4f0: 70 72 6f 63 65 73 73 2e 20 20 54 68 65 20 61 72  process.  The ar
b500: 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e  gument is a poin
b510: 74 65 72 20 74 6f 20 61 6e 20 61 72 72 61 79 20  ter to an array 
b520: 6f 66 20 74 77 6f 0a 2a 2a 20 69 6e 74 65 67 65  of two.** intege
b530: 72 73 20 77 68 65 72 65 20 74 68 65 20 66 69 72  rs where the fir
b540: 73 74 20 69 6e 74 65 67 65 72 20 69 20 74 68 65  st integer i the
b550: 20 6e 65 77 20 72 65 74 72 79 20 63 6f 75 6e 74   new retry count
b560: 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 0a   and the second.
b570: 2a 2a 20 69 6e 74 65 67 65 72 20 69 73 20 74 68  ** integer is th
b580: 65 20 64 65 6c 61 79 2e 20 20 49 66 20 65 69 74  e delay.  If eit
b590: 68 65 72 20 69 6e 74 65 67 65 72 20 69 73 20 6e  her integer is n
b5a0: 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68  egative, then th
b5b0: 65 20 73 65 74 74 69 6e 67 0a 2a 2a 20 69 73 20  e setting.** is 
b5c0: 6e 6f 74 20 63 68 61 6e 67 65 64 20 62 75 74 20  not changed but 
b5d0: 69 6e 73 74 65 61 64 20 74 68 65 20 70 72 69 6f  instead the prio
b5e0: 72 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20  r value of that 
b5f0: 73 65 74 74 69 6e 67 20 69 73 20 77 72 69 74 74  setting is writt
b600: 65 6e 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 61  en.** into the a
b610: 72 72 61 79 20 65 6e 74 72 79 2c 20 61 6c 6c 6f  rray entry, allo
b620: 77 69 6e 67 20 74 68 65 20 63 75 72 72 65 6e 74  wing the current
b630: 20 72 65 74 72 79 20 73 65 74 74 69 6e 67 73 20   retry settings 
b640: 74 6f 20 62 65 0a 2a 2a 20 69 6e 74 65 72 72 6f  to be.** interro
b650: 67 61 74 65 64 2e 20 20 54 68 65 20 7a 44 62 4e  gated.  The zDbN
b660: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69 73  ame parameter is
b670: 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20   ignored..**.** 
b680: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
b690: 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d 5d  TL_PERSIST_WAL]]
b6a0: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
b6b0: 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57  _FCNTL_PERSIST_W
b6c0: 41 4c 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  AL] opcode is us
b6d0: 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65  ed to set or que
b6e0: 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73  ry the.** persis
b6f0: 74 65 6e 74 20 5b 57 41 4c 20 7c 20 57 72 69 74  tent [WAL | Writ
b700: 65 20 41 68 65 61 64 20 4c 6f 67 5d 20 73 65 74  e Ahead Log] set
b710: 74 69 6e 67 2e 20 20 42 79 20 64 65 66 61 75 6c  ting.  By defaul
b720: 74 2c 20 74 68 65 20 61 75 78 69 6c 69 61 72 79  t, the auxiliary
b730: 0a 2a 2a 20 77 72 69 74 65 20 61 68 65 61 64 20  .** write ahead 
b740: 6c 6f 67 20 61 6e 64 20 73 68 61 72 65 64 20 6d  log and shared m
b750: 65 6d 6f 72 79 20 66 69 6c 65 73 20 75 73 65 64  emory files used
b760: 20 66 6f 72 20 74 72 61 6e 73 61 63 74 69 6f 6e   for transaction
b770: 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 61 72 65 20   control.** are 
b780: 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65  automatically de
b790: 6c 65 74 65 64 20 77 68 65 6e 20 74 68 65 20 6c  leted when the l
b7a0: 61 74 65 73 74 20 63 6f 6e 6e 65 63 74 69 6f 6e  atest connection
b7b0: 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65   to the database
b7c0: 0a 2a 2a 20 63 6c 6f 73 65 73 2e 20 20 53 65 74  .** closes.  Set
b7d0: 74 69 6e 67 20 70 65 72 73 69 73 74 65 6e 74 20  ting persistent 
b7e0: 57 41 4c 20 6d 6f 64 65 20 63 61 75 73 65 73 20  WAL mode causes 
b7f0: 74 68 6f 73 65 20 66 69 6c 65 73 20 74 6f 20 70  those files to p
b800: 65 72 73 69 73 74 20 61 66 74 65 72 0a 2a 2a 20  ersist after.** 
b810: 63 6c 6f 73 65 2e 20 20 50 65 72 73 69 73 74 69  close.  Persisti
b820: 6e 67 20 74 68 65 20 66 69 6c 65 73 20 69 73 20  ng the files is 
b830: 75 73 65 66 75 6c 20 77 68 65 6e 20 6f 74 68 65  useful when othe
b840: 72 20 70 72 6f 63 65 73 73 65 73 20 74 68 61 74  r processes that
b850: 20 64 6f 20 6e 6f 74 0a 2a 2a 20 68 61 76 65 20   do not.** have 
b860: 77 72 69 74 65 20 70 65 72 6d 69 73 73 69 6f 6e  write permission
b870: 20 6f 6e 20 74 68 65 20 64 69 72 65 63 74 6f 72   on the director
b880: 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  y containing the
b890: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77   database file w
b8a0: 61 6e 74 0a 2a 2a 20 74 6f 20 72 65 61 64 20 74  ant.** to read t
b8b0: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
b8c0: 2c 20 61 73 20 74 68 65 20 57 41 4c 20 61 6e 64  , as the WAL and
b8d0: 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66   shared memory f
b8e0: 69 6c 65 73 20 6d 75 73 74 20 65 78 69 73 74 0a  iles must exist.
b8f0: 2a 2a 20 69 6e 20 6f 72 64 65 72 20 66 6f 72 20  ** in order for 
b900: 74 68 65 20 64 61 74 61 62 61 73 65 20 74 6f 20  the database to 
b910: 62 65 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68  be readable.  Th
b920: 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
b930: 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  er to.** [sqlite
b940: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
b950: 5d 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64  ] for this opcod
b960: 65 20 73 68 6f 75 6c 64 20 62 65 20 61 20 70 6f  e should be a po
b970: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65  inter to an inte
b980: 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74  ger..** That int
b990: 65 67 65 72 20 69 73 20 30 20 74 6f 20 64 69 73  eger is 0 to dis
b9a0: 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74 20  able persistent 
b9b0: 57 41 4c 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f  WAL mode or 1 to
b9c0: 20 65 6e 61 62 6c 65 20 70 65 72 73 69 73 74 65   enable persiste
b9d0: 6e 74 0a 2a 2a 20 57 41 4c 20 6d 6f 64 65 2e 20  nt.** WAL mode. 
b9e0: 20 49 66 20 74 68 65 20 69 6e 74 65 67 65 72 20   If the integer 
b9f0: 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69  is -1, then it i
ba00: 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69  s overwritten wi
ba10: 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a  th the current.*
ba20: 2a 20 57 41 4c 20 70 65 72 73 69 73 74 65 6e 63  * WAL persistenc
ba30: 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a  e setting..**.**
ba40: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
ba50: 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56  NTL_POWERSAFE_OV
ba60: 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68  ERWRITE]].** ^Th
ba70: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
ba80: 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52  POWERSAFE_OVERWR
ba90: 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  ITE] opcode is u
baa0: 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75  sed to set or qu
bab0: 65 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69  ery the.** persi
bac0: 73 74 65 6e 74 20 22 70 6f 77 65 72 73 61 66 65  stent "powersafe
bad0: 2d 6f 76 65 72 77 72 69 74 65 22 20 6f 72 20 22  -overwrite" or "
bae0: 50 53 4f 57 22 20 73 65 74 74 69 6e 67 2e 20 20  PSOW" setting.  
baf0: 54 68 65 20 50 53 4f 57 20 73 65 74 74 69 6e 67  The PSOW setting
bb00: 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 73 20 74  .** determines t
bb10: 68 65 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  he [SQLITE_IOCAP
bb20: 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57  _POWERSAFE_OVERW
bb30: 52 49 54 45 5d 20 62 69 74 20 6f 66 20 74 68 65  RITE] bit of the
bb40: 0a 2a 2a 20 78 44 65 76 69 63 65 43 68 61 72 61  .** xDeviceChara
bb50: 63 74 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f  cteristics metho
bb60: 64 73 2e 20 54 68 65 20 66 6f 75 72 74 68 20 70  ds. The fourth p
bb70: 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b  arameter to.** [
bb80: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
bb90: 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73  trol()] for this
bba0: 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62   opcode should b
bbb0: 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  e a pointer to a
bbc0: 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68  n integer..** Th
bbd0: 61 74 20 69 6e 74 65 67 65 72 20 69 73 20 30 20  at integer is 0 
bbe0: 74 6f 20 64 69 73 61 62 6c 65 20 7a 65 72 6f 2d  to disable zero-
bbf0: 64 61 6d 61 67 65 20 6d 6f 64 65 20 6f 72 20 31  damage mode or 1
bc00: 20 74 6f 20 65 6e 61 62 6c 65 20 7a 65 72 6f 2d   to enable zero-
bc10: 64 61 6d 61 67 65 0a 2a 2a 20 6d 6f 64 65 2e 20  damage.** mode. 
bc20: 20 49 66 20 74 68 65 20 69 6e 74 65 67 65 72 20   If the integer 
bc30: 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69  is -1, then it i
bc40: 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69  s overwritten wi
bc50: 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a  th the current.*
bc60: 2a 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f  * zero-damage mo
bc70: 64 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a  de setting..**.*
bc80: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
bc90: 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 5d  CNTL_OVERWRITE]]
bca0: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
bcb0: 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45  _FCNTL_OVERWRITE
bcc0: 5d 20 6f 70 63 6f 64 65 20 69 73 20 69 6e 76 6f  ] opcode is invo
bcd0: 6b 65 64 20 62 79 20 53 51 4c 69 74 65 20 61 66  ked by SQLite af
bce0: 74 65 72 20 6f 70 65 6e 69 6e 67 0a 2a 2a 20 61  ter opening.** a
bcf0: 20 77 72 69 74 65 20 74 72 61 6e 73 61 63 74 69   write transacti
bd00: 6f 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74  on to indicate t
bd10: 68 61 74 2c 20 75 6e 6c 65 73 73 20 69 74 20 69  hat, unless it i
bd20: 73 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 66 6f  s rolled back fo
bd30: 72 20 73 6f 6d 65 0a 2a 2a 20 72 65 61 73 6f 6e  r some.** reason
bd40: 2c 20 74 68 65 20 65 6e 74 69 72 65 20 64 61 74  , the entire dat
bd50: 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20  abase file will 
bd60: 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20 62  be overwritten b
bd70: 79 20 74 68 65 20 63 75 72 72 65 6e 74 20 0a 2a  y the current .*
bd80: 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 54  * transaction. T
bd90: 68 69 73 20 69 73 20 75 73 65 64 20 62 79 20 56  his is used by V
bda0: 41 43 55 55 4d 20 6f 70 65 72 61 74 69 6f 6e 73  ACUUM operations
bdb0: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
bdc0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41  LITE_FCNTL_VFSNA
bdd0: 4d 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  ME]].** ^The [SQ
bde0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41  LITE_FCNTL_VFSNA
bdf0: 4d 45 5d 20 6f 70 63 6f 64 65 20 63 61 6e 20 62  ME] opcode can b
be00: 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e  e used to obtain
be10: 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 0a 2a 2a   the names of.**
be20: 20 61 6c 6c 20 5b 56 46 53 65 73 5d 20 69 6e 20   all [VFSes] in 
be30: 74 68 65 20 56 46 53 20 73 74 61 63 6b 2e 20 20  the VFS stack.  
be40: 54 68 65 20 6e 61 6d 65 73 20 61 72 65 20 6f 66  The names are of
be50: 20 61 6c 6c 20 56 46 53 20 73 68 69 6d 73 20 61   all VFS shims a
be60: 6e 64 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20  nd the.** final 
be70: 62 6f 74 74 6f 6d 2d 6c 65 76 65 6c 20 56 46 53  bottom-level VFS
be80: 20 61 72 65 20 77 72 69 74 74 65 6e 20 69 6e 74   are written int
be90: 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  o memory obtaine
bea0: 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69  d from .** [sqli
beb0: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e  te3_malloc()] an
bec0: 64 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  d the result is 
bed0: 73 74 6f 72 65 64 20 69 6e 20 74 68 65 20 63 68  stored in the ch
bee0: 61 72 2a 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20  ar* variable.** 
bef0: 74 68 61 74 20 74 68 65 20 66 6f 75 72 74 68 20  that the fourth 
bf00: 70 61 72 61 6d 65 74 65 72 20 6f 66 20 5b 73 71  parameter of [sq
bf10: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
bf20: 6f 6c 28 29 5d 20 70 6f 69 6e 74 73 20 74 6f 2e  ol()] points to.
bf30: 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 65 72 20 69  .** The caller i
bf40: 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f  s responsible fo
bf50: 72 20 66 72 65 65 69 6e 67 20 74 68 65 20 6d 65  r freeing the me
bf60: 6d 6f 72 79 20 77 68 65 6e 20 64 6f 6e 65 2e 20  mory when done. 
bf70: 20 41 73 20 77 69 74 68 0a 2a 2a 20 61 6c 6c 20   As with.** all 
bf80: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 61 63 74  file-control act
bf90: 69 6f 6e 73 2c 20 74 68 65 72 65 20 69 73 20 6e  ions, there is n
bfa0: 6f 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74  o guarantee that
bfb0: 20 74 68 69 73 20 77 69 6c 6c 20 61 63 74 75 61   this will actua
bfc0: 6c 6c 79 0a 2a 2a 20 64 6f 20 61 6e 79 74 68 69  lly.** do anythi
bfd0: 6e 67 2e 20 20 43 61 6c 6c 65 72 73 20 73 68 6f  ng.  Callers sho
bfe0: 75 6c 64 20 69 6e 69 74 69 61 6c 69 7a 65 20 74  uld initialize t
bff0: 68 65 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c  he char* variabl
c000: 65 20 74 6f 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70  e to a NULL.** p
c010: 6f 69 6e 74 65 72 20 69 6e 20 63 61 73 65 20 74  ointer in case t
c020: 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c  his file-control
c030: 20 69 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e   is not implemen
c040: 74 65 64 2e 20 20 54 68 69 73 20 66 69 6c 65 2d  ted.  This file-
c050: 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 69 73 20 69 6e  control.** is in
c060: 74 65 6e 64 65 64 20 66 6f 72 20 64 69 61 67 6e  tended for diagn
c070: 6f 73 74 69 63 20 75 73 65 20 6f 6e 6c 79 2e 0a  ostic use only..
c080: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
c090: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
c0a0: 5d 0a 2a 2a 20 5e 57 68 65 6e 65 76 65 72 20 61  ].** ^Whenever a
c0b0: 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d   [PRAGMA] statem
c0c0: 65 6e 74 20 69 73 20 70 61 72 73 65 64 2c 20 61  ent is parsed, a
c0d0: 6e 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  n [SQLITE_FCNTL_
c0e0: 50 52 41 47 4d 41 5d 20 0a 2a 2a 20 66 69 6c 65  PRAGMA] .** file
c0f0: 20 63 6f 6e 74 72 6f 6c 20 69 73 20 73 65 6e 74   control is sent
c100: 20 74 6f 20 74 68 65 20 6f 70 65 6e 20 5b 73 71   to the open [sq
c110: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
c120: 63 74 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  ct corresponding
c130: 0a 2a 2a 20 74 6f 20 74 68 65 20 64 61 74 61 62  .** to the datab
c140: 61 73 65 20 66 69 6c 65 20 74 6f 20 77 68 69 63  ase file to whic
c150: 68 20 74 68 65 20 70 72 61 67 6d 61 20 73 74 61  h the pragma sta
c160: 74 65 6d 65 6e 74 20 72 65 66 65 72 73 2e 20 5e  tement refers. ^
c170: 54 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  The argument.** 
c180: 74 6f 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46  to the [SQLITE_F
c190: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c  CNTL_PRAGMA] fil
c1a0: 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 61 6e 20  e control is an 
c1b0: 61 72 72 61 79 20 6f 66 0a 2a 2a 20 70 6f 69 6e  array of.** poin
c1c0: 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20  ters to strings 
c1d0: 28 63 68 61 72 2a 2a 29 20 69 6e 20 77 68 69 63  (char**) in whic
c1e0: 68 20 74 68 65 20 73 65 63 6f 6e 64 20 65 6c 65  h the second ele
c1f0: 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 72 72 61  ment of the arra
c200: 79 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65  y.** is the name
c210: 20 6f 66 20 74 68 65 20 70 72 61 67 6d 61 20 61   of the pragma a
c220: 6e 64 20 74 68 65 20 74 68 69 72 64 20 65 6c 65  nd the third ele
c230: 6d 65 6e 74 20 69 73 20 74 68 65 20 61 72 67 75  ment is the argu
c240: 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 70  ment to the.** p
c250: 72 61 67 6d 61 20 6f 72 20 4e 55 4c 4c 20 69 66  ragma or NULL if
c260: 20 74 68 65 20 70 72 61 67 6d 61 20 68 61 73 20   the pragma has 
c270: 6e 6f 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 54  no argument.  ^T
c280: 68 65 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61  he handler for a
c290: 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e  n.** [SQLITE_FCN
c2a0: 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20  TL_PRAGMA] file 
c2b0: 63 6f 6e 74 72 6f 6c 20 63 61 6e 20 6f 70 74 69  control can opti
c2c0: 6f 6e 61 6c 6c 79 20 6d 61 6b 65 20 74 68 65 20  onally make the 
c2d0: 66 69 72 73 74 20 65 6c 65 6d 65 6e 74 0a 2a 2a  first element.**
c2e0: 20 6f 66 20 74 68 65 20 63 68 61 72 2a 2a 20 61   of the char** a
c2f0: 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 20 74 6f  rgument point to
c300: 20 61 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e   a string obtain
c310: 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
c320: 5f 6d 70 72 69 6e 74 66 28 29 5d 0a 2a 2a 20 6f  _mprintf()].** o
c330: 72 20 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74  r the equivalent
c340: 20 61 6e 64 20 74 68 61 74 20 73 74 72 69 6e 67   and that string
c350: 20 77 69 6c 6c 20 62 65 63 6f 6d 65 20 74 68 65   will become the
c360: 20 72 65 73 75 6c 74 20 6f 66 20 74 68 65 20 70   result of the p
c370: 72 61 67 6d 61 20 6f 72 0a 2a 2a 20 74 68 65 20  ragma or.** the 
c380: 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 69 66  error message if
c390: 20 74 68 65 20 70 72 61 67 6d 61 20 66 61 69 6c   the pragma fail
c3a0: 73 2e 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53  s. ^If the.** [S
c3b0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
c3c0: 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  MA] file control
c3d0: 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
c3e0: 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 65 6e  _NOTFOUND], then
c3f0: 20 6e 6f 72 6d 61 6c 20 0a 2a 2a 20 5b 50 52 41   normal .** [PRA
c400: 47 4d 41 5d 20 70 72 6f 63 65 73 73 69 6e 67 20  GMA] processing 
c410: 63 6f 6e 74 69 6e 75 65 73 2e 20 20 5e 49 66 20  continues.  ^If 
c420: 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  the [SQLITE_FCNT
c430: 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c  L_PRAGMA].** fil
c440: 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e  e control return
c450: 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74  s [SQLITE_OK], t
c460: 68 65 6e 20 74 68 65 20 70 61 72 73 65 72 20 61  hen the parser a
c470: 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a  ssumes that the.
c480: 2a 2a 20 56 46 53 20 68 61 73 20 68 61 6e 64 6c  ** VFS has handl
c490: 65 64 20 74 68 65 20 50 52 41 47 4d 41 20 69 74  ed the PRAGMA it
c4a0: 73 65 6c 66 20 61 6e 64 20 74 68 65 20 70 61 72  self and the par
c4b0: 73 65 72 20 67 65 6e 65 72 61 74 65 73 20 61 20  ser generates a 
c4c0: 6e 6f 2d 6f 70 0a 2a 2a 20 70 72 65 70 61 72 65  no-op.** prepare
c4d0: 64 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 49  d statement.  ^I
c4e0: 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  f the [SQLITE_FC
c4f0: 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65  NTL_PRAGMA] file
c500: 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73   control returns
c510: 0a 2a 2a 20 61 6e 79 20 72 65 73 75 6c 74 20 63  .** any result c
c520: 6f 64 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  ode other than [
c530: 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 5b 53  SQLITE_OK] or [S
c540: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c  QLITE_NOTFOUND],
c550: 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74   that means.** t
c560: 68 61 74 20 74 68 65 20 56 46 53 20 65 6e 63 6f  hat the VFS enco
c570: 75 6e 74 65 72 65 64 20 61 6e 20 65 72 72 6f 72  untered an error
c580: 20 77 68 69 6c 65 20 68 61 6e 64 6c 69 6e 67 20   while handling 
c590: 74 68 65 20 5b 50 52 41 47 4d 41 5d 20 61 6e 64  the [PRAGMA] and
c5a0: 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 61 74   the.** compilat
c5b0: 69 6f 6e 20 6f 66 20 74 68 65 20 50 52 41 47 4d  ion of the PRAGM
c5c0: 41 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e 20  A fails with an 
c5d0: 65 72 72 6f 72 2e 20 20 5e 54 68 65 20 5b 53 51  error.  ^The [SQ
c5e0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
c5f0: 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72  A].** file contr
c600: 6f 6c 20 6f 63 63 75 72 73 20 61 74 20 74 68 65  ol occurs at the
c610: 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 70 72   beginning of pr
c620: 61 67 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 61  agma statement a
c630: 6e 61 6c 79 73 69 73 20 61 6e 64 20 73 6f 0a 2a  nalysis and so.*
c640: 2a 20 69 74 20 69 73 20 61 62 6c 65 20 74 6f 20  * it is able to 
c650: 6f 76 65 72 72 69 64 65 20 62 75 69 6c 74 2d 69  override built-i
c660: 6e 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 65  n [PRAGMA] state
c670: 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  ments..**.** <li
c680: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
c690: 42 55 53 59 48 41 4e 44 4c 45 52 5d 5d 0a 2a 2a  BUSYHANDLER]].**
c6a0: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43   ^The [SQLITE_FC
c6b0: 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d  NTL_BUSYHANDLER]
c6c0: 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c  .** file-control
c6d0: 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20   may be invoked 
c6e0: 62 79 20 53 51 4c 69 74 65 20 6f 6e 20 74 68 65  by SQLite on the
c6f0: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 68   database file h
c700: 61 6e 64 6c 65 0a 2a 2a 20 73 68 6f 72 74 6c 79  andle.** shortly
c710: 20 61 66 74 65 72 20 69 74 20 69 73 20 6f 70 65   after it is ope
c720: 6e 65 64 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ned in order to 
c730: 70 72 6f 76 69 64 65 20 61 20 63 75 73 74 6f 6d  provide a custom
c740: 20 56 46 53 20 77 69 74 68 20 61 63 63 65 73 73   VFS with access
c750: 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6e 6e 65  .** to the conne
c760: 63 74 69 6f 6e 73 20 62 75 73 79 2d 68 61 6e 64  ctions busy-hand
c770: 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 54 68  ler callback. Th
c780: 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 66  e argument is of
c790: 20 74 79 70 65 20 28 76 6f 69 64 20 2a 2a 29 0a   type (void **).
c7a0: 2a 2a 20 2d 20 61 6e 20 61 72 72 61 79 20 6f 66  ** - an array of
c7b0: 20 74 77 6f 20 28 76 6f 69 64 20 2a 29 20 76 61   two (void *) va
c7c0: 6c 75 65 73 2e 20 54 68 65 20 66 69 72 73 74 20  lues. The first 
c7d0: 28 76 6f 69 64 20 2a 29 20 61 63 74 75 61 6c 6c  (void *) actuall
c7e0: 79 20 70 6f 69 6e 74 73 0a 2a 2a 20 74 6f 20 61  y points.** to a
c7f0: 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70   function of typ
c800: 65 20 28 69 6e 74 20 28 2a 29 28 76 6f 69 64 20  e (int (*)(void 
c810: 2a 29 29 2e 20 49 6e 20 6f 72 64 65 72 20 74 6f  *)). In order to
c820: 20 69 6e 76 6f 6b 65 20 74 68 65 20 63 6f 6e 6e   invoke the conn
c830: 65 63 74 69 6f 6e 73 0a 2a 2a 20 62 75 73 79 2d  ections.** busy-
c840: 68 61 6e 64 6c 65 72 2c 20 74 68 69 73 20 66 75  handler, this fu
c850: 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65  nction should be
c860: 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 68   invoked with th
c870: 65 20 73 65 63 6f 6e 64 20 28 76 6f 69 64 20 2a  e second (void *
c880: 29 20 69 6e 0a 2a 2a 20 74 68 65 20 61 72 72 61  ) in.** the arra
c890: 79 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 61 72  y as the only ar
c8a0: 67 75 6d 65 6e 74 2e 20 49 66 20 69 74 20 72 65  gument. If it re
c8b0: 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  turns non-zero, 
c8c0: 74 68 65 6e 20 74 68 65 20 6f 70 65 72 61 74 69  then the operati
c8d0: 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20  on.** should be 
c8e0: 72 65 74 72 69 65 64 2e 20 49 66 20 69 74 20 72  retried. If it r
c8f0: 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65  eturns zero, the
c900: 20 63 75 73 74 6f 6d 20 56 46 53 20 73 68 6f 75   custom VFS shou
c910: 6c 64 20 61 62 61 6e 64 6f 6e 20 74 68 65 0a 2a  ld abandon the.*
c920: 2a 20 63 75 72 72 65 6e 74 20 6f 70 65 72 61 74  * current operat
c930: 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ion..**.** <li>[
c940: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45  [SQLITE_FCNTL_TE
c950: 4d 50 46 49 4c 45 4e 41 4d 45 5d 5d 0a 2a 2a 20  MPFILENAME]].** 
c960: 5e 41 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e  ^Application can
c970: 20 69 6e 76 6f 6b 65 20 74 68 65 20 5b 53 51 4c   invoke the [SQL
c980: 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49  ITE_FCNTL_TEMPFI
c990: 4c 45 4e 41 4d 45 5d 20 66 69 6c 65 2d 63 6f 6e  LENAME] file-con
c9a0: 74 72 6f 6c 0a 2a 2a 20 74 6f 20 68 61 76 65 20  trol.** to have 
c9b0: 53 51 4c 69 74 65 20 67 65 6e 65 72 61 74 65 20  SQLite generate 
c9c0: 61 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66  a.** temporary f
c9d0: 69 6c 65 6e 61 6d 65 20 75 73 69 6e 67 20 74 68  ilename using th
c9e0: 65 20 73 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d  e same algorithm
c9f0: 20 74 68 61 74 20 69 73 20 66 6f 6c 6c 6f 77 65   that is followe
ca00: 64 20 74 6f 20 67 65 6e 65 72 61 74 65 0a 2a 2a  d to generate.**
ca10: 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e   temporary filen
ca20: 61 6d 65 73 20 66 6f 72 20 54 45 4d 50 20 74 61  ames for TEMP ta
ca30: 62 6c 65 73 20 61 6e 64 20 6f 74 68 65 72 20 69  bles and other i
ca40: 6e 74 65 72 6e 61 6c 20 75 73 65 73 2e 20 20 54  nternal uses.  T
ca50: 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73  he.** argument s
ca60: 68 6f 75 6c 64 20 62 65 20 61 20 63 68 61 72 2a  hould be a char*
ca70: 2a 20 77 68 69 63 68 20 77 69 6c 6c 20 62 65 20  * which will be 
ca80: 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20  filled with the 
ca90: 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 77 72 69 74  filename.** writ
caa0: 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20  ten into memory 
cab0: 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
cac0: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
cad0: 2e 20 20 54 68 65 20 63 61 6c 6c 65 72 20 73 68  .  The caller sh
cae0: 6f 75 6c 64 0a 2a 2a 20 69 6e 76 6f 6b 65 20 5b  ould.** invoke [
caf0: 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
cb00: 6f 6e 20 74 68 65 20 72 65 73 75 6c 74 20 74 6f  on the result to
cb10: 20 61 76 6f 69 64 20 61 20 6d 65 6d 6f 72 79 20   avoid a memory 
cb20: 6c 65 61 6b 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  leak..**.** <li>
cb30: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d  [[SQLITE_FCNTL_M
cb40: 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68  MAP_SIZE]].** Th
cb50: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
cb60: 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c 65 20  MMAP_SIZE] file 
cb70: 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 20  control is used 
cb80: 74 6f 20 71 75 65 72 79 20 6f 72 20 73 65 74 20  to query or set 
cb90: 74 68 65 0a 2a 2a 20 6d 61 78 69 6d 75 6d 20 6e  the.** maximum n
cba0: 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 74  umber of bytes t
cbb0: 68 61 74 20 77 69 6c 6c 20 62 65 20 75 73 65 64  hat will be used
cbc0: 20 66 6f 72 20 6d 65 6d 6f 72 79 2d 6d 61 70 70   for memory-mapp
cbd0: 65 64 20 49 2f 4f 2e 0a 2a 2a 20 54 68 65 20 61  ed I/O..** The a
cbe0: 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
cbf0: 6e 74 65 72 20 74 6f 20 61 20 76 61 6c 75 65 20  nter to a value 
cc00: 6f 66 20 74 79 70 65 20 73 71 6c 69 74 65 33 5f  of type sqlite3_
cc10: 69 6e 74 36 34 20 74 68 61 74 0a 2a 2a 20 69 73  int64 that.** is
cc20: 20 61 6e 20 61 64 76 69 73 6f 72 79 20 6d 61 78   an advisory max
cc30: 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62  imum number of b
cc40: 79 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65  ytes in the file
cc50: 20 74 6f 20 6d 65 6d 6f 72 79 20 6d 61 70 2e 20   to memory map. 
cc60: 20 54 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20   The.** pointer 
cc70: 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77  is overwritten w
cc80: 69 74 68 20 74 68 65 20 6f 6c 64 20 76 61 6c 75  ith the old valu
cc90: 65 2e 20 20 54 68 65 20 6c 69 6d 69 74 20 69 73  e.  The limit is
cca0: 20 6e 6f 74 20 63 68 61 6e 67 65 64 20 69 66 0a   not changed if.
ccb0: 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f 72 69  ** the value ori
ccc0: 67 69 6e 61 6c 6c 79 20 70 6f 69 6e 74 65 64 20  ginally pointed 
ccd0: 74 6f 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  to is negative, 
cce0: 61 6e 64 20 73 6f 20 74 68 65 20 63 75 72 72 65  and so the curre
ccf0: 6e 74 20 6c 69 6d 69 74 20 0a 2a 2a 20 63 61 6e  nt limit .** can
cd00: 20 62 65 20 71 75 65 72 69 65 64 20 62 79 20 70   be queried by p
cd10: 61 73 73 69 6e 67 20 69 6e 20 61 20 70 6f 69 6e  assing in a poin
cd20: 74 65 72 20 74 6f 20 61 20 6e 65 67 61 74 69 76  ter to a negativ
cd30: 65 20 6e 75 6d 62 65 72 2e 20 20 54 68 69 73 0a  e number.  This.
cd40: 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20  ** file-control 
cd50: 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c  is used internal
cd60: 6c 79 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  ly to implement 
cd70: 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a  [PRAGMA mmap_siz
cd80: 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  e]..**.** <li>[[
cd90: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41  SQLITE_FCNTL_TRA
cda0: 43 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  CE]].** The [SQL
cdb0: 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d  ITE_FCNTL_TRACE]
cdc0: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 70 72   file control pr
cdd0: 6f 76 69 64 65 73 20 61 64 76 69 73 6f 72 79 20  ovides advisory 
cde0: 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 74  information.** t
cdf0: 6f 20 74 68 65 20 56 46 53 20 61 62 6f 75 74 20  o the VFS about 
ce00: 77 68 61 74 20 74 68 65 20 68 69 67 68 65 72 20  what the higher 
ce10: 6c 61 79 65 72 73 20 6f 66 20 74 68 65 20 53 51  layers of the SQ
ce20: 4c 69 74 65 20 73 74 61 63 6b 20 61 72 65 20 64  Lite stack are d
ce30: 6f 69 6e 67 2e 0a 2a 2a 20 54 68 69 73 20 66 69  oing..** This fi
ce40: 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73  le control is us
ce50: 65 64 20 62 79 20 73 6f 6d 65 20 56 46 53 20 61  ed by some VFS a
ce60: 63 74 69 76 69 74 79 20 74 72 61 63 69 6e 67 20  ctivity tracing 
ce70: 5b 73 68 69 6d 73 5d 2e 0a 2a 2a 20 54 68 65 20  [shims]..** The 
ce80: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 7a 65  argument is a ze
ce90: 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74  ro-terminated st
cea0: 72 69 6e 67 2e 20 20 48 69 67 68 65 72 20 6c 61  ring.  Higher la
ceb0: 79 65 72 73 20 69 6e 20 74 68 65 0a 2a 2a 20 53  yers in the.** S
cec0: 51 4c 69 74 65 20 73 74 61 63 6b 20 6d 61 79 20  QLite stack may 
ced0: 67 65 6e 65 72 61 74 65 20 69 6e 73 74 61 6e 63  generate instanc
cee0: 65 73 20 6f 66 20 74 68 69 73 20 66 69 6c 65 20  es of this file 
cef0: 63 6f 6e 74 72 6f 6c 20 69 66 0a 2a 2a 20 74 68  control if.** th
cf00: 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 46 43  e [SQLITE_USE_FC
cf10: 4e 54 4c 5f 54 52 41 43 45 5d 20 63 6f 6d 70 69  NTL_TRACE] compi
cf20: 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69  le-time option i
cf30: 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a  s enabled..**.**
cf40: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
cf50: 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d 5d 0a  NTL_HAS_MOVED]].
cf60: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
cf70: 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d 20  CNTL_HAS_MOVED] 
cf80: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 6e 74  file control int
cf90: 65 72 70 72 65 74 73 20 69 74 73 20 61 72 67 75  erprets its argu
cfa0: 6d 65 6e 74 20 61 73 20 61 0a 2a 2a 20 70 6f 69  ment as a.** poi
cfb0: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67  nter to an integ
cfc0: 65 72 20 61 6e 64 20 69 74 20 77 72 69 74 65 73  er and it writes
cfd0: 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e 74 6f 20   a boolean into 
cfe0: 74 68 61 74 20 69 6e 74 65 67 65 72 20 64 65 70  that integer dep
cff0: 65 6e 64 69 6e 67 0a 2a 2a 20 6f 6e 20 77 68 65  ending.** on whe
d000: 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20  ther or not the 
d010: 66 69 6c 65 20 68 61 73 20 62 65 65 6e 20 72 65  file has been re
d020: 6e 61 6d 65 64 2c 20 6d 6f 76 65 64 2c 20 6f 72  named, moved, or
d030: 20 64 65 6c 65 74 65 64 20 73 69 6e 63 65 20 69   deleted since i
d040: 74 0a 2a 2a 20 77 61 73 20 66 69 72 73 74 20 6f  t.** was first o
d050: 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  pened..**.** <li
d060: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
d070: 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45  WIN32_SET_HANDLE
d080: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
d090: 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45  E_FCNTL_WIN32_SE
d0a0: 54 5f 48 41 4e 44 4c 45 5d 20 6f 70 63 6f 64 65  T_HANDLE] opcode
d0b0: 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65 62   is used for deb
d0c0: 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a  ugging.  This.**
d0d0: 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20 74   opcode causes t
d0e0: 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  he xFileControl 
d0f0: 6d 65 74 68 6f 64 20 74 6f 20 73 77 61 70 20 74  method to swap t
d100: 68 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 20 77  he file handle w
d110: 69 74 68 20 74 68 65 20 6f 6e 65 0a 2a 2a 20 70  ith the one.** p
d120: 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65  ointed to by the
d130: 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74 2e 20   pArg argument. 
d140: 20 54 68 69 73 20 63 61 70 61 62 69 6c 69 74 79   This capability
d150: 20 69 73 20 75 73 65 64 20 64 75 72 69 6e 67 20   is used during 
d160: 74 65 73 74 69 6e 67 0a 2a 2a 20 61 6e 64 20 6f  testing.** and o
d170: 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 62 65 20  nly needs to be 
d180: 73 75 70 70 6f 72 74 65 64 20 77 68 65 6e 20 53  supported when S
d190: 51 4c 49 54 45 5f 54 45 53 54 20 69 73 20 64 65  QLITE_TEST is de
d1a0: 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 2f 75  fined..**.** </u
d1b0: 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  l>.*/.#define SQ
d1c0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53  LITE_FCNTL_LOCKS
d1d0: 54 41 54 45 20 20 20 20 20 20 20 20 20 20 20 20  TATE            
d1e0: 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c     1.#define SQL
d1f0: 49 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58  ITE_GET_LOCKPROX
d200: 59 46 49 4c 45 20 20 20 20 20 20 20 20 20 20 20  YFILE           
d210: 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
d220: 54 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59  TE_SET_LOCKPROXY
d230: 46 49 4c 45 20 20 20 20 20 20 20 20 20 20 20 20  FILE            
d240: 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   3.#define SQLIT
d250: 45 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20  E_LAST_ERRNO    
d260: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
d270: 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
d280: 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54  _FCNTL_SIZE_HINT
d290: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 35                 5
d2a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
d2b0: 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45  FCNTL_CHUNK_SIZE
d2c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 36 0a                6.
d2d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
d2e0: 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45  CNTL_FILE_POINTE
d2f0: 52 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23  R            7.#
d300: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
d310: 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44  NTL_SYNC_OMITTED
d320: 20 20 20 20 20 20 20 20 20 20 20 20 38 0a 23 64              8.#d
d330: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
d340: 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52  TL_WIN32_AV_RETR
d350: 59 20 20 20 20 20 20 20 20 20 20 39 0a 23 64 65  Y          9.#de
d360: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
d370: 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 20 20 20  L_PERSIST_WAL   
d380: 20 20 20 20 20 20 20 20 20 31 30 0a 23 64 65 66           10.#def
d390: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
d3a0: 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 20 20  _OVERWRITE      
d3b0: 20 20 20 20 20 20 20 20 31 31 0a 23 64 65 66 69          11.#defi
d3c0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
d3d0: 56 46 53 4e 41 4d 45 20 20 20 20 20 20 20 20 20  VFSNAME         
d3e0: 20 20 20 20 20 20 20 31 32 0a 23 64 65 66 69 6e         12.#defin
d3f0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50  e SQLITE_FCNTL_P
d400: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49  OWERSAFE_OVERWRI
d410: 54 45 20 20 20 20 31 33 0a 23 64 65 66 69 6e 65  TE    13.#define
d420: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52   SQLITE_FCNTL_PR
d430: 41 47 4d 41 20 20 20 20 20 20 20 20 20 20 20 20  AGMA            
d440: 20 20 20 20 20 31 34 0a 23 64 65 66 69 6e 65 20       14.#define 
d450: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53  SQLITE_FCNTL_BUS
d460: 59 48 41 4e 44 4c 45 52 20 20 20 20 20 20 20 20  YHANDLER        
d470: 20 20 20 20 31 35 0a 23 64 65 66 69 6e 65 20 53      15.#define S
d480: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50  QLITE_FCNTL_TEMP
d490: 46 49 4c 45 4e 41 4d 45 20 20 20 20 20 20 20 20  FILENAME        
d4a0: 20 20 20 31 36 0a 23 64 65 66 69 6e 65 20 53 51     16.#define SQ
d4b0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f  LITE_FCNTL_MMAP_
d4c0: 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 20 20  SIZE            
d4d0: 20 20 31 38 0a 23 64 65 66 69 6e 65 20 53 51 4c    18.#define SQL
d4e0: 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 20  ITE_FCNTL_TRACE 
d4f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
d500: 20 31 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   19.#define SQLI
d510: 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56  TE_FCNTL_HAS_MOV
d520: 45 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ED              
d530: 32 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  20.#define SQLIT
d540: 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 20 20 20 20  E_FCNTL_SYNC    
d550: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
d560: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
d570: 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48  _FCNTL_COMMIT_PH
d580: 41 53 45 54 57 4f 20 20 20 20 20 20 20 20 32 32  ASETWO        22
d590: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
d5a0: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f  FCNTL_WIN32_SET_
d5b0: 48 41 4e 44 4c 45 20 20 20 20 20 20 20 32 33 0a  HANDLE       23.
d5c0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
d5d0: 20 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a 2a 2a   Mutex Handle.**
d5e0: 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 6d 6f  .** The mutex mo
d5f0: 64 75 6c 65 20 77 69 74 68 69 6e 20 53 51 4c 69  dule within SQLi
d600: 74 65 20 64 65 66 69 6e 65 73 20 5b 73 71 6c 69  te defines [sqli
d610: 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65  te3_mutex] to be
d620: 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74 20   an.** abstract 
d630: 74 79 70 65 20 66 6f 72 20 61 20 6d 75 74 65 78  type for a mutex
d640: 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 53 51   object.  The SQ
d650: 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 65 72 20  Lite core never 
d660: 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20  looks.** at the 
d670: 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65  internal represe
d680: 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73  ntation of an [s
d690: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20  qlite3_mutex].  
d6a0: 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73  It only.** deals
d6b0: 20 77 69 74 68 20 70 6f 69 6e 74 65 72 73 20 74   with pointers t
d6c0: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  o the [sqlite3_m
d6d0: 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  utex] object..**
d6e0: 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61 72 65 20  .** Mutexes are 
d6f0: 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73  created using [s
d700: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c  qlite3_mutex_all
d710: 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65  oc()]..*/.typede
d720: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
d730: 5f 6d 75 74 65 78 20 73 71 6c 69 74 65 33 5f 6d  _mutex sqlite3_m
d740: 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  utex;../*.** CAP
d750: 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66  I3REF: OS Interf
d760: 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a  ace Object.**.**
d770: 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   An instance of 
d780: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20  the sqlite3_vfs 
d790: 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74  object defines t
d7a0: 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 74  he interface bet
d7b0: 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 69  ween.** the SQLi
d7c0: 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65 20  te core and the 
d7d0: 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61  underlying opera
d7e0: 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 68  ting system.  Th
d7f0: 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68  e "vfs".** in th
d800: 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f 62  e name of the ob
d810: 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72 20  ject stands for 
d820: 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79  "virtual file sy
d830: 73 74 65 6d 22 2e 20 20 53 65 65 0a 2a 2a 20 74  stem".  See.** t
d840: 68 65 20 5b 56 46 53 20 7c 20 56 46 53 20 64 6f  he [VFS | VFS do
d850: 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72  cumentation] for
d860: 20 66 75 72 74 68 65 72 20 69 6e 66 6f 72 6d 61   further informa
d870: 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  tion..**.** The 
d880: 76 61 6c 75 65 20 6f 66 20 74 68 65 20 69 56 65  value of the iVe
d890: 72 73 69 6f 6e 20 66 69 65 6c 64 20 69 73 20 69  rsion field is i
d8a0: 6e 69 74 69 61 6c 6c 79 20 31 20 62 75 74 20 6d  nitially 1 but m
d8b0: 61 79 20 62 65 20 6c 61 72 67 65 72 20 69 6e 0a  ay be larger in.
d8c0: 2a 2a 20 66 75 74 75 72 65 20 76 65 72 73 69 6f  ** future versio
d8d0: 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41  ns of SQLite.  A
d8e0: 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73  dditional fields
d8f0: 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64   may be appended
d900: 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65   to this.** obje
d910: 63 74 20 77 68 65 6e 20 74 68 65 20 69 56 65 72  ct when the iVer
d920: 73 69 6f 6e 20 76 61 6c 75 65 20 69 73 20 69 6e  sion value is in
d930: 63 72 65 61 73 65 64 2e 20 20 4e 6f 74 65 20 74  creased.  Note t
d940: 68 61 74 20 74 68 65 20 73 74 72 75 63 74 75 72  hat the structur
d950: 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69  e.** of the sqli
d960: 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 63  te3_vfs object c
d970: 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 74 72  hanges in the tr
d980: 61 6e 73 61 63 74 69 6f 6e 20 62 65 74 77 65 65  ansaction betwee
d990: 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73  n.** SQLite vers
d9a0: 69 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e  ion 3.5.9 and 3.
d9b0: 36 2e 30 20 61 6e 64 20 79 65 74 20 74 68 65 20  6.0 and yet the 
d9c0: 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 77  iVersion field w
d9d0: 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69  as not.** modifi
d9e0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a  ed..**.** The sz
d9f0: 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 69 73 20  OsFile field is 
da00: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
da10: 73 75 62 63 6c 61 73 73 65 64 20 5b 73 71 6c 69  subclassed [sqli
da20: 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72  te3_file].** str
da30: 75 63 74 75 72 65 20 75 73 65 64 20 62 79 20 74  ucture used by t
da40: 68 69 73 20 56 46 53 2e 20 20 6d 78 50 61 74 68  his VFS.  mxPath
da50: 6e 61 6d 65 20 69 73 20 74 68 65 20 6d 61 78 69  name is the maxi
da60: 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a  mum length of.**
da70: 20 61 20 70 61 74 68 6e 61 6d 65 20 69 6e 20 74   a pathname in t
da80: 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52  his VFS..**.** R
da90: 65 67 69 73 74 65 72 65 64 20 73 71 6c 69 74 65  egistered sqlite
daa0: 33 5f 76 66 73 20 6f 62 6a 65 63 74 73 20 61 72  3_vfs objects ar
dab0: 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b  e kept on a link
dac0: 65 64 20 6c 69 73 74 20 66 6f 72 6d 65 64 20 62  ed list formed b
dad0: 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74 20 70  y.** the pNext p
dae0: 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 5b 73 71  ointer.  The [sq
daf0: 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74  lite3_vfs_regist
db00: 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71  er()].** and [sq
db10: 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69  lite3_vfs_unregi
db20: 73 74 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63  ster()] interfac
db30: 65 73 20 6d 61 6e 61 67 65 20 74 68 69 73 20 6c  es manage this l
db40: 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65  ist.** in a thre
db50: 61 64 2d 73 61 66 65 20 77 61 79 2e 20 20 54 68  ad-safe way.  Th
db60: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 66  e [sqlite3_vfs_f
db70: 69 6e 64 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ind()] interface
db80: 0a 2a 2a 20 73 65 61 72 63 68 65 73 20 74 68 65  .** searches the
db90: 20 6c 69 73 74 2e 20 20 4e 65 69 74 68 65 72 20   list.  Neither 
dba0: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
dbb0: 63 6f 64 65 20 6e 6f 72 20 74 68 65 20 56 46 53  code nor the VFS
dbc0: 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
dbd0: 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 74 68  on should use th
dbe0: 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e  e pNext pointer.
dbf0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74  .**.** The pNext
dc00: 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 6f 6e   field is the on
dc10: 6c 79 20 66 69 65 6c 64 20 69 6e 20 74 68 65 20  ly field in the 
dc20: 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73  sqlite3_vfs.** s
dc30: 74 72 75 63 74 75 72 65 20 74 68 61 74 20 53 51  tructure that SQ
dc40: 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 72 20 6d  Lite will ever m
dc50: 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 65 20 77  odify.  SQLite w
dc60: 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a  ill only access.
dc70: 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69  ** or modify thi
dc80: 73 20 66 69 65 6c 64 20 77 68 69 6c 65 20 68 6f  s field while ho
dc90: 6c 64 69 6e 67 20 61 20 70 61 72 74 69 63 75 6c  lding a particul
dca0: 61 72 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e  ar static mutex.
dcb0: 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
dcc0: 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72  ion should never
dcd0: 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 6e 67   modify anything
dce0: 20 77 69 74 68 69 6e 20 74 68 65 20 73 71 6c 69   within the sqli
dcf0: 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63  te3_vfs.** objec
dd00: 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65 63  t once the objec
dd10: 74 20 68 61 73 20 62 65 65 6e 20 72 65 67 69 73  t has been regis
dd20: 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tered..**.** The
dd30: 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c   zName field hol
dd40: 64 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  ds the name of t
dd50: 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20  he VFS module.  
dd60: 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a  The name must.**
dd70: 20 62 65 20 75 6e 69 71 75 65 20 61 63 72 6f 73   be unique acros
dd80: 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65  s all VFS module
dd90: 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74  s..**.** [[sqlit
dda0: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d 0a 2a  e3_vfs.xOpen]].*
ddb0: 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e  * ^SQLite guaran
ddc0: 74 65 65 73 20 74 68 61 74 20 74 68 65 20 7a 46  tees that the zF
ddd0: 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65  ilename paramete
dde0: 72 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69 73  r to xOpen.** is
ddf0: 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70   either a NULL p
de00: 6f 69 6e 74 65 72 20 6f 72 20 73 74 72 69 6e 67  ointer or string
de10: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
de20: 6d 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28  m xFullPathname(
de30: 29 20 77 69 74 68 20 61 6e 20 6f 70 74 69 6f 6e  ) with an option
de40: 61 6c 20 73 75 66 66 69 78 20 61 64 64 65 64 2e  al suffix added.
de50: 0a 2a 2a 20 5e 49 66 20 61 20 73 75 66 66 69 78  .** ^If a suffix
de60: 20 69 73 20 61 64 64 65 64 20 74 6f 20 74 68 65   is added to the
de70: 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d   zFilename param
de80: 65 74 65 72 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a  eter, it will.**
de90: 20 63 6f 6e 73 69 73 74 20 6f 66 20 61 20 73 69   consist of a si
dea0: 6e 67 6c 65 20 22 2d 22 20 63 68 61 72 61 63 74  ngle "-" charact
deb0: 65 72 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 6e  er followed by n
dec0: 6f 20 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a 20 31  o more than.** 1
ded0: 31 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 61  1 alphanumeric a
dee0: 6e 64 2f 6f 72 20 22 2d 22 20 63 68 61 72 61 63  nd/or "-" charac
def0: 74 65 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  ters..** ^SQLite
df00: 20 66 75 72 74 68 65 72 20 67 75 61 72 61 6e 74   further guarant
df10: 65 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ees that.** the 
df20: 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 76  string will be v
df30: 61 6c 69 64 20 61 6e 64 20 75 6e 63 68 61 6e 67  alid and unchang
df40: 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28  ed until xClose(
df50: 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20  ) is.** called. 
df60: 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 70  Because of the p
df70: 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65  revious sentence
df80: 2c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65  ,.** the [sqlite
df90: 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61 66 65  3_file] can safe
dfa0: 6c 79 20 73 74 6f 72 65 20 61 20 70 6f 69 6e 74  ly store a point
dfb0: 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c  er to the.** fil
dfc0: 65 6e 61 6d 65 20 69 66 20 69 74 20 6e 65 65 64  ename if it need
dfd0: 73 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 68  s to remember th
dfe0: 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73  e filename for s
dff0: 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49  ome reason..** I
e000: 66 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20  f the zFilename 
e010: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70  parameter to xOp
e020: 65 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  en is a NULL poi
e030: 6e 74 65 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a  nter then xOpen.
e040: 2a 2a 20 6d 75 73 74 20 69 6e 76 65 6e 74 20 69  ** must invent i
e050: 74 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79  ts own temporary
e060: 20 6e 61 6d 65 20 66 6f 72 20 74 68 65 20 66 69   name for the fi
e070: 6c 65 2e 20 20 5e 57 68 65 6e 65 76 65 72 20 74  le.  ^Whenever t
e080: 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65  he .** xFilename
e090: 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55   parameter is NU
e0a0: 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20  LL it will also 
e0b0: 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74  be the case that
e0c0: 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61   the.** flags pa
e0d0: 72 61 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e 63  rameter will inc
e0e0: 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  lude [SQLITE_OPE
e0f0: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d  N_DELETEONCLOSE]
e100: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67  ..**.** The flag
e110: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f  s argument to xO
e120: 70 65 6e 28 29 20 69 6e 63 6c 75 64 65 73 20 61  pen() includes a
e130: 6c 6c 20 62 69 74 73 20 73 65 74 20 69 6e 0a 2a  ll bits set in.*
e140: 2a 20 74 68 65 20 66 6c 61 67 73 20 61 72 67 75  * the flags argu
e150: 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  ment to [sqlite3
e160: 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72  _open_v2()].  Or
e170: 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   if [sqlite3_ope
e180: 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  n()].** or [sqli
e190: 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73  te3_open16()] is
e1a0: 20 75 73 65 64 2c 20 74 68 65 6e 20 66 6c 61 67   used, then flag
e1b0: 73 20 69 6e 63 6c 75 64 65 73 20 61 74 20 6c 65  s includes at le
e1c0: 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  ast.** [SQLITE_O
e1d0: 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c  PEN_READWRITE] |
e1e0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52   [SQLITE_OPEN_CR
e1f0: 45 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f  EATE]. .** If xO
e200: 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 66 69  pen() opens a fi
e210: 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65  le read-only the
e220: 6e 20 69 74 20 73 65 74 73 20 2a 70 4f 75 74 46  n it sets *pOutF
e230: 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75  lags to.** inclu
e240: 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  de [SQLITE_OPEN_
e250: 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65  READONLY].  Othe
e260: 72 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 74 46  r bits in *pOutF
e270: 6c 61 67 73 20 6d 61 79 20 62 65 20 73 65 74 2e  lags may be set.
e280: 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 20  .**.** ^(SQLite 
e290: 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f 6e  will also add on
e2a0: 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69  e of the followi
e2b0: 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20  ng flags to the 
e2c0: 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c  xOpen().** call,
e2d0: 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68   depending on th
e2e0: 65 20 6f 62 6a 65 63 74 20 62 65 69 6e 67 20 6f  e object being o
e2f0: 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  pened:.**.** <ul
e300: 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  >.** <li>  [SQLI
e310: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d  TE_OPEN_MAIN_DB]
e320: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
e330: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52  E_OPEN_MAIN_JOUR
e340: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  NAL].** <li>  [S
e350: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
e360: 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  DB].** <li>  [SQ
e370: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a  LITE_OPEN_TEMP_J
e380: 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20  OURNAL].** <li> 
e390: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52   [SQLITE_OPEN_TR
e3a0: 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c  ANSIENT_DB].** <
e3b0: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
e3c0: 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a  N_SUBJOURNAL].**
e3d0: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
e3e0: 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e  PEN_MASTER_JOURN
e3f0: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  AL].** <li>  [SQ
e400: 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a  LITE_OPEN_WAL].*
e410: 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20  * </ul>)^.**.** 
e420: 54 68 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70  The file I/O imp
e430: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20  lementation can 
e440: 75 73 65 20 74 68 65 20 6f 62 6a 65 63 74 20 74  use the object t
e450: 79 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20  ype flags to.** 
e460: 63 68 61 6e 67 65 20 74 68 65 20 77 61 79 20 69  change the way i
e470: 74 20 64 65 61 6c 73 20 77 69 74 68 20 66 69 6c  t deals with fil
e480: 65 73 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65  es.  For example
e490: 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  , an application
e4a0: 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f  .** that does no
e4b0: 74 20 63 61 72 65 20 61 62 6f 75 74 20 63 72 61  t care about cra
e4c0: 73 68 20 72 65 63 6f 76 65 72 79 20 6f 72 20 72  sh recovery or r
e4d0: 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d 61  ollback might ma
e4e0: 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f  ke.** the open o
e4f0: 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65  f a journal file
e500: 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65   a no-op.  Write
e510: 73 20 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61  s to this journa
e520: 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20  l would.** also 
e530: 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61  be no-ops, and a
e540: 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65  ny attempt to re
e550: 61 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77  ad the journal w
e560: 6f 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53  ould return.** S
e570: 51 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72  QLITE_IOERR.  Or
e580: 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
e590: 69 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e  ion might recogn
e5a0: 69 7a 65 20 74 68 61 74 20 61 20 64 61 74 61 62  ize that a datab
e5b0: 61 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c  ase.** file will
e5c0: 20 62 65 20 64 6f 69 6e 67 20 70 61 67 65 2d 61   be doing page-a
e5d0: 6c 69 67 6e 65 64 20 73 65 63 74 6f 72 20 72 65  ligned sector re
e5e0: 61 64 73 20 61 6e 64 20 77 72 69 74 65 73 20 69  ads and writes i
e5f0: 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72  n a random.** or
e600: 64 65 72 20 61 6e 64 20 73 65 74 20 75 70 20 69  der and set up i
e610: 74 73 20 49 2f 4f 20 73 75 62 73 79 73 74 65 6d  ts I/O subsystem
e620: 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a   accordingly..**
e630: 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 74  .** SQLite might
e640: 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66   also add one of
e650: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66   the following f
e660: 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65  lags to the xOpe
e670: 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20  n method:.**.** 
e680: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  <ul>.** <li> [SQ
e690: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
e6a0: 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e  ONCLOSE].** <li>
e6b0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58   [SQLITE_OPEN_EX
e6c0: 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c  CLUSIVE].** </ul
e6d0: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  >.**.** The [SQL
e6e0: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
e6f0: 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61  NCLOSE] flag mea
e700: 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75  ns the file shou
e710: 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64  ld be.** deleted
e720: 20 77 68 65 6e 20 69 74 20 69 73 20 63 6c 6f 73   when it is clos
e730: 65 64 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54  ed.  ^The [SQLIT
e740: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
e750: 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65  LOSE].** will be
e760: 20 73 65 74 20 66 6f 72 20 54 45 4d 50 20 64 61   set for TEMP da
e770: 74 61 62 61 73 65 73 20 61 6e 64 20 74 68 65 69  tabases and thei
e780: 72 20 6a 6f 75 72 6e 61 6c 73 2c 20 74 72 61 6e  r journals, tran
e790: 73 69 65 6e 74 0a 2a 2a 20 64 61 74 61 62 61 73  sient.** databas
e7a0: 65 73 2c 20 61 6e 64 20 73 75 62 6a 6f 75 72 6e  es, and subjourn
e7b0: 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  als..**.** ^The 
e7c0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43  [SQLITE_OPEN_EXC
e7d0: 4c 55 53 49 56 45 5d 20 66 6c 61 67 20 69 73 20  LUSIVE] flag is 
e7e0: 61 6c 77 61 79 73 20 75 73 65 64 20 69 6e 20 63  always used in c
e7f0: 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69  onjunction.** wi
e800: 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  th the [SQLITE_O
e810: 50 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61 67  PEN_CREATE] flag
e820: 2c 20 77 68 69 63 68 20 61 72 65 20 62 6f 74 68  , which are both
e830: 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e 61   directly.** ana
e840: 6c 6f 67 6f 75 73 20 74 6f 20 74 68 65 20 4f 5f  logous to the O_
e850: 45 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41 54  EXCL and O_CREAT
e860: 20 66 6c 61 67 73 20 6f 66 20 74 68 65 20 50 4f   flags of the PO
e870: 53 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 50  SIX open().** AP
e880: 49 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 4f  I.  The SQLITE_O
e890: 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 66 6c  PEN_EXCLUSIVE fl
e8a0: 61 67 2c 20 77 68 65 6e 20 70 61 69 72 65 64 20  ag, when paired 
e8b0: 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c  with the .** SQL
e8c0: 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2c  ITE_OPEN_CREATE,
e8d0: 20 69 73 20 75 73 65 64 20 74 6f 20 69 6e 64 69   is used to indi
e8e0: 63 61 74 65 20 74 68 61 74 20 66 69 6c 65 20 73  cate that file s
e8f0: 68 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a 20  hould always.** 
e900: 62 65 20 63 72 65 61 74 65 64 2c 20 61 6e 64 20  be created, and 
e910: 74 68 61 74 20 69 74 20 69 73 20 61 6e 20 65 72  that it is an er
e920: 72 6f 72 20 69 66 20 69 74 20 61 6c 72 65 61 64  ror if it alread
e930: 79 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74 20  y exists..** It 
e940: 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73  is <i>not</i> us
e950: 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74  ed to indicate t
e960: 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62  he file should b
e970: 65 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f 72  e opened .** for
e980: 20 65 78 63 6c 75 73 69 76 65 20 61 63 63 65 73   exclusive acces
e990: 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61  s..**.** ^At lea
e9a0: 73 74 20 73 7a 4f 73 46 69 6c 65 20 62 79 74 65  st szOsFile byte
e9b0: 73 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65 20  s of memory are 
e9c0: 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c  allocated by SQL
e9d0: 69 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74  ite.** to hold t
e9e0: 68 65 20 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  he  [sqlite3_fil
e9f0: 65 5d 20 73 74 72 75 63 74 75 72 65 20 70 61 73  e] structure pas
ea00: 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64  sed as the third
ea10: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  .** argument to 
ea20: 78 4f 70 65 6e 2e 20 20 54 68 65 20 78 4f 70 65  xOpen.  The xOpe
ea30: 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f  n method does no
ea40: 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c  t have to.** all
ea50: 6f 63 61 74 65 20 74 68 65 20 73 74 72 75 63 74  ocate the struct
ea60: 75 72 65 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a  ure; it should j
ea70: 75 73 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e 20  ust fill it in. 
ea80: 20 4e 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74 68   Note that.** th
ea90: 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6d  e xOpen method m
eaa0: 75 73 74 20 73 65 74 20 74 68 65 20 73 71 6c 69  ust set the sqli
eab0: 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64  te3_file.pMethod
eac0: 73 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 61  s to either.** a
ead0: 20 76 61 6c 69 64 20 5b 73 71 6c 69 74 65 33 5f   valid [sqlite3_
eae0: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
eaf0: 63 74 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20 20  ct or to NULL.  
eb00: 78 4f 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a  xOpen must do.**
eb10: 20 74 68 69 73 20 65 76 65 6e 20 69 66 20 74 68   this even if th
eb20: 65 20 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20 53  e open fails.  S
eb30: 51 4c 69 74 65 20 65 78 70 65 63 74 73 20 74 68  QLite expects th
eb40: 61 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66  at the sqlite3_f
eb50: 69 6c 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a 20  ile.pMethods.** 
eb60: 65 6c 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20  element will be 
eb70: 76 61 6c 69 64 20 61 66 74 65 72 20 78 4f 70 65  valid after xOpe
eb80: 6e 20 72 65 74 75 72 6e 73 20 72 65 67 61 72 64  n returns regard
eb90: 6c 65 73 73 20 6f 66 20 74 68 65 20 73 75 63 63  less of the succ
eba0: 65 73 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75 72  ess.** or failur
ebb0: 65 20 6f 66 20 74 68 65 20 78 4f 70 65 6e 20 63  e of the xOpen c
ebc0: 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c  all..**.** [[sql
ebd0: 69 74 65 33 5f 76 66 73 2e 78 41 63 63 65 73 73  ite3_vfs.xAccess
ebe0: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 66 6c 61 67 73  ]].** ^The flags
ebf0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 41 63   argument to xAc
ec00: 63 65 73 73 28 29 20 6d 61 79 20 62 65 20 5b 53  cess() may be [S
ec10: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49  QLITE_ACCESS_EXI
ec20: 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20  STS].** to test 
ec30: 66 6f 72 20 74 68 65 20 65 78 69 73 74 65 6e 63  for the existenc
ec40: 65 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72 20  e of a file, or 
ec50: 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52  [SQLITE_ACCESS_R
ec60: 45 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a 20  EADWRITE] to.** 
ec70: 74 65 73 74 20 77 68 65 74 68 65 72 20 61 20 66  test whether a f
ec80: 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 20  ile is readable 
ec90: 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20 6f 72  and writable, or
eca0: 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f   [SQLITE_ACCESS_
ecb0: 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73 74  READ].** to test
ecc0: 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20   whether a file 
ecd0: 69 73 20 61 74 20 6c 65 61 73 74 20 72 65 61 64  is at least read
ece0: 61 62 6c 65 2e 20 20 20 54 68 65 20 66 69 6c 65  able.   The file
ecf0: 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69 72   can be a.** dir
ed00: 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53  ectory..**.** ^S
ed10: 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 61 79  QLite will alway
ed20: 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c 65  s allocate at le
ed30: 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b 31  ast mxPathname+1
ed40: 20 62 79 74 65 73 20 66 6f 72 20 74 68 65 0a 2a   bytes for the.*
ed50: 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 20  * output buffer 
ed60: 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20 20  xFullPathname.  
ed70: 54 68 65 20 65 78 61 63 74 20 73 69 7a 65 20 6f  The exact size o
ed80: 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66  f the output buf
ed90: 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20 70  fer.** is also p
eda0: 61 73 73 65 64 20 61 73 20 61 20 70 61 72 61 6d  assed as a param
edb0: 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20 6d 65  eter to both  me
edc0: 74 68 6f 64 73 2e 20 49 66 20 74 68 65 20 6f 75  thods. If the ou
edd0: 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69  tput buffer.** i
ede0: 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f 75  s not large enou
edf0: 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54  gh, [SQLITE_CANT
ee00: 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65 20  OPEN] should be 
ee10: 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63 65 20  returned. Since 
ee20: 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64 6c  this is.** handl
ee30: 65 64 20 61 73 20 61 20 66 61 74 61 6c 20 65 72  ed as a fatal er
ee40: 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c 20 76  ror by SQLite, v
ee50: 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  fs implementatio
ee60: 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 61 76  ns should endeav
ee70: 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e 74  or.** to prevent
ee80: 20 74 68 69 73 20 62 79 20 73 65 74 74 69 6e 67   this by setting
ee90: 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f 20 61   mxPathname to a
eea0: 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20 6c 61   sufficiently la
eeb0: 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a  rge value..**.**
eec0: 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73   The xRandomness
eed0: 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 78 43  (), xSleep(), xC
eee0: 75 72 72 65 6e 74 54 69 6d 65 28 29 2c 20 61 6e  urrentTime(), an
eef0: 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e  d xCurrentTimeIn
ef00: 74 36 34 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  t64().** interfa
ef10: 63 65 73 20 61 72 65 20 6e 6f 74 20 73 74 72 69  ces are not stri
ef20: 63 74 6c 79 20 61 20 70 61 72 74 20 6f 66 20 74  ctly a part of t
ef30: 68 65 20 66 69 6c 65 73 79 73 74 65 6d 2c 20 62  he filesystem, b
ef40: 75 74 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 69  ut they are.** i
ef50: 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 20 56  ncluded in the V
ef60: 46 53 20 73 74 72 75 63 74 75 72 65 20 66 6f 72  FS structure for
ef70: 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a   completeness..*
ef80: 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73  * The xRandomnes
ef90: 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 74 74  s() function att
efa0: 65 6d 70 74 73 20 74 6f 20 72 65 74 75 72 6e 20  empts to return 
efb0: 6e 42 79 74 65 73 20 62 79 74 65 73 0a 2a 2a 20  nBytes bytes.** 
efc0: 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20  of good-quality 
efd0: 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20  randomness into 
efe0: 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 74 75 72  zOut.  The retur
eff0: 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68  n value is.** th
f000: 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 65 72 20  e actual number 
f010: 6f 66 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64  of bytes of rand
f020: 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 2e  omness obtained.
f030: 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65 70 28 29  .** The xSleep()
f040: 20 6d 65 74 68 6f 64 20 63 61 75 73 65 73 20 74   method causes t
f050: 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61  he calling threa
f060: 64 20 74 6f 20 73 6c 65 65 70 20 66 6f 72 20 61  d to sleep for a
f070: 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65 20 6e  t.** least the n
f080: 75 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f 73 65  umber of microse
f090: 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20 5e 54  conds given.  ^T
f0a0: 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28  he xCurrentTime(
f0b0: 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75  ).** method retu
f0c0: 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44 61 79  rns a Julian Day
f0d0: 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 68 65 20   Number for the 
f0e0: 63 75 72 72 65 6e 74 20 64 61 74 65 20 61 6e 64  current date and
f0f0: 20 74 69 6d 65 20 61 73 0a 2a 2a 20 61 20 66 6c   time as.** a fl
f100: 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c  oating point val
f110: 75 65 2e 0a 2a 2a 20 5e 54 68 65 20 78 43 75 72  ue..** ^The xCur
f120: 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20  rentTimeInt64() 
f130: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 2c 20  method returns, 
f140: 61 73 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74  as an integer, t
f150: 68 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44 61 79  he Julian.** Day
f160: 20 4e 75 6d 62 65 72 20 6d 75 6c 74 69 70 6c 69   Number multipli
f170: 65 64 20 62 79 20 38 36 34 30 30 30 30 30 20 28  ed by 86400000 (
f180: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69  the number of mi
f190: 6c 6c 69 73 65 63 6f 6e 64 73 20 69 6e 20 0a 2a  lliseconds in .*
f1a0: 2a 20 61 20 32 34 2d 68 6f 75 72 20 64 61 79 29  * a 24-hour day)
f1b0: 2e 20 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77  .  .** ^SQLite w
f1c0: 69 6c 6c 20 75 73 65 20 74 68 65 20 78 43 75 72  ill use the xCur
f1d0: 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20  rentTimeInt64() 
f1e0: 6d 65 74 68 6f 64 20 74 6f 20 67 65 74 20 74 68  method to get th
f1f0: 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 64 61 74  e current.** dat
f200: 65 20 61 6e 64 20 74 69 6d 65 20 69 66 20 74 68  e and time if th
f210: 61 74 20 6d 65 74 68 6f 64 20 69 73 20 61 76 61  at method is ava
f220: 69 6c 61 62 6c 65 20 28 69 66 20 69 56 65 72 73  ilable (if iVers
f230: 69 6f 6e 20 69 73 20 32 20 6f 72 20 0a 2a 2a 20  ion is 2 or .** 
f240: 67 72 65 61 74 65 72 20 61 6e 64 20 74 68 65 20  greater and the 
f250: 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72  function pointer
f260: 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 61 6e   is not NULL) an
f270: 64 20 77 69 6c 6c 20 66 61 6c 6c 20 62 61 63 6b  d will fall back
f280: 0a 2a 2a 20 74 6f 20 78 43 75 72 72 65 6e 74 54  .** to xCurrentT
f290: 69 6d 65 28 29 20 69 66 20 78 43 75 72 72 65 6e  ime() if xCurren
f2a0: 74 54 69 6d 65 49 6e 74 36 34 28 29 20 69 73 20  tTimeInt64() is 
f2b0: 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 0a  unavailable..**.
f2c0: 2a 2a 20 5e 54 68 65 20 78 53 65 74 53 79 73 74  ** ^The xSetSyst
f2d0: 65 6d 43 61 6c 6c 28 29 2c 20 78 47 65 74 53 79  emCall(), xGetSy
f2e0: 73 74 65 6d 43 61 6c 6c 28 29 2c 20 61 6e 64 20  stemCall(), and 
f2f0: 78 4e 65 73 74 53 79 73 74 65 6d 43 61 6c 6c 28  xNestSystemCall(
f300: 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  ) interfaces.** 
f310: 61 72 65 20 6e 6f 74 20 75 73 65 64 20 62 79 20  are not used by 
f320: 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 2e  the SQLite core.
f330: 20 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 61 6c    These optional
f340: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
f350: 70 72 6f 76 69 64 65 64 0a 2a 2a 20 62 79 20 73  provided.** by s
f360: 6f 6d 65 20 56 46 53 65 73 20 74 6f 20 66 61 63  ome VFSes to fac
f370: 69 6c 69 74 61 74 65 20 74 65 73 74 69 6e 67 20  ilitate testing 
f380: 6f 66 20 74 68 65 20 56 46 53 20 63 6f 64 65 2e  of the VFS code.
f390: 20 42 79 20 6f 76 65 72 72 69 64 69 6e 67 20 0a   By overriding .
f3a0: 2a 2a 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20  ** system calls 
f3b0: 77 69 74 68 20 66 75 6e 63 74 69 6f 6e 73 20 75  with functions u
f3c0: 6e 64 65 72 20 69 74 73 20 63 6f 6e 74 72 6f 6c  nder its control
f3d0: 2c 20 61 20 74 65 73 74 20 70 72 6f 67 72 61 6d  , a test program
f3e0: 20 63 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61 74 65   can.** simulate
f3f0: 20 66 61 75 6c 74 73 20 61 6e 64 20 65 72 72 6f   faults and erro
f400: 72 20 63 6f 6e 64 69 74 69 6f 6e 73 20 74 68 61  r conditions tha
f410: 74 20 77 6f 75 6c 64 20 6f 74 68 65 72 77 69 73  t would otherwis
f420: 65 20 62 65 20 64 69 66 66 69 63 75 6c 74 0a 2a  e be difficult.*
f430: 2a 20 6f 72 20 69 6d 70 6f 73 73 69 62 6c 65 20  * or impossible 
f440: 74 6f 20 69 6e 64 75 63 65 2e 20 20 54 68 65 20  to induce.  The 
f450: 73 65 74 20 6f 66 20 73 79 73 74 65 6d 20 63 61  set of system ca
f460: 6c 6c 73 20 74 68 61 74 20 63 61 6e 20 62 65 20  lls that can be 
f470: 6f 76 65 72 72 69 64 64 65 6e 0a 2a 2a 20 76 61  overridden.** va
f480: 72 69 65 73 20 66 72 6f 6d 20 6f 6e 65 20 56 46  ries from one VF
f490: 53 20 74 6f 20 61 6e 6f 74 68 65 72 2c 20 61 6e  S to another, an
f4a0: 64 20 66 72 6f 6d 20 6f 6e 65 20 76 65 72 73 69  d from one versi
f4b0: 6f 6e 20 6f 66 20 74 68 65 20 73 61 6d 65 20 56  on of the same V
f4c0: 46 53 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65 78  FS to the.** nex
f4d0: 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  t.  Applications
f4e0: 20 74 68 61 74 20 75 73 65 20 74 68 65 73 65 20   that use these 
f4f0: 69 6e 74 65 72 66 61 63 65 73 20 6d 75 73 74 20  interfaces must 
f500: 62 65 20 70 72 65 70 61 72 65 64 20 66 6f 72 20  be prepared for 
f510: 61 6e 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20 6f 66  any.** or all of
f520: 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   these interface
f530: 73 20 74 6f 20 62 65 20 4e 55 4c 4c 20 6f 72 20  s to be NULL or 
f540: 66 6f 72 20 74 68 65 69 72 20 62 65 68 61 76 69  for their behavi
f550: 6f 72 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a 20  or to change.** 
f560: 66 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73 65  from one release
f570: 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 20 20 41   to the next.  A
f580: 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73 74  pplications must
f590: 20 6e 6f 74 20 61 74 74 65 6d 70 74 20 74 6f 20   not attempt to 
f5a0: 61 63 63 65 73 73 0a 2a 2a 20 61 6e 79 20 6f 66  access.** any of
f5b0: 20 74 68 65 73 65 20 6d 65 74 68 6f 64 73 20 69   these methods i
f5c0: 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 6f  f the iVersion o
f5d0: 66 20 74 68 65 20 56 46 53 20 69 73 20 6c 65 73  f the VFS is les
f5e0: 73 20 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74 79 70  s than 3..*/.typ
f5f0: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
f600: 74 65 33 5f 76 66 73 20 73 71 6c 69 74 65 33 5f  te3_vfs sqlite3_
f610: 76 66 73 3b 0a 74 79 70 65 64 65 66 20 76 6f 69  vfs;.typedef voi
f620: 64 20 28 2a 73 71 6c 69 74 65 33 5f 73 79 73 63  d (*sqlite3_sysc
f630: 61 6c 6c 5f 70 74 72 29 28 76 6f 69 64 29 3b 0a  all_ptr)(void);.
f640: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
f650: 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73  fs {.  int iVers
f660: 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20  ion;            
f670: 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76 65 72  /* Structure ver
f680: 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 63 75 72  sion number (cur
f690: 72 65 6e 74 6c 79 20 33 29 20 2a 2f 0a 20 20 69  rently 3) */.  i
f6a0: 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20  nt szOsFile;    
f6b0: 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a 65 20          /* Size 
f6c0: 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20 73 71  of subclassed sq
f6d0: 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20  lite3_file */.  
f6e0: 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20  int mxPathname; 
f6f0: 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
f700: 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e 61 6d  mum file pathnam
f710: 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71  e length */.  sq
f720: 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 78 74  lite3_vfs *pNext
f730: 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 20 72  ;      /* Next r
f740: 65 67 69 73 74 65 72 65 64 20 56 46 53 20 2a 2f  egistered VFS */
f750: 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
f760: 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e  Name;       /* N
f770: 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69 72 74  ame of this virt
f780: 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 20  ual file system 
f790: 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44  */.  void *pAppD
f7a0: 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 2f 2a  ata;          /*
f7b0: 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 70 6c   Pointer to appl
f7c0: 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 69 63  ication-specific
f7d0: 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28   data */.  int (
f7e0: 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f  *xOpen)(sqlite3_
f7f0: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
f800: 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33   *zName, sqlite3
f810: 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20  _file*,.        
f820: 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61 67 73         int flags
f830: 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73  , int *pOutFlags
f840: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c 65  );.  int (*xDele
f850: 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  te)(sqlite3_vfs*
f860: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
f870: 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 69 72  ame, int syncDir
f880: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 63 65  );.  int (*xAcce
f890: 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ss)(sqlite3_vfs*
f8a0: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
f8b0: 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c 20  ame, int flags, 
f8c0: 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20  int *pResOut);. 
f8d0: 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74 68   int (*xFullPath
f8e0: 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66  name)(sqlite3_vf
f8f0: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
f900: 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c  zName, int nOut,
f910: 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20   char *zOut);.  
f920: 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29  void *(*xDlOpen)
f930: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
f940: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65  onst char *zFile
f950: 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a  name);.  void (*
f960: 78 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 74 65  xDlError)(sqlite
f970: 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74  3_vfs*, int nByt
f980: 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67  e, char *zErrMsg
f990: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78 44  );.  void (*(*xD
f9a0: 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f 76 66  lSym)(sqlite3_vf
f9b0: 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20  s*,void*, const 
f9c0: 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29 28  char *zSymbol))(
f9d0: 76 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20 28 2a  void);.  void (*
f9e0: 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74 65  xDlClose)(sqlite
f9f0: 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a  3_vfs*, void*);.
fa00: 20 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e    int (*xRandomn
fa10: 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ess)(sqlite3_vfs
fa20: 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68  *, int nByte, ch
fa30: 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74  ar *zOut);.  int
fa40: 20 28 2a 78 53 6c 65 65 70 29 28 73 71 6c 69 74   (*xSleep)(sqlit
fa50: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63  e3_vfs*, int mic
fa60: 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e  roseconds);.  in
fa70: 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65  t (*xCurrentTime
fa80: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
fa90: 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 20  double*);.  int 
faa0: 28 2a 78 47 65 74 4c 61 73 74 45 72 72 6f 72 29  (*xGetLastError)
fab0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
fac0: 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20 2f  nt, char *);.  /
fad0: 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f  *.  ** The metho
fae0: 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20  ds above are in 
faf0: 76 65 72 73 69 6f 6e 20 31 20 6f 66 20 74 68 65  version 1 of the
fb00: 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65   sqlite_vfs obje
fb10: 63 74 0a 20 20 2a 2a 20 64 65 66 69 6e 69 74 69  ct.  ** definiti
fb20: 6f 6e 2e 20 20 54 68 6f 73 65 20 74 68 61 74 20  on.  Those that 
fb30: 66 6f 6c 6c 6f 77 20 61 72 65 20 61 64 64 65 64  follow are added
fb40: 20 69 6e 20 76 65 72 73 69 6f 6e 20 32 20 6f 72   in version 2 or
fb50: 20 6c 61 74 65 72 0a 20 20 2a 2f 0a 20 20 69 6e   later.  */.  in
fb60: 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65  t (*xCurrentTime
fb70: 49 6e 74 36 34 29 28 73 71 6c 69 74 65 33 5f 76  Int64)(sqlite3_v
fb80: 66 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  fs*, sqlite3_int
fb90: 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20  64*);.  /*.  ** 
fba0: 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76  The methods abov
fbb0: 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e  e are in version
fbc0: 73 20 31 20 61 6e 64 20 32 20 6f 66 20 74 68 65  s 1 and 2 of the
fbd0: 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65   sqlite_vfs obje
fbe0: 63 74 2e 0a 20 20 2a 2a 20 54 68 6f 73 65 20 62  ct..  ** Those b
fbf0: 65 6c 6f 77 20 61 72 65 20 66 6f 72 20 76 65 72  elow are for ver
fc00: 73 69 6f 6e 20 33 20 61 6e 64 20 67 72 65 61 74  sion 3 and great
fc10: 65 72 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28  er..  */.  int (
fc20: 2a 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 29  *xSetSystemCall)
fc30: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
fc40: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
fc50: 2c 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c  , sqlite3_syscal
fc60: 6c 5f 70 74 72 29 3b 0a 20 20 73 71 6c 69 74 65  l_ptr);.  sqlite
fc70: 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 20 28 2a  3_syscall_ptr (*
fc80: 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28  xGetSystemCall)(
fc90: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
fca0: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29  nst char *zName)
fcb0: 3b 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  ;.  const char *
fcc0: 28 2a 78 4e 65 78 74 53 79 73 74 65 6d 43 61 6c  (*xNextSystemCal
fcd0: 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  l)(sqlite3_vfs*,
fce0: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
fcf0: 6d 65 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54  me);.  /*.  ** T
fd00: 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65  he methods above
fd10: 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73   are in versions
fd20: 20 31 20 74 68 72 6f 75 67 68 20 33 20 6f 66 20   1 through 3 of 
fd30: 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f  the sqlite_vfs o
fd40: 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e 65 77 20  bject..  ** New 
fd50: 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70  fields may be ap
fd60: 70 65 6e 64 65 64 20 69 6e 20 66 69 67 75 72 65  pended in figure
fd70: 20 76 65 72 73 69 6f 6e 73 2e 20 20 54 68 65 20   versions.  The 
fd80: 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61  iVersion.  ** va
fd90: 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65  lue will increme
fda0: 6e 74 20 77 68 65 6e 65 76 65 72 20 74 68 69 73  nt whenever this
fdb0: 20 68 61 70 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a   happens. .  */.
fdc0: 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
fdd0: 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68  EF: Flags for th
fde0: 65 20 78 41 63 63 65 73 73 20 56 46 53 20 6d 65  e xAccess VFS me
fdf0: 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  thod.**.** These
fe00: 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e   integer constan
fe10: 74 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 61  ts can be used a
fe20: 73 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  s the third para
fe30: 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20  meter to.** the 
fe40: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 6f  xAccess method o
fe50: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66  f an [sqlite3_vf
fe60: 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 79  s] object.  They
fe70: 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68   determine.** wh
fe80: 61 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69  at kind of permi
fe90: 73 73 69 6f 6e 73 20 74 68 65 20 78 41 63 63 65  ssions the xAcce
fea0: 73 73 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f  ss method is loo
feb0: 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 74  king for..** Wit
fec0: 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  h SQLITE_ACCESS_
fed0: 45 58 49 53 54 53 2c 20 74 68 65 20 78 41 63 63  EXISTS, the xAcc
fee0: 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69  ess method.** si
fef0: 6d 70 6c 79 20 63 68 65 63 6b 73 20 77 68 65 74  mply checks whet
ff00: 68 65 72 20 74 68 65 20 66 69 6c 65 20 65 78 69  her the file exi
ff10: 73 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c  sts..** With SQL
ff20: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
ff30: 52 49 54 45 2c 20 74 68 65 20 78 41 63 63 65 73  RITE, the xAcces
ff40: 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63  s method.** chec
ff50: 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 6e  ks whether the n
ff60: 61 6d 65 64 20 64 69 72 65 63 74 6f 72 79 20 69  amed directory i
ff70: 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c 65 20  s both readable 
ff80: 61 6e 64 20 77 72 69 74 61 62 6c 65 0a 2a 2a 20  and writable.** 
ff90: 28 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c  (in other words,
ffa0: 20 69 66 20 66 69 6c 65 73 20 63 61 6e 20 62 65   if files can be
ffb0: 20 61 64 64 65 64 2c 20 72 65 6d 6f 76 65 64 2c   added, removed,
ffc0: 20 61 6e 64 20 72 65 6e 61 6d 65 64 20 77 69 74   and renamed wit
ffd0: 68 69 6e 0a 2a 2a 20 74 68 65 20 64 69 72 65 63  hin.** the direc
ffe0: 74 6f 72 79 29 2e 0a 2a 2a 20 54 68 65 20 53 51  tory)..** The SQ
fff0: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
10000 57 52 49 54 45 20 63 6f 6e 73 74 61 6e 74 20 69  WRITE constant i
10010 73 20 63 75 72 72 65 6e 74 6c 79 20 75 73 65 64  s currently used
10020 20 6f 6e 6c 79 20 62 79 20 74 68 65 0a 2a 2a 20   only by the.** 
10030 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65  [temp_store_dire
10040 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 2c 20 74  ctory pragma], t
10050 68 6f 75 67 68 20 74 68 69 73 20 63 6f 75 6c 64  hough this could
10060 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75 74   change in a fut
10070 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f  ure.** release o
10080 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 57 69 74  f SQLite..** Wit
10090 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  h SQLITE_ACCESS_
100a0 52 45 41 44 2c 20 74 68 65 20 78 41 63 63 65 73  READ, the xAcces
100b0 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63  s method.** chec
100c0 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66  ks whether the f
100d0 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 2e  ile is readable.
100e0 20 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43    The SQLITE_ACC
100f0 45 53 53 5f 52 45 41 44 20 63 6f 6e 73 74 61 6e  ESS_READ constan
10100 74 20 69 73 0a 2a 2a 20 63 75 72 72 65 6e 74 6c  t is.** currentl
10110 79 20 75 6e 75 73 65 64 2c 20 74 68 6f 75 67 68  y unused, though
10120 20 69 74 20 6d 69 67 68 74 20 62 65 20 75 73 65   it might be use
10130 64 20 69 6e 20 61 20 66 75 74 75 72 65 20 72 65  d in a future re
10140 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69  lease of.** SQLi
10150 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  te..*/.#define S
10160 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49  QLITE_ACCESS_EXI
10170 53 54 53 20 20 20 20 30 0a 23 64 65 66 69 6e 65  STS    0.#define
10180 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
10190 45 41 44 57 52 49 54 45 20 31 20 20 20 2f 2a 20  EADWRITE 1   /* 
101a0 55 73 65 64 20 62 79 20 50 52 41 47 4d 41 20 74  Used by PRAGMA t
101b0 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74  emp_store_direct
101c0 6f 72 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ory */.#define S
101d0 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
101e0 44 20 20 20 20 20 20 32 20 20 20 2f 2a 20 55 6e  D      2   /* Un
101f0 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  used */../*.** C
10200 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66  API3REF: Flags f
10210 6f 72 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20  or the xShmLock 
10220 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a  VFS method.**.**
10230 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63   These integer c
10240 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20  onstants define 
10250 74 68 65 20 76 61 72 69 6f 75 73 20 6c 6f 63 6b  the various lock
10260 69 6e 67 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a  ing operations.*
10270 2a 20 61 6c 6c 6f 77 65 64 20 62 79 20 74 68 65  * allowed by the
10280 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64   xShmLock method
10290 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f   of [sqlite3_io_
102a0 6d 65 74 68 6f 64 73 5d 2e 20 20 54 68 65 0a 2a  methods].  The.*
102b0 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 72 65 20  * following are 
102c0 74 68 65 20 6f 6e 6c 79 20 6c 65 67 61 6c 20 63  the only legal c
102d0 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 6f 66 20 66  ombinations of f
102e0 6c 61 67 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78  lags to the.** x
102f0 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a  ShmLock method:.
10300 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
10310 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c  i>  SQLITE_SHM_L
10320 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d  OCK | SQLITE_SHM
10330 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20  _SHARED.** <li> 
10340 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b   SQLITE_SHM_LOCK
10350 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58   | SQLITE_SHM_EX
10360 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20  CLUSIVE.** <li> 
10370 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f   SQLITE_SHM_UNLO
10380 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f  CK | SQLITE_SHM_
10390 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20  SHARED.** <li>  
103a0 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43  SQLITE_SHM_UNLOC
103b0 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45  K | SQLITE_SHM_E
103c0 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c  XCLUSIVE.** </ul
103d0 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c  >.**.** When unl
103e0 6f 63 6b 69 6e 67 2c 20 74 68 65 20 73 61 6d 65  ocking, the same
103f0 20 53 48 41 52 45 44 20 6f 72 20 45 58 43 4c 55   SHARED or EXCLU
10400 53 49 56 45 20 66 6c 61 67 20 6d 75 73 74 20 62  SIVE flag must b
10410 65 20 73 75 70 70 6c 69 65 64 20 61 73 0a 2a 2a  e supplied as.**
10420 20 77 61 73 20 67 69 76 65 6e 20 6f 6e 20 74 68   was given on th
10430 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
10440 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68  lock.  .**.** Th
10450 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f  e xShmLock metho
10460 64 20 63 61 6e 20 74 72 61 6e 73 69 74 69 6f 6e  d can transition
10470 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65   between unlocke
10480 64 20 61 6e 64 20 53 48 41 52 45 44 20 6f 72 0a  d and SHARED or.
10490 2a 2a 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63  ** between unloc
104a0 6b 65 64 20 61 6e 64 20 45 58 43 4c 55 53 49 56  ked and EXCLUSIV
104b0 45 2e 20 20 49 74 20 63 61 6e 6e 6f 74 20 74 72  E.  It cannot tr
104c0 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e  ansition between
104d0 20 53 48 41 52 45 44 0a 2a 2a 20 61 6e 64 20 45   SHARED.** and E
104e0 58 43 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23 64 65  XCLUSIVE..*/.#de
104f0 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f  fine SQLITE_SHM_
10500 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 31 0a 23  UNLOCK       1.#
10510 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
10520 4d 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 32  M_LOCK         2
10530 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
10540 53 48 4d 5f 53 48 41 52 45 44 20 20 20 20 20 20  SHM_SHARED      
10550 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   4.#define SQLIT
10560 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 20  E_SHM_EXCLUSIVE 
10570 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49     8../*.** CAPI
10580 33 52 45 46 3a 20 4d 61 78 69 6d 75 6d 20 78 53  3REF: Maximum xS
10590 68 6d 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a  hmLock index.**.
105a0 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20  ** The xShmLock 
105b0 6d 65 74 68 6f 64 20 6f 6e 20 5b 73 71 6c 69 74  method on [sqlit
105c0 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d  e3_io_methods] m
105d0 61 79 20 75 73 65 20 76 61 6c 75 65 73 0a 2a 2a  ay use values.**
105e0 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74   between 0 and t
105f0 68 69 73 20 75 70 70 65 72 20 62 6f 75 6e 64 20  his upper bound 
10600 61 73 20 69 74 73 20 22 6f 66 66 73 65 74 22 20  as its "offset" 
10610 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65  argument..** The
10620 20 53 51 4c 69 74 65 20 63 6f 72 65 20 77 69 6c   SQLite core wil
10630 6c 20 6e 65 76 65 72 20 61 74 74 65 6d 70 74 20  l never attempt 
10640 74 6f 20 61 63 71 75 69 72 65 20 6f 72 20 72 65  to acquire or re
10650 6c 65 61 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20  lease a.** lock 
10660 6f 75 74 73 69 64 65 20 6f 66 20 74 68 69 73 20  outside of this 
10670 72 61 6e 67 65 0a 2a 2f 0a 23 64 65 66 69 6e 65  range.*/.#define
10680 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43   SQLITE_SHM_NLOC
10690 4b 20 20 20 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a  K        8.../*.
106a0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 69  ** CAPI3REF: Ini
106b0 74 69 61 6c 69 7a 65 20 54 68 65 20 53 51 4c 69  tialize The SQLi
106c0 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a  te Library.**.**
106d0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
106e0 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69  itialize() routi
106f0 6e 65 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74  ne initializes t
10700 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69 62  he.** SQLite lib
10710 72 61 72 79 2e 20 20 5e 54 68 65 20 73 71 6c 69  rary.  ^The sqli
10720 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 72  te3_shutdown() r
10730 6f 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f  outine.** deallo
10740 63 61 74 65 73 20 61 6e 79 20 72 65 73 6f 75 72  cates any resour
10750 63 65 73 20 74 68 61 74 20 77 65 72 65 20 61 6c  ces that were al
10760 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69 74  located by sqlit
10770 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e  e3_initialize().
10780 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
10790 65 73 20 61 72 65 20 64 65 73 69 67 6e 65 64 20  es are designed 
107a0 74 6f 20 61 69 64 20 69 6e 20 70 72 6f 63 65 73  to aid in proces
107b0 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  s initialization
107c0 20 61 6e 64 0a 2a 2a 20 73 68 75 74 64 6f 77 6e   and.** shutdown
107d0 20 6f 6e 20 65 6d 62 65 64 64 65 64 20 73 79 73   on embedded sys
107e0 74 65 6d 73 2e 20 20 57 6f 72 6b 73 74 61 74 69  tems.  Workstati
107f0 6f 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  on applications 
10800 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 69 74 65 20  using.** SQLite 
10810 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74 20  normally do not 
10820 6e 65 65 64 20 74 6f 20 69 6e 76 6f 6b 65 20 65  need to invoke e
10830 69 74 68 65 72 20 6f 66 20 74 68 65 73 65 20 72  ither of these r
10840 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41  outines..**.** A
10850 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
10860 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
10870 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 22 20   an "effective" 
10880 63 61 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a 2a  call if it is.**
10890 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20   the first time 
108a0 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
108b0 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20  ze() is invoked 
108c0 64 75 72 69 6e 67 20 74 68 65 20 6c 69 66 65 74  during the lifet
108d0 69 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70 72  ime of.** the pr
108e0 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 69 74 20  ocess, or if it 
108f0 69 73 20 74 68 65 20 66 69 72 73 74 20 74 69 6d  is the first tim
10900 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
10910 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  lize() is invoke
10920 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  d.** following a
10930 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
10940 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 5e 28  _shutdown().  ^(
10950 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63 74 69 76  Only an effectiv
10960 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c  e call.** of sql
10970 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
10980 29 20 64 6f 65 73 20 61 6e 79 20 69 6e 69 74 69  ) does any initi
10990 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c 20  alization.  All 
109a0 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 61  other calls.** a
109b0 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f  re harmless no-o
109c0 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61  ps.)^.**.** A ca
109d0 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68  ll to sqlite3_sh
109e0 75 74 64 6f 77 6e 28 29 20 69 73 20 61 6e 20 22  utdown() is an "
109f0 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20  effective" call 
10a00 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69 72  if it is the fir
10a10 73 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 71  st.** call to sq
10a20 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
10a30 20 73 69 6e 63 65 20 74 68 65 20 6c 61 73 74 20   since the last 
10a40 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
10a50 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a  ze().  ^(Only.**
10a60 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61   an effective ca
10a70 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68  ll to sqlite3_sh
10a80 75 74 64 6f 77 6e 28 29 20 64 6f 65 73 20 61 6e  utdown() does an
10a90 79 20 64 65 69 6e 69 74 69 61 6c 69 7a 61 74 69  y deinitializati
10aa0 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65 72  on..** All other
10ab0 20 76 61 6c 69 64 20 63 61 6c 6c 73 20 74 6f 20   valid calls to 
10ac0 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
10ad0 28 29 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20  () are harmless 
10ae0 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20  no-ops.)^.**.** 
10af0 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  The sqlite3_init
10b00 69 61 6c 69 7a 65 28 29 20 69 6e 74 65 72 66 61  ialize() interfa
10b10 63 65 20 69 73 20 74 68 72 65 61 64 73 61 66 65  ce is threadsafe
10b20 2c 20 62 75 74 20 73 71 6c 69 74 65 33 5f 73 68  , but sqlite3_sh
10b30 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 73 20 6e  utdown().** is n
10b40 6f 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  ot.  The sqlite3
10b50 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 6e 74 65  _shutdown() inte
10b60 72 66 61 63 65 20 6d 75 73 74 20 6f 6e 6c 79 20  rface must only 
10b70 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61  be called from a
10b80 0a 2a 2a 20 73 69 6e 67 6c 65 20 74 68 72 65 61  .** single threa
10b90 64 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 5b 64 61  d.  All open [da
10ba0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
10bb0 6e 73 5d 20 6d 75 73 74 20 62 65 20 63 6c 6f 73  ns] must be clos
10bc0 65 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74  ed and all.** ot
10bd0 68 65 72 20 53 51 4c 69 74 65 20 72 65 73 6f 75  her SQLite resou
10be0 72 63 65 73 20 6d 75 73 74 20 62 65 20 64 65 61  rces must be dea
10bf0 6c 6c 6f 63 61 74 65 64 20 70 72 69 6f 72 20 74  llocated prior t
10c00 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71  o invoking.** sq
10c10 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
10c20 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74  ..**.** Among ot
10c30 68 65 72 20 74 68 69 6e 67 73 2c 20 5e 73 71 6c  her things, ^sql
10c40 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
10c50 29 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a  ) will invoke.**
10c60 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
10c70 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c 20  ().  Similarly, 
10c80 5e 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77  ^sqlite3_shutdow
10c90 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f  n().** will invo
10ca0 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  ke sqlite3_os_en
10cb0 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  d()..**.** ^The 
10cc0 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
10cd0 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  ze() routine ret
10ce0 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
10cf0 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a 20   on success..** 
10d00 5e 49 66 20 66 6f 72 20 73 6f 6d 65 20 72 65 61  ^If for some rea
10d10 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69  son, sqlite3_ini
10d20 74 69 61 6c 69 7a 65 28 29 20 69 73 20 75 6e 61  tialize() is una
10d30 62 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c 69 7a  ble to initializ
10d40 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61 72 79  e.** the library
10d50 20 28 70 65 72 68 61 70 73 20 69 74 20 69 73 20   (perhaps it is 
10d60 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61  unable to alloca
10d70 74 65 20 61 20 6e 65 65 64 65 64 20 72 65 73 6f  te a needed reso
10d80 75 72 63 65 20 73 75 63 68 0a 2a 2a 20 61 73 20  urce such.** as 
10d90 61 20 6d 75 74 65 78 29 20 69 74 20 72 65 74 75  a mutex) it retu
10da0 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f  rns an [error co
10db0 64 65 5d 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  de] other than [
10dc0 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a  SQLITE_OK]..**.*
10dd0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
10de0 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74  nitialize() rout
10df0 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 69 6e  ine is called in
10e00 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e 79  ternally by many
10e10 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65   other.** SQLite
10e20 20 69 6e 74 65 72 66 61 63 65 73 20 73 6f 20 74   interfaces so t
10e30 68 61 74 20 61 6e 20 61 70 70 6c 69 63 61 74 69  hat an applicati
10e40 6f 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65 73 20  on usually does 
10e50 6e 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 69  not need to.** i
10e60 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e  nvoke sqlite3_in
10e70 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63  itialize() direc
10e80 74 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c  tly.  For exampl
10e90 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  e, [sqlite3_open
10ea0 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 6c  ()].** calls sql
10eb0 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
10ec0 29 20 73 6f 20 74 68 65 20 53 51 4c 69 74 65 20  ) so the SQLite 
10ed0 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 62 65 20  library will be 
10ee0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a  automatically.**
10ef0 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 77 68 65   initialized whe
10f00 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  n [sqlite3_open(
10f10 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 69 66 20  )] is called if 
10f20 69 74 20 68 61 73 20 6e 6f 74 20 62 65 20 69 6e  it has not be in
10f30 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72  itialized.** alr
10f40 65 61 64 79 2e 20 20 5e 48 6f 77 65 76 65 72 2c  eady.  ^However,
10f50 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f   if SQLite is co
10f60 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 20  mpiled with the 
10f70 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54  [SQLITE_OMIT_AUT
10f80 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c  OINIT].** compil
10f90 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 74  e-time option, t
10fa0 68 65 6e 20 74 68 65 20 61 75 74 6f 6d 61 74 69  hen the automati
10fb0 63 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  c calls to sqlit
10fc0 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a  e3_initialize().
10fd0 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65 64 20 61  ** are omitted a
10fe0 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  nd the applicati
10ff0 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73 71 6c  on must call sql
11000 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
11010 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70 72  ) directly.** pr
11020 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79  ior to using any
11030 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e   other SQLite in
11040 74 65 72 66 61 63 65 2e 20 20 46 6f 72 20 6d 61  terface.  For ma
11050 78 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69 74  ximum portabilit
11060 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65 63 6f  y,.** it is reco
11070 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70  mmended that app
11080 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77 61 79 73  lications always
11090 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
110a0 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20  initialize().** 
110b0 64 69 72 65 63 74 6c 79 20 70 72 69 6f 72 20 74  directly prior t
110c0 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65  o using any othe
110d0 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  r SQLite interfa
110e0 63 65 2e 20 20 46 75 74 75 72 65 20 72 65 6c 65  ce.  Future rele
110f0 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69 74  ases.** of SQLit
11100 65 20 6d 61 79 20 72 65 71 75 69 72 65 20 74 68  e may require th
11110 69 73 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f  is.  In other wo
11120 72 64 73 2c 20 74 68 65 20 62 65 68 61 76 69 6f  rds, the behavio
11130 72 20 65 78 68 69 62 69 74 65 64 0a 2a 2a 20 77  r exhibited.** w
11140 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f  hen SQLite is co
11150 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c  mpiled with [SQL
11160 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49  ITE_OMIT_AUTOINI
11170 54 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d 65 20  T] might become 
11180 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20 62  the.** default b
11190 65 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65 20  ehavior in some 
111a0 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f  future release o
111b0 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20  f SQLite..**.** 
111c0 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  The sqlite3_os_i
111d0 6e 69 74 28 29 20 72 6f 75 74 69 6e 65 20 64 6f  nit() routine do
111e0 65 73 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73  es operating-sys
111f0 74 65 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a 20  tem specific.** 
11200 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f  initialization o
11210 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62  f the SQLite lib
11220 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c 69 74  rary.  The sqlit
11230 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 72  e3_os_end().** r
11240 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 20 74 68  outine undoes th
11250 65 20 65 66 66 65 63 74 20 6f 66 20 73 71 6c 69  e effect of sqli
11260 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20  te3_os_init().  
11270 54 79 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a 2a  Typical tasks.**
11280 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20 74 68   performed by th
11290 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69 6e 63  ese routines inc
112a0 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  lude allocation 
112b0 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a  or deallocation.
112c0 2a 2a 20 6f 66 20 73 74 61 74 69 63 20 72 65 73  ** of static res
112d0 6f 75 72 63 65 73 2c 20 69 6e 69 74 69 61 6c 69  ources, initiali
112e0 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c  zation of global
112f0 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20 73   variables,.** s
11300 65 74 74 69 6e 67 20 75 70 20 61 20 64 65 66 61  etting up a defa
11310 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  ult [sqlite3_vfs
11320 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65 74  ] module, or set
11330 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65 66  ting up.** a def
11340 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69  ault configurati
11350 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  on using [sqlite
11360 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a  3_config()]..**.
11370 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
11380 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20  on should never 
11390 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 73 71  invoke either sq
113a0 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a  lite3_os_init().
113b0 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73  ** or sqlite3_os
113c0 5f 65 6e 64 28 29 20 64 69 72 65 63 74 6c 79 2e  _end() directly.
113d0 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f    The applicatio
113e0 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e  n should only in
113f0 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  voke.** sqlite3_
11400 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64  initialize() and
11410 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
11420 6e 28 29 2e 20 20 54 68 65 20 73 71 6c 69 74 65  n().  The sqlite
11430 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 69  3_os_init().** i
11440 6e 74 65 72 66 61 63 65 20 69 73 20 63 61 6c 6c  nterface is call
11450 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ed automatically
11460 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   by sqlite3_init
11470 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a 20  ialize() and.** 
11480 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
11490 20 69 73 20 63 61 6c 6c 65 64 20 62 79 20 73 71   is called by sq
114a0 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
114b0 2e 20 20 41 70 70 72 6f 70 72 69 61 74 65 0a 2a  .  Appropriate.*
114c0 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
114d0 73 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73  s for sqlite3_os
114e0 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69  _init() and sqli
114f0 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20  te3_os_end().** 
11500 61 72 65 20 62 75 69 6c 74 20 69 6e 74 6f 20 53  are built into S
11510 51 4c 69 74 65 20 77 68 65 6e 20 69 74 20 69 73  QLite when it is
11520 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 55 6e   compiled for Un
11530 69 78 2c 20 57 69 6e 64 6f 77 73 2c 20 6f 72 20  ix, Windows, or 
11540 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63  OS/2..** When [c
11550 75 73 74 6f 6d 20 62 75 69 6c 64 73 20 7c 20 62  ustom builds | b
11560 75 69 6c 74 20 66 6f 72 20 6f 74 68 65 72 20 70  uilt for other p
11570 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73  latforms].** (us
11580 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ing the [SQLITE_
11590 4f 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f 6d 70  OS_OTHER=1] comp
115a0 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69  ile-time.** opti
115b0 6f 6e 29 20 74 68 65 20 61 70 70 6c 69 63 61 74  on) the applicat
115c0 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c 79 20  ion must supply 
115d0 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70 6c 65  a suitable imple
115e0 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a  mentation for.**
115f0 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
11600 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f  () and sqlite3_o
11610 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61 70 70  s_end().  An app
11620 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65  lication-supplie
11630 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  d.** implementat
11640 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f  ion of sqlite3_o
11650 73 5f 69 6e 69 74 28 29 20 6f 72 20 73 71 6c 69  s_init() or sqli
11660 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20  te3_os_end().** 
11670 6d 75 73 74 20 72 65 74 75 72 6e 20 5b 53 51 4c  must return [SQL
11680 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65  ITE_OK] on succe
11690 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65  ss and some othe
116a0 72 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 75  r [error code] u
116b0 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a  pon.** failure..
116c0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
116d0 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  t sqlite3_initia
116e0 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 53 51 4c 49  lize(void);.SQLI
116f0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
11700 65 33 5f 73 68 75 74 64 6f 77 6e 28 76 6f 69 64  e3_shutdown(void
11710 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
11720 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  t sqlite3_os_ini
11730 74 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f  t(void);.SQLITE_
11740 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
11750 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f  os_end(void);../
11760 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
11770 6f 6e 66 69 67 75 72 69 6e 67 20 54 68 65 20 53  onfiguring The S
11780 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a  QLite Library.**
11790 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
117a0 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61  config() interfa
117b0 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61  ce is used to ma
117c0 6b 65 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67  ke global config
117d0 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67  uration.** chang
117e0 65 73 20 74 6f 20 53 51 4c 69 74 65 20 69 6e 20  es to SQLite in 
117f0 6f 72 64 65 72 20 74 6f 20 74 75 6e 65 20 53 51  order to tune SQ
11800 4c 69 74 65 20 74 6f 20 74 68 65 20 73 70 65 63  Lite to the spec
11810 69 66 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a  ific needs of.**
11820 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
11830 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 63  .  The default c
11840 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 69 73 20  onfiguration is 
11850 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20  recommended for 
11860 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74  most.** applicat
11870 69 6f 6e 73 20 61 6e 64 20 73 6f 20 74 68 69 73  ions and so this
11880 20 72 6f 75 74 69 6e 65 20 69 73 20 75 73 75 61   routine is usua
11890 6c 6c 79 20 6e 6f 74 20 6e 65 63 65 73 73 61 72  lly not necessar
118a0 79 2e 20 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f  y.  It is.** pro
118b0 76 69 64 65 64 20 74 6f 20 73 75 70 70 6f 72 74  vided to support
118c0 20 72 61 72 65 20 61 70 70 6c 69 63 61 74 69 6f   rare applicatio
118d0 6e 73 20 77 69 74 68 20 75 6e 75 73 75 61 6c 20  ns with unusual 
118e0 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  needs..**.** The
118f0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
11900 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e  ) interface is n
11910 6f 74 20 74 68 72 65 61 64 73 61 66 65 2e 20 20  ot threadsafe.  
11920 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a  The application.
11930 2a 2a 20 6d 75 73 74 20 69 6e 73 75 72 65 20 74  ** must insure t
11940 68 61 74 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c  hat no other SQL
11950 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 61  ite interfaces a
11960 72 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74  re invoked by ot
11970 68 65 72 0a 2a 2a 20 74 68 72 65 61 64 73 20 77  her.** threads w
11980 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e  hile sqlite3_con
11990 66 69 67 28 29 20 69 73 20 72 75 6e 6e 69 6e 67  fig() is running
119a0 2e 20 20 46 75 72 74 68 65 72 6d 6f 72 65 2c 20  .  Furthermore, 
119b0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
119c0 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  .** may only be 
119d0 69 6e 76 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f  invoked prior to
119e0 20 6c 69 62 72 61 72 79 20 69 6e 69 74 69 61 6c   library initial
119f0 69 7a 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a  ization using.**
11a00 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61   [sqlite3_initia
11a10 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72  lize()] or after
11a20 20 73 68 75 74 64 6f 77 6e 20 62 79 20 5b 73 71   shutdown by [sq
11a30 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
11a40 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  ]..** ^If sqlite
11a50 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 63 61  3_config() is ca
11a60 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69  lled after [sqli
11a70 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
11a80 5d 20 61 6e 64 20 62 65 66 6f 72 65 0a 2a 2a 20  ] and before.** 
11a90 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77  [sqlite3_shutdow
11aa0 6e 28 29 5d 20 74 68 65 6e 20 69 74 20 77 69 6c  n()] then it wil
11ab0 6c 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f  l return SQLITE_
11ac0 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c  MISUSE..** Note,
11ad0 20 68 6f 77 65 76 65 72 2c 20 74 68 61 74 20 5e   however, that ^
11ae0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
11af0 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61   can be called a
11b00 73 20 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a  s part of the.**
11b10 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
11b20 6f 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  of an applicatio
11b30 6e 2d 64 65 66 69 6e 65 64 20 5b 73 71 6c 69 74  n-defined [sqlit
11b40 65 33 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a  e3_os_init()]..*
11b50 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  *.** The first a
11b60 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
11b70 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 61  e3_config() is a
11b80 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 63 6f  n integer.** [co
11b90 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
11ba0 6f 6e 5d 20 74 68 61 74 20 64 65 74 65 72 6d 69  on] that determi
11bb0 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f 70  nes.** what prop
11bc0 65 72 74 79 20 6f 66 20 53 51 4c 69 74 65 20 69  erty of SQLite i
11bd0 73 20 74 6f 20 62 65 20 63 6f 6e 66 69 67 75 72  s to be configur
11be0 65 64 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20  ed.  Subsequent 
11bf0 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 72  arguments.** var
11c00 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  y depending on t
11c10 68 65 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f  he [configuratio
11c20 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20  n option].** in 
11c30 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
11c40 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20  nt..**.** ^When 
11c50 61 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  a configuration 
11c60 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 2c 20 73  option is set, s
11c70 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
11c80 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
11c90 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  OK]..** ^If the 
11ca0 6f 70 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77  option is unknow
11cb0 6e 20 6f 72 20 53 51 4c 69 74 65 20 69 73 20 75  n or SQLite is u
11cc0 6e 61 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65  nable to set the
11cd0 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20   option.** then 
11ce0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74  this routine ret
11cf0 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20  urns a non-zero 
11d00 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f  [error code]..*/
11d10 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
11d20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 69  sqlite3_config(i
11d30 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a  nt, ...);../*.**
11d40 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69   CAPI3REF: Confi
11d50 67 75 72 65 20 64 61 74 61 62 61 73 65 20 63 6f  gure database co
11d60 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  nnections.**.** 
11d70 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 63  The sqlite3_db_c
11d80 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63  onfig() interfac
11d90 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b  e is used to mak
11da0 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a  e configuration.
11db0 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 61 20  ** changes to a 
11dc0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
11dd0 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65  tion].  The inte
11de0 72 66 61 63 65 20 69 73 20 73 69 6d 69 6c 61 72  rface is similar
11df0 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
11e00 63 6f 6e 66 69 67 28 29 5d 20 65 78 63 65 70 74  config()] except
11e10 20 74 68 61 74 20 74 68 65 20 63 68 61 6e 67 65   that the change
11e20 73 20 61 70 70 6c 79 20 74 6f 20 61 20 73 69 6e  s apply to a sin
11e30 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  gle.** [database
11e40 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70   connection] (sp
11e50 65 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 66  ecified in the f
11e60 69 72 73 74 20 61 72 67 75 6d 65 6e 74 29 2e 0a  irst argument)..
11e70 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  **.** The second
11e80 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
11e90 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44  ite3_db_config(D
11ea0 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a  ,V,...)  is the.
11eb0 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ** [SQLITE_DBCON
11ec0 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 7c 20  FIG_LOOKASIDE | 
11ed0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65  configuration ve
11ee0 72 62 5d 20 2d 20 61 6e 20 69 6e 74 65 67 65 72  rb] - an integer
11ef0 20 63 6f 64 65 20 0a 2a 2a 20 74 68 61 74 20 69   code .** that i
11f00 6e 64 69 63 61 74 65 73 20 77 68 61 74 20 61 73  ndicates what as
11f10 70 65 63 74 20 6f 66 20 74 68 65 20 5b 64 61 74  pect of the [dat
11f20 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
11f30 5d 20 69 73 20 62 65 69 6e 67 20 63 6f 6e 66 69  ] is being confi
11f40 67 75 72 65 64 2e 0a 2a 2a 20 53 75 62 73 65 71  gured..** Subseq
11f50 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 20 76  uent arguments v
11f60 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ary depending on
11f70 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69   the configurati
11f80 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e  on verb..**.** ^
11f90 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  Calls to sqlite3
11fa0 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 72 65 74  _db_config() ret
11fb0 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66  urn SQLITE_OK if
11fc0 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20   and only if.** 
11fd0 74 68 65 20 63 61 6c 6c 20 69 73 20 63 6f 6e 73  the call is cons
11fe0 69 64 65 72 65 64 20 73 75 63 63 65 73 73 66 75  idered successfu
11ff0 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  l..*/.SQLITE_API
12000 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f   int sqlite3_db_
12010 63 6f 6e 66 69 67 28 73 71 6c 69 74 65 33 2a 2c  config(sqlite3*,
12020 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a   int op, ...);..
12030 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
12040 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f  Memory Allocatio
12050 6e 20 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a  n Routines.**.**
12060 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   An instance of 
12070 74 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69  this object defi
12080 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63  nes the interfac
12090 65 20 62 65 74 77 65 65 6e 20 53 51 4c 69 74 65  e between SQLite
120a0 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65  .** and low-leve
120b0 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  l memory allocat
120c0 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  ion routines..**
120d0 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20  .** This object 
120e0 69 73 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20  is used in only 
120f0 6f 6e 65 20 70 6c 61 63 65 20 69 6e 20 74 68 65  one place in the
12100 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
12110 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20  e..** A pointer 
12120 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
12130 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73  f this object is
12140 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f   the argument to
12150 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
12160 66 69 67 28 29 5d 20 77 68 65 6e 20 74 68 65 20  fig()] when the 
12170 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
12180 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49  tion is.** [SQLI
12190 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
121a0 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  ] or [SQLITE_CON
121b0 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20  FIG_GETMALLOC]. 
121c0 20 0a 2a 2a 20 42 79 20 63 72 65 61 74 69 6e 67   .** By creating
121d0 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
121e0 74 68 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61  this object.** a
121f0 6e 64 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f  nd passing it to
12200 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
12210 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ]([SQLITE_CONFIG
12220 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72  _MALLOC]).** dur
12230 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ing configuratio
12240 6e 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  n, an applicatio
12250 6e 20 63 61 6e 20 73 70 65 63 69 66 79 20 61 6e  n can specify an
12260 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20   alternative.** 
12270 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
12280 6e 20 73 75 62 73 79 73 74 65 6d 20 66 6f 72 20  n subsystem for 
12290 53 51 4c 69 74 65 20 74 6f 20 75 73 65 20 66 6f  SQLite to use fo
122a0 72 20 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a 20  r all of its.** 
122b0 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e  dynamic memory n
122c0 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  eeds..**.** Note
122d0 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 6f 6d   that SQLite com
122e0 65 73 20 77 69 74 68 20 73 65 76 65 72 61 6c 20  es with several 
122f0 5b 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79  [built-in memory
12300 20 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20   allocators].** 
12310 74 68 61 74 20 61 72 65 20 70 65 72 66 65 63 74  that are perfect
12320 6c 79 20 61 64 65 71 75 61 74 65 20 66 6f 72 20  ly adequate for 
12330 74 68 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67  the overwhelming
12340 20 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70   majority of app
12350 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64  lications.** and
12360 20 74 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63   that this objec
12370 74 20 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c  t is only useful
12380 20 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72   to a tiny minor
12390 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69  ity of applicati
123a0 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63  ons.** with spec
123b0 69 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61  ialized memory a
123c0 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72  llocation requir
123d0 65 6d 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62  ements.  This ob
123e0 6a 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20  ject is.** also 
123f0 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74  used during test
12400 69 6e 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e  ing of SQLite in
12410 20 6f 72 64 65 72 20 74 6f 20 73 70 65 63 69 66   order to specif
12420 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65  y an alternative
12430 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  .** memory alloc
12440 61 74 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61  ator that simula
12450 74 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f  tes memory out-o
12460 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69  f-memory conditi
12470 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20  ons in.** order 
12480 74 6f 20 76 65 72 69 66 79 20 74 68 61 74 20 53  to verify that S
12490 51 4c 69 74 65 20 72 65 63 6f 76 65 72 73 20 67  QLite recovers g
124a0 72 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73  racefully from s
124b0 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e  uch.** condition
124c0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61  s..**.** The xMa
124d0 6c 6c 6f 63 2c 20 78 52 65 61 6c 6c 6f 63 2c 20  lloc, xRealloc, 
124e0 61 6e 64 20 78 46 72 65 65 20 6d 65 74 68 6f 64  and xFree method
124f0 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65  s must work like
12500 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29   the.** malloc()
12510 2c 20 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20  , realloc() and 
12520 66 72 65 65 28 29 20 66 75 6e 63 74 69 6f 6e 73  free() functions
12530 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61   from the standa
12540 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a  rd C library..**
12550 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74   ^SQLite guarant
12560 65 65 73 20 74 68 61 74 20 74 68 65 20 73 65 63  ees that the sec
12570 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  ond argument to.
12580 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 61  ** xRealloc is a
12590 6c 77 61 79 73 20 61 20 76 61 6c 75 65 20 72 65  lways a value re
125a0 74 75 72 6e 65 64 20 62 79 20 61 20 70 72 69 6f  turned by a prio
125b0 72 20 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e 64  r call to xRound
125c0 75 70 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20  up..**.** xSize 
125d0 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68  should return th
125e0 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65  e allocated size
125f0 20 6f 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c   of a memory all
12600 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76 69  ocation.** previ
12610 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66  ously obtained f
12620 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20 78  rom xMalloc or x
12630 52 65 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61 6c  Realloc.  The al
12640 6c 6f 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a 20  located size.** 
12650 69 73 20 61 6c 77 61 79 73 20 61 74 20 6c 65 61  is always at lea
12660 73 74 20 61 73 20 62 69 67 20 61 73 20 74 68 65  st as big as the
12670 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 20   requested size 
12680 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65  but may be large
12690 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 6f  r..**.** The xRo
126a0 75 6e 64 75 70 20 6d 65 74 68 6f 64 20 72 65 74  undup method ret
126b0 75 72 6e 73 20 77 68 61 74 20 77 6f 75 6c 64 20  urns what would 
126c0 62 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64  be the allocated
126d0 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d 65   size of.** a me
126e0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
126f0 67 69 76 65 6e 20 61 20 70 61 72 74 69 63 75 6c  given a particul
12700 61 72 20 72 65 71 75 65 73 74 65 64 20 73 69 7a  ar requested siz
12710 65 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a  e.  Most memory.
12720 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f  ** allocators ro
12730 75 6e 64 20 75 70 20 6d 65 6d 6f 72 79 20 61 6c  und up memory al
12740 6c 6f 63 61 74 69 6f 6e 73 20 61 74 20 6c 65 61  locations at lea
12750 73 74 20 74 6f 20 74 68 65 20 6e 65 78 74 20 6d  st to the next m
12760 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e  ultiple.** of 8.
12770 20 20 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f 72    Some allocator
12780 73 20 72 6f 75 6e 64 20 75 70 20 74 6f 20 61 20  s round up to a 
12790 6c 61 72 67 65 72 20 6d 75 6c 74 69 70 6c 65 20  larger multiple 
127a0 6f 72 20 74 6f 20 61 20 70 6f 77 65 72 20 6f 66  or to a power of
127b0 20 32 2e 0a 2a 2a 20 45 76 65 72 79 20 6d 65 6d   2..** Every mem
127c0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
127d0 65 71 75 65 73 74 20 63 6f 6d 69 6e 67 20 69 6e  equest coming in
127e0 20 74 68 72 6f 75 67 68 20 5b 73 71 6c 69 74 65   through [sqlite
127f0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f  3_malloc()].** o
12800 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  r [sqlite3_reall
12810 6f 63 28 29 5d 20 66 69 72 73 74 20 63 61 6c 6c  oc()] first call
12820 73 20 78 52 6f 75 6e 64 75 70 2e 20 20 49 66 20  s xRoundup.  If 
12830 78 52 6f 75 6e 64 75 70 20 72 65 74 75 72 6e 73  xRoundup returns
12840 20 30 2c 20 0a 2a 2a 20 74 68 61 74 20 63 61 75   0, .** that cau
12850 73 65 73 20 74 68 65 20 63 6f 72 72 65 73 70 6f  ses the correspo
12860 6e 64 69 6e 67 20 6d 65 6d 6f 72 79 20 61 6c 6c  nding memory all
12870 6f 63 61 74 69 6f 6e 20 74 6f 20 66 61 69 6c 2e  ocation to fail.
12880 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74  .**.** The xInit
12890 20 6d 65 74 68 6f 64 20 69 6e 69 74 69 61 6c 69   method initiali
128a0 7a 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  zes the memory a
128b0 6c 6c 6f 63 61 74 6f 72 2e 20 20 46 6f 72 20 65  llocator.  For e
128c0 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69  xample,.** it mi
128d0 67 68 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79  ght allocate any
128e0 20 72 65 71 75 69 72 65 20 6d 75 74 65 78 65 73   require mutexes
128f0 20 6f 72 20 69 6e 69 74 69 61 6c 69 7a 65 20 69   or initialize i
12900 6e 74 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20  nternal data.** 
12910 73 74 72 75 63 74 75 72 65 73 2e 20 20 54 68 65  structures.  The
12920 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f   xShutdown metho
12930 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e  d is invoked (in
12940 64 69 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20  directly) by.** 
12950 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77  [sqlite3_shutdow
12960 6e 28 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20  n()] and should 
12970 64 65 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72  deallocate any r
12980 65 73 6f 75 72 63 65 73 20 61 63 71 75 69 72 65  esources acquire
12990 64 0a 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20 20  d.** by xInit.  
129a0 54 68 65 20 70 41 70 70 44 61 74 61 20 70 6f 69  The pAppData poi
129b0 6e 74 65 72 20 69 73 20 75 73 65 64 20 61 73 20  nter is used as 
129c0 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74  the only paramet
129d0 65 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61  er to.** xInit a
129e0 6e 64 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a  nd xShutdown..**
129f0 0a 2a 2a 20 53 51 4c 69 74 65 20 68 6f 6c 64 73  .** SQLite holds
12a00 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54   the [SQLITE_MUT
12a10 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 45 52  EX_STATIC_MASTER
12a20 5d 20 6d 75 74 65 78 20 77 68 65 6e 20 69 74 20  ] mutex when it 
12a30 69 6e 76 6f 6b 65 73 0a 2a 2a 20 74 68 65 20 78  invokes.** the x
12a40 49 6e 69 74 20 6d 65 74 68 6f 64 2c 20 73 6f 20  Init method, so 
12a50 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64  the xInit method
12a60 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 74 68 72   need not be thr
12a70 65 61 64 73 61 66 65 2e 20 20 54 68 65 0a 2a 2a  eadsafe.  The.**
12a80 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f   xShutdown metho
12a90 64 20 69 73 20 6f 6e 6c 79 20 63 61 6c 6c 65 64  d is only called
12aa0 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73   from [sqlite3_s
12ab0 68 75 74 64 6f 77 6e 28 29 5d 20 73 6f 20 69 74  hutdown()] so it
12ac0 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65   does.** not nee
12ad0 64 20 74 6f 20 62 65 20 74 68 72 65 61 64 73 61  d to be threadsa
12ae0 66 65 20 65 69 74 68 65 72 2e 20 20 46 6f 72 20  fe either.  For 
12af0 61 6c 6c 20 6f 74 68 65 72 20 6d 65 74 68 6f 64  all other method
12b00 73 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c  s, SQLite.** hol
12b10 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d  ds the [SQLITE_M
12b20 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 5d  UTEX_STATIC_MEM]
12b30 20 6d 75 74 65 78 20 61 73 20 6c 6f 6e 67 20 61   mutex as long a
12b40 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  s the.** [SQLITE
12b50 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
12b60 53 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  S] configuration
12b70 20 6f 70 74 69 6f 6e 20 69 73 20 74 75 72 6e 65   option is turne
12b80 64 20 6f 6e 20 28 77 68 69 63 68 0a 2a 2a 20 69  d on (which.** i
12b90 74 20 69 73 20 62 79 20 64 65 66 61 75 6c 74 29  t is by default)
12ba0 20 61 6e 64 20 73 6f 20 74 68 65 20 6d 65 74 68   and so the meth
12bb0 6f 64 73 20 61 72 65 20 61 75 74 6f 6d 61 74 69  ods are automati
12bc0 63 61 6c 6c 79 20 73 65 72 69 61 6c 69 7a 65 64  cally serialized
12bd0 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 69 66  ..** However, if
12be0 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
12bf0 4d 45 4d 53 54 41 54 55 53 5d 20 69 73 20 64 69  MEMSTATUS] is di
12c00 73 61 62 6c 65 64 2c 20 74 68 65 6e 20 74 68 65  sabled, then the
12c10 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 74 68 6f 64   other.** method
12c20 73 20 6d 75 73 74 20 62 65 20 74 68 72 65 61 64  s must be thread
12c30 73 61 66 65 20 6f 72 20 65 6c 73 65 20 6d 61 6b  safe or else mak
12c40 65 20 74 68 65 69 72 20 6f 77 6e 20 61 72 72 61  e their own arra
12c50 6e 67 65 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a 20  ngements for.** 
12c60 73 65 72 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a  serialization..*
12c70 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c  *.** SQLite will
12c80 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 78 49   never invoke xI
12c90 6e 69 74 28 29 20 6d 6f 72 65 20 74 68 61 6e 20  nit() more than 
12ca0 6f 6e 63 65 20 77 69 74 68 6f 75 74 20 61 6e 20  once without an 
12cb0 69 6e 74 65 72 76 65 6e 69 6e 67 0a 2a 2a 20 63  intervening.** c
12cc0 61 6c 6c 20 74 6f 20 78 53 68 75 74 64 6f 77 6e  all to xShutdown
12cd0 28 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  ()..*/.typedef s
12ce0 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65  truct sqlite3_me
12cf0 6d 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65  m_methods sqlite
12d00 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73  3_mem_methods;.s
12d10 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65  truct sqlite3_me
12d20 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76 6f  m_methods {.  vo
12d30 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 69  id *(*xMalloc)(i
12d40 6e 74 29 3b 20 20 20 20 20 20 20 20 20 2f 2a 20  nt);         /* 
12d50 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  Memory allocatio
12d60 6e 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20  n function */.  
12d70 76 6f 69 64 20 28 2a 78 46 72 65 65 29 28 76 6f  void (*xFree)(vo
12d80 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 2f  id*);          /
12d90 2a 20 46 72 65 65 20 61 20 70 72 69 6f 72 20 61  * Free a prior a
12da0 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 76  llocation */.  v
12db0 6f 69 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 29  oid *(*xRealloc)
12dc0 28 76 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a  (void*,int);  /*
12dd0 20 52 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f 63   Resize an alloc
12de0 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28  ation */.  int (
12df0 2a 78 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b 20  *xSize)(void*); 
12e00 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 65 74            /* Ret
12e10 75 72 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20  urn the size of 
12e20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f  an allocation */
12e30 0a 20 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64 75  .  int (*xRoundu
12e40 70 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20  p)(int);        
12e50 20 20 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72 65    /* Round up re
12e60 71 75 65 73 74 20 73 69 7a 65 20 74 6f 20 61 6c  quest size to al
12e70 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a 2f  location size */
12e80 0a 20 20 69 6e 74 20 28 2a 78 49 6e 69 74 29 28  .  int (*xInit)(
12e90 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20  void*);         
12ea0 20 20 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65 20    /* Initialize 
12eb0 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
12ec0 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 28  ator */.  void (
12ed0 2a 78 53 68 75 74 64 6f 77 6e 29 28 76 6f 69 64  *xShutdown)(void
12ee0 2a 29 3b 20 20 20 20 20 20 2f 2a 20 44 65 69 6e  *);      /* Dein
12ef0 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d  itialize the mem
12f00 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f  ory allocator */
12f10 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74  .  void *pAppDat
12f20 61 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  a;              
12f30 20 20 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74 6f    /* Argument to
12f40 20 78 49 6e 69 74 28 29 20 61 6e 64 20 78 53 68   xInit() and xSh
12f50 75 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a  utdown() */.};..
12f60 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
12f70 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70  Configuration Op
12f80 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  tions.** KEYWORD
12f90 53 3a 20 7b 63 6f 6e 66 69 67 75 72 61 74 69 6f  S: {configuratio
12fa0 6e 20 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20  n option}.**.** 
12fb0 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
12fc0 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c  are the availabl
12fd0 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67  e integer config
12fe0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
12ff0 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70  that.** can be p
13000 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69 72  assed as the fir
13010 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
13020 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  he [sqlite3_conf
13030 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ig()] interface.
13040 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69  .**.** New confi
13050 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
13060 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
13070 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
13080 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45   of SQLite..** E
13090 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72  xisting configur
130a0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69  ation options mi
130b0 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e  ght be discontin
130c0 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ued.  Applicatio
130d0 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65  ns.** should che
130e0 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f  ck the return co
130f0 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  de from [sqlite3
13100 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61  _config()] to ma
13110 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20  ke sure that.** 
13120 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e  the call worked.
13130 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63    The [sqlite3_c
13140 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61  onfig()] interfa
13150 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61  ce will return a
13160 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72  .** non-zero [er
13170 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64  ror code] if a d
13180 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75  iscontinued or u
13190 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69  nsupported confi
131a0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a  guration option.
131b0 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a  ** is invoked..*
131c0 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53  *.** <dl>.** [[S
131d0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
131e0 47 4c 45 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e  GLETHREAD]] <dt>
131f0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
13200 4e 47 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e 0a  NGLETHREAD</dt>.
13210 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65  ** <dd>There are
13220 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f   no arguments to
13230 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e   this option.  ^
13240 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73  This option sets
13250 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69   the.** [threadi
13260 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 69 6e 67  ng mode] to Sing
13270 6c 65 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f  le-thread.  In o
13280 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64  ther words, it d
13290 69 73 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d  isables.** all m
132a0 75 74 65 78 69 6e 67 20 61 6e 64 20 70 75 74 73  utexing and puts
132b0 20 53 51 4c 69 74 65 20 69 6e 74 6f 20 61 20 6d   SQLite into a m
132c0 6f 64 65 20 77 68 65 72 65 20 69 74 20 63 61 6e  ode where it can
132d0 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a 2a   only be used.**
132e0 20 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72   by a single thr
132f0 65 61 64 2e 20 20 20 5e 49 66 20 53 51 4c 69 74  ead.   ^If SQLit
13300 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
13310 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54  th.** the [SQLIT
13320 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53  E_THREADSAFE | S
13330 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
13340 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =0] compile-time
13350 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20   option then.** 
13360 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62  it is not possib
13370 6c 65 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65  le to change the
13380 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
13390 5d 20 66 72 6f 6d 20 69 74 73 20 64 65 66 61 75  ] from its defau
133a0 6c 74 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 53  lt.** value of S
133b0 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 61 6e 64  ingle-thread and
133c0 20 73 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e   so [sqlite3_con
133d0 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75  fig()] will retu
133e0 72 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45  rn .** [SQLITE_E
133f0 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20  RROR] if called 
13400 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f  with the SQLITE_
13410 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
13420 45 41 44 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61  EAD.** configura
13430 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64  tion option.</dd
13440 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
13450 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
13460 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  EAD]] <dt>SQLITE
13470 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
13480 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  EAD</dt>.** <dd>
13490 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67  There are no arg
134a0 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f  uments to this o
134b0 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70  ption.  ^This op
134c0 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a  tion sets the.**
134d0 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
134e0 5d 20 74 6f 20 4d 75 6c 74 69 2d 74 68 72 65 61  ] to Multi-threa
134f0 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  d.  In other wor
13500 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a  ds, it disables.
13510 2a 2a 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20 5b  ** mutexing on [
13520 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
13530 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72  ion] and [prepar
13540 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62  ed statement] ob
13550 6a 65 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61 70  jects..** The ap
13560 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 72 65 73  plication is res
13570 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 73 65 72  ponsible for ser
13580 69 61 6c 69 7a 69 6e 67 20 61 63 63 65 73 73 20  ializing access 
13590 74 6f 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  to.** [database 
135a0 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64  connections] and
135b0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
135c0 6d 65 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74 68  ments].  But oth
135d0 65 72 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72  er mutexes.** ar
135e0 65 20 65 6e 61 62 6c 65 64 20 73 6f 20 74 68 61  e enabled so tha
135f0 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65  t SQLite will be
13600 20 73 61 66 65 20 74 6f 20 75 73 65 20 69 6e 20   safe to use in 
13610 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64  a multi-threaded
13620 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 20  .** environment 
13630 61 73 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77  as long as no tw
13640 6f 20 74 68 72 65 61 64 73 20 61 74 74 65 6d 70  o threads attemp
13650 74 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d  t to use the sam
13660 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  e.** [database c
13670 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 74 68  onnection] at th
13680 65 20 73 61 6d 65 20 74 69 6d 65 2e 20 20 5e 49  e same time.  ^I
13690 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
136a0 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65  iled with.** the
136b0 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
136c0 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52  AFE | SQLITE_THR
136d0 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69  EADSAFE=0] compi
136e0 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74  le-time option t
136f0 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74  hen.** it is not
13700 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74   possible to set
13710 20 74 68 65 20 4d 75 6c 74 69 2d 74 68 72 65 61   the Multi-threa
13720 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  d [threading mod
13730 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  e] and.** [sqlit
13740 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c  e3_config()] wil
13750 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  l return [SQLITE
13760 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65  _ERROR] if calle
13770 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51  d with the.** SQ
13780 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
13790 49 54 48 52 45 41 44 20 63 6f 6e 66 69 67 75 72  ITHREAD configur
137a0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64  ation option.</d
137b0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
137c0 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49  E_CONFIG_SERIALI
137d0 5a 45 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  ZED]] <dt>SQLITE
137e0 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a  _CONFIG_SERIALIZ
137f0 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  ED</dt>.** <dd>T
13800 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75  here are no argu
13810 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70  ments to this op
13820 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74  tion.  ^This opt
13830 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20  ion sets the.** 
13840 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
13850 20 74 6f 20 53 65 72 69 61 6c 69 7a 65 64 2e 20   to Serialized. 
13860 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
13870 74 68 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62  this option enab
13880 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78  les.** all mutex
13890 65 73 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 65  es including the
138a0 20 72 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75   recursive.** mu
138b0 74 65 78 65 73 20 6f 6e 20 5b 64 61 74 61 62 61  texes on [databa
138c0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61  se connection] a
138d0 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  nd [prepared sta
138e0 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e  tement] objects.
138f0 0a 2a 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64 65  .** In this mode
13900 20 28 77 68 69 63 68 20 69 73 20 74 68 65 20 64   (which is the d
13910 65 66 61 75 6c 74 20 77 68 65 6e 20 53 51 4c 69  efault when SQLi
13920 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
13930 69 74 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54  ith.** [SQLITE_T
13940 48 52 45 41 44 53 41 46 45 3d 31 5d 29 20 74 68  HREADSAFE=1]) th
13950 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  e SQLite library
13960 20 77 69 6c 6c 20 69 74 73 65 6c 66 20 73 65 72   will itself ser
13970 69 61 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a  ialize access.**
13980 20 74 6f 20 5b 64 61 74 61 62 61 73 65 20 63 6f   to [database co
13990 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b  nnections] and [
139a0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
139b0 6e 74 73 5d 20 73 6f 20 74 68 61 74 20 74 68 65  nts] so that the
139c0 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  .** application 
139d0 69 73 20 66 72 65 65 20 74 6f 20 75 73 65 20 74  is free to use t
139e0 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73  he same [databas
139f0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72  e connection] or
13a00 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72   the.** same [pr
13a10 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
13a20 5d 20 69 6e 20 64 69 66 66 65 72 65 6e 74 20 74  ] in different t
13a30 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61  hreads at the sa
13a40 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20  me time..** ^If 
13a50 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
13a60 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
13a70 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
13a80 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41  E | SQLITE_THREA
13a90 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65  DSAFE=0] compile
13aa0 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65  -time option the
13ab0 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70  n.** it is not p
13ac0 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74  ossible to set t
13ad0 68 65 20 53 65 72 69 61 6c 69 7a 65 64 20 5b 74  he Serialized [t
13ae0 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61  hreading mode] a
13af0 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  nd.** [sqlite3_c
13b00 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65  onfig()] will re
13b10 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52  turn [SQLITE_ERR
13b20 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69  OR] if called wi
13b30 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45  th the.** SQLITE
13b40 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a  _CONFIG_SERIALIZ
13b50 45 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ED configuration
13b60 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a   option.</dd>.**
13b70 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
13b80 46 49 47 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74  FIG_MALLOC]] <dt
13b90 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  >SQLITE_CONFIG_M
13ba0 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ALLOC</dt>.** <d
13bb0 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f  d> ^(The SQLITE_
13bc0 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 6f 70  CONFIG_MALLOC op
13bd0 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
13be0 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
13bf0 63 68 20 69 73 20 0a 2a 2a 20 61 20 70 6f 69 6e  ch is .** a poin
13c00 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e  ter to an instan
13c10 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ce of the [sqlit
13c20 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20  e3_mem_methods] 
13c30 73 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68  structure..** Th
13c40 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69  e argument speci
13c50 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74  fies.** alternat
13c60 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65  ive low-level me
13c70 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
13c80 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75  routines to be u
13c90 73 65 64 20 69 6e 20 70 6c 61 63 65 20 6f 66 0a  sed in place of.
13ca0 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c  ** the memory al
13cb0 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  location routine
13cc0 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c  s built into SQL
13cd0 69 74 65 2e 29 5e 20 5e 53 51 4c 69 74 65 20 6d  ite.)^ ^SQLite m
13ce0 61 6b 65 73 0a 2a 2a 20 69 74 73 20 6f 77 6e 20  akes.** its own 
13cf0 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20  private copy of 
13d00 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74  the content of t
13d10 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  he [sqlite3_mem_
13d20 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
13d30 72 65 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 65  re.** before the
13d40 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
13d50 28 29 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e 73  ()] call returns
13d60 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
13d70 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
13d80 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c  MALLOC]] <dt>SQL
13d90 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41  ITE_CONFIG_GETMA
13da0 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  LLOC</dt>.** <dd
13db0 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43  > ^(The SQLITE_C
13dc0 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20  ONFIG_GETMALLOC 
13dd0 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
13de0 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
13df0 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69  hich.** is a poi
13e00 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
13e10 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  nce of the [sqli
13e20 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
13e30 20 73 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54   structure..** T
13e40 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  he [sqlite3_mem_
13e50 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75  methods].** stru
13e60 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20  cture is filled 
13e70 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74  with the current
13e80 6c 79 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f 72  ly defined memor
13e90 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75  y allocation rou
13ea0 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73  tines.)^.** This
13eb0 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75   option can be u
13ec0 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20  sed to overload 
13ed0 74 68 65 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f  the default memo
13ee0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  ry allocation.**
13ef0 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61   routines with a
13f00 20 77 72 61 70 70 65 72 20 74 68 61 74 20 73 69   wrapper that si
13f10 6d 75 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79  mulations memory
13f20 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c   allocation fail
13f30 75 72 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73  ure or.** tracks
13f40 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 2c 20 66   memory usage, f
13f50 6f 72 20 65 78 61 6d 70 6c 65 2e 20 3c 2f 64 64  or example. </dd
13f60 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
13f70 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
13f80 53 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  S]] <dt>SQLITE_C
13f90 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c  ONFIG_MEMSTATUS<
13fa0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
13fb0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
13fc0 4d 45 4d 53 54 41 54 55 53 20 6f 70 74 69 6f 6e  MEMSTATUS option
13fd0 20 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 61 72   takes single ar
13fe0 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69  gument of type i
13ff0 6e 74 2c 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74  nt,.** interpret
14000 65 64 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e 2c  ed as a boolean,
14010 20 77 68 69 63 68 20 65 6e 61 62 6c 65 73 20 6f   which enables o
14020 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 63  r disables the c
14030 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 0a 2a 2a 20  ollection of.** 
14040 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
14050 6e 20 73 74 61 74 69 73 74 69 63 73 2e 20 5e 28  n statistics. ^(
14060 57 68 65 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  When memory allo
14070 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63  cation statistic
14080 73 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65  s are.** disable
14090 64 2c 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  d, the following
140a0 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
140b0 65 73 20 62 65 63 6f 6d 65 20 6e 6f 6e 2d 6f 70  es become non-op
140c0 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20  erational:.**   
140d0 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b  <ul>.**   <li> [
140e0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
140f0 73 65 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e  sed()].**   <li>
14100 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
14110 5f 68 69 67 68 77 61 74 65 72 28 29 5d 0a 2a 2a  _highwater()].**
14120 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33     <li> [sqlite3
14130 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74  _soft_heap_limit
14140 36 34 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20  64()].**   <li> 
14150 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73 28  [sqlite3_status(
14160 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e 0a  )].**   </ul>)^.
14170 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ** ^Memory alloc
14180 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73  ation statistics
14190 20 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20   are enabled by 
141a0 64 65 66 61 75 6c 74 20 75 6e 6c 65 73 73 20 53  default unless S
141b0 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70  QLite is.** comp
141c0 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54  iled with [SQLIT
141d0 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41  E_DEFAULT_MEMSTA
141e0 54 55 53 5d 3d 30 20 69 6e 20 77 68 69 63 68 20  TUS]=0 in which 
141f0 63 61 73 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61  case memory.** a
14200 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73  llocation statis
14210 74 69 63 73 20 61 72 65 20 64 69 73 61 62 6c 65  tics are disable
14220 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a  d by default..**
14230 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
14240 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
14250 41 54 43 48 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  ATCH]] <dt>SQLIT
14260 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48  E_CONFIG_SCRATCH
14270 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
14280 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
14290 5f 53 43 52 41 54 43 48 20 6f 70 74 69 6f 6e 20  _SCRATCH option 
142a0 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74  specifies a stat
142b0 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  ic memory buffer
142c0 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20  .** that SQLite 
142d0 63 61 6e 20 75 73 65 20 66 6f 72 20 73 63 72 61  can use for scra
142e0 74 63 68 20 6d 65 6d 6f 72 79 2e 20 20 5e 28 54  tch memory.  ^(T
142f0 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61  here are three a
14300 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 74 6f 20 53  rguments.** to S
14310 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
14320 41 54 43 48 3a 20 20 41 20 70 6f 69 6e 74 65 72  ATCH:  A pointer
14330 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c   an 8-byte.** al
14340 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20 62 75 66  igned memory buf
14350 66 65 72 20 66 72 6f 6d 20 77 68 69 63 68 20 74  fer from which t
14360 68 65 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63  he scratch alloc
14370 61 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65 0a 2a  ations will be.*
14380 2a 20 64 72 61 77 6e 2c 20 74 68 65 20 73 69 7a  * drawn, the siz
14390 65 20 6f 66 20 65 61 63 68 20 73 63 72 61 74 63  e of each scratc
143a0 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 28 73 7a  h allocation (sz
143b0 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6d 61  ),.** and the ma
143c0 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
143d0 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69  scratch allocati
143e0 6f 6e 73 20 28 4e 29 2e 29 5e 0a 2a 2a 20 54 68  ons (N).)^.** Th
143f0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
14400 20 6d 75 73 74 20 62 65 20 61 20 70 6f 69 6e 74   must be a point
14410 65 72 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20  er to an 8-byte 
14420 61 6c 69 67 6e 65 64 20 62 75 66 66 65 72 0a 2a  aligned buffer.*
14430 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a  * of at least sz
14440 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f  *N bytes of memo
14450 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77  ry..** ^SQLite w
14460 69 6c 6c 20 6e 6f 74 20 75 73 65 20 6d 6f 72 65  ill not use more
14470 20 74 68 61 6e 20 6f 6e 65 20 73 63 72 61 74 63   than one scratc
14480 68 20 62 75 66 66 65 72 73 20 70 65 72 20 74 68  h buffers per th
14490 72 65 61 64 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  read..** ^SQLite
144a0 20 77 69 6c 6c 20 6e 65 76 65 72 20 72 65 71 75   will never requ
144b0 65 73 74 20 61 20 73 63 72 61 74 63 68 20 62 75  est a scratch bu
144c0 66 66 65 72 20 74 68 61 74 20 69 73 20 6d 6f 72  ffer that is mor
144d0 65 20 74 68 61 6e 20 36 0a 2a 2a 20 74 69 6d 65  e than 6.** time
144e0 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 70  s the database p
144f0 61 67 65 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66  age size..** ^If
14500 20 53 51 4c 69 74 65 20 6e 65 65 64 73 20 6e 65   SQLite needs ne
14510 65 64 73 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  eds additional.*
14520 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79  * scratch memory
14530 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20   beyond what is 
14540 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 69 73  provided by this
14550 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
14560 70 74 69 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a 20  ption, then .** 
14570 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
14580 29 5d 20 77 69 6c 6c 20 62 65 20 75 73 65 64 20  )] will be used 
14590 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6d 65  to obtain the me
145a0 6d 6f 72 79 20 6e 65 65 64 65 64 2e 3c 70 3e 0a  mory needed.<p>.
145b0 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 61 70 70  ** ^When the app
145c0 6c 69 63 61 74 69 6f 6e 20 70 72 6f 76 69 64 65  lication provide
145d0 73 20 61 6e 79 20 61 6d 6f 75 6e 74 20 6f 66 20  s any amount of 
145e0 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 75  scratch memory u
145f0 73 69 6e 67 0a 2a 2a 20 53 51 4c 49 54 45 5f 43  sing.** SQLITE_C
14600 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 2c 20 53  ONFIG_SCRATCH, S
14610 51 4c 69 74 65 20 61 76 6f 69 64 73 20 75 6e 6e  QLite avoids unn
14620 65 63 65 73 73 61 72 79 20 6c 61 72 67 65 0a 2a  ecessary large.*
14630 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  * [sqlite3_mallo
14640 63 7c 68 65 61 70 20 61 6c 6c 6f 63 61 74 69 6f  c|heap allocatio
14650 6e 73 5d 2e 0a 2a 2a 20 54 68 69 73 20 63 61 6e  ns]..** This can
14660 20 68 65 6c 70 20 5b 52 6f 62 73 6f 6e 20 70 72   help [Robson pr
14670 6f 6f 66 7c 70 72 65 76 65 6e 74 20 6d 65 6d 6f  oof|prevent memo
14680 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61  ry allocation fa
14690 69 6c 75 72 65 73 5d 20 64 75 65 20 74 6f 20 68  ilures] due to h
146a0 65 61 70 0a 2a 2a 20 66 72 61 67 6d 65 6e 74 61  eap.** fragmenta
146b0 74 69 6f 6e 20 69 6e 20 6c 6f 77 2d 6d 65 6d 6f  tion in low-memo
146c0 72 79 20 65 6d 62 65 64 64 65 64 20 73 79 73 74  ry embedded syst
146d0 65 6d 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a  ems..** </dd>.**
146e0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
146f0 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 5d 20  FIG_PAGECACHE]] 
14700 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
14710 47 5f 50 41 47 45 43 41 43 48 45 3c 2f 64 74 3e  G_PAGECACHE</dt>
14720 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51  .** <dd> ^The SQ
14730 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
14740 43 41 43 48 45 20 6f 70 74 69 6f 6e 20 73 70 65  CACHE option spe
14750 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20  cifies a static 
14760 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 0a 2a 2a  memory buffer.**
14770 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e   that SQLite can
14780 20 75 73 65 20 66 6f 72 20 74 68 65 20 64 61 74   use for the dat
14790 61 62 61 73 65 20 70 61 67 65 20 63 61 63 68 65  abase page cache
147a0 20 77 69 74 68 20 74 68 65 20 64 65 66 61 75 6c   with the defaul
147b0 74 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20  t page.** cache 
147c0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20  implementation. 
147d0 20 0a 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69 67   .** This config
147e0 75 72 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e  uration should n
147f0 6f 74 20 62 65 20 75 73 65 64 20 69 66 20 61 6e  ot be used if an
14800 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
14810 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63 61 63 68  ine page.** cach
14820 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
14830 20 69 73 20 6c 6f 61 64 65 64 20 75 73 69 6e 67   is loaded using
14840 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e   the [SQLITE_CON
14850 46 49 47 5f 50 43 41 43 48 45 32 5d 0a 2a 2a 20  FIG_PCACHE2].** 
14860 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
14870 74 69 6f 6e 2e 0a 2a 2a 20 5e 54 68 65 72 65 20  tion..** ^There 
14880 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65  are three argume
14890 6e 74 73 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f  nts to SQLITE_CO
148a0 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 3a 20  NFIG_PAGECACHE: 
148b0 41 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20  A pointer to.** 
148c0 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 0a 2a  8-byte aligned.*
148d0 2a 20 6d 65 6d 6f 72 79 2c 20 74 68 65 20 73 69  * memory, the si
148e0 7a 65 20 6f 66 20 65 61 63 68 20 70 61 67 65 20  ze of each page 
148f0 62 75 66 66 65 72 20 28 73 7a 29 2c 20 61 6e 64  buffer (sz), and
14900 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70   the number of p
14910 61 67 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65  ages (N)..** The
14920 20 73 7a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f   sz argument sho
14930 75 6c 64 20 62 65 20 74 68 65 20 73 69 7a 65 20  uld be the size 
14940 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 64  of the largest d
14950 61 74 61 62 61 73 65 20 70 61 67 65 0a 2a 2a 20  atabase page.** 
14960 28 61 20 70 6f 77 65 72 20 6f 66 20 74 77 6f 20  (a power of two 
14970 62 65 74 77 65 65 6e 20 35 31 32 20 61 6e 64 20  between 512 and 
14980 36 35 35 33 36 29 20 70 6c 75 73 20 73 6f 6d 65  65536) plus some
14990 20 65 78 74 72 61 20 62 79 74 65 73 20 66 6f 72   extra bytes for
149a0 20 65 61 63 68 0a 2a 2a 20 70 61 67 65 20 68 65   each.** page he
149b0 61 64 65 72 2e 20 20 5e 54 68 65 20 6e 75 6d 62  ader.  ^The numb
149c0 65 72 20 6f 66 20 65 78 74 72 61 20 62 79 74 65  er of extra byte
149d0 73 20 6e 65 65 64 65 64 20 62 79 20 74 68 65 20  s needed by the 
149e0 70 61 67 65 20 68 65 61 64 65 72 0a 2a 2a 20 63  page header.** c
149f0 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64  an be determined
14a00 20 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49   using the [SQLI
14a10 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
14a20 5f 48 44 52 53 5a 5d 20 6f 70 74 69 6f 6e 20 0a  _HDRSZ] option .
14a30 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ** to [sqlite3_c
14a40 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 20 5e 49 74  onfig()]..** ^It
14a50 20 69 73 20 68 61 72 6d 6c 65 73 73 2c 20 61 70   is harmless, ap
14a60 61 72 74 20 66 72 6f 6d 20 74 68 65 20 77 61 73  art from the was
14a70 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 66  ted memory,.** f
14a80 6f 72 20 74 68 65 20 73 7a 20 70 61 72 61 6d 65  or the sz parame
14a90 74 65 72 20 74 6f 20 62 65 20 6c 61 72 67 65 72  ter to be larger
14aa0 20 74 68 61 6e 20 6e 65 63 65 73 73 61 72 79 2e   than necessary.
14ab0 20 20 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 61    The first.** a
14ac0 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70  rgument should p
14ad0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d 62  ointer to an 8-b
14ae0 79 74 65 20 61 6c 69 67 6e 65 64 20 62 6c 6f 63  yte aligned bloc
14af0 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 74 68 61 74  k of memory that
14b00 0a 2a 2a 20 69 73 20 61 74 20 6c 65 61 73 74 20  .** is at least 
14b10 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65  sz*N bytes of me
14b20 6d 6f 72 79 2c 20 6f 74 68 65 72 77 69 73 65 20  mory, otherwise 
14b30 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 76  subsequent behav
14b40 69 6f 72 20 69 73 0a 2a 2a 20 75 6e 64 65 66 69  ior is.** undefi
14b50 6e 65 64 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ned..** ^SQLite 
14b60 77 69 6c 6c 20 75 73 65 20 74 68 65 20 6d 65 6d  will use the mem
14b70 6f 72 79 20 70 72 6f 76 69 64 65 64 20 62 79 20  ory provided by 
14b80 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
14b90 6e 74 20 74 6f 20 73 61 74 69 73 66 79 20 69 74  nt to satisfy it
14ba0 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e 65 65 64  s.** memory need
14bb0 73 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20  s for the first 
14bc0 4e 20 70 61 67 65 73 20 74 68 61 74 20 69 74 20  N pages that it 
14bd0 61 64 64 73 20 74 6f 20 63 61 63 68 65 2e 20 20  adds to cache.  
14be0 5e 49 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  ^If additional.*
14bf0 2a 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d  * page cache mem
14c00 6f 72 79 20 69 73 20 6e 65 65 64 65 64 20 62 65  ory is needed be
14c10 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f  yond what is pro
14c20 76 69 64 65 64 20 62 79 20 74 68 69 73 20 6f 70  vided by this op
14c30 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20 53 51  tion, then.** SQ
14c40 4c 69 74 65 20 67 6f 65 73 20 74 6f 20 5b 73 71  Lite goes to [sq
14c50 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
14c60 66 6f 72 20 74 68 65 20 61 64 64 69 74 69 6f 6e  for the addition
14c70 61 6c 20 73 74 6f 72 61 67 65 20 73 70 61 63 65  al storage space
14c80 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
14c90 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41  QLITE_CONFIG_HEA
14ca0 50 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  P]] <dt>SQLITE_C
14cb0 4f 4e 46 49 47 5f 48 45 41 50 3c 2f 64 74 3e 0a  ONFIG_HEAP</dt>.
14cc0 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c  ** <dd> ^The SQL
14cd0 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20  ITE_CONFIG_HEAP 
14ce0 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73  option specifies
14cf0 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79   a static memory
14d00 20 62 75 66 66 65 72 20 0a 2a 2a 20 74 68 61 74   buffer .** that
14d10 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65   SQLite will use
14d20 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20   for all of its 
14d30 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61  dynamic memory a
14d40 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 0a  llocation needs.
14d50 2a 2a 20 62 65 79 6f 6e 64 20 74 68 6f 73 65 20  ** beyond those 
14d60 70 72 6f 76 69 64 65 64 20 66 6f 72 20 62 79 20  provided for by 
14d70 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
14d80 43 52 41 54 43 48 5d 20 61 6e 64 0a 2a 2a 20 5b  CRATCH] and.** [
14d90 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
14da0 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 5e 54 68  GECACHE]..** ^Th
14db0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
14dc0 48 45 41 50 20 6f 70 74 69 6f 6e 20 69 73 20 6f  HEAP option is o
14dd0 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66  nly available if
14de0 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
14df0 6c 65 64 0a 2a 2a 20 77 69 74 68 20 65 69 74 68  led.** with eith
14e00 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  er [SQLITE_ENABL
14e10 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 20 5b 53  E_MEMSYS3] or [S
14e20 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d  QLITE_ENABLE_MEM
14e30 53 59 53 35 5d 20 61 6e 64 20 72 65 74 75 72 6e  SYS5] and return
14e40 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52  s.** [SQLITE_ERR
14e50 4f 52 5d 20 69 66 20 69 6e 76 6f 6b 65 64 20 6f  OR] if invoked o
14e60 74 68 65 72 77 69 73 65 2e 0a 2a 2a 20 5e 54 68  therwise..** ^Th
14e70 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72  ere are three ar
14e80 67 75 6d 65 6e 74 73 20 74 6f 20 53 51 4c 49 54  guments to SQLIT
14e90 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3a 0a 2a  E_CONFIG_HEAP:.*
14ea0 2a 20 41 6e 20 38 2d 62 79 74 65 20 61 6c 69 67  * An 8-byte alig
14eb0 6e 65 64 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  ned pointer to t
14ec0 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68  he memory,.** th
14ed0 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
14ee0 73 20 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20  s in the memory 
14ef0 62 75 66 66 65 72 2c 20 61 6e 64 20 74 68 65 20  buffer, and the 
14f00 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69  minimum allocati
14f10 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20  on size..** ^If 
14f20 74 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65  the first pointe
14f30 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f  r (the memory po
14f40 69 6e 74 65 72 29 20 69 73 20 4e 55 4c 4c 2c 20  inter) is NULL, 
14f50 74 68 65 6e 20 53 51 4c 69 74 65 20 72 65 76 65  then SQLite reve
14f60 72 74 73 0a 2a 2a 20 74 6f 20 75 73 69 6e 67 20  rts.** to using 
14f70 69 74 73 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f  its default memo
14f80 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 28 74 68  ry allocator (th
14f90 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28  e system malloc(
14fa0 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  ) implementation
14fb0 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20 61 6e  ),.** undoing an
14fc0 79 20 70 72 69 6f 72 20 69 6e 76 6f 63 61 74 69  y prior invocati
14fd0 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f 43 4f  on of [SQLITE_CO
14fe0 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 5e  NFIG_MALLOC].  ^
14ff0 49 66 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79  If the.** memory
15000 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20   pointer is not 
15010 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 61 6c  NULL then the al
15020 74 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79  ternative memory
15030 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 20 69 73  .** allocator is
15040 20 65 6e 67 61 67 65 64 20 74 6f 20 68 61 6e 64   engaged to hand
15050 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c 69 74 65  le all of SQLite
15060 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  s memory allocat
15070 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20 54 68  ion needs..** Th
15080 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20  e first pointer 
15090 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e  (the memory poin
150a0 74 65 72 29 20 6d 75 73 74 20 62 65 20 61 6c 69  ter) must be ali
150b0 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74  gned to an 8-byt
150c0 65 0a 2a 2a 20 62 6f 75 6e 64 61 72 79 20 6f 72  e.** boundary or
150d0 20 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61   subsequent beha
150e0 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 20 77  vior of SQLite w
150f0 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64  ill be undefined
15100 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e 69 6d 75 6d  ..** The minimum
15110 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65   allocation size
15120 20 69 73 20 63 61 70 70 65 64 20 61 74 20 32 2a   is capped at 2*
15130 2a 31 32 2e 20 52 65 61 73 6f 6e 61 62 6c 65 20  *12. Reasonable 
15140 76 61 6c 75 65 73 0a 2a 2a 20 66 6f 72 20 74 68  values.** for th
15150 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61  e minimum alloca
15160 74 69 6f 6e 20 73 69 7a 65 20 61 72 65 20 32 2a  tion size are 2*
15170 2a 35 20 74 68 72 6f 75 67 68 20 32 2a 2a 38 2e  *5 through 2**8.
15180 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
15190 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45  LITE_CONFIG_MUTE
151a0 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  X]] <dt>SQLITE_C
151b0 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e  ONFIG_MUTEX</dt>
151c0 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53  .** <dd> ^(The S
151d0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54  QLITE_CONFIG_MUT
151e0 45 58 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  EX option takes 
151f0 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
15200 74 20 77 68 69 63 68 20 69 73 20 61 0a 2a 2a 20  t which is a.** 
15210 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
15220 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73  stance of the [s
15230 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
15240 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
15250 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74  .** The argument
15260 20 73 70 65 63 69 66 69 65 73 20 61 6c 74 65 72   specifies alter
15270 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c  native low-level
15280 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20   mutex routines 
15290 74 6f 20 62 65 20 75 73 65 64 0a 2a 2a 20 69 6e  to be used.** in
152a0 20 70 6c 61 63 65 20 74 68 65 20 6d 75 74 65 78   place the mutex
152b0 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20   routines built 
152c0 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 20  into SQLite.)^  
152d0 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20  ^SQLite makes a 
152e0 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63  copy of.** the c
152f0 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73  ontent of the [s
15300 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
15310 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 20  hods] structure 
15320 62 65 66 6f 72 65 20 74 68 65 20 63 61 6c 6c 20  before the call 
15330 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  to.** [sqlite3_c
15340 6f 6e 66 69 67 28 29 5d 20 72 65 74 75 72 6e 73  onfig()] returns
15350 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20  . ^If SQLite is 
15360 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
15370 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
15380 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45  EADSAFE | SQLITE
15390 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63  _THREADSAFE=0] c
153a0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
153b0 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65  on then.** the e
153c0 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73  ntire mutexing s
153d0 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74  ubsystem is omit
153e0 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69  ted from the bui
153f0 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c  ld and hence cal
15400 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ls to.** [sqlite
15410 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68  3_config()] with
15420 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46   the SQLITE_CONF
15430 49 47 5f 4d 55 54 45 58 20 63 6f 6e 66 69 67 75  IG_MUTEX configu
15440 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69  ration option wi
15450 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51  ll.** return [SQ
15460 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64  LITE_ERROR].</dd
15470 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
15480 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58  _CONFIG_GETMUTEX
15490 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
154a0 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 3c 2f 64  NFIG_GETMUTEX</d
154b0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65  t>.** <dd> ^(The
154c0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
154d0 45 54 4d 55 54 45 58 20 6f 70 74 69 6f 6e 20 74  ETMUTEX option t
154e0 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
154f0 67 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20  gument which.** 
15500 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
15510 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
15520 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  he [sqlite3_mute
15530 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  x_methods] struc
15540 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73  ture.  The.** [s
15550 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
15560 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75  hods].** structu
15570 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74  re is filled wit
15580 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20  h the currently 
15590 64 65 66 69 6e 65 64 20 6d 75 74 65 78 20 72 6f  defined mutex ro
155a0 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69  utines.)^.** Thi
155b0 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20  s option can be 
155c0 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64  used to overload
155d0 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74   the default mut
155e0 65 78 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  ex allocation.**
155f0 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61   routines with a
15600 20 77 72 61 70 70 65 72 20 75 73 65 64 20 74 6f   wrapper used to
15610 20 74 72 61 63 6b 20 6d 75 74 65 78 20 75 73 61   track mutex usa
15620 67 65 20 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e  ge for performan
15630 63 65 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20  ce.** profiling 
15640 6f 72 20 74 65 73 74 69 6e 67 2c 20 66 6f 72 20  or testing, for 
15650 65 78 61 6d 70 6c 65 2e 20 20 20 5e 49 66 20 53  example.   ^If S
15660 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
15670 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53  d with.** the [S
15680 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
15690 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44   | SQLITE_THREAD
156a0 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d  SAFE=0] compile-
156b0 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e  time option then
156c0 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d  .** the entire m
156d0 75 74 65 78 69 6e 67 20 73 75 62 73 79 73 74 65  utexing subsyste
156e0 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f  m is omitted fro
156f0 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20  m the build and 
15700 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a  hence calls to.*
15710 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
15720 67 28 29 5d 20 77 69 74 68 20 74 68 65 20 53 51  g()] with the SQ
15730 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
15740 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69  UTEX configurati
15750 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a  on option will.*
15760 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  * return [SQLITE
15770 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a  _ERROR].</dd>.**
15780 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
15790 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 5d 20  FIG_LOOKASIDE]] 
157a0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
157b0 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e  G_LOOKASIDE</dt>
157c0 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53  .** <dd> ^(The S
157d0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f  QLITE_CONFIG_LOO
157e0 4b 41 53 49 44 45 20 6f 70 74 69 6f 6e 20 74 61  KASIDE option ta
157f0 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74  kes two argument
15800 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65  s that determine
15810 0a 2a 2a 20 74 68 65 20 64 65 66 61 75 6c 74 20  .** the default 
15820 73 69 7a 65 20 6f 66 20 6c 6f 6f 6b 61 73 69 64  size of lookasid
15830 65 20 6d 65 6d 6f 72 79 20 6f 6e 20 65 61 63 68  e memory on each
15840 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
15850 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 68 65 20 66  ction]..** The f
15860 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73  irst argument is
15870 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20   the.** size of 
15880 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62  each lookaside b
15890 75 66 66 65 72 20 73 6c 6f 74 20 61 6e 64 20 74  uffer slot and t
158a0 68 65 20 73 65 63 6f 6e 64 20 69 73 20 74 68 65  he second is the
158b0 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c   number of.** sl
158c0 6f 74 73 20 61 6c 6c 6f 63 61 74 65 64 20 74 6f  ots allocated to
158d0 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63   each database c
158e0 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20 20 5e 28  onnection.)^  ^(
158f0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
15900 4f 4b 41 53 49 44 45 0a 2a 2a 20 73 65 74 73 20  OKASIDE.** sets 
15910 74 68 65 20 3c 69 3e 64 65 66 61 75 6c 74 3c 2f  the <i>default</
15920 69 3e 20 6c 6f 6f 6b 61 73 69 64 65 20 73 69 7a  i> lookaside siz
15930 65 2e 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 44  e. The [SQLITE_D
15940 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
15950 45 5d 0a 2a 2a 20 6f 70 74 69 6f 6e 20 74 6f 20  E].** option to 
15960 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
15970 69 67 28 29 5d 20 63 61 6e 20 62 65 20 75 73 65  ig()] can be use
15980 64 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20  d to change the 
15990 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 63 6f 6e  lookaside.** con
159a0 66 69 67 75 72 61 74 69 6f 6e 20 6f 6e 20 69 6e  figuration on in
159b0 64 69 76 69 64 75 61 6c 20 63 6f 6e 6e 65 63 74  dividual connect
159c0 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a  ions.)^ </dd>.**
159d0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
159e0 46 49 47 5f 50 43 41 43 48 45 32 5d 5d 20 3c 64  FIG_PCACHE2]] <d
159f0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
15a00 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20  PCACHE2</dt>.** 
15a10 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54  <dd> ^(The SQLIT
15a20 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32  E_CONFIG_PCACHE2
15a30 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
15a40 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
15a50 77 68 69 63 68 20 69 73 20 0a 2a 2a 20 61 20 70  which is .** a p
15a60 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 5b 73 71  ointer to an [sq
15a70 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74  lite3_pcache_met
15a80 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20  hods2] object.  
15a90 54 68 69 73 20 6f 62 6a 65 63 74 20 73 70 65 63  This object spec
15aa0 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 69 6e 74  ifies.** the int
15ab0 65 72 66 61 63 65 20 74 6f 20 61 20 63 75 73 74  erface to a cust
15ac0 6f 6d 20 70 61 67 65 20 63 61 63 68 65 20 69 6d  om page cache im
15ad0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 29 5e 0a  plementation.)^.
15ae0 2a 2a 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73  ** ^SQLite makes
15af0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b   a copy of the [
15b00 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d  sqlite3_pcache_m
15b10 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e  ethods2] object.
15b20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
15b30 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
15b40 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c  CACHE2]] <dt>SQL
15b50 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
15b60 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ACHE2</dt>.** <d
15b70 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f  d> ^(The SQLITE_
15b80 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
15b90 32 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  2 option takes a
15ba0 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
15bb0 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70   which.** is a p
15bc0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 5b 73 71  ointer to an [sq
15bd0 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74  lite3_pcache_met
15be0 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20  hods2] object.  
15bf0 53 51 4c 69 74 65 20 63 6f 70 69 65 73 20 6f 66  SQLite copies of
15c00 0a 2a 2a 20 74 68 65 20 63 75 72 72 65 6e 74 20  .** the current 
15c10 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65  page cache imple
15c20 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74 6f 20 74  mentation into t
15c30 68 61 74 20 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f  hat object.)^ </
15c40 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
15c50 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 5d 5d 20  TE_CONFIG_LOG]] 
15c60 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
15c70 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  G_LOG</dt>.** <d
15c80 64 3e 20 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  d> The SQLITE_CO
15c90 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20  NFIG_LOG option 
15ca0 69 73 20 75 73 65 64 20 74 6f 20 63 6f 6e 66 69  is used to confi
15cb0 67 75 72 65 20 74 68 65 20 53 51 4c 69 74 65 0a  gure the SQLite.
15cc0 2a 2a 20 67 6c 6f 62 61 6c 20 5b 65 72 72 6f 72  ** global [error
15cd0 20 6c 6f 67 5d 2e 0a 2a 2a 20 28 5e 54 68 65 20   log]..** (^The 
15ce0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
15cf0 47 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74  G option takes t
15d00 77 6f 20 61 72 67 75 6d 65 6e 74 73 3a 20 61 20  wo arguments: a 
15d10 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a 2a 2a 20  pointer to a.** 
15d20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20  function with a 
15d30 63 61 6c 6c 20 73 69 67 6e 61 74 75 72 65 20 6f  call signature o
15d40 66 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c  f void(*)(void*,
15d50 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29  int,const char*)
15d60 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 70 6f 69 6e  , .** and a poin
15d70 74 65 72 20 74 6f 20 76 6f 69 64 2e 20 5e 49 66  ter to void. ^If
15d80 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f   the function po
15d90 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c  inter is not NUL
15da0 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 69 6e 76 6f  L, it is.** invo
15db0 6b 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ked by [sqlite3_
15dc0 6c 6f 67 28 29 5d 20 74 6f 20 70 72 6f 63 65 73  log()] to proces
15dd0 73 20 65 61 63 68 20 6c 6f 67 67 69 6e 67 20 65  s each logging e
15de0 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a  vent.  ^If the.*
15df0 2a 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74  * function point
15e00 65 72 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 20  er is NULL, the 
15e10 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20  [sqlite3_log()] 
15e20 69 6e 74 65 72 66 61 63 65 20 62 65 63 6f 6d 65  interface become
15e30 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54  s a no-op..** ^T
15e40 68 65 20 76 6f 69 64 20 70 6f 69 6e 74 65 72 20  he void pointer 
15e50 74 68 61 74 20 69 73 20 74 68 65 20 73 65 63 6f  that is the seco
15e60 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 53  nd argument to S
15e70 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47  QLITE_CONFIG_LOG
15e80 20 69 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 68   is.** passed th
15e90 72 6f 75 67 68 20 61 73 20 74 68 65 20 66 69 72  rough as the fir
15ea0 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
15eb0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
15ec0 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a  defined logger.*
15ed0 2a 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 6e 65  * function whene
15ee0 76 65 72 20 74 68 61 74 20 66 75 6e 63 74 69 6f  ver that functio
15ef0 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e  n is invoked.  ^
15f00 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
15f10 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 6c  eter to.** the l
15f20 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 20 69  ogger function i
15f30 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
15f40 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
15f50 74 6f 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  to the correspon
15f60 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ding.** [sqlite3
15f70 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c 20 61 6e 64  _log()] call and
15f80 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20   is intended to 
15f90 62 65 20 61 20 5b 72 65 73 75 6c 74 20 63 6f 64  be a [result cod
15fa0 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 78 74  e] or an.** [ext
15fb0 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
15fc0 65 5d 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20  e].  ^The third 
15fd0 70 61 72 61 6d 65 74 65 72 20 70 61 73 73 65 64  parameter passed
15fe0 20 74 6f 20 74 68 65 20 6c 6f 67 67 65 72 20 69   to the logger i
15ff0 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73 61 67 65  s.** log message
16000 20 61 66 74 65 72 20 66 6f 72 6d 61 74 74 69 6e   after formattin
16010 67 20 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 73  g via [sqlite3_s
16020 6e 70 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a 20 54  nprintf()]..** T
16030 68 65 20 53 51 4c 69 74 65 20 6c 6f 67 67 69 6e  he SQLite loggin
16040 67 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e  g interface is n
16050 6f 74 20 72 65 65 6e 74 72 61 6e 74 3b 20 74 68  ot reentrant; th
16060 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f  e logger functio
16070 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20 62 79  n.** supplied by
16080 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
16090 20 6d 75 73 74 20 6e 6f 74 20 69 6e 76 6f 6b 65   must not invoke
160a0 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65   any SQLite inte
160b0 72 66 61 63 65 2e 0a 2a 2a 20 49 6e 20 61 20 6d  rface..** In a m
160c0 75 6c 74 69 2d 74 68 72 65 61 64 65 64 20 61 70  ulti-threaded ap
160d0 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65 20 61  plication, the a
160e0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
160f0 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e  ed logger.** fun
16100 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 74 68  ction must be th
16110 72 65 61 64 73 61 66 65 2e 20 3c 2f 64 64 3e 0a  readsafe. </dd>.
16120 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
16130 4f 4e 46 49 47 5f 55 52 49 5d 5d 20 3c 64 74 3e  ONFIG_URI]] <dt>
16140 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52  SQLITE_CONFIG_UR
16150 49 0a 2a 2a 20 3c 64 64 3e 5e 28 54 68 65 20 53  I.** <dd>^(The S
16160 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49  QLITE_CONFIG_URI
16170 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
16180 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
16190 6f 66 20 74 79 70 65 20 69 6e 74 2e 0a 2a 2a 20  of type int..** 
161a0 49 66 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  If non-zero, the
161b0 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69  n URI handling i
161c0 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c  s globally enabl
161d0 65 64 2e 20 49 66 20 74 68 65 20 70 61 72 61 6d  ed. If the param
161e0 65 74 65 72 20 69 73 20 7a 65 72 6f 2c 0a 2a 2a  eter is zero,.**
161f0 20 74 68 65 6e 20 55 52 49 20 68 61 6e 64 6c 69   then URI handli
16200 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64  ng is globally d
16210 69 73 61 62 6c 65 64 2e 29 5e 20 5e 49 66 20 55  isabled.)^ ^If U
16220 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67  RI handling is g
16230 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 65 6e 61 62 6c  lobally.** enabl
16240 65 64 2c 20 61 6c 6c 20 66 69 6c 65 6e 61 6d 65  ed, all filename
16250 73 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c  s passed to [sql
16260 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
16270 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
16280 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f  ],.** [sqlite3_o
16290 70 65 6e 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 73  pen16()] or.** s
162a0 70 65 63 69 66 69 65 64 20 61 73 20 70 61 72 74  pecified as part
162b0 20 6f 66 20 5b 41 54 54 41 43 48 5d 20 63 6f 6d   of [ATTACH] com
162c0 6d 61 6e 64 73 20 61 72 65 20 69 6e 74 65 72 70  mands are interp
162d0 72 65 74 65 64 20 61 73 20 55 52 49 73 2c 20 72  reted as URIs, r
162e0 65 67 61 72 64 6c 65 73 73 0a 2a 2a 20 6f 66 20  egardless.** of 
162f0 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
16300 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
16310 55 52 49 5d 20 66 6c 61 67 20 69 73 20 73 65 74  URI] flag is set
16320 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   when the databa
16330 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
16340 20 69 73 20 6f 70 65 6e 65 64 2e 20 5e 49 66 20   is opened. ^If 
16350 69 74 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64  it is globally d
16360 69 73 61 62 6c 65 64 2c 20 66 69 6c 65 6e 61 6d  isabled, filenam
16370 65 73 20 61 72 65 0a 2a 2a 20 6f 6e 6c 79 20 69  es are.** only i
16380 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55 52  nterpreted as UR
16390 49 73 20 69 66 20 74 68 65 20 53 51 4c 49 54 45  Is if the SQLITE
163a0 5f 4f 50 45 4e 5f 55 52 49 20 66 6c 61 67 20 69  _OPEN_URI flag i
163b0 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 0a 2a  s set when the.*
163c0 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
163d0 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e  ction is opened.
163e0 20 5e 28 42 79 20 64 65 66 61 75 6c 74 2c 20 55   ^(By default, U
163f0 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67  RI handling is g
16400 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 64 69 73 61 62  lobally.** disab
16410 6c 65 64 2e 20 54 68 65 20 64 65 66 61 75 6c 74  led. The default
16420 20 76 61 6c 75 65 20 6d 61 79 20 62 65 20 63 68   value may be ch
16430 61 6e 67 65 64 20 62 79 20 63 6f 6d 70 69 6c 69  anged by compili
16440 6e 67 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b  ng with the.** [
16450 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20  SQLITE_USE_URI] 
16460 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 29  symbol defined.)
16470 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
16480 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47  _CONFIG_COVERING
16490 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 5d 20 3c 64  _INDEX_SCAN]] <d
164a0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
164b0 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53  COVERING_INDEX_S
164c0 43 41 4e 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20  CAN.** <dd>^The 
164d0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f  SQLITE_CONFIG_CO
164e0 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41  VERING_INDEX_SCA
164f0 4e 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  N option takes a
16500 20 73 69 6e 67 6c 65 20 69 6e 74 65 67 65 72 0a   single integer.
16510 2a 2a 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  ** argument whic
16520 68 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64  h is interpreted
16530 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e   as a boolean in
16540 20 6f 72 64 65 72 20 74 6f 20 65 6e 61 62 6c 65   order to enable
16550 20 6f 72 20 64 69 73 61 62 6c 65 0a 2a 2a 20 74   or disable.** t
16560 68 65 20 75 73 65 20 6f 66 20 63 6f 76 65 72 69  he use of coveri
16570 6e 67 20 69 6e 64 69 63 65 73 20 66 6f 72 20 66  ng indices for f
16580 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e 73 20  ull table scans 
16590 69 6e 20 74 68 65 20 71 75 65 72 79 20 6f 70 74  in the query opt
165a0 69 6d 69 7a 65 72 2e 0a 2a 2a 20 5e 54 68 65 20  imizer..** ^The 
165b0 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20  default setting 
165c0 69 73 20 64 65 74 65 72 6d 69 6e 65 64 0a 2a 2a  is determined.**
165d0 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   by the [SQLITE_
165e0 41 4c 4c 4f 57 5f 43 4f 56 45 52 49 4e 47 5f 49  ALLOW_COVERING_I
165f0 4e 44 45 58 5f 53 43 41 4e 5d 20 63 6f 6d 70 69  NDEX_SCAN] compi
16600 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20  le-time option, 
16610 6f 72 20 69 73 20 22 6f 6e 22 0a 2a 2a 20 69 66  or is "on".** if
16620 20 74 68 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69   that compile-ti
16630 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6d 69  me option is omi
16640 74 74 65 64 2e 0a 2a 2a 20 54 68 65 20 61 62 69  tted..** The abi
16650 6c 69 74 79 20 74 6f 20 64 69 73 61 62 6c 65 20  lity to disable 
16660 74 68 65 20 75 73 65 20 6f 66 20 63 6f 76 65 72  the use of cover
16670 69 6e 67 20 69 6e 64 69 63 65 73 20 66 6f 72 20  ing indices for 
16680 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e 73  full table scans
16690 0a 2a 2a 20 69 73 20 62 65 63 61 75 73 65 20 73  .** is because s
166a0 6f 6d 65 20 69 6e 63 6f 72 72 65 63 74 6c 79 20  ome incorrectly 
166b0 63 6f 64 65 64 20 6c 65 67 61 63 79 20 61 70 70  coded legacy app
166c0 6c 69 63 61 74 69 6f 6e 73 20 6d 69 67 68 74 20  lications might 
166d0 6d 61 6c 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77  malfunction.** w
166e0 68 65 6e 20 74 68 65 20 6f 70 74 69 6d 69 7a 61  hen the optimiza
166f0 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e  tion is enabled.
16700 20 20 50 72 6f 76 69 64 69 6e 67 20 74 68 65 20    Providing the 
16710 61 62 69 6c 69 74 79 20 74 6f 0a 2a 2a 20 64 69  ability to.** di
16720 73 61 62 6c 65 20 74 68 65 20 6f 70 74 69 6d 69  sable the optimi
16730 7a 61 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 74 68  zation allows th
16740 65 20 6f 6c 64 65 72 2c 20 62 75 67 67 79 20 61  e older, buggy a
16750 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20  pplication code 
16760 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69 74 68 6f  to work.** witho
16770 75 74 20 63 68 61 6e 67 65 20 65 76 65 6e 20 77  ut change even w
16780 69 74 68 20 6e 65 77 65 72 20 76 65 72 73 69 6f  ith newer versio
16790 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  ns of SQLite..**
167a0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
167b0 46 49 47 5f 50 43 41 43 48 45 5d 5d 20 5b 5b 53  FIG_PCACHE]] [[S
167c0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
167d0 50 43 41 43 48 45 5d 5d 0a 2a 2a 20 3c 64 74 3e  PCACHE]].** <dt>
167e0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
167f0 41 43 48 45 20 61 6e 64 20 53 51 4c 49 54 45 5f  ACHE and SQLITE_
16800 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
16810 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 73 65 20 6f  .** <dd> These o
16820 70 74 69 6f 6e 73 20 61 72 65 20 6f 62 73 6f 6c  ptions are obsol
16830 65 74 65 20 61 6e 64 20 73 68 6f 75 6c 64 20 6e  ete and should n
16840 6f 74 20 62 65 20 75 73 65 64 20 62 79 20 6e 65  ot be used by ne
16850 77 20 63 6f 64 65 2e 0a 2a 2a 20 54 68 65 79 20  w code..** They 
16860 61 72 65 20 72 65 74 61 69 6e 65 64 20 66 6f 72  are retained for
16870 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
16880 74 69 62 69 6c 69 74 79 20 62 75 74 20 61 72 65  tibility but are
16890 20 6e 6f 77 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20   now no-ops..** 
168a0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
168b0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c  LITE_CONFIG_SQLL
168c0 4f 47 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  OG]].** <dt>SQLI
168d0 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47  TE_CONFIG_SQLLOG
168e0 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74  .** <dd>This opt
168f0 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69  ion is only avai
16900 6c 61 62 6c 65 20 69 66 20 73 71 6c 69 74 65 20  lable if sqlite 
16910 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
16920 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
16930 45 4e 41 42 4c 45 5f 53 51 4c 4c 4f 47 5d 20 70  ENABLE_SQLLOG] p
16940 72 65 2d 70 72 6f 63 65 73 73 6f 72 20 6d 61 63  re-processor mac
16950 72 6f 20 64 65 66 69 6e 65 64 2e 20 54 68 65 20  ro defined. The 
16960 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 73  first argument s
16970 68 6f 75 6c 64 0a 2a 2a 20 62 65 20 61 20 70 6f  hould.** be a po
16980 69 6e 74 65 72 20 74 6f 20 61 20 66 75 6e 63 74  inter to a funct
16990 69 6f 6e 20 6f 66 20 74 79 70 65 20 76 6f 69 64  ion of type void
169a0 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65  (*)(void*,sqlite
169b0 33 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  3*,const char*, 
169c0 69 6e 74 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63  int)..** The sec
169d0 6f 6e 64 20 73 68 6f 75 6c 64 20 62 65 20 6f 66  ond should be of
169e0 20 74 79 70 65 20 28 76 6f 69 64 2a 29 2e 20 54   type (void*). T
169f0 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  he callback is i
16a00 6e 76 6f 6b 65 64 20 62 79 20 74 68 65 20 6c 69  nvoked by the li
16a10 62 72 61 72 79 0a 2a 2a 20 69 6e 20 74 68 72 65  brary.** in thre
16a20 65 20 73 65 70 61 72 61 74 65 20 63 69 72 63 75  e separate circu
16a30 6d 73 74 61 6e 63 65 73 2c 20 69 64 65 6e 74 69  mstances, identi
16a40 66 69 65 64 20 62 79 20 74 68 65 20 76 61 6c 75  fied by the valu
16a50 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 0a  e passed as the.
16a60 2a 2a 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  ** fourth parame
16a70 74 65 72 2e 20 49 66 20 74 68 65 20 66 6f 75 72  ter. If the four
16a80 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
16a90 30 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  0, then the data
16aa0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
16ab0 2a 2a 20 70 61 73 73 65 64 20 61 73 20 74 68 65  ** passed as the
16ac0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
16ad0 20 68 61 73 20 6a 75 73 74 20 62 65 65 6e 20 6f   has just been o
16ae0 70 65 6e 65 64 2e 20 54 68 65 20 74 68 69 72 64  pened. The third
16af0 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 70 6f 69   argument.** poi
16b00 6e 74 73 20 74 6f 20 61 20 62 75 66 66 65 72 20  nts to a buffer 
16b10 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e  containing the n
16b20 61 6d 65 20 6f 66 20 74 68 65 20 6d 61 69 6e 20  ame of the main 
16b30 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 20 49  database file. I
16b40 66 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20  f the.** fourth 
16b50 70 61 72 61 6d 65 74 65 72 20 69 73 20 31 2c 20  parameter is 1, 
16b60 74 68 65 6e 20 74 68 65 20 53 51 4c 20 73 74 61  then the SQL sta
16b70 74 65 6d 65 6e 74 20 74 68 61 74 20 74 68 65 20  tement that the 
16b80 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 0a  third parameter.
16b90 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20 68 61 73  ** points to has
16ba0 20 6a 75 73 74 20 62 65 65 6e 20 65 78 65 63 75   just been execu
16bb0 74 65 64 2e 20 4f 72 2c 20 69 66 20 74 68 65 20  ted. Or, if the 
16bc0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
16bd0 20 69 73 20 32 2c 20 74 68 65 6e 0a 2a 2a 20 74   is 2, then.** t
16be0 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 65  he connection be
16bf0 69 6e 67 20 70 61 73 73 65 64 20 61 73 20 74 68  ing passed as th
16c00 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
16c10 65 72 20 69 73 20 62 65 69 6e 67 20 63 6c 6f 73  er is being clos
16c20 65 64 2e 20 54 68 65 0a 2a 2a 20 74 68 69 72 64  ed. The.** third
16c30 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 61   parameter is pa
16c40 73 73 65 64 20 4e 55 4c 4c 20 49 6e 20 74 68 69  ssed NULL In thi
16c50 73 20 63 61 73 65 2e 20 20 41 6e 20 65 78 61 6d  s case.  An exam
16c60 70 6c 65 20 6f 66 20 75 73 69 6e 67 20 74 68 69  ple of using thi
16c70 73 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69  s.** configurati
16c80 6f 6e 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65  on option can be
16c90 20 73 65 65 6e 20 69 6e 20 74 68 65 20 22 74 65   seen in the "te
16ca0 73 74 5f 73 71 6c 6c 6f 67 2e 63 22 20 73 6f 75  st_sqllog.c" sou
16cb0 72 63 65 20 66 69 6c 65 20 69 6e 0a 2a 2a 20 74  rce file in.** t
16cc0 68 65 20 63 61 6e 6f 6e 69 63 61 6c 20 53 51 4c  he canonical SQL
16cd0 69 74 65 20 73 6f 75 72 63 65 20 74 72 65 65 2e  ite source tree.
16ce0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
16cf0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50  LITE_CONFIG_MMAP
16d00 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53  _SIZE]].** <dt>S
16d10 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41  QLITE_CONFIG_MMA
16d20 50 5f 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 53  P_SIZE.** <dd>^S
16d30 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41  QLITE_CONFIG_MMA
16d40 50 5f 53 49 5a 45 20 74 61 6b 65 73 20 74 77 6f  P_SIZE takes two
16d50 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20   64-bit integer 
16d60 28 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 20  (sqlite3_int64) 
16d70 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 61  values.** that a
16d80 72 65 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d  re the default m
16d90 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69 74 20 28  map size limit (
16da0 74 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74  the default sett
16db0 69 6e 67 20 66 6f 72 0a 2a 2a 20 5b 50 52 41 47  ing for.** [PRAG
16dc0 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 29 20 61  MA mmap_size]) a
16dd0 6e 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 61  nd the maximum a
16de0 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a 65  llowed mmap size
16df0 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 54 68 65 20   limit..** ^The 
16e00 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20  default setting 
16e10 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64 65  can be overridde
16e20 6e 20 62 79 20 65 61 63 68 20 64 61 74 61 62 61  n by each databa
16e30 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 75 73  se connection us
16e40 69 6e 67 0a 2a 2a 20 65 69 74 68 65 72 20 74 68  ing.** either th
16e50 65 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73  e [PRAGMA mmap_s
16e60 69 7a 65 5d 20 63 6f 6d 6d 61 6e 64 2c 20 6f 72  ize] command, or
16e70 20 62 79 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a   by using the.**
16e80 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d   [SQLITE_FCNTL_M
16e90 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c 65 20 63  MAP_SIZE] file c
16ea0 6f 6e 74 72 6f 6c 2e 20 20 5e 28 54 68 65 20 6d  ontrol.  ^(The m
16eb0 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d  aximum allowed m
16ec0 6d 61 70 20 73 69 7a 65 0a 2a 2a 20 77 69 6c 6c  map size.** will
16ed0 20 62 65 20 73 69 6c 65 6e 74 6c 79 20 74 72 75   be silently tru
16ee0 6e 63 61 74 65 64 20 69 66 20 6e 65 63 65 73 73  ncated if necess
16ef0 61 72 79 20 73 6f 20 74 68 61 74 20 69 74 20 64  ary so that it d
16f00 6f 65 73 20 6e 6f 74 20 65 78 63 65 65 64 20 74  oes not exceed t
16f10 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69  he.** compile-ti
16f20 6d 65 20 6d 61 78 69 6d 75 6d 20 6d 6d 61 70 20  me maximum mmap 
16f30 73 69 7a 65 20 73 65 74 20 62 79 20 74 68 65 0a  size set by the.
16f40 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 4d  ** [SQLITE_MAX_M
16f50 4d 41 50 5f 53 49 5a 45 5d 20 63 6f 6d 70 69 6c  MAP_SIZE] compil
16f60 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 29 5e  e-time option.)^
16f70 0a 2a 2a 20 5e 49 66 20 65 69 74 68 65 72 20 61  .** ^If either a
16f80 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 69 73 20  rgument to this 
16f90 6f 70 74 69 6f 6e 20 69 73 20 6e 65 67 61 74 69  option is negati
16fa0 76 65 2c 20 74 68 65 6e 20 74 68 61 74 20 61 72  ve, then that ar
16fb0 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 63 68 61  gument is.** cha
16fc0 6e 67 65 64 20 74 6f 20 69 74 73 20 63 6f 6d 70  nged to its comp
16fd0 69 6c 65 2d 74 69 6d 65 20 64 65 66 61 75 6c 74  ile-time default
16fe0 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ..**.** [[SQLITE
16ff0 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45  _CONFIG_WIN32_HE
17000 41 50 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e  APSIZE]].** <dt>
17010 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49  SQLITE_CONFIG_WI
17020 4e 33 32 5f 48 45 41 50 53 49 5a 45 0a 2a 2a 20  N32_HEAPSIZE.** 
17030 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f  <dd>^The SQLITE_
17040 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41  CONFIG_WIN32_HEA
17050 50 53 49 5a 45 20 6f 70 74 69 6f 6e 20 69 73 20  PSIZE option is 
17060 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69  only available i
17070 66 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63  f SQLite is.** c
17080 6f 6d 70 69 6c 65 64 20 66 6f 72 20 57 69 6e 64  ompiled for Wind
17090 6f 77 73 20 77 69 74 68 20 74 68 65 20 5b 53 51  ows with the [SQ
170a0 4c 49 54 45 5f 57 49 4e 33 32 5f 4d 41 4c 4c 4f  LITE_WIN32_MALLO
170b0 43 5d 20 70 72 65 2d 70 72 6f 63 65 73 73 6f 72  C] pre-processor
170c0 20 6d 61 63 72 6f 0a 2a 2a 20 64 65 66 69 6e 65   macro.** define
170d0 64 2e 20 5e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  d. ^SQLITE_CONFI
170e0 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45  G_WIN32_HEAPSIZE
170f0 20 74 61 6b 65 73 20 61 20 33 32 2d 62 69 74 20   takes a 32-bit 
17100 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  unsigned integer
17110 20 76 61 6c 75 65 0a 2a 2a 20 74 68 61 74 20 73   value.** that s
17120 70 65 63 69 66 69 65 73 20 74 68 65 20 6d 61 78  pecifies the max
17130 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 74 68 65  imum size of the
17140 20 63 72 65 61 74 65 64 20 68 65 61 70 2e 0a 2a   created heap..*
17150 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  * </dl>.**.** [[
17160 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
17170 41 43 48 45 5f 48 44 52 53 5a 5d 5d 0a 2a 2a 20  ACHE_HDRSZ]].** 
17180 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
17190 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 0a 2a  G_PCACHE_HDRSZ.*
171a0 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54  * <dd>^The SQLIT
171b0 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f  E_CONFIG_PCACHE_
171c0 48 44 52 53 5a 20 6f 70 74 69 6f 6e 20 74 61 6b  HDRSZ option tak
171d0 65 73 20 61 20 73 69 6e 67 6c 65 20 70 61 72 61  es a single para
171e0 6d 65 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69  meter which.** i
171f0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
17200 6e 20 69 6e 74 65 67 65 72 20 61 6e 64 20 77 72  n integer and wr
17210 69 74 65 73 20 69 6e 74 6f 20 74 68 61 74 20 69  ites into that i
17220 6e 74 65 67 65 72 20 74 68 65 20 6e 75 6d 62 65  nteger the numbe
17230 72 20 6f 66 20 65 78 74 72 61 0a 2a 2a 20 62 79  r of extra.** by
17240 74 65 73 20 70 65 72 20 70 61 67 65 20 72 65 71  tes per page req
17250 75 69 72 65 64 20 66 6f 72 20 65 61 63 68 20 70  uired for each p
17260 61 67 65 20 69 6e 20 5b 53 51 4c 49 54 45 5f 43  age in [SQLITE_C
17270 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d  ONFIG_PAGECACHE]
17280 2e 0a 2a 2a 20 54 68 65 20 61 6d 6f 75 6e 74 20  ..** The amount 
17290 6f 66 20 65 78 74 72 61 20 73 70 61 63 65 20 72  of extra space r
172a0 65 71 75 69 72 65 64 20 63 61 6e 20 63 68 61 6e  equired can chan
172b0 67 65 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  ge depending on 
172c0 74 68 65 20 63 6f 6d 70 69 6c 65 72 2c 0a 2a 2a  the compiler,.**
172d0 20 74 61 72 67 65 74 20 70 6c 61 74 66 6f 72 6d   target platform
172e0 2c 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72  , and SQLite ver
172f0 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  sion..**.** [[SQ
17300 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53  LITE_CONFIG_PMAS
17310 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  Z]].** <dt>SQLIT
17320 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 0a 2a  E_CONFIG_PMASZ.*
17330 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54  * <dd>^The SQLIT
17340 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 20 6f  E_CONFIG_PMASZ o
17350 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
17360 6e 67 6c 65 20 70 61 72 61 6d 65 74 65 72 20 77  ngle parameter w
17370 68 69 63 68 0a 2a 2a 20 69 73 20 61 6e 20 75 6e  hich.** is an un
17380 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61  signed integer a
17390 6e 64 20 73 65 74 73 20 74 68 65 20 22 4d 69 6e  nd sets the "Min
173a0 69 6d 75 6d 20 50 4d 41 20 53 69 7a 65 22 20 66  imum PMA Size" f
173b0 6f 72 20 74 68 65 20 6d 75 6c 74 69 74 68 72 65  or the multithre
173c0 61 64 65 64 0a 2a 2a 20 73 6f 72 74 65 72 20 74  aded.** sorter t
173d0 6f 20 74 68 61 74 20 69 6e 74 65 67 65 72 2e 20  o that integer. 
173e0 20 54 68 65 20 64 65 66 61 75 6c 74 20 6d 69 6e   The default min
173f0 69 6d 75 6d 20 50 4d 41 20 53 69 7a 65 20 69 73  imum PMA Size is
17400 20 73 65 74 20 62 79 20 74 68 65 0a 2a 2a 20 5b   set by the.** [
17410 53 51 4c 49 54 45 5f 53 4f 52 54 45 52 5f 50 4d  SQLITE_SORTER_PM
17420 41 53 5a 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  ASZ] compile-tim
17430 65 20 6f 70 74 69 6f 6e 2e 20 20 4e 65 77 20 74  e option.  New t
17440 68 72 65 61 64 73 20 61 72 65 20 6c 61 75 6e 63  hreads are launc
17450 68 65 64 0a 2a 2a 20 74 6f 20 68 65 6c 70 20 77  hed.** to help w
17460 69 74 68 20 73 6f 72 74 20 6f 70 65 72 61 74 69  ith sort operati
17470 6f 6e 73 20 77 68 65 6e 20 6d 75 6c 74 69 74 68  ons when multith
17480 72 65 61 64 65 64 20 73 6f 72 74 69 6e 67 0a 2a  readed sorting.*
17490 2a 20 69 73 20 65 6e 61 62 6c 65 64 20 28 75 73  * is enabled (us
174a0 69 6e 67 20 74 68 65 20 5b 50 52 41 47 4d 41 20  ing the [PRAGMA 
174b0 74 68 72 65 61 64 73 5d 20 63 6f 6d 6d 61 6e 64  threads] command
174c0 29 20 61 6e 64 20 74 68 65 20 61 6d 6f 75 6e 74  ) and the amount
174d0 20 6f 66 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 74   of content.** t
174e0 6f 20 62 65 20 73 6f 72 74 65 64 20 65 78 63 65  o be sorted exce
174f0 65 64 73 20 74 68 65 20 70 61 67 65 20 73 69 7a  eds the page siz
17500 65 20 74 69 6d 65 73 20 74 68 65 20 6d 69 6e 69  e times the mini
17510 6d 75 6d 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 50  mum of the.** [P
17520 52 41 47 4d 41 20 63 61 63 68 65 5f 73 69 7a 65  RAGMA cache_size
17530 5d 20 73 65 74 74 69 6e 67 20 61 6e 64 20 74 68  ] setting and th
17540 69 73 20 76 61 6c 75 65 2e 0a 2a 2a 20 3c 2f 64  is value..** </d
17550 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  l>.*/.#define SQ
17560 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
17570 4c 45 54 48 52 45 41 44 20 20 31 20 20 2f 2a 20  LETHREAD  1  /* 
17580 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nil */.#define S
17590 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
175a0 54 49 54 48 52 45 41 44 20 20 20 32 20 20 2f 2a  TITHREAD   2  /*
175b0 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20   nil */.#define 
175c0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45  SQLITE_CONFIG_SE
175d0 52 49 41 4c 49 5a 45 44 20 20 20 20 33 20 20 2f  RIALIZED    3  /
175e0 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65  * nil */.#define
175f0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
17600 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 34 20 20  ALLOC        4  
17610 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  /* sqlite3_mem_m
17620 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69  ethods* */.#defi
17630 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
17640 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20 20 35  _GETMALLOC     5
17650 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d    /* sqlite3_mem
17660 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65  _methods* */.#de
17670 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
17680 49 47 5f 53 43 52 41 54 43 48 20 20 20 20 20 20  IG_SCRATCH      
17690 20 36 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e   6  /* void*, in
176a0 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23  t sz, int N */.#
176b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
176c0 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 20 20  NFIG_PAGECACHE  
176d0 20 20 20 37 20 20 2f 2a 20 76 6f 69 64 2a 2c 20     7  /* void*, 
176e0 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f  int sz, int N */
176f0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
17700 43 4f 4e 46 49 47 5f 48 45 41 50 20 20 20 20 20  CONFIG_HEAP     
17710 20 20 20 20 20 38 20 20 2f 2a 20 76 6f 69 64 2a       8  /* void*
17720 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 69 6e 74  , int nByte, int
17730 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20   min */.#define 
17740 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
17750 4d 53 54 41 54 55 53 20 20 20 20 20 39 20 20 2f  MSTATUS     9  /
17760 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65  * boolean */.#de
17770 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
17780 49 47 5f 4d 55 54 45 58 20 20 20 20 20 20 20 20  IG_MUTEX        
17790 31 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d  10  /* sqlite3_m
177a0 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f  utex_methods* */
177b0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
177c0 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20  CONFIG_GETMUTEX 
177d0 20 20 20 20 31 31 20 20 2f 2a 20 73 71 6c 69 74      11  /* sqlit
177e0 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
177f0 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f 75 73  * */./* previous
17800 6c 79 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ly SQLITE_CONFIG
17810 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 31 32 20 77  _CHUNKALLOC 12 w
17820 68 69 63 68 20 69 73 20 6e 6f 77 20 75 6e 75 73  hich is now unus
17830 65 64 2e 20 2a 2f 20 0a 23 64 65 66 69 6e 65 20  ed. */ .#define 
17840 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
17850 4f 4b 41 53 49 44 45 20 20 20 20 31 33 20 20 2f  OKASIDE    13  /
17860 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65  * int int */.#de
17870 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
17880 49 47 5f 50 43 41 43 48 45 20 20 20 20 20 20 20  IG_PCACHE       
17890 31 34 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a  14  /* no-op */.
178a0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
178b0 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 20  ONFIG_GETPCACHE 
178c0 20 20 20 31 35 20 20 2f 2a 20 6e 6f 2d 6f 70 20     15  /* no-op 
178d0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
178e0 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 20 20 20  E_CONFIG_LOG    
178f0 20 20 20 20 20 20 31 36 20 20 2f 2a 20 78 46 75        16  /* xFu
17900 6e 63 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65  nc, void* */.#de
17910 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
17920 49 47 5f 55 52 49 20 20 20 20 20 20 20 20 20 20  IG_URI          
17930 31 37 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64  17  /* int */.#d
17940 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
17950 46 49 47 5f 50 43 41 43 48 45 32 20 20 20 20 20  FIG_PCACHE2     
17960 20 31 38 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f   18  /* sqlite3_
17970 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a  pcache_methods2*
17980 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
17990 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41  TE_CONFIG_GETPCA
179a0 43 48 45 32 20 20 20 31 39 20 20 2f 2a 20 73 71  CHE2   19  /* sq
179b0 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74  lite3_pcache_met
179c0 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e  hods2* */.#defin
179d0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
179e0 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53  COVERING_INDEX_S
179f0 43 41 4e 20 32 30 20 20 2f 2a 20 69 6e 74 20 2a  CAN 20  /* int *
17a00 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
17a10 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 20 20  _CONFIG_SQLLOG  
17a20 20 20 20 20 20 32 31 20 20 2f 2a 20 78 53 71 6c       21  /* xSql
17a30 6c 6f 67 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23 64  log, void* */.#d
17a40 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
17a50 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 20 20 20  FIG_MMAP_SIZE   
17a60 20 32 32 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f   22  /* sqlite3_
17a70 69 6e 74 36 34 2c 20 73 71 6c 69 74 65 33 5f 69  int64, sqlite3_i
17a80 6e 74 36 34 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nt64 */.#define 
17a90 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49  SQLITE_CONFIG_WI
17aa0 4e 33 32 5f 48 45 41 50 53 49 5a 45 20 20 20 20  N32_HEAPSIZE    
17ab0 20 20 32 33 20 20 2f 2a 20 69 6e 74 20 6e 42 79    23  /* int nBy
17ac0 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  te */.#define SQ
17ad0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
17ae0 48 45 5f 48 44 52 53 5a 20 20 20 20 20 20 20 20  HE_HDRSZ        
17af0 32 34 20 20 2f 2a 20 69 6e 74 20 2a 70 73 7a 20  24  /* int *psz 
17b00 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
17b10 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 20 20  E_CONFIG_PMASZ  
17b20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 35 20               25 
17b30 20 2f 2a 20 75 6e 73 69 67 6e 65 64 20 69 6e 74   /* unsigned int
17b40 20 73 7a 50 6d 61 20 2a 2f 0a 0a 2f 2a 0a 2a 2a   szPma */../*.**
17b50 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62   CAPI3REF: Datab
17b60 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 43  ase Connection C
17b70 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74  onfiguration Opt
17b80 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ions.**.** These
17b90 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74   constants are t
17ba0 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74  he available int
17bb0 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69  eger configurati
17bc0 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a  on options that.
17bd0 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65 64  ** can be passed
17be0 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61   as the second a
17bf0 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b  rgument to the [
17c00 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
17c10 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a  g()] interface..
17c20 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67  **.** New config
17c30 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
17c40 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
17c50 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
17c60 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78  of SQLite..** Ex
17c70 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61  isting configura
17c80 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67  tion options mig
17c90 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75  ht be discontinu
17ca0 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  ed.  Application
17cb0 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63  s.** should chec
17cc0 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64  k the return cod
17cd0 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  e from [sqlite3_
17ce0 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20  db_config()] to 
17cf0 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a  make sure that.*
17d00 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65  * the call worke
17d10 64 2e 20 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  d.  ^The [sqlite
17d20 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69  3_db_config()] i
17d30 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65  nterface will re
17d40 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65  turn a.** non-ze
17d50 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  ro [error code] 
17d60 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65  if a discontinue
17d70 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64  d or unsupported
17d80 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
17d90 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f  ption.** is invo
17da0 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  ked..**.** <dl>.
17db0 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42  ** <dt>SQLITE_DB
17dc0 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
17dd0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
17de0 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
17df0 20 74 68 72 65 65 20 61 64 64 69 74 69 6f 6e 61   three additiona
17e00 6c 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74  l arguments that
17e10 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 0a   determine the .
17e20 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  ** [lookaside me
17e30 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20  mory allocator] 
17e40 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f  configuration fo
17e50 72 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  r the [database 
17e60 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20  connection]..** 
17e70 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
17e80 65 6e 74 20 28 74 68 65 20 74 68 69 72 64 20 70  ent (the third p
17e90 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
17ea0 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
17eb0 5d 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65  ] is a.** pointe
17ec0 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 62 75  r to a memory bu
17ed0 66 66 65 72 20 74 6f 20 75 73 65 20 66 6f 72 20  ffer to use for 
17ee0 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79  lookaside memory
17ef0 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  ..** ^The first 
17f00 61 72 67 75 6d 65 6e 74 20 61 66 74 65 72 20 74  argument after t
17f10 68 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  he SQLITE_DBCONF
17f20 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 76 65 72  IG_LOOKASIDE ver
17f30 62 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c  b.** may be NULL
17f40 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 53   in which case S
17f50 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 6c 6f 63  QLite will alloc
17f60 61 74 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f 6b 61  ate the.** looka
17f70 73 69 64 65 20 62 75 66 66 65 72 20 69 74 73 65  side buffer itse
17f80 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  lf using [sqlite
17f90 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 5e 54 68  3_malloc()]. ^Th
17fa0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
17fb0 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65  t is the.** size
17fc0 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69   of each lookasi
17fd0 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 2e 20  de buffer slot. 
17fe0 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 67 75   ^The third argu
17ff0 6d 65 6e 74 20 69 73 20 74 68 65 20 6e 75 6d 62  ment is the numb
18000 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20  er of.** slots. 
18010 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   The size of the
18020 20 62 75 66 66 65 72 20 69 6e 20 74 68 65 20 66   buffer in the f
18030 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75  irst argument mu
18040 73 74 20 62 65 20 67 72 65 61 74 65 72 20 74 68  st be greater th
18050 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61 6c 20 74  an.** or equal t
18060 6f 20 74 68 65 20 70 72 6f 64 75 63 74 20 6f 66  o the product of
18070 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20   the second and 
18080 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 73 2e  third arguments.
18090 20 20 54 68 65 20 62 75 66 66 65 72 0a 2a 2a 20    The buffer.** 
180a0 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20  must be aligned 
180b0 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f 75  to an 8-byte bou
180c0 6e 64 61 72 79 2e 20 20 5e 49 66 20 74 68 65 20  ndary.  ^If the 
180d0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
180e0 74 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f 44 42 43  to.** SQLITE_DBC
180f0 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20  ONFIG_LOOKASIDE 
18100 69 73 20 6e 6f 74 20 61 20 6d 75 6c 74 69 70 6c  is not a multipl
18110 65 20 6f 66 20 38 2c 20 69 74 20 69 73 20 69 6e  e of 8, it is in
18120 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72 6f 75 6e  ternally.** roun
18130 64 65 64 20 64 6f 77 6e 20 74 6f 20 74 68 65 20  ded down to the 
18140 6e 65 78 74 20 73 6d 61 6c 6c 65 72 20 6d 75 6c  next smaller mul
18150 74 69 70 6c 65 20 6f 66 20 38 2e 20 20 5e 28 54  tiple of 8.  ^(T
18160 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  he lookaside mem
18170 6f 72 79 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61  ory.** configura
18180 74 69 6f 6e 20 66 6f 72 20 61 20 64 61 74 61 62  tion for a datab
18190 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63  ase connection c
181a0 61 6e 20 6f 6e 6c 79 20 62 65 20 63 68 61 6e 67  an only be chang
181b0 65 64 20 77 68 65 6e 20 74 68 61 74 0a 2a 2a 20  ed when that.** 
181c0 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6e 6f  connection is no
181d0 74 20 63 75 72 72 65 6e 74 6c 79 20 75 73 69 6e  t currently usin
181e0 67 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f  g lookaside memo
181f0 72 79 2c 20 6f 72 20 69 6e 20 6f 74 68 65 72 20  ry, or in other 
18200 77 6f 72 64 73 0a 2a 2a 20 77 68 65 6e 20 74 68  words.** when th
18210 65 20 22 63 75 72 72 65 6e 74 20 76 61 6c 75 65  e "current value
18220 22 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  " returned by.**
18230 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 73 74 61   [sqlite3_db_sta
18240 74 75 73 5d 28 44 2c 5b 53 51 4c 49 54 45 5f 43  tus](D,[SQLITE_C
18250 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d  ONFIG_LOOKASIDE]
18260 2c 2e 2e 2e 29 20 69 73 20 7a 65 72 6f 2e 0a 2a  ,...) is zero..*
18270 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f  * Any attempt to
18280 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b   change the look
18290 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 63 6f 6e  aside memory con
182a0 66 69 67 75 72 61 74 69 6f 6e 20 77 68 65 6e 20  figuration when 
182b0 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 6d 65 6d  lookaside.** mem
182c0 6f 72 79 20 69 73 20 69 6e 20 75 73 65 20 6c 65  ory is in use le
182d0 61 76 65 73 20 74 68 65 20 63 6f 6e 66 69 67 75  aves the configu
182e0 72 61 74 69 6f 6e 20 75 6e 63 68 61 6e 67 65 64  ration unchanged
182f0 20 61 6e 64 20 72 65 74 75 72 6e 73 20 0a 2a 2a   and returns .**
18300 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 29   [SQLITE_BUSY].)
18310 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  ^</dd>.**.** <dt
18320 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  >SQLITE_DBCONFIG
18330 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 3c 2f 64 74  _ENABLE_FKEY</dt
18340 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20  >.** <dd> ^This 
18350 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74  option is used t
18360 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61  o enable or disa
18370 62 6c 65 20 74 68 65 20 65 6e 66 6f 72 63 65 6d  ble the enforcem
18380 65 6e 74 20 6f 66 0a 2a 2a 20 5b 66 6f 72 65 69  ent of.** [forei
18390 67 6e 20 6b 65 79 20 63 6f 6e 73 74 72 61 69 6e  gn key constrain
183a0 74 73 5d 2e 20 20 54 68 65 72 65 20 73 68 6f 75  ts].  There shou
183b0 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 69  ld be two additi
183c0 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a  onal arguments..
183d0 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
183e0 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65  ument is an inte
183f0 67 65 72 20 77 68 69 63 68 20 69 73 20 30 20 74  ger which is 0 t
18400 6f 20 64 69 73 61 62 6c 65 20 46 4b 20 65 6e 66  o disable FK enf
18410 6f 72 63 65 6d 65 6e 74 2c 0a 2a 2a 20 70 6f 73  orcement,.** pos
18420 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20  itive to enable 
18430 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f  FK enforcement o
18440 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65  r negative to le
18450 61 76 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65  ave FK enforceme
18460 6e 74 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64 2e  nt.** unchanged.
18470 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72    The second par
18480 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e  ameter is a poin
18490 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ter to an intege
184a0 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20  r into which.** 
184b0 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20  is written 0 or 
184c0 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68  1 to indicate wh
184d0 65 74 68 65 72 20 46 4b 20 65 6e 66 6f 72 63 65  ether FK enforce
184e0 6d 65 6e 74 20 69 73 20 6f 66 66 20 6f 72 20 6f  ment is off or o
184f0 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74  n.** following t
18500 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73  his call.  The s
18510 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
18520 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f  may be a NULL po
18530 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69  inter, in.** whi
18540 63 68 20 63 61 73 65 20 74 68 65 20 46 4b 20 65  ch case the FK e
18550 6e 66 6f 72 63 65 6d 65 6e 74 20 73 65 74 74 69  nforcement setti
18560 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74  ng is not report
18570 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a  ed back. </dd>.*
18580 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
18590 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f  DBCONFIG_ENABLE_
185a0 54 52 49 47 47 45 52 3c 2f 64 74 3e 0a 2a 2a 20  TRIGGER</dt>.** 
185b0 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
185c0 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61  n is used to ena
185d0 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 5b  ble or disable [
185e0 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c  CREATE TRIGGER |
185f0 20 74 72 69 67 67 65 72 73 5d 2e 0a 2a 2a 20 54   triggers]..** T
18600 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74  here should be t
18610 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72  wo additional ar
18620 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20  guments..** The 
18630 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69  first argument i
18640 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69  s an integer whi
18650 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 62  ch is 0 to disab
18660 6c 65 20 74 72 69 67 67 65 72 73 2c 0a 2a 2a 20  le triggers,.** 
18670 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62  positive to enab
18680 6c 65 20 74 72 69 67 67 65 72 73 20 6f 72 20 6e  le triggers or n
18690 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65  egative to leave
186a0 20 74 68 65 20 73 65 74 74 69 6e 67 20 75 6e 63   the setting unc
186b0 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73  hanged..** The s
186c0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
186d0 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
186e0 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20  an integer into 
186f0 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74  which.** is writ
18700 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e  ten 0 or 1 to in
18710 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20 74  dicate whether t
18720 72 69 67 67 65 72 73 20 61 72 65 20 64 69 73 61  riggers are disa
18730 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a  bled or enabled.
18740 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69  ** following thi
18750 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63  s call.  The sec
18760 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61  ond parameter ma
18770 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  y be a NULL poin
18780 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68  ter, in.** which
18790 20 63 61 73 65 20 74 68 65 20 74 72 69 67 67 65   case the trigge
187a0 72 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74  r setting is not
187b0 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20   reported back. 
187c0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c  </dd>.**.** </dl
187d0 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  >.*/.#define SQL
187e0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
187f0 4b 41 53 49 44 45 20 20 20 20 20 20 20 31 30 30  KASIDE       100
18800 31 20 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74 20  1  /* void* int 
18810 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  int */.#define S
18820 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45  QLITE_DBCONFIG_E
18830 4e 41 42 4c 45 5f 46 4b 45 59 20 20 20 20 20 31  NABLE_FKEY     1
18840 30 30 32 20 20 2f 2a 20 69 6e 74 20 69 6e 74 2a  002  /* int int*
18850 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
18860 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
18870 4c 45 5f 54 52 49 47 47 45 52 20 20 31 30 30 33  LE_TRIGGER  1003
18880 20 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f    /* int int* */
18890 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  .../*.** CAPI3RE
188a0 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73  F: Enable Or Dis
188b0 61 62 6c 65 20 45 78 74 65 6e 64 65 64 20 52 65  able Extended Re
188c0 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a  sult Codes.**.**
188d0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78   ^The sqlite3_ex
188e0 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f  tended_result_co
188f0 64 65 73 28 29 20 72 6f 75 74 69 6e 65 20 65 6e  des() routine en
18900 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65  ables or disable
18910 73 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64  s the.** [extend
18920 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  ed result codes]
18930 20 66 65 61 74 75 72 65 20 6f 66 20 53 51 4c 69   feature of SQLi
18940 74 65 2e 20 5e 54 68 65 20 65 78 74 65 6e 64 65  te. ^The extende
18950 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65  d result.** code
18960 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 62  s are disabled b
18970 79 20 64 65 66 61 75 6c 74 20 66 6f 72 20 68 69  y default for hi
18980 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 69  storical compati
18990 62 69 6c 69 74 79 2e 0a 2a 2f 0a 53 51 4c 49 54  bility..*/.SQLIT
189a0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
189b0 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c  3_extended_resul
189c0 74 5f 63 6f 64 65 73 28 73 71 6c 69 74 65 33 2a  t_codes(sqlite3*
189d0 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f  , int onoff);../
189e0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c  *.** CAPI3REF: L
189f0 61 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69 64  ast Insert Rowid
18a00 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 65 6e 74  .**.** ^Each ent
18a10 72 79 20 69 6e 20 6d 6f 73 74 20 53 51 4c 69 74  ry in most SQLit
18a20 65 20 74 61 62 6c 65 73 20 28 65 78 63 65 70 74  e tables (except
18a30 20 66 6f 72 20 5b 57 49 54 48 4f 55 54 20 52 4f   for [WITHOUT RO
18a40 57 49 44 5d 20 74 61 62 6c 65 73 29 0a 2a 2a 20  WID] tables).** 
18a50 68 61 73 20 61 20 75 6e 69 71 75 65 20 36 34 2d  has a unique 64-
18a60 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e  bit signed.** in
18a70 74 65 67 65 72 20 6b 65 79 20 63 61 6c 6c 65 64  teger key called
18a80 20 74 68 65 20 5b 52 4f 57 49 44 20 7c 20 22 72   the [ROWID | "r
18a90 6f 77 69 64 22 5d 2e 20 5e 54 68 65 20 72 6f 77  owid"]. ^The row
18aa0 69 64 20 69 73 20 61 6c 77 61 79 73 20 61 76 61  id is always ava
18ab0 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e 20  ilable.** as an 
18ac0 75 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d  undeclared colum
18ad0 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f  n named ROWID, O
18ae0 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20 61  ID, or _ROWID_ a
18af0 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65 0a  s long as those.
18b00 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74  ** names are not
18b10 20 61 6c 73 6f 20 75 73 65 64 20 62 79 20 65 78   also used by ex
18b20 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65  plicitly declare
18b30 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a 2a  d columns. ^If.*
18b40 2a 20 74 68 65 20 74 61 62 6c 65 20 68 61 73 20  * the table has 
18b50 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65  a column of type
18b60 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52   [INTEGER PRIMAR
18b70 59 20 4b 45 59 5d 20 74 68 65 6e 20 74 68 61 74  Y KEY] then that
18b80 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e   column.** is an
18b90 6f 74 68 65 72 20 61 6c 69 61 73 20 66 6f 72 20  other alias for 
18ba0 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a  the rowid..**.**
18bb0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 61   ^The sqlite3_la
18bc0 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
18bd0 44 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  D) interface ret
18be0 75 72 6e 73 20 74 68 65 20 5b 72 6f 77 69 64 5d  urns the [rowid]
18bf0 20 6f 66 20 74 68 65 20 0a 2a 2a 20 6d 6f 73 74   of the .** most
18c00 20 72 65 63 65 6e 74 20 73 75 63 63 65 73 73 66   recent successf
18c10 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74 6f  ul [INSERT] into
18c20 20 61 20 72 6f 77 69 64 20 74 61 62 6c 65 20 6f   a rowid table o
18c30 72 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65  r [virtual table
18c40 5d 0a 2a 2a 20 6f 6e 20 64 61 74 61 62 61 73 65  ].** on database
18c50 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 0a 2a   connection D..*
18c60 2a 20 5e 49 6e 73 65 72 74 73 20 69 6e 74 6f 20  * ^Inserts into 
18c70 5b 57 49 54 48 4f 55 54 20 52 4f 57 49 44 5d 20  [WITHOUT ROWID] 
18c80 74 61 62 6c 65 73 20 61 72 65 20 6e 6f 74 20 72  tables are not r
18c90 65 63 6f 72 64 65 64 2e 0a 2a 2a 20 5e 49 66 20  ecorded..** ^If 
18ca0 6e 6f 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49  no successful [I
18cb0 4e 53 45 52 54 5d 73 20 69 6e 74 6f 20 72 6f 77  NSERT]s into row
18cc0 69 64 20 74 61 62 6c 65 73 0a 2a 2a 20 68 61 76  id tables.** hav
18cd0 65 20 65 76 65 72 20 6f 63 63 75 72 72 65 64 20  e ever occurred 
18ce0 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  on the database 
18cf0 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2c 20 0a 2a  connection D, .*
18d00 2a 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6c  * then sqlite3_l
18d10 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
18d20 28 44 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  (D) returns zero
18d30 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e 20  ..**.** ^(If an 
18d40 5b 49 4e 53 45 52 54 5d 20 6f 63 63 75 72 73 20  [INSERT] occurs 
18d50 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72  within a trigger
18d60 20 6f 72 20 77 69 74 68 69 6e 20 61 20 5b 76 69   or within a [vi
18d70 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20  rtual table].** 
18d80 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 69  method, then thi
18d90 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 72  s routine will r
18da0 65 74 75 72 6e 20 74 68 65 20 5b 72 6f 77 69 64  eturn the [rowid
18db0 5d 20 6f 66 20 74 68 65 20 69 6e 73 65 72 74 65  ] of the inserte
18dc0 64 0a 2a 2a 20 72 6f 77 20 61 73 20 6c 6f 6e 67  d.** row as long
18dd0 20 61 73 20 74 68 65 20 74 72 69 67 67 65 72 20   as the trigger 
18de0 6f 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  or virtual table
18df0 20 6d 65 74 68 6f 64 20 69 73 20 72 75 6e 6e 69   method is runni
18e00 6e 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 20  ng..** But once 
18e10 74 68 65 20 74 72 69 67 67 65 72 20 6f 72 20 76  the trigger or v
18e20 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 65 74  irtual table met
18e30 68 6f 64 20 65 6e 64 73 2c 20 74 68 65 20 76 61  hod ends, the va
18e40 6c 75 65 20 72 65 74 75 72 6e 65 64 20 0a 2a 2a  lue returned .**
18e50 20 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65   by this routine
18e60 20 72 65 76 65 72 74 73 20 74 6f 20 77 68 61 74   reverts to what
18e70 20 69 74 20 77 61 73 20 62 65 66 6f 72 65 20 74   it was before t
18e80 68 65 20 74 72 69 67 67 65 72 20 6f 72 20 76 69  he trigger or vi
18e90 72 74 75 61 6c 0a 2a 2a 20 74 61 62 6c 65 20 6d  rtual.** table m
18ea0 65 74 68 6f 64 20 62 65 67 61 6e 2e 29 5e 0a 2a  ethod began.)^.*
18eb0 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 54  *.** ^An [INSERT
18ec0 5d 20 74 68 61 74 20 66 61 69 6c 73 20 64 75 65  ] that fails due
18ed0 20 74 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e 74   to a constraint
18ee0 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f   violation is no
18ef0 74 20 61 0a 2a 2a 20 73 75 63 63 65 73 73 66 75  t a.** successfu
18f00 6c 20 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20 64  l [INSERT] and d
18f10 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74  oes not change t
18f20 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
18f30 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75  d by this.** rou
18f40 74 69 6e 65 2e 20 20 5e 54 68 75 73 20 49 4e 53  tine.  ^Thus INS
18f50 45 52 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53  ERT OR FAIL, INS
18f60 45 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49  ERT OR IGNORE, I
18f70 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43  NSERT OR ROLLBAC
18f80 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54  K,.** and INSERT
18f90 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e   OR ABORT make n
18fa0 6f 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65  o changes to the
18fb0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
18fc0 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65   this.** routine
18fd0 20 77 68 65 6e 20 74 68 65 69 72 20 69 6e 73 65   when their inse
18fe0 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 5e 28  rtion fails.  ^(
18ff0 57 68 65 6e 20 49 4e 53 45 52 54 20 4f 52 20 52  When INSERT OR R
19000 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e  EPLACE.** encoun
19010 74 65 72 73 20 61 20 63 6f 6e 73 74 72 61 69 6e  ters a constrain
19020 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20  t violation, it 
19030 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20  does not fail.  
19040 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f  The.** INSERT co
19050 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c  ntinues to compl
19060 65 74 69 6f 6e 20 61 66 74 65 72 20 64 65 6c 65  etion after dele
19070 74 69 6e 67 20 72 6f 77 73 20 74 68 61 74 20 63  ting rows that c
19080 61 75 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e  aused.** the con
19090 73 74 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20  straint problem 
190a0 73 6f 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50  so INSERT OR REP
190b0 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77 61 79 73  LACE will always
190c0 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72   change.** the r
190d0 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74  eturn value of t
190e0 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e 29 5e  his interface.)^
190f0 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20  .**.** ^For the 
19100 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73  purposes of this
19110 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e   routine, an [IN
19120 53 45 52 54 5d 20 69 73 20 63 6f 6e 73 69 64 65  SERT] is conside
19130 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63  red to.** be suc
19140 63 65 73 73 66 75 6c 20 65 76 65 6e 20 69 66 20  cessful even if 
19150 69 74 20 69 73 20 73 75 62 73 65 71 75 65 6e 74  it is subsequent
19160 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a  ly rolled back..
19170 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74  **.** This funct
19180 69 6f 6e 20 69 73 20 61 63 63 65 73 73 69 62 6c  ion is accessibl
19190 65 20 74 6f 20 53 51 4c 20 73 74 61 74 65 6d 65  e to SQL stateme
191a0 6e 74 73 20 76 69 61 20 74 68 65 0a 2a 2a 20 5b  nts via the.** [
191b0 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
191c0 64 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  d() SQL function
191d0 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65  ]..**.** If a se
191e0 70 61 72 61 74 65 20 74 68 72 65 61 64 20 70 65  parate thread pe
191f0 72 66 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e  rforms a new [IN
19200 53 45 52 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d  SERT] on the sam
19210 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  e.** database co
19220 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74  nnection while t
19230 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74  he [sqlite3_last
19240 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d  _insert_rowid()]
19250 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  .** function is 
19260 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 73  running and thus
19270 20 63 68 61 6e 67 65 73 20 74 68 65 20 6c 61 73   changes the las
19280 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d  t insert [rowid]
19290 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 76 61  ,.** then the va
192a0 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
192b0 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e  [sqlite3_last_in
192c0 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 69 73  sert_rowid()] is
192d0 0a 2a 2a 20 75 6e 70 72 65 64 69 63 74 61 62 6c  .** unpredictabl
192e0 65 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20  e and might not 
192f0 65 71 75 61 6c 20 65 69 74 68 65 72 20 74 68 65  equal either the
19300 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 0a   old or the new.
19310 2a 2a 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b  ** last insert [
19320 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 53 51 4c 49 54  rowid]..*/.SQLIT
19330 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e  E_API sqlite3_in
19340 74 36 34 20 73 71 6c 69 74 65 33 5f 6c 61 73 74  t64 sqlite3_last
19350 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 71  _insert_rowid(sq
19360 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
19370 43 41 50 49 33 52 45 46 3a 20 43 6f 75 6e 74 20  CAPI3REF: Count 
19380 54 68 65 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f  The Number Of Ro
19390 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a  ws Modified.**.*
193a0 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  * ^This function
193b0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
193c0 62 65 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69  ber of rows modi
193d0 66 69 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f  fied, inserted o
193e0 72 0a 2a 2a 20 64 65 6c 65 74 65 64 20 62 79 20  r.** deleted by 
193f0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c  the most recentl
19400 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45  y completed INSE
19410 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45  RT, UPDATE or DE
19420 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  LETE.** statemen
19430 74 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73  t on the databas
19440 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 70 65  e connection spe
19450 63 69 66 69 65 64 20 62 79 20 74 68 65 20 6f 6e  cified by the on
19460 6c 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  ly parameter..**
19470 20 5e 45 78 65 63 75 74 69 6e 67 20 61 6e 79 20   ^Executing any 
19480 6f 74 68 65 72 20 74 79 70 65 20 6f 66 20 53 51  other type of SQ
19490 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73  L statement does
194a0 20 6e 6f 74 20 6d 6f 64 69 66 79 20 74 68 65 20   not modify the 
194b0 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65  value.** returne
194c0 64 20 62 79 20 74 68 69 73 20 66 75 6e 63 74 69  d by this functi
194d0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20  on..**.** ^Only 
194e0 63 68 61 6e 67 65 73 20 6d 61 64 65 20 64 69 72  changes made dir
194f0 65 63 74 6c 79 20 62 79 20 74 68 65 20 49 4e 53  ectly by the INS
19500 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44  ERT, UPDATE or D
19510 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20  ELETE statement 
19520 61 72 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65  are.** considere
19530 64 20 2d 20 61 75 78 69 6c 69 61 72 79 20 63 68  d - auxiliary ch
19540 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20  anges caused by 
19550 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20  [CREATE TRIGGER 
19560 7c 20 74 72 69 67 67 65 72 73 5d 2c 20 0a 2a 2a  | triggers], .**
19570 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63   [foreign key ac
19580 74 69 6f 6e 73 5d 20 6f 72 20 5b 52 45 50 4c 41  tions] or [REPLA
19590 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20 72  CE] constraint r
195a0 65 73 6f 6c 75 74 69 6f 6e 20 61 72 65 20 6e 6f  esolution are no
195b0 74 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20 0a 2a  t counted..** .*
195c0 2a 20 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76  * Changes to a v
195d0 69 65 77 20 74 68 61 74 20 61 72 65 20 69 6e 74  iew that are int
195e0 65 72 63 65 70 74 65 64 20 62 79 20 0a 2a 2a 20  ercepted by .** 
195f0 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67  [INSTEAD OF trig
19600 67 65 72 20 7c 20 49 4e 53 54 45 41 44 20 4f 46  ger | INSTEAD OF
19610 20 74 72 69 67 67 65 72 73 5d 20 61 72 65 20 6e   triggers] are n
19620 6f 74 20 63 6f 75 6e 74 65 64 2e 20 5e 54 68 65  ot counted. ^The
19630 20 76 61 6c 75 65 20 0a 2a 2a 20 72 65 74 75 72   value .** retur
19640 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  ned by sqlite3_c
19650 68 61 6e 67 65 73 28 29 20 69 6d 6d 65 64 69 61  hanges() immedia
19660 74 65 6c 79 20 61 66 74 65 72 20 61 6e 20 49 4e  tely after an IN
19670 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20  SERT, UPDATE or 
19680 0a 2a 2a 20 44 45 4c 45 54 45 20 73 74 61 74 65  .** DELETE state
19690 6d 65 6e 74 20 72 75 6e 20 6f 6e 20 61 20 76 69  ment run on a vi
196a0 65 77 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72  ew is always zer
196b0 6f 2e 20 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20  o. Only changes 
196c0 6d 61 64 65 20 74 6f 20 72 65 61 6c 20 0a 2a 2a  made to real .**
196d0 20 74 61 62 6c 65 73 20 61 72 65 20 63 6f 75 6e   tables are coun
196e0 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 67  ted..**.** Thing
196f0 73 20 61 72 65 20 6d 6f 72 65 20 63 6f 6d 70 6c  s are more compl
19700 69 63 61 74 65 64 20 69 66 20 74 68 65 20 73 71  icated if the sq
19710 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20  lite3_changes() 
19720 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 65  function is.** e
19730 78 65 63 75 74 65 64 20 77 68 69 6c 65 20 61 20  xecuted while a 
19740 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20  trigger program 
19750 69 73 20 72 75 6e 6e 69 6e 67 2e 20 54 68 69 73  is running. This
19760 20 6d 61 79 20 68 61 70 70 65 6e 20 69 66 20 74   may happen if t
19770 68 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73  he.** program us
19780 65 73 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28  es the [changes(
19790 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2c  ) SQL function],
197a0 20 6f 72 20 69 66 20 73 6f 6d 65 20 6f 74 68 65   or if some othe
197b0 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75  r callback.** fu
197c0 6e 63 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 73  nction invokes s
197d0 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
197e0 20 64 69 72 65 63 74 6c 79 2e 20 45 73 73 65 6e   directly. Essen
197f0 74 69 61 6c 6c 79 3a 0a 2a 2a 20 0a 2a 2a 20 3c  tially:.** .** <
19800 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28  ul>.**   <li> ^(
19810 42 65 66 6f 72 65 20 65 6e 74 65 72 69 6e 67 20  Before entering 
19820 61 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61  a trigger progra
19830 6d 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  m the value retu
19840 72 6e 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20  rned by.**      
19850 20 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65    sqlite3_change
19860 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  s() function is 
19870 73 61 76 65 64 2e 20 41 66 74 65 72 20 74 68 65  saved. After the
19880 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d   trigger program
19890 20 0a 2a 2a 20 20 20 20 20 20 20 20 68 61 73 20   .**        has 
198a0 66 69 6e 69 73 68 65 64 2c 20 74 68 65 20 6f 72  finished, the or
198b0 69 67 69 6e 61 6c 20 76 61 6c 75 65 20 69 73 20  iginal value is 
198c0 72 65 73 74 6f 72 65 64 2e 29 5e 0a 2a 2a 20 0a  restored.)^.** .
198d0 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28 57 69 74 68  **   <li> ^(With
198e0 69 6e 20 61 20 74 72 69 67 67 65 72 20 70 72 6f  in a trigger pro
198f0 67 72 61 6d 20 65 61 63 68 20 49 4e 53 45 52 54  gram each INSERT
19900 2c 20 55 50 44 41 54 45 20 61 6e 64 20 44 45 4c  , UPDATE and DEL
19910 45 54 45 20 0a 2a 2a 20 20 20 20 20 20 20 20 73  ETE .**        s
19920 74 61 74 65 6d 65 6e 74 20 73 65 74 73 20 74 68  tatement sets th
19930 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
19940 20 62 79 20 73 71 6c 69 74 65 33 5f 63 68 61 6e   by sqlite3_chan
19950 67 65 73 28 29 20 0a 2a 2a 20 20 20 20 20 20 20  ges() .**       
19960 20 75 70 6f 6e 20 63 6f 6d 70 6c 65 74 69 6f 6e   upon completion
19970 20 61 73 20 6e 6f 72 6d 61 6c 2e 20 4f 66 20 63   as normal. Of c
19980 6f 75 72 73 65 2c 20 74 68 69 73 20 76 61 6c 75  ourse, this valu
19990 65 20 77 69 6c 6c 20 6e 6f 74 20 69 6e 63 6c 75  e will not inclu
199a0 64 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 61 6e  de .**        an
199b0 79 20 63 68 61 6e 67 65 73 20 70 65 72 66 6f 72  y changes perfor
199c0 6d 65 64 20 62 79 20 73 75 62 2d 74 72 69 67 67  med by sub-trigg
199d0 65 72 73 2c 20 61 73 20 74 68 65 20 73 71 6c 69  ers, as the sqli
199e0 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 0a 2a  te3_changes() .*
199f0 2a 20 20 20 20 20 20 20 20 76 61 6c 75 65 20 77  *        value w
19a00 69 6c 6c 20 62 65 20 73 61 76 65 64 20 61 6e 64  ill be saved and
19a10 20 72 65 73 74 6f 72 65 64 20 61 66 74 65 72 20   restored after 
19a20 65 61 63 68 20 73 75 62 2d 74 72 69 67 67 65 72  each sub-trigger
19a30 20 68 61 73 20 72 75 6e 2e 29 5e 0a 2a 2a 20 3c   has run.)^.** <
19a40 2f 75 6c 3e 0a 2a 2a 20 0a 2a 2a 20 5e 54 68 69  /ul>.** .** ^Thi
19a50 73 20 6d 65 61 6e 73 20 74 68 61 74 20 69 66 20  s means that if 
19a60 74 68 65 20 63 68 61 6e 67 65 73 28 29 20 53 51  the changes() SQ
19a70 4c 20 66 75 6e 63 74 69 6f 6e 20 28 6f 72 20 73  L function (or s
19a80 69 6d 69 6c 61 72 29 20 69 73 20 75 73 65 64 0a  imilar) is used.
19a90 2a 2a 20 62 79 20 74 68 65 20 66 69 72 73 74 20  ** by the first 
19aa0 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f  INSERT, UPDATE o
19ab0 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65  r DELETE stateme
19ac0 6e 74 20 77 69 74 68 69 6e 20 61 20 74 72 69 67  nt within a trig
19ad0 67 65 72 2c 20 69 74 20 0a 2a 2a 20 72 65 74 75  ger, it .** retu
19ae0 72 6e 73 20 74 68 65 20 76 61 6c 75 65 20 61 73  rns the value as
19af0 20 73 65 74 20 77 68 65 6e 20 74 68 65 20 63 61   set when the ca
19b00 6c 6c 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20  lling statement 
19b10 62 65 67 61 6e 20 65 78 65 63 75 74 69 6e 67 2e  began executing.
19b20 0a 2a 2a 20 5e 49 66 20 69 74 20 69 73 20 75 73  .** ^If it is us
19b30 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64  ed by the second
19b40 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 73   or subsequent s
19b50 75 63 68 20 73 74 61 74 65 6d 65 6e 74 20 77 69  uch statement wi
19b60 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 20 0a  thin a trigger .
19b70 2a 2a 20 70 72 6f 67 72 61 6d 2c 20 74 68 65 20  ** program, the 
19b80 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 72  value returned r
19b90 65 66 6c 65 63 74 73 20 74 68 65 20 6e 75 6d 62  eflects the numb
19ba0 65 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66  er of rows modif
19bb0 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 70  ied by the .** p
19bc0 72 65 76 69 6f 75 73 20 49 4e 53 45 52 54 2c 20  revious INSERT, 
19bd0 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45  UPDATE or DELETE
19be0 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69   statement withi
19bf0 6e 20 74 68 65 20 73 61 6d 65 20 74 72 69 67 67  n the same trigg
19c00 65 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  er..**.** See al
19c10 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  so the [sqlite3_
19c20 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d  total_changes()]
19c30 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a   interface, the.
19c40 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65  ** [count_change
19c50 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74  s pragma], and t
19c60 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51  he [changes() SQ
19c70 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a  L function]..**.
19c80 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65  ** If a separate
19c90 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68   thread makes ch
19ca0 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d  anges on the sam
19cb0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
19cc0 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b  ction.** while [
19cd0 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
19ce0 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68  )] is running th
19cf0 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  en the value ret
19d00 75 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72  urned.** is unpr
19d10 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f  edictable and no
19d20 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f  t meaningful..*/
19d30 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
19d40 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
19d50 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
19d60 2a 20 43 41 50 49 33 52 45 46 3a 20 54 6f 74 61  * CAPI3REF: Tota
19d70 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73  l Number Of Rows
19d80 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20   Modified.**.** 
19d90 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72  ^This function r
19da0 65 74 75 72 6e 73 20 74 68 65 20 74 6f 74 61 6c  eturns the total
19db0 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20   number of rows 
19dc0 69 6e 73 65 72 74 65 64 2c 20 6d 6f 64 69 66 69  inserted, modifi
19dd0 65 64 20 6f 72 0a 2a 2a 20 64 65 6c 65 74 65 64  ed or.** deleted
19de0 20 62 79 20 61 6c 6c 20 5b 49 4e 53 45 52 54 5d   by all [INSERT]
19df0 2c 20 5b 55 50 44 41 54 45 5d 20 6f 72 20 5b 44  , [UPDATE] or [D
19e00 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65 6e 74  ELETE] statement
19e10 73 20 63 6f 6d 70 6c 65 74 65 64 0a 2a 2a 20 73  s completed.** s
19e20 69 6e 63 65 20 74 68 65 20 64 61 74 61 62 61 73  ince the databas
19e30 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 61 73  e connection was
19e40 20 6f 70 65 6e 65 64 2c 20 69 6e 63 6c 75 64 69   opened, includi
19e50 6e 67 20 74 68 6f 73 65 20 65 78 65 63 75 74 65  ng those execute
19e60 64 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20  d as.** part of 
19e70 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 73  trigger programs
19e80 2e 20 5e 45 78 65 63 75 74 69 6e 67 20 61 6e 79  . ^Executing any
19e90 20 6f 74 68 65 72 20 74 79 70 65 20 6f 66 20 53   other type of S
19ea0 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  QL statement.** 
19eb0 64 6f 65 73 20 6e 6f 74 20 61 66 66 65 63 74 20  does not affect 
19ec0 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
19ed0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 6f  ed by sqlite3_to
19ee0 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 2e 0a 2a  tal_changes()..*
19ef0 2a 20 0a 2a 2a 20 5e 43 68 61 6e 67 65 73 20 6d  * .** ^Changes m
19f00 61 64 65 20 61 73 20 70 61 72 74 20 6f 66 20 5b  ade as part of [
19f10 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69  foreign key acti
19f20 6f 6e 73 5d 20 61 72 65 20 69 6e 63 6c 75 64 65  ons] are include
19f30 64 20 69 6e 20 74 68 65 0a 2a 2a 20 63 6f 75 6e  d in the.** coun
19f40 74 2c 20 62 75 74 20 74 68 6f 73 65 20 6d 61 64  t, but those mad
19f50 65 20 61 73 20 70 61 72 74 20 6f 66 20 52 45 50  e as part of REP
19f60 4c 41 43 45 20 63 6f 6e 73 74 72 61 69 6e 74 20  LACE constraint 
19f70 72 65 73 6f 6c 75 74 69 6f 6e 20 61 72 65 0a 2a  resolution are.*
19f80 2a 20 6e 6f 74 2e 20 5e 43 68 61 6e 67 65 73 20  * not. ^Changes 
19f90 74 6f 20 61 20 76 69 65 77 20 74 68 61 74 20 61  to a view that a
19fa0 72 65 20 69 6e 74 65 72 63 65 70 74 65 64 20 62  re intercepted b
19fb0 79 20 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69  y INSTEAD OF tri
19fc0 67 67 65 72 73 20 0a 2a 2a 20 61 72 65 20 6e 6f  ggers .** are no
19fd0 74 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20 0a 2a  t counted..** .*
19fe0 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b  * See also the [
19ff0 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
1a000 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68  )] interface, th
1a010 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e  e.** [count_chan
1a020 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64  ges pragma], and
1a030 20 74 68 65 20 5b 74 6f 74 61 6c 5f 63 68 61 6e   the [total_chan
1a040 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69  ges() SQL functi
1a050 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20  on]..**.** If a 
1a060 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20  separate thread 
1a070 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e  makes changes on
1a080 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
1a090 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
1a0a0 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f   while [sqlite3_
1a0b0 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d  total_changes()]
1a0c0 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e   is running then
1a0d0 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65   the value.** re
1a0e0 74 75 72 6e 65 64 20 69 73 20 75 6e 70 72 65 64  turned is unpred
1a0f0 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20  ictable and not 
1a100 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 53  meaningful..*/.S
1a110 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
1a120 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
1a130 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  ges(sqlite3*);..
1a140 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1a150 49 6e 74 65 72 72 75 70 74 20 41 20 4c 6f 6e 67  Interrupt A Long
1a160 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72 79 0a 2a  -Running Query.*
1a170 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74  *.** ^This funct
1a180 69 6f 6e 20 63 61 75 73 65 73 20 61 6e 79 20 70  ion causes any p
1a190 65 6e 64 69 6e 67 20 64 61 74 61 62 61 73 65 20  ending database 
1a1a0 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f  operation to abo
1a1b0 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e  rt and.** return
1a1c0 20 61 74 20 69 74 73 20 65 61 72 6c 69 65 73 74   at its earliest
1a1d0 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20 54 68   opportunity. Th
1a1e0 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74 79  is routine is ty
1a1f0 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65  pically.** calle
1a200 64 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f  d in response to
1a210 20 61 20 75 73 65 72 20 61 63 74 69 6f 6e 20 73   a user action s
1a220 75 63 68 20 61 73 20 70 72 65 73 73 69 6e 67 20  uch as pressing 
1a230 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43  "Cancel".** or C
1a240 74 72 6c 2d 43 20 77 68 65 72 65 20 74 68 65 20  trl-C where the 
1a250 75 73 65 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e  user wants a lon
1a260 67 20 71 75 65 72 79 20 6f 70 65 72 61 74 69 6f  g query operatio
1a270 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d  n to halt.** imm
1a280 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ediately..**.** 
1a290 5e 49 74 20 69 73 20 73 61 66 65 20 74 6f 20 63  ^It is safe to c
1a2a0 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65  all this routine
1a2b0 20 66 72 6f 6d 20 61 20 74 68 72 65 61 64 20 64   from a thread d
1a2c0 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 68  ifferent from th
1a2d0 65 0a 2a 2a 20 74 68 72 65 61 64 20 74 68 61 74  e.** thread that
1a2e0 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 72 75   is currently ru
1a2f0 6e 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62 61  nning the databa
1a300 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42  se operation.  B
1a310 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20  ut it.** is not 
1a320 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69  safe to call thi
1a330 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61  s routine with a
1a340 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1a350 63 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69  ction] that.** i
1a360 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68  s closed or migh
1a370 74 20 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 73  t close before s
1a380 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
1a390 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a  () returns..**.*
1a3a0 2a 20 5e 49 66 20 61 6e 20 53 51 4c 20 6f 70 65  * ^If an SQL ope
1a3b0 72 61 74 69 6f 6e 20 69 73 20 76 65 72 79 20 6e  ration is very n
1a3c0 65 61 72 6c 79 20 66 69 6e 69 73 68 65 64 20 61  early finished a
1a3d0 74 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e 0a  t the time when.
1a3e0 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  ** sqlite3_inter
1a3f0 72 75 70 74 28 29 20 69 73 20 63 61 6c 6c 65 64  rupt() is called
1a400 2c 20 74 68 65 6e 20 69 74 20 6d 69 67 68 74 20  , then it might 
1a410 6e 6f 74 20 68 61 76 65 20 61 6e 20 6f 70 70 6f  not have an oppo
1a420 72 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65  rtunity.** to be
1a430 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 6e 64   interrupted and
1a440 20 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75 65 20   might continue 
1a450 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a  to completion..*
1a460 2a 0a 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 65  *.** ^An SQL ope
1a470 72 61 74 69 6f 6e 20 74 68 61 74 20 69 73 20 69  ration that is i
1a480 6e 74 65 72 72 75 70 74 65 64 20 77 69 6c 6c 20  nterrupted will 
1a490 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49  return [SQLITE_I
1a4a0 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49  NTERRUPT]..** ^I
1a4b0 66 20 74 68 65 20 69 6e 74 65 72 72 75 70 74 65  f the interrupte
1a4c0 64 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20  d SQL operation 
1a4d0 69 73 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50  is an INSERT, UP
1a4e0 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a  DATE, or DELETE.
1a4f0 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 73 69 64  ** that is insid
1a500 65 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72  e an explicit tr
1a510 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20  ansaction, then 
1a520 74 68 65 20 65 6e 74 69 72 65 20 74 72 61 6e 73  the entire trans
1a530 61 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62  action.** will b
1a540 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75  e rolled back au
1a550 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a  tomatically..**.
1a560 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1a570 69 6e 74 65 72 72 75 70 74 28 44 29 20 63 61 6c  interrupt(D) cal
1a580 6c 20 69 73 20 69 6e 20 65 66 66 65 63 74 20 75  l is in effect u
1a590 6e 74 69 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74  ntil all current
1a5a0 6c 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51  ly running.** SQ
1a5b0 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20  L statements on 
1a5c0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1a5d0 74 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65  tion] D complete
1a5e0 2e 20 20 5e 41 6e 79 20 6e 65 77 20 53 51 4c 20  .  ^Any new SQL 
1a5f0 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68  statements.** th
1a600 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61  at are started a
1a610 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 33  fter the sqlite3
1a620 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c  _interrupt() cal
1a630 6c 20 61 6e 64 20 62 65 66 6f 72 65 20 74 68 65  l and before the
1a640 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61   .** running sta
1a650 74 65 6d 65 6e 74 73 20 72 65 61 63 68 65 73 20  tements reaches 
1a660 7a 65 72 6f 20 61 72 65 20 69 6e 74 65 72 72 75  zero are interru
1a670 70 74 65 64 20 61 73 20 69 66 20 74 68 65 79 20  pted as if they 
1a680 68 61 64 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e  had been.** runn
1a690 69 6e 67 20 70 72 69 6f 72 20 74 6f 20 74 68 65  ing prior to the
1a6a0 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
1a6b0 70 74 28 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 77  pt() call.  ^New
1a6c0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
1a6d0 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72  ** that are star
1a6e0 74 65 64 20 61 66 74 65 72 20 74 68 65 20 72 75  ted after the ru
1a6f0 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20  nning statement 
1a700 63 6f 75 6e 74 20 72 65 61 63 68 65 73 20 7a 65  count reaches ze
1a710 72 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66  ro are.** not ef
1a720 66 65 63 74 65 64 20 62 79 20 74 68 65 20 73 71  fected by the sq
1a730 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
1a740 29 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f  )..** ^A call to
1a750 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
1a760 70 74 28 44 29 20 74 68 61 74 20 6f 63 63 75 72  pt(D) that occur
1a770 73 20 77 68 65 6e 20 74 68 65 72 65 20 61 72 65  s when there are
1a780 20 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53   no running.** S
1a790 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 73  QL statements is
1a7a0 20 61 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73   a no-op and has
1a7b0 20 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20 53 51   no effect on SQ
1a7c0 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
1a7d0 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64  that are started
1a7e0 20 61 66 74 65 72 20 74 68 65 20 73 71 6c 69 74   after the sqlit
1a7f0 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63  e3_interrupt() c
1a800 61 6c 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a  all returns..**.
1a810 2a 2a 20 49 66 20 74 68 65 20 64 61 74 61 62 61  ** If the databa
1a820 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c  se connection cl
1a830 6f 73 65 73 20 77 68 69 6c 65 20 5b 73 71 6c 69  oses while [sqli
1a840 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d  te3_interrupt()]
1a850 0a 2a 2a 20 69 73 20 72 75 6e 6e 69 6e 67 20 74  .** is running t
1a860 68 65 6e 20 62 61 64 20 74 68 69 6e 67 73 20 77  hen bad things w
1a870 69 6c 6c 20 6c 69 6b 65 6c 79 20 68 61 70 70 65  ill likely happe
1a880 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  n..*/.SQLITE_API
1a890 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 6e   void sqlite3_in
1a8a0 74 65 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a  terrupt(sqlite3*
1a8b0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1a8c0 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66  EF: Determine If
1a8d0 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e   An SQL Statemen
1a8e0 74 20 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a  t Is Complete.**
1a8f0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
1a900 65 73 20 61 72 65 20 75 73 65 66 75 6c 20 64 75  es are useful du
1a910 72 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e  ring command-lin
1a920 65 20 69 6e 70 75 74 20 74 6f 20 64 65 74 65 72  e input to deter
1a930 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20 63  mine if the.** c
1a940 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64  urrently entered
1a950 20 74 65 78 74 20 73 65 65 6d 73 20 74 6f 20 66   text seems to f
1a960 6f 72 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20 53  orm a complete S
1a970 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a  QL statement or.
1a980 2a 2a 20 69 66 20 61 64 64 69 74 69 6f 6e 61 6c  ** if additional
1a990 20 69 6e 70 75 74 20 69 73 20 6e 65 65 64 65 64   input is needed
1a9a0 20 62 65 66 6f 72 65 20 73 65 6e 64 69 6e 67 20   before sending 
1a9b0 74 68 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a  the text into.**
1a9c0 20 53 51 4c 69 74 65 20 66 6f 72 20 70 61 72 73   SQLite for pars
1a9d0 69 6e 67 2e 20 20 5e 54 68 65 73 65 20 72 6f 75  ing.  ^These rou
1a9e0 74 69 6e 65 73 20 72 65 74 75 72 6e 20 31 20 69  tines return 1 i
1a9f0 66 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69  f the input stri
1aa00 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73 20 74 6f  ng.** appears to
1aa10 20 62 65 20 61 20 63 6f 6d 70 6c 65 74 65 20 53   be a complete S
1aa20 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e  QL statement.  ^
1aa30 41 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6a  A statement is j
1aa40 75 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63  udged to be.** c
1aa50 6f 6d 70 6c 65 74 65 20 69 66 20 69 74 20 65 6e  omplete if it en
1aa60 64 73 20 77 69 74 68 20 61 20 73 65 6d 69 63 6f  ds with a semico
1aa70 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73  lon token and is
1aa80 20 6e 6f 74 20 61 20 70 72 65 66 69 78 20 6f 66   not a prefix of
1aa90 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65   a.** well-forme
1aaa0 64 20 43 52 45 41 54 45 20 54 52 49 47 47 45 52  d CREATE TRIGGER
1aab0 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65   statement.  ^Se
1aac0 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72  micolons that ar
1aad0 65 20 65 6d 62 65 64 64 65 64 20 77 69 74 68 69  e embedded withi
1aae0 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65  n.** string lite
1aaf0 72 61 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69  rals or quoted i
1ab00 64 65 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20  dentifier names 
1ab10 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20  or comments are 
1ab20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65  not.** independe
1ab30 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20  nt tokens (they 
1ab40 61 72 65 20 70 61 72 74 20 6f 66 20 74 68 65 20  are part of the 
1ab50 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74  token in which t
1ab60 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64  hey are.** embed
1ab70 64 65 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f  ded) and thus do
1ab80 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20   not count as a 
1ab90 73 74 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e  statement termin
1aba0 61 74 6f 72 2e 20 20 5e 57 68 69 74 65 73 70 61  ator.  ^Whitespa
1abb0 63 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e  ce.** and commen
1abc0 74 73 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74  ts that follow t
1abd0 68 65 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c  he final semicol
1abe0 6f 6e 20 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a  on are ignored..
1abf0 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
1ac00 74 69 6e 65 73 20 72 65 74 75 72 6e 20 30 20 69  tines return 0 i
1ac10 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
1ac20 69 73 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20  is incomplete.  
1ac30 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20  ^If a.** memory 
1ac40 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73  allocation fails
1ac50 2c 20 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f  , then SQLITE_NO
1ac60 4d 45 4d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  MEM is returned.
1ac70 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
1ac80 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61  utines do not pa
1ac90 72 73 65 20 74 68 65 20 53 51 4c 20 73 74 61 74  rse the SQL stat
1aca0 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77  ements thus.** w
1acb0 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73  ill not detect s
1acc0 79 6e 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63  yntactically inc
1acd0 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a  orrect SQL..**.*
1ace0 2a 20 5e 28 49 66 20 53 51 4c 69 74 65 20 68 61  * ^(If SQLite ha
1acf0 73 20 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74 69  s not been initi
1ad00 61 6c 69 7a 65 64 20 75 73 69 6e 67 20 5b 73 71  alized using [sq
1ad10 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
1ad20 28 29 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f  ()] prior .** to
1ad30 20 69 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65   invoking sqlite
1ad40 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 74  3_complete16() t
1ad50 68 65 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  hen sqlite3_init
1ad60 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f  ialize() is invo
1ad70 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63  ked.** automatic
1ad80 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f  ally by sqlite3_
1ad90 63 6f 6d 70 6c 65 74 65 31 36 28 29 2e 20 20 49  complete16().  I
1ada0 66 20 74 68 61 74 20 69 6e 69 74 69 61 6c 69 7a  f that initializ
1adb0 61 74 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20  ation fails,.** 
1adc0 74 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20  then the return 
1add0 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74  value from sqlit
1ade0 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20  e3_complete16() 
1adf0 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f  will be non-zero
1ae00 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73 73 20 6f  .** regardless o
1ae10 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
1ae20 20 74 68 65 20 69 6e 70 75 74 20 53 51 4c 20 69   the input SQL i
1ae30 73 20 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a  s complete.)^.**
1ae40 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f  .** The input to
1ae50 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65   [sqlite3_comple
1ae60 74 65 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20  te()] must be a 
1ae70 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
1ae80 2a 2a 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e  ** UTF-8 string.
1ae90 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74  .**.** The input
1aea0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d   to [sqlite3_com
1aeb0 70 6c 65 74 65 31 36 28 29 5d 20 6d 75 73 74 20  plete16()] must 
1aec0 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  be a zero-termin
1aed0 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73  ated.** UTF-16 s
1aee0 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20  tring in native 
1aef0 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 53  byte order..*/.S
1af00 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
1af10 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63  lite3_complete(c
1af20 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 29 3b  onst char *sql);
1af30 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
1af40 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
1af50 31 36 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  16(const void *s
1af60 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ql);../*.** CAPI
1af70 33 52 45 46 3a 20 52 65 67 69 73 74 65 72 20 41  3REF: Register A
1af80 20 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e   Callback To Han
1af90 64 6c 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20  dle SQLITE_BUSY 
1afa0 45 72 72 6f 72 73 0a 2a 2a 20 4b 45 59 57 4f 52  Errors.** KEYWOR
1afb0 44 53 3a 20 7b 62 75 73 79 2d 68 61 6e 64 6c 65  DS: {busy-handle
1afc0 72 20 63 61 6c 6c 62 61 63 6b 7d 20 7b 62 75 73  r callback} {bus
1afd0 79 20 68 61 6e 64 6c 65 72 7d 0a 2a 2a 0a 2a 2a  y handler}.**.**
1afe0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 75   ^The sqlite3_bu
1aff0 73 79 5f 68 61 6e 64 6c 65 72 28 44 2c 58 2c 50  sy_handler(D,X,P
1b000 29 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61  ) routine sets a
1b010 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
1b020 6f 6e 20 58 0a 2a 2a 20 74 68 61 74 20 6d 69 67  on X.** that mig
1b030 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69  ht be invoked wi
1b040 74 68 20 61 72 67 75 6d 65 6e 74 20 50 20 77 68  th argument P wh
1b050 65 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74 74  enever.** an att
1b060 65 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f 20  empt is made to 
1b070 61 63 63 65 73 73 20 61 20 64 61 74 61 62 61 73  access a databas
1b080 65 20 74 61 62 6c 65 20 61 73 73 6f 63 69 61 74  e table associat
1b090 65 64 20 77 69 74 68 0a 2a 2a 20 5b 64 61 74 61  ed with.** [data
1b0a0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1b0b0 20 44 20 77 68 65 6e 20 61 6e 6f 74 68 65 72 20   D when another 
1b0c0 74 68 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72 6f  thread.** or pro
1b0d0 63 65 73 73 20 68 61 73 20 74 68 65 20 74 61 62  cess has the tab
1b0e0 6c 65 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 20 54 68  le locked..** Th
1b0f0 65 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68  e sqlite3_busy_h
1b100 61 6e 64 6c 65 72 28 29 20 69 6e 74 65 72 66 61  andler() interfa
1b110 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 69 6d  ce is used to im
1b120 70 6c 65 6d 65 6e 74 0a 2a 2a 20 5b 73 71 6c 69  plement.** [sqli
1b130 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74  te3_busy_timeout
1b140 28 29 5d 20 61 6e 64 20 5b 50 52 41 47 4d 41 20  ()] and [PRAGMA 
1b150 62 75 73 79 5f 74 69 6d 65 6f 75 74 5d 2e 0a 2a  busy_timeout]..*
1b160 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 62 75 73  *.** ^If the bus
1b170 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55  y callback is NU
1b180 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45  LL, then [SQLITE
1b190 5f 42 55 53 59 5d 0a 2a 2a 20 69 73 20 72 65 74  _BUSY].** is ret
1b1a0 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c  urned immediatel
1b1b0 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72  y upon encounter
1b1c0 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20 20 5e  ing the lock.  ^
1b1d0 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c  If the busy call
1b1e0 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e  back.** is not N
1b1f0 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 63 61  ULL, then the ca
1b200 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 62 65 20  llback might be 
1b210 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 77 6f  invoked with two
1b220 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a   arguments..**.*
1b230 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67  * ^The first arg
1b240 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 62 75 73  ument to the bus
1b250 79 20 68 61 6e 64 6c 65 72 20 69 73 20 61 20 63  y handler is a c
1b260 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a  opy of the void*
1b270 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 0a 2a   pointer which.*
1b280 2a 20 69 73 20 74 68 65 20 74 68 69 72 64 20 61  * is the third a
1b290 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
1b2a0 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  e3_busy_handler(
1b2b0 29 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  ).  ^The second 
1b2c0 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74  argument to.** t
1b2d0 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  he busy handler 
1b2e0 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20  callback is the 
1b2f0 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20  number of times 
1b300 74 68 61 74 20 74 68 65 20 62 75 73 79 20 68 61  that the busy ha
1b310 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65 65  ndler has.** bee
1b320 6e 20 69 6e 76 6f 6b 65 64 20 70 72 65 76 69 6f  n invoked previo
1b330 75 73 6c 79 20 66 6f 72 20 74 68 65 20 73 61 6d  usly for the sam
1b340 65 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e  e locking event.
1b350 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 62 75 73    ^If the.** bus
1b360 79 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  y callback retur
1b370 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64  ns 0, then no ad
1b380 64 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74  ditional attempt
1b390 73 20 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a  s are made to.**
1b3a0 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61   access the data
1b3b0 62 61 73 65 20 61 6e 64 20 5b 53 51 4c 49 54 45  base and [SQLITE
1b3c0 5f 42 55 53 59 5d 20 69 73 20 72 65 74 75 72 6e  _BUSY] is return
1b3d0 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 61 70 70  ed.** to the app
1b3e0 6c 69 63 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66  lication..** ^If
1b3f0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
1b400 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  turns non-zero, 
1b410 74 68 65 6e 20 61 6e 6f 74 68 65 72 20 61 74 74  then another att
1b420 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20  empt.** is made 
1b430 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 64 61  to access the da
1b440 74 61 62 61 73 65 20 61 6e 64 20 74 68 65 20 63  tabase and the c
1b450 79 63 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a  ycle repeats..**
1b460 0a 2a 2a 20 54 68 65 20 70 72 65 73 65 6e 63 65  .** The presence
1b470 20 6f 66 20 61 20 62 75 73 79 20 68 61 6e 64 6c   of a busy handl
1b480 65 72 20 64 6f 65 73 20 6e 6f 74 20 67 75 61 72  er does not guar
1b490 61 6e 74 65 65 20 74 68 61 74 20 69 74 20 77 69  antee that it wi
1b4a0 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a  ll be invoked.**
1b4b0 20 77 68 65 6e 20 74 68 65 72 65 20 69 73 20 6c   when there is l
1b4c0 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20  ock contention. 
1b4d0 5e 49 66 20 53 51 4c 69 74 65 20 64 65 74 65 72  ^If SQLite deter
1b4e0 6d 69 6e 65 73 20 74 68 61 74 20 69 6e 76 6f 6b  mines that invok
1b4f0 69 6e 67 20 74 68 65 20 62 75 73 79 0a 2a 2a 20  ing the busy.** 
1b500 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72 65  handler could re
1b510 73 75 6c 74 20 69 6e 20 61 20 64 65 61 64 6c 6f  sult in a deadlo
1b520 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f 20 61  ck, it will go a
1b530 68 65 61 64 20 61 6e 64 20 72 65 74 75 72 6e 20  head and return 
1b540 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a  [SQLITE_BUSY].**
1b550 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74   to the applicat
1b560 69 6f 6e 20 69 6e 73 74 65 61 64 20 6f 66 20 69  ion instead of i
1b570 6e 76 6f 6b 69 6e 67 20 74 68 65 20 0a 2a 2a 20  nvoking the .** 
1b580 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a  busy handler..**
1b590 20 43 6f 6e 73 69 64 65 72 20 61 20 73 63 65 6e   Consider a scen
1b5a0 61 72 69 6f 20 77 68 65 72 65 20 6f 6e 65 20 70  ario where one p
1b5b0 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e  rocess is holdin
1b5c0 67 20 61 20 72 65 61 64 20 6c 6f 63 6b 20 74 68  g a read lock th
1b5d0 61 74 0a 2a 2a 20 69 74 20 69 73 20 74 72 79 69  at.** it is tryi
1b5e0 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f  ng to promote to
1b5f0 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b   a reserved lock
1b600 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64   and.** a second
1b610 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64   process is hold
1b620 69 6e 67 20 61 20 72 65 73 65 72 76 65 64 20 6c  ing a reserved l
1b630 6f 63 6b 20 74 68 61 74 20 69 74 20 69 73 20 74  ock that it is t
1b640 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d  rying.** to prom
1b650 6f 74 65 20 74 6f 20 61 6e 20 65 78 63 6c 75 73  ote to an exclus
1b660 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66  ive lock.  The f
1b670 69 72 73 74 20 70 72 6f 63 65 73 73 20 63 61 6e  irst process can
1b680 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62  not proceed.** b
1b690 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f  ecause it is blo
1b6a0 63 6b 65 64 20 62 79 20 74 68 65 20 73 65 63 6f  cked by the seco
1b6b0 6e 64 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e  nd and the secon
1b6c0 64 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74  d process cannot
1b6d0 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62 65 63 61  .** proceed beca
1b6e0 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65  use it is blocke
1b6f0 64 20 62 79 20 74 68 65 20 66 69 72 73 74 2e 20  d by the first. 
1b700 20 49 66 20 62 6f 74 68 20 70 72 6f 63 65 73 73   If both process
1b710 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65  es.** invoke the
1b720 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2c 20   busy handlers, 
1b730 6e 65 69 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b  neither will mak
1b740 65 20 61 6e 79 20 70 72 6f 67 72 65 73 73 2e 20  e any progress. 
1b750 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53   Therefore,.** S
1b760 51 4c 69 74 65 20 72 65 74 75 72 6e 73 20 5b 53  QLite returns [S
1b770 51 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f 72 20  QLITE_BUSY] for 
1b780 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73  the first proces
1b790 73 2c 20 68 6f 70 69 6e 67 20 74 68 61 74 20 74  s, hoping that t
1b7a0 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75  his.** will indu
1b7b0 63 65 20 74 68 65 20 66 69 72 73 74 20 70 72 6f  ce the first pro
1b7c0 63 65 73 73 20 74 6f 20 72 65 6c 65 61 73 65 20  cess to release 
1b7d0 69 74 73 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e  its read lock an
1b7e0 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73  d allow.** the s
1b7f0 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 74 6f  econd process to
1b800 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20   proceed..**.** 
1b810 5e 54 68 65 20 64 65 66 61 75 6c 74 20 62 75 73  ^The default bus
1b820 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55  y callback is NU
1b830 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72  LL..**.** ^(Ther
1b840 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20  e can only be a 
1b850 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64  single busy hand
1b860 6c 65 72 20 64 65 66 69 6e 65 64 20 66 6f 72 20  ler defined for 
1b870 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73  each.** [databas
1b880 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20  e connection].  
1b890 53 65 74 74 69 6e 67 20 61 20 6e 65 77 20 62 75  Setting a new bu
1b8a0 73 79 20 68 61 6e 64 6c 65 72 20 63 6c 65 61 72  sy handler clear
1b8b0 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f 75  s any.** previou
1b8c0 73 6c 79 20 73 65 74 20 68 61 6e 64 6c 65 72 2e  sly set handler.
1b8d0 29 5e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 63  )^  ^Note that c
1b8e0 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
1b8f0 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 0a  busy_timeout()].
1b900 2a 2a 20 6f 72 20 65 76 61 6c 75 61 74 69 6e 67  ** or evaluating
1b910 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f 74 69   [PRAGMA busy_ti
1b920 6d 65 6f 75 74 3d 4e 5d 20 77 69 6c 6c 20 63 68  meout=N] will ch
1b930 61 6e 67 65 20 74 68 65 0a 2a 2a 20 62 75 73 79  ange the.** busy
1b940 20 68 61 6e 64 6c 65 72 20 61 6e 64 20 74 68 75   handler and thu
1b950 73 20 63 6c 65 61 72 20 61 6e 79 20 70 72 65 76  s clear any prev
1b960 69 6f 75 73 6c 79 20 73 65 74 20 62 75 73 79 20  iously set busy 
1b970 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54  handler..**.** T
1b980 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  he busy callback
1b990 20 73 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b 65   should not take
1b9a0 20 61 6e 79 20 61 63 74 69 6f 6e 73 20 77 68 69   any actions whi
1b9b0 63 68 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a 2a  ch modify the.**
1b9c0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1b9d0 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65  tion that invoke
1b9e0 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  d the busy handl
1b9f0 65 72 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f  er.  In other wo
1ba00 72 64 73 2c 0a 2a 2a 20 74 68 65 20 62 75 73 79  rds,.** the busy
1ba10 20 68 61 6e 64 6c 65 72 20 69 73 20 6e 6f 74 20   handler is not 
1ba20 72 65 65 6e 74 72 61 6e 74 2e 20 20 41 6e 79 20  reentrant.  Any 
1ba30 73 75 63 68 20 61 63 74 69 6f 6e 73 0a 2a 2a 20  such actions.** 
1ba40 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69  result in undefi
1ba50 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a  ned behavior..**
1ba60 20 0a 2a 2a 20 41 20 62 75 73 79 20 68 61 6e 64   .** A busy hand
1ba70 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f  ler must not clo
1ba80 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  se the database 
1ba90 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72  connection.** or
1baa0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
1bab0 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b  ment] that invok
1bac0 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ed the busy hand
1bad0 6c 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ler..*/.SQLITE_A
1bae0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  PI int sqlite3_b
1baf0 75 73 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69  usy_handler(sqli
1bb00 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69  te3*, int(*)(voi
1bb10 64 2a 2c 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b  d*,int), void*);
1bb20 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1bb30 3a 20 53 65 74 20 41 20 42 75 73 79 20 54 69 6d  : Set A Busy Tim
1bb40 65 6f 75 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  eout.**.** ^This
1bb50 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20   routine sets a 
1bb60 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61  [sqlite3_busy_ha
1bb70 6e 64 6c 65 72 20 7c 20 62 75 73 79 20 68 61 6e  ndler | busy han
1bb80 64 6c 65 72 5d 20 74 68 61 74 20 73 6c 65 65 70  dler] that sleep
1bb90 73 0a 2a 2a 20 66 6f 72 20 61 20 73 70 65 63 69  s.** for a speci
1bba0 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74  fied amount of t
1bbb0 69 6d 65 20 77 68 65 6e 20 61 20 74 61 62 6c 65  ime when a table
1bbc0 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20 5e 54 68   is locked.  ^Th
1bbd0 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c  e handler.** wil
1bbe0 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65  l sleep multiple
1bbf0 20 74 69 6d 65 73 20 75 6e 74 69 6c 20 61 74 20   times until at 
1bc00 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69  least "ms" milli
1bc10 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70  seconds of sleep
1bc20 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61 63 63 75  ing.** have accu
1bc30 6d 75 6c 61 74 65 64 2e 20 20 5e 41 66 74 65 72  mulated.  ^After
1bc40 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d   at least "ms" m
1bc50 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73  illiseconds of s
1bc60 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20  leeping,.** the 
1bc70 68 61 6e 64 6c 65 72 20 72 65 74 75 72 6e 73 20  handler returns 
1bc80 30 20 77 68 69 63 68 20 63 61 75 73 65 73 20 5b  0 which causes [
1bc90 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1bca0 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51  to return.** [SQ
1bcb0 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 0a 2a  LITE_BUSY]..**.*
1bcc0 2a 20 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73 20  * ^Calling this 
1bcd0 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 6e 20  routine with an 
1bce0 61 72 67 75 6d 65 6e 74 20 6c 65 73 73 20 74 68  argument less th
1bcf0 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a  an or equal to z
1bd00 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66  ero.** turns off
1bd10 20 61 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c 65   all busy handle
1bd20 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72  rs..**.** ^(Ther
1bd30 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20  e can only be a 
1bd40 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64  single busy hand
1bd50 6c 65 72 20 66 6f 72 20 61 20 70 61 72 74 69 63  ler for a partic
1bd60 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73  ular.** [databas
1bd70 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74  e connection] at
1bd80 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e   any given momen
1bd90 74 2e 20 20 49 66 20 61 6e 6f 74 68 65 72 20 62  t.  If another b
1bda0 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77  usy handler.** w
1bdb0 61 73 20 64 65 66 69 6e 65 64 20 20 28 75 73 69  as defined  (usi
1bdc0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  ng [sqlite3_busy
1bdd0 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20 70 72 69  _handler()]) pri
1bde0 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a  or to calling.**
1bdf0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 74   this routine, t
1be00 68 61 74 20 6f 74 68 65 72 20 62 75 73 79 20 68  hat other busy h
1be10 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 61 72 65  andler is cleare
1be20 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  d.)^.**.** See a
1be30 6c 73 6f 3a 20 20 5b 50 52 41 47 4d 41 20 62 75  lso:  [PRAGMA bu
1be40 73 79 5f 74 69 6d 65 6f 75 74 5d 0a 2a 2f 0a 53  sy_timeout].*/.S
1be50 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
1be60 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f  lite3_busy_timeo
1be70 75 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  ut(sqlite3*, int
1be80 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50   ms);../*.** CAP
1be90 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e  I3REF: Convenien
1bea0 63 65 20 52 6f 75 74 69 6e 65 73 20 46 6f 72 20  ce Routines For 
1beb0 52 75 6e 6e 69 6e 67 20 51 75 65 72 69 65 73 0a  Running Queries.
1bec0 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20  **.** This is a 
1bed0 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65  legacy interface
1bee0 20 74 68 61 74 20 69 73 20 70 72 65 73 65 72 76   that is preserv
1bef0 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73  ed for backwards
1bf00 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a   compatibility..
1bf10 2a 2a 20 55 73 65 20 6f 66 20 74 68 69 73 20 69  ** Use of this i
1bf20 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20  nterface is not 
1bf30 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a  recommended..**.
1bf40 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41  ** Definition: A
1bf50 20 3c 62 3e 72 65 73 75 6c 74 20 74 61 62 6c 65   <b>result table
1bf60 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64  </b> is memory d
1bf70 61 74 61 20 73 74 72 75 63 74 75 72 65 20 63 72  ata structure cr
1bf80 65 61 74 65 64 20 62 79 20 74 68 65 0a 2a 2a 20  eated by the.** 
1bf90 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62  [sqlite3_get_tab
1bfa0 6c 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  le()] interface.
1bfb0 20 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65    A result table
1bfc0 20 72 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20   records the.** 
1bfd0 63 6f 6d 70 6c 65 74 65 20 71 75 65 72 79 20 72  complete query r
1bfe0 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20  esults from one 
1bff0 6f 72 20 6d 6f 72 65 20 71 75 65 72 69 65 73 2e  or more queries.
1c000 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65  .**.** The table
1c010 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68 61   conceptually ha
1c020 73 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  s a number of ro
1c030 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20  ws and columns. 
1c040 20 42 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75   But.** these nu
1c050 6d 62 65 72 73 20 61 72 65 20 6e 6f 74 20 70 61  mbers are not pa
1c060 72 74 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  rt of the result
1c070 20 74 61 62 6c 65 20 69 74 73 65 6c 66 2e 20 20   table itself.  
1c080 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73  These.** numbers
1c090 20 61 72 65 20 6f 62 74 61 69 6e 65 64 20 73 65   are obtained se
1c0a0 70 61 72 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e  parately.  Let N
1c0b0 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   be the number o
1c0c0 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20  f rows.** and M 
1c0d0 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  be the number of
1c0e0 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20   columns..**.** 
1c0f0 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69  A result table i
1c100 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f  s an array of po
1c110 69 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74  inters to zero-t
1c120 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20  erminated UTF-8 
1c130 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 72  strings..** Ther
1c140 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c  e are (N+1)*M el
1c150 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 61 72  ements in the ar
1c160 72 61 79 2e 20 20 54 68 65 20 66 69 72 73 74 20  ray.  The first 
1c170 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74  M pointers point
1c180 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d  .** to zero-term
1c190 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74  inated strings t
1c1a0 68 61 74 20 20 63 6f 6e 74 61 69 6e 20 74 68 65  hat  contain the
1c1b0 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 20 63 6f   names of the co
1c1c0 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65  lumns..** The re
1c1d0 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69 65 73 20  maining entries 
1c1e0 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75 65  all point to que
1c1f0 72 79 20 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c  ry results.  NUL
1c200 4c 20 76 61 6c 75 65 73 20 72 65 73 75 6c 74 0a  L values result.
1c210 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74  ** in NULL point
1c220 65 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20  ers.  All other 
1c230 76 61 6c 75 65 73 20 61 72 65 20 69 6e 20 74 68  values are in th
1c240 65 69 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74  eir UTF-8 zero-t
1c250 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72  erminated.** str
1c260 69 6e 67 20 72 65 70 72 65 73 65 6e 74 61 74 69  ing representati
1c270 6f 6e 20 61 73 20 72 65 74 75 72 6e 65 64 20 62  on as returned b
1c280 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  y [sqlite3_colum
1c290 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a  n_text()]..**.**
1c2a0 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
1c2b0 6d 69 67 68 74 20 63 6f 6e 73 69 73 74 20 6f 66  might consist of
1c2c0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d   one or more mem
1c2d0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e  ory allocations.
1c2e0 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61  .** It is not sa
1c2f0 66 65 20 74 6f 20 70 61 73 73 20 61 20 72 65 73  fe to pass a res
1c300 75 6c 74 20 74 61 62 6c 65 20 64 69 72 65 63 74  ult table direct
1c310 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  ly to [sqlite3_f
1c320 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73  ree()]..** A res
1c330 75 6c 74 20 74 61 62 6c 65 20 73 68 6f 75 6c 64  ult table should
1c340 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   be deallocated 
1c350 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
1c360 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a  ree_table()]..**
1c370 0a 2a 2a 20 5e 28 41 73 20 61 6e 20 65 78 61 6d  .** ^(As an exam
1c380 70 6c 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c  ple of the resul
1c390 74 20 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c 20  t table format, 
1c3a0 73 75 70 70 6f 73 65 20 61 20 71 75 65 72 79 20  suppose a query 
1c3b0 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73 20  result.** is as 
1c3c0 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c  follows:.**.** <
1c3d0 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
1c3e0 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d 65 20  .**        Name 
1c3f0 20 20 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20         | Age.** 
1c400 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d         ---------
1c410 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a  --------------.*
1c420 2a 20 20 20 20 20 20 20 20 41 6c 69 63 65 20 20  *        Alice  
1c430 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20       | 43.**    
1c440 20 20 20 20 42 6f 62 20 20 20 20 20 20 20 20 20      Bob         
1c450 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20 20 20 43  | 28.**        C
1c460 69 6e 64 79 20 20 20 20 20 20 20 7c 20 32 31 0a  indy       | 21.
1c470 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
1c480 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  quote>.**.** The
1c490 72 65 20 61 72 65 20 74 77 6f 20 63 6f 6c 75 6d  re are two colum
1c4a0 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68 72  n (M==2) and thr
1c4b0 65 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e 20  ee rows (N==3). 
1c4c0 20 54 68 75 73 20 74 68 65 0a 2a 2a 20 72 65 73   Thus the.** res
1c4d0 75 6c 74 20 74 61 62 6c 65 20 68 61 73 20 38 20  ult table has 8 
1c4e0 65 6e 74 72 69 65 73 2e 20 20 53 75 70 70 6f 73  entries.  Suppos
1c4f0 65 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62  e the result tab
1c500 6c 65 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20  le is stored.** 
1c510 69 6e 20 61 6e 20 61 72 72 61 79 20 6e 61 6d 65  in an array name
1c520 73 20 61 7a 52 65 73 75 6c 74 2e 20 20 54 68 65  s azResult.  The
1c530 6e 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64 73  n azResult holds
1c540 20 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a   this content:.*
1c550 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
1c560 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20  ><pre>.**       
1c570 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 30 5d   azResult&#91;0]
1c580 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20   = "Name";.**   
1c590 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
1c5a0 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a  1;1] = "Age";.**
1c5b0 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
1c5c0 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65  &#91;2] = "Alice
1c5d0 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
1c5e0 65 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22  esult&#91;3] = "
1c5f0 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  43";.**        a
1c600 7a 52 65 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d  zResult&#91;4] =
1c610 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20   "Bob";.**      
1c620 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 35    azResult&#91;5
1c630 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20  ] = "28";.**    
1c640 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
1c650 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a  ;6] = "Cindy";.*
1c660 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
1c670 74 26 23 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b  t&#91;7] = "21";
1c680 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
1c690 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20  kquote>)^.**.** 
1c6a0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74  ^The sqlite3_get
1c6b0 5f 74 61 62 6c 65 28 29 20 66 75 6e 63 74 69 6f  _table() functio
1c6c0 6e 20 65 76 61 6c 75 61 74 65 73 20 6f 6e 65 20  n evaluates one 
1c6d0 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 63  or more.** semic
1c6e0 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 20 53  olon-separated S
1c6f0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e  QL statements in
1c700 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e   the zero-termin
1c710 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73 74  ated UTF-8.** st
1c720 72 69 6e 67 20 6f 66 20 69 74 73 20 32 6e 64 20  ring of its 2nd 
1c730 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65  parameter and re
1c740 74 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20 74  turns a result t
1c750 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20 70  able to the.** p
1c760 6f 69 6e 74 65 72 20 67 69 76 65 6e 20 69 6e 20  ointer given in 
1c770 69 74 73 20 33 72 64 20 70 61 72 61 6d 65 74 65  its 3rd paramete
1c780 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74  r..**.** After t
1c790 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 68  he application h
1c7a0 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68  as finished with
1c7b0 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d   the result from
1c7c0 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
1c7d0 6c 65 28 29 2c 0a 2a 2a 20 69 74 20 6d 75 73 74  le(),.** it must
1c7e0 20 70 61 73 73 20 74 68 65 20 72 65 73 75 6c 74   pass the result
1c7f0 20 74 61 62 6c 65 20 70 6f 69 6e 74 65 72 20 74   table pointer t
1c800 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74  o sqlite3_free_t
1c810 61 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 72 20  able() in order 
1c820 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74 68  to.** release th
1c830 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 77 61  e memory that wa
1c840 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63  s malloced.  Bec
1c850 61 75 73 65 20 6f 66 20 74 68 65 20 77 61 79 20  ause of the way 
1c860 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
1c870 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e  malloc()] happen
1c880 73 20 77 69 74 68 69 6e 20 73 71 6c 69 74 65 33  s within sqlite3
1c890 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 20 74 68  _get_table(), th
1c8a0 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e  e calling.** fun
1c8b0 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74  ction must not t
1c8c0 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69  ry to call [sqli
1c8d0 74 65 33 5f 66 72 65 65 28 29 5d 20 64 69 72 65  te3_free()] dire
1c8e0 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b  ctly.  Only.** [
1c8f0 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62  sqlite3_free_tab
1c900 6c 65 28 29 5d 20 69 73 20 61 62 6c 65 20 74 6f  le()] is able to
1c910 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d   release the mem
1c920 6f 72 79 20 70 72 6f 70 65 72 6c 79 20 61 6e 64  ory properly and
1c930 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54   safely..**.** T
1c940 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  he sqlite3_get_t
1c950 61 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65  able() interface
1c960 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20   is implemented 
1c970 61 73 20 61 20 77 72 61 70 70 65 72 20 61 72 6f  as a wrapper aro
1c980 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  und.** [sqlite3_
1c990 65 78 65 63 28 29 5d 2e 20 20 54 68 65 20 73 71  exec()].  The sq
1c9a0 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
1c9b0 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e  ) routine does n
1c9c0 6f 74 20 68 61 76 65 20 61 63 63 65 73 73 0a 2a  ot have access.*
1c9d0 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61  * to any interna
1c9e0 6c 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65  l data structure
1c9f0 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 49 74  s of SQLite.  It
1ca00 20 75 73 65 73 20 6f 6e 6c 79 20 74 68 65 20 70   uses only the p
1ca10 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61  ublic.** interfa
1ca20 63 65 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e  ce defined here.
1ca30 20 20 41 73 20 61 20 63 6f 6e 73 65 71 75 65 6e    As a consequen
1ca40 63 65 2c 20 65 72 72 6f 72 73 20 74 68 61 74 20  ce, errors that 
1ca50 6f 63 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20  occur in the.** 
1ca60 77 72 61 70 70 65 72 20 6c 61 79 65 72 20 6f 75  wrapper layer ou
1ca70 74 73 69 64 65 20 6f 66 20 74 68 65 20 69 6e 74  tside of the int
1ca80 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65  ernal [sqlite3_e
1ca90 78 65 63 28 29 5d 20 63 61 6c 6c 20 61 72 65 20  xec()] call are 
1caa0 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64  not.** reflected
1cab0 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63   in subsequent c
1cac0 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
1cad0 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f 72 0a 2a  _errcode()] or.*
1cae0 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  * [sqlite3_errms
1caf0 67 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  g()]..*/.SQLITE_
1cb00 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
1cb10 67 65 74 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c  get_table(.  sql
1cb20 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
1cb30 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61     /* An open da
1cb40 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73  tabase */.  cons
1cb50 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20  t char *zSql,   
1cb60 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65    /* SQL to be e
1cb70 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63 68  valuated */.  ch
1cb80 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c  ar ***pazResult,
1cb90 20 20 20 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f      /* Results o
1cba0 66 20 74 68 65 20 71 75 65 72 79 20 2a 2f 0a 20  f the query */. 
1cbb0 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20   int *pnRow,    
1cbc0 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72         /* Number
1cbd0 20 6f 66 20 72 65 73 75 6c 74 20 72 6f 77 73 20   of result rows 
1cbe0 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a  written here */.
1cbf0 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c    int *pnColumn,
1cc00 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65          /* Numbe
1cc10 72 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c 75  r of result colu
1cc20 6d 6e 73 20 77 72 69 74 74 65 6e 20 68 65 72 65  mns written here
1cc30 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45   */.  char **pzE
1cc40 72 72 6d 73 67 20 20 20 20 20 20 20 2f 2a 20 45  rrmsg       /* E
1cc50 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e  rror msg written
1cc60 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49   here */.);.SQLI
1cc70 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69  TE_API void sqli
1cc80 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 63  te3_free_table(c
1cc90 68 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a  har **result);..
1cca0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1ccb0 46 6f 72 6d 61 74 74 65 64 20 53 74 72 69 6e 67  Formatted String
1ccc0 20 50 72 69 6e 74 69 6e 67 20 46 75 6e 63 74 69   Printing Functi
1ccd0 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ons.**.** These 
1cce0 72 6f 75 74 69 6e 65 73 20 61 72 65 20 77 6f 72  routines are wor
1ccf0 6b 2d 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 20  k-alikes of the 
1cd00 22 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69 6c  "printf()" famil
1cd10 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a  y of functions.*
1cd20 2a 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64  * from the stand
1cd30 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a  ard C library..*
1cd40 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1cd50 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20  3_mprintf() and 
1cd60 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66  sqlite3_vmprintf
1cd70 28 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74  () routines writ
1cd80 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c  e their.** resul
1cd90 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f  ts into memory o
1cda0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
1cdb0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e  lite3_malloc()].
1cdc0 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20  .** The strings 
1cdd0 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73  returned by thes
1cde0 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73  e two routines s
1cdf0 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65  hould be.** rele
1ce00 61 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  ased by [sqlite3
1ce10 5f 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74 68  _free()].  ^Both
1ce20 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
1ce30 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74   a.** NULL point
1ce40 65 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d  er if [sqlite3_m
1ce50 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62  alloc()] is unab
1ce60 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65  le to allocate e
1ce70 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20  nough.** memory 
1ce80 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75  to hold the resu
1ce90 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a  lting string..**
1cea0 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65  .** ^(The sqlite
1ceb0 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75  3_snprintf() rou
1cec0 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20  tine is similar 
1ced0 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 22 20  to "snprintf()" 
1cee0 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e  from.** the stan
1cef0 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20  dard C library. 
1cf00 20 54 68 65 20 72 65 73 75 6c 74 20 69 73 20 77   The result is w
1cf10 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a  ritten into the.
1cf20 2a 2a 20 62 75 66 66 65 72 20 73 75 70 70 6c 69  ** buffer suppli
1cf30 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
1cf40 20 70 61 72 61 6d 65 74 65 72 20 77 68 6f 73 65   parameter whose
1cf50 20 73 69 7a 65 20 69 73 20 67 69 76 65 6e 20 62   size is given b
1cf60 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70  y.** the first p
1cf70 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74  arameter. Note t
1cf80 68 61 74 20 74 68 65 20 6f 72 64 65 72 20 6f 66  hat the order of
1cf90 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 77   the.** first tw
1cfa0 6f 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20  o parameters is 
1cfb0 72 65 76 65 72 73 65 64 20 66 72 6f 6d 20 73 6e  reversed from sn
1cfc0 70 72 69 6e 74 66 28 29 2e 29 5e 20 20 54 68 69  printf().)^  Thi
1cfd0 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f  s is an.** histo
1cfe0 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74  rical accident t
1cff0 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69  hat cannot be fi
1d000 78 65 64 20 77 69 74 68 6f 75 74 20 62 72 65 61  xed without brea
1d010 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64  king.** backward
1d020 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  s compatibility.
1d030 20 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74 68    ^(Note also th
1d040 61 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  at sqlite3_snpri
1d050 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73  ntf().** returns
1d060 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74   a pointer to it
1d070 73 20 62 75 66 66 65 72 20 69 6e 73 74 65 61 64  s buffer instead
1d080 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   of the number o
1d090 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20  f.** characters 
1d0a0 61 63 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e  actually written
1d0b0 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72   into the buffer
1d0c0 2e 29 5e 20 20 57 65 20 61 64 6d 69 74 20 74 68  .)^  We admit th
1d0d0 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  at.** the number
1d0e0 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 20 77   of characters w
1d0f0 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20  ritten would be 
1d100 61 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65  a more useful re
1d110 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75  turn.** value bu
1d120 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e  t we cannot chan
1d130 67 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  ge the implement
1d140 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33  ation of sqlite3
1d150 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e  _snprintf().** n
1d160 6f 77 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b  ow without break
1d170 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  ing compatibilit
1d180 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e  y..**.** ^As lon
1d190 67 20 61 73 20 74 68 65 20 62 75 66 66 65 72 20  g as the buffer 
1d1a0 73 69 7a 65 20 69 73 20 67 72 65 61 74 65 72 20  size is greater 
1d1b0 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74  than zero, sqlit
1d1c0 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a  e3_snprintf().**
1d1d0 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
1d1e0 20 74 68 65 20 62 75 66 66 65 72 20 69 73 20 61   the buffer is a
1d1f0 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69  lways zero-termi
1d200 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 66 69 72  nated.  ^The fir
1d210 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  st.** parameter 
1d220 22 6e 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c  "n" is the total
1d230 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66   size of the buf
1d240 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73  fer, including s
1d250 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20  pace for.** the 
1d260 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e  zero terminator.
1d270 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74    So the longest
1d280 20 73 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e   string that can
1d290 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a   be completely.*
1d2a0 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62  * written will b
1d2b0 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73  e n-1 characters
1d2c0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
1d2d0 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 29  ite3_vsnprintf()
1d2e0 20 72 6f 75 74 69 6e 65 20 69 73 20 61 20 76 61   routine is a va
1d2f0 72 61 72 67 73 20 76 65 72 73 69 6f 6e 20 6f 66  rargs version of
1d300 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
1d310 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  f()..**.** These
1d320 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d   routines all im
1d330 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64  plement some add
1d340 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69  itional formatti
1d350 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68  ng.** options th
1d360 61 74 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f  at are useful fo
1d370 72 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53  r constructing S
1d380 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  QL statements..*
1d390 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75  * All of the usu
1d3a0 61 6c 20 70 72 69 6e 74 66 28 29 20 66 6f 72 6d  al printf() form
1d3b0 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61  atting options a
1d3c0 70 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69  pply.  In additi
1d3d0 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20  on, there.** is 
1d3e0 61 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20  are "%q", "%Q", 
1d3f0 61 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73  and "%z" options
1d400 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 71  ..**.** ^(The %q
1d410 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69   option works li
1d420 6b 65 20 25 73 20 69 6e 20 74 68 61 74 20 69 74  ke %s in that it
1d430 20 73 75 62 73 74 69 74 75 74 65 73 20 61 20 6e   substitutes a n
1d440 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ul-terminated.**
1d450 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 65   string from the
1d460 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20   argument list. 
1d470 20 42 75 74 20 25 71 20 61 6c 73 6f 20 64 6f 75   But %q also dou
1d480 62 6c 65 73 20 65 76 65 72 79 20 27 5c 27 27 20  bles every '\'' 
1d490 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71  character..** %q
1d4a0 20 69 73 20 64 65 73 69 67 6e 65 64 20 66 6f 72   is designed for
1d4b0 20 75 73 65 20 69 6e 73 69 64 65 20 61 20 73 74   use inside a st
1d4c0 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 29 5e 20  ring literal.)^ 
1d4d0 20 42 79 20 64 6f 75 62 6c 69 6e 67 20 65 61 63   By doubling eac
1d4e0 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63  h '\''.** charac
1d4f0 74 65 72 20 69 74 20 65 73 63 61 70 65 73 20 74  ter it escapes t
1d500 68 61 74 20 63 68 61 72 61 63 74 65 72 20 61 6e  hat character an
1d510 64 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62  d allows it to b
1d520 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a  e inserted into.
1d530 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a  ** the string..*
1d540 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65  *.** For example
1d550 2c 20 61 73 73 75 6d 65 20 74 68 65 20 73 74 72  , assume the str
1d560 69 6e 67 20 76 61 72 69 61 62 6c 65 20 7a 54 65  ing variable zTe
1d570 78 74 20 63 6f 6e 74 61 69 6e 73 20 74 65 78 74  xt contains text
1d580 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
1d590 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
1d5a0 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a  pre>.**  char *z
1d5b0 54 65 78 74 20 3d 20 22 49 74 27 73 20 61 20 68  Text = "It's a h
1d5c0 61 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c  appy day!";.** <
1d5d0 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1d5e0 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e  e>.**.** One can
1d5f0 20 75 73 65 20 74 68 69 73 20 74 65 78 74 20 69   use this text i
1d600 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  n an SQL stateme
1d610 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  nt as follows:.*
1d620 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
1d630 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20  ><pre>.**  char 
1d640 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f  *zSQL = sqlite3_
1d650 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20  mprintf("INSERT 
1d660 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45  INTO table VALUE
1d670 53 28 27 25 71 27 29 22 2c 20 7a 54 65 78 74 29  S('%q')", zText)
1d680 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78  ;.**  sqlite3_ex
1d690 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20  ec(db, zSQL, 0, 
1d6a0 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  0, 0);.**  sqlit
1d6b0 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a  e3_free(zSQL);.*
1d6c0 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
1d6d0 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61  uote>.**.** Beca
1d6e0 75 73 65 20 74 68 65 20 25 71 20 66 6f 72 6d 61  use the %q forma
1d6f0 74 20 73 74 72 69 6e 67 20 69 73 20 75 73 65 64  t string is used
1d700 2c 20 74 68 65 20 27 5c 27 27 20 63 68 61 72 61  , the '\'' chara
1d710 63 74 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a  cter in zText.**
1d720 20 69 73 20 65 73 63 61 70 65 64 20 61 6e 64 20   is escaped and 
1d730 74 68 65 20 53 51 4c 20 67 65 6e 65 72 61 74 65  the SQL generate
1d740 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  d is as follows:
1d750 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
1d760 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53  te><pre>.**  INS
1d770 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20  ERT INTO table1 
1d780 56 41 4c 55 45 53 28 27 49 74 27 27 73 20 61 20  VALUES('It''s a 
1d790 68 61 70 70 79 20 64 61 79 21 27 29 0a 2a 2a 20  happy day!').** 
1d7a0 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
1d7b0 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  te>.**.** This i
1d7c0 73 20 63 6f 72 72 65 63 74 2e 20 20 48 61 64 20  s correct.  Had 
1d7d0 77 65 20 75 73 65 64 20 25 73 20 69 6e 73 74 65  we used %s inste
1d7e0 61 64 20 6f 66 20 25 71 2c 20 74 68 65 20 67 65  ad of %q, the ge
1d7f0 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77  nerated SQL.** w
1d800 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64  ould have looked
1d810 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a   like this:.**.*
1d820 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
1d830 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49  re>.**  INSERT I
1d840 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45  NTO table1 VALUE
1d850 53 28 27 49 74 27 73 20 61 20 68 61 70 70 79 20  S('It's a happy 
1d860 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65  day!');.** </pre
1d870 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
1d880 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e 64  *.** This second
1d890 20 65 78 61 6d 70 6c 65 20 69 73 20 61 6e 20 53   example is an S
1d8a0 51 4c 20 73 79 6e 74 61 78 20 65 72 72 6f 72 2e  QL syntax error.
1d8b0 20 20 41 73 20 61 20 67 65 6e 65 72 61 6c 20 72    As a general r
1d8c0 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a 2a  ule you should.*
1d8d0 2a 20 61 6c 77 61 79 73 20 75 73 65 20 25 71 20  * always use %q 
1d8e0 69 6e 73 74 65 61 64 20 6f 66 20 25 73 20 77 68  instead of %s wh
1d8f0 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 74 65 78  en inserting tex
1d900 74 20 69 6e 74 6f 20 61 20 73 74 72 69 6e 67 20  t into a string 
1d910 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e  literal..**.** ^
1d920 28 54 68 65 20 25 51 20 6f 70 74 69 6f 6e 20 77  (The %Q option w
1d930 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20 65 78 63  orks like %q exc
1d940 65 70 74 20 69 74 20 61 6c 73 6f 20 61 64 64 73  ept it also adds
1d950 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 20 61   single quotes a
1d960 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74  round.** the out
1d970 73 69 64 65 20 6f 66 20 74 68 65 20 74 6f 74 61  side of the tota
1d980 6c 20 73 74 72 69 6e 67 2e 20 20 41 64 64 69 74  l string.  Addit
1d990 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68 65 20  ionally, if the 
1d9a0 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65  parameter in the
1d9b0 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c 69 73  .** argument lis
1d9c0 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  t is a NULL poin
1d9d0 74 65 72 2c 20 25 51 20 73 75 62 73 74 69 74 75  ter, %Q substitu
1d9e0 74 65 73 20 74 68 65 20 74 65 78 74 20 22 4e 55  tes the text "NU
1d9f0 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a 2a 20  LL" (without.** 
1da00 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 29 2e 29  single quotes).)
1da10 5e 20 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70  ^  So, for examp
1da20 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61  le, one could sa
1da30 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  y:.**.** <blockq
1da40 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63  uote><pre>.**  c
1da50 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69  har *zSQL = sqli
1da60 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53  te3_mprintf("INS
1da70 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56  ERT INTO table V
1da80 41 4c 55 45 53 28 25 51 29 22 2c 20 7a 54 65 78  ALUES(%Q)", zTex
1da90 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f  t);.**  sqlite3_
1daa0 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30  exec(db, zSQL, 0
1dab0 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c  , 0, 0);.**  sql
1dac0 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b  ite3_free(zSQL);
1dad0 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
1dae0 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
1daf0 65 20 63 6f 64 65 20 61 62 6f 76 65 20 77 69 6c  e code above wil
1db00 6c 20 72 65 6e 64 65 72 20 61 20 63 6f 72 72 65  l render a corre
1db10 63 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ct SQL statement
1db20 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20   in the zSQL.** 
1db30 76 61 72 69 61 62 6c 65 20 65 76 65 6e 20 69 66  variable even if
1db40 20 74 68 65 20 7a 54 65 78 74 20 76 61 72 69 61   the zText varia
1db50 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  ble is a NULL po
1db60 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  inter..**.** ^(T
1db70 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69  he "%z" formatti
1db80 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20  ng option works 
1db90 6c 69 6b 65 20 22 25 73 22 20 62 75 74 20 77 69  like "%s" but wi
1dba0 74 68 20 74 68 65 0a 2a 2a 20 61 64 64 69 74 69  th the.** additi
1dbb0 6f 6e 20 74 68 61 74 20 61 66 74 65 72 20 74 68  on that after th
1dbc0 65 20 73 74 72 69 6e 67 20 68 61 73 20 62 65 65  e string has bee
1dbd0 6e 20 72 65 61 64 20 61 6e 64 20 63 6f 70 69 65  n read and copie
1dbe0 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65  d into.** the re
1dbf0 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66  sult, [sqlite3_f
1dc00 72 65 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64  ree()] is called
1dc10 20 6f 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74   on the input st
1dc20 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 53 51 4c 49 54  ring.)^.*/.SQLIT
1dc30 45 5f 41 50 49 20 63 68 61 72 20 2a 73 71 6c 69  E_API char *sqli
1dc40 74 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73  te3_mprintf(cons
1dc50 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 53 51  t char*,...);.SQ
1dc60 4c 49 54 45 5f 41 50 49 20 63 68 61 72 20 2a 73  LITE_API char *s
1dc70 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28  qlite3_vmprintf(
1dc80 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f  const char*, va_
1dc90 6c 69 73 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50  list);.SQLITE_AP
1dca0 49 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  I char *sqlite3_
1dcb0 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61  snprintf(int,cha
1dcc0 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  r*,const char*, 
1dcd0 2e 2e 2e 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ...);.SQLITE_API
1dce0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76   char *sqlite3_v
1dcf0 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61  snprintf(int,cha
1dd00 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  r*,const char*, 
1dd10 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a  va_list);../*.**
1dd20 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72   CAPI3REF: Memor
1dd30 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62  y Allocation Sub
1dd40 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65  system.**.** The
1dd50 20 53 51 4c 69 74 65 20 63 6f 72 65 20 75 73 65   SQLite core use
1dd60 73 20 74 68 65 73 65 20 74 68 72 65 65 20 72 6f  s these three ro
1dd70 75 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f  utines for all o
1dd80 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74  f its own.** int
1dd90 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c  ernal memory all
1dda0 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22  ocation needs. "
1ddb0 43 6f 72 65 22 20 69 6e 20 74 68 65 20 70 72 65  Core" in the pre
1ddc0 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a  vious sentence.*
1ddd0 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75  * does not inclu
1dde0 64 65 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73  de operating-sys
1ddf0 74 65 6d 20 73 70 65 63 69 66 69 63 20 56 46 53  tem specific VFS
1de00 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e   implementation.
1de10 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73    The.** Windows
1de20 20 56 46 53 20 75 73 65 73 20 6e 61 74 69 76 65   VFS uses native
1de30 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72   malloc() and fr
1de40 65 65 28 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70  ee() for some op
1de50 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20  erations..**.** 
1de60 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c  ^The sqlite3_mal
1de70 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 72 65  loc() routine re
1de80 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
1de90 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66  to a block.** of
1dea0 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61 73 74   memory at least
1deb0 20 4e 20 62 79 74 65 73 20 69 6e 20 6c 65 6e 67   N bytes in leng
1dec0 74 68 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74  th, where N is t
1ded0 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  he parameter..**
1dee0 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c   ^If sqlite3_mal
1def0 6c 6f 63 28 29 20 69 73 20 75 6e 61 62 6c 65 20  loc() is unable 
1df00 74 6f 20 6f 62 74 61 69 6e 20 73 75 66 66 69 63  to obtain suffic
1df10 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d  ient free.** mem
1df20 6f 72 79 2c 20 69 74 20 72 65 74 75 72 6e 73 20  ory, it returns 
1df30 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20  a NULL pointer. 
1df40 20 5e 49 66 20 74 68 65 20 70 61 72 61 6d 65 74   ^If the paramet
1df50 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  er N to.** sqlit
1df60 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a  e3_malloc() is z
1df70 65 72 6f 20 6f 72 20 6e 65 67 61 74 69 76 65 20  ero or negative 
1df80 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c  then sqlite3_mal
1df90 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a  loc() returns.**
1dfa0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
1dfb0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1dfc0 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 4e 29 20  te3_malloc64(N) 
1dfd0 72 6f 75 74 69 6e 65 20 77 6f 72 6b 73 20 6a 75  routine works ju
1dfe0 73 74 20 6c 69 6b 65 0a 2a 2a 20 73 71 6c 69 74  st like.** sqlit
1dff0 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 65 78 63  e3_malloc(N) exc
1e000 65 70 74 20 74 68 61 74 20 4e 20 69 73 20 61 6e  ept that N is an
1e010 20 75 6e 73 69 67 6e 65 64 20 36 34 2d 62 69 74   unsigned 64-bit
1e020 20 69 6e 74 65 67 65 72 20 69 6e 73 74 65 61 64   integer instead
1e030 0a 2a 2a 20 6f 66 20 61 20 73 69 67 6e 65 64 20  .** of a signed 
1e040 33 32 2d 62 69 74 20 69 6e 74 65 67 65 72 2e 0a  32-bit integer..
1e050 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73  **.** ^Calling s
1e060 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 77 69  qlite3_free() wi
1e070 74 68 20 61 20 70 6f 69 6e 74 65 72 20 70 72 65  th a pointer pre
1e080 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64  viously returned
1e090 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 6d  .** by sqlite3_m
1e0a0 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74  alloc() or sqlit
1e0b0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c  e3_realloc() rel
1e0c0 65 61 73 65 73 20 74 68 61 74 20 6d 65 6d 6f 72  eases that memor
1e0d0 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20  y so.** that it 
1e0e0 6d 69 67 68 74 20 62 65 20 72 65 75 73 65 64 2e  might be reused.
1e0f0 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66    ^The sqlite3_f
1e100 72 65 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73  ree() routine is
1e110 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69  .** a no-op if i
1e120 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20  s called with a 
1e130 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50  NULL pointer.  P
1e140 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f  assing a NULL po
1e150 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69  inter.** to sqli
1e160 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 68 61  te3_free() is ha
1e170 72 6d 6c 65 73 73 2e 20 20 41 66 74 65 72 20 62  rmless.  After b
1e180 65 69 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f  eing freed, memo
1e190 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69  ry.** should nei
1e1a0 74 68 65 72 20 62 65 20 72 65 61 64 20 6e 6f 72  ther be read nor
1e1b0 20 77 72 69 74 74 65 6e 2e 20 20 45 76 65 6e 20   written.  Even 
1e1c0 72 65 61 64 69 6e 67 20 70 72 65 76 69 6f 75 73  reading previous
1e1d0 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f  ly freed.** memo
1e1e0 72 79 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20  ry might result 
1e1f0 69 6e 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f  in a segmentatio
1e200 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74 68 65 72  n fault or other
1e210 20 73 65 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a   severe error..*
1e220 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70 74  * Memory corrupt
1e230 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61 74  ion, a segmentat
1e240 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74  ion fault, or ot
1e250 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72  her severe error
1e260 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73 75 6c 74  .** might result
1e270 20 69 66 20 73 71 6c 69 74 65 33 5f 66 72 65 65   if sqlite3_free
1e280 28 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74  () is called wit
1e290 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69  h a non-NULL poi
1e2a0 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20 77 61 73  nter that.** was
1e2b0 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20 66 72   not obtained fr
1e2c0 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  om sqlite3_mallo
1e2d0 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  c() or sqlite3_r
1e2e0 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20  ealloc()..**.** 
1e2f0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61  ^The sqlite3_rea
1e300 6c 6c 6f 63 28 58 2c 4e 29 20 69 6e 74 65 72 66  lloc(X,N) interf
1e310 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20  ace attempts to 
1e320 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f  resize a.** prio
1e330 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  r memory allocat
1e340 69 6f 6e 20 58 20 74 6f 20 62 65 20 61 74 20 6c  ion X to be at l
1e350 65 61 73 74 20 4e 20 62 79 74 65 73 2e 0a 2a 2a  east N bytes..**
1e360 20 5e 49 66 20 74 68 65 20 58 20 70 61 72 61 6d   ^If the X param
1e370 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
1e380 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 0a 2a 2a 20  realloc(X,N).** 
1e390 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
1e3a0 72 20 74 68 65 6e 20 69 74 73 20 62 65 68 61 76  r then its behav
1e3b0 69 6f 72 20 69 73 20 69 64 65 6e 74 69 63 61 6c  ior is identical
1e3c0 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73   to calling.** s
1e3d0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29  qlite3_malloc(N)
1e3e0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e 20 70  ..** ^If the N p
1e3f0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
1e400 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29  te3_realloc(X,N)
1e410 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e   is zero or.** n
1e420 65 67 61 74 69 76 65 20 74 68 65 6e 20 74 68 65  egative then the
1e430 20 62 65 68 61 76 69 6f 72 20 69 73 20 65 78 61   behavior is exa
1e440 63 74 6c 79 20 74 68 65 20 73 61 6d 65 20 61 73  ctly the same as
1e450 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69   calling.** sqli
1e460 74 65 33 5f 66 72 65 65 28 58 29 2e 0a 2a 2a 20  te3_free(X)..** 
1e470 5e 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  ^sqlite3_realloc
1e480 28 58 2c 4e 29 20 72 65 74 75 72 6e 73 20 61 20  (X,N) returns a 
1e490 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d  pointer to a mem
1e4a0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  ory allocation.*
1e4b0 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20  * of at least N 
1e4c0 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 6f 72  bytes in size or
1e4d0 20 4e 55 4c 4c 20 69 66 20 69 6e 73 75 66 66 69   NULL if insuffi
1e4e0 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20  cient memory is 
1e4f0 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49  available..** ^I
1e500 66 20 4d 20 69 73 20 74 68 65 20 73 69 7a 65 20  f M is the size 
1e510 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c  of the prior all
1e520 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69  ocation, then mi
1e530 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20  n(N,M) bytes.** 
1e540 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c  of the prior all
1e550 6f 63 61 74 69 6f 6e 20 61 72 65 20 63 6f 70 69  ocation are copi
1e560 65 64 20 69 6e 74 6f 20 74 68 65 20 62 65 67 69  ed into the begi
1e570 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66 65 72 20  nning of buffer 
1e580 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73  returned.** by s
1e590 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58  qlite3_realloc(X
1e5a0 2c 4e 29 20 61 6e 64 20 74 68 65 20 70 72 69 6f  ,N) and the prio
1e5b0 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20  r allocation is 
1e5c0 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 73 71  freed..** ^If sq
1e5d0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c  lite3_realloc(X,
1e5e0 4e 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20  N) returns NULL 
1e5f0 61 6e 64 20 4e 20 69 73 20 70 6f 73 69 74 69 76  and N is positiv
1e600 65 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 70  e, then the.** p
1e610 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  rior allocation 
1e620 69 73 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a  is not freed..**
1e630 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1e640 5f 72 65 61 6c 6c 6f 63 36 34 28 58 2c 4e 29 20  _realloc64(X,N) 
1e650 69 6e 74 65 72 66 61 63 65 73 20 77 6f 72 6b 73  interfaces works
1e660 20 74 68 65 20 73 61 6d 65 20 61 73 0a 2a 2a 20   the same as.** 
1e670 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1e680 58 2c 4e 29 20 65 78 63 65 70 74 20 74 68 61 74  X,N) except that
1e690 20 4e 20 69 73 20 61 20 36 34 2d 62 69 74 20 75   N is a 64-bit u
1e6a0 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20  nsigned integer 
1e6b0 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20  instead.** of a 
1e6c0 33 32 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  32-bit signed in
1e6d0 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  teger..**.** ^If
1e6e0 20 58 20 69 73 20 61 20 6d 65 6d 6f 72 79 20 61   X is a memory a
1e6f0 6c 6c 6f 63 61 74 69 6f 6e 20 70 72 65 76 69 6f  llocation previo
1e700 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72  usly obtained fr
1e710 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  om sqlite3_mallo
1e720 63 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  c(),.** sqlite3_
1e730 6d 61 6c 6c 6f 63 36 34 28 29 2c 20 73 71 6c 69  malloc64(), sqli
1e740 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2c 20 6f  te3_realloc(), o
1e750 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  r sqlite3_reallo
1e760 63 36 34 28 29 2c 20 74 68 65 6e 0a 2a 2a 20 73  c64(), then.** s
1e770 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20  qlite3_msize(X) 
1e780 72 65 74 75 72 6e 73 20 74 68 65 20 73 69 7a 65  returns the size
1e790 20 6f 66 20 74 68 61 74 20 6d 65 6d 6f 72 79 20   of that memory 
1e7a0 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 6e 20 62 79  allocation in by
1e7b0 74 65 73 2e 0a 2a 2a 20 5e 54 68 65 20 76 61 6c  tes..** ^The val
1e7c0 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ue returned by s
1e7d0 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20  qlite3_msize(X) 
1e7e0 6d 69 67 68 74 20 62 65 20 6c 61 72 67 65 72 20  might be larger 
1e7f0 74 68 61 6e 20 74 68 65 20 6e 75 6d 62 65 72 0a  than the number.
1e800 2a 2a 20 6f 66 20 62 79 74 65 73 20 72 65 71 75  ** of bytes requ
1e810 65 73 74 65 64 20 77 68 65 6e 20 58 20 77 61 73  ested when X was
1e820 20 61 6c 6c 6f 63 61 74 65 64 2e 20 20 5e 49 66   allocated.  ^If
1e830 20 58 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69   X is a NULL poi
1e840 6e 74 65 72 20 74 68 65 6e 0a 2a 2a 20 73 71 6c  nter then.** sql
1e850 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 72 65  ite3_msize(X) re
1e860 74 75 72 6e 73 20 7a 65 72 6f 2e 20 20 49 66 20  turns zero.  If 
1e870 58 20 70 6f 69 6e 74 73 20 74 6f 20 73 6f 6d 65  X points to some
1e880 74 68 69 6e 67 20 74 68 61 74 20 69 73 20 6e 6f  thing that is no
1e890 74 0a 2a 2a 20 74 68 65 20 62 65 67 69 6e 6e 69  t.** the beginni
1e8a0 6e 67 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c  ng of memory all
1e8b0 6f 63 61 74 69 6f 6e 2c 20 6f 72 20 69 66 20 69  ocation, or if i
1e8c0 74 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 66 6f  t points to a fo
1e8d0 72 6d 65 72 6c 79 0a 2a 2a 20 76 61 6c 69 64 20  rmerly.** valid 
1e8e0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
1e8f0 6e 20 74 68 61 74 20 68 61 73 20 6e 6f 77 20 62  n that has now b
1e900 65 65 6e 20 66 72 65 65 64 2c 20 74 68 65 6e 20  een freed, then 
1e910 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20  the behavior.** 
1e920 6f 66 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65  of sqlite3_msize
1e930 28 58 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64  (X) is undefined
1e940 20 61 6e 64 20 70 6f 73 73 69 62 6c 79 20 68 61   and possibly ha
1e950 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  rmful..**.** ^Th
1e960 65 20 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e 65  e memory returne
1e970 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c  d by sqlite3_mal
1e980 6c 6f 63 28 29 2c 20 73 71 6c 69 74 65 33 5f 72  loc(), sqlite3_r
1e990 65 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c  ealloc(),.** sql
1e9a0 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c  ite3_malloc64(),
1e9b0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 61   and sqlite3_rea
1e9c0 6c 6c 6f 63 36 34 28 29 0a 2a 2a 20 69 73 20 61  lloc64().** is a
1e9d0 6c 77 61 79 73 20 61 6c 69 67 6e 65 64 20 74 6f  lways aligned to
1e9e0 20 61 74 20 6c 65 61 73 74 20 61 6e 20 38 20 62   at least an 8 b
1e9f0 79 74 65 20 62 6f 75 6e 64 61 72 79 2c 20 6f 72  yte boundary, or
1ea00 20 74 6f 20 61 0a 2a 2a 20 34 20 62 79 74 65 20   to a.** 4 byte 
1ea10 62 6f 75 6e 64 61 72 79 20 69 66 20 74 68 65 20  boundary if the 
1ea20 5b 53 51 4c 49 54 45 5f 34 5f 42 59 54 45 5f 41  [SQLITE_4_BYTE_A
1ea30 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63  LIGNED_MALLOC] c
1ea40 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f  ompile-time.** o
1ea50 70 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a  ption is used..*
1ea60 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20 76  *.** In SQLite v
1ea70 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64  ersion 3.5.0 and
1ea80 20 33 2e 35 2e 31 2c 20 69 74 20 77 61 73 20 70   3.5.1, it was p
1ea90 6f 73 73 69 62 6c 65 20 74 6f 20 64 65 66 69 6e  ossible to defin
1eaa0 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54 45 5f  e.** the SQLITE_
1eab0 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f  OMIT_MEMORY_ALLO
1eac0 43 41 54 49 4f 4e 20 77 68 69 63 68 20 77 6f 75  CATION which wou
1ead0 6c 64 20 63 61 75 73 65 20 74 68 65 20 62 75 69  ld cause the bui
1eae0 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65  lt-in.** impleme
1eaf0 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 73 65  ntation of these
1eb00 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20   routines to be 
1eb10 6f 6d 69 74 74 65 64 2e 20 20 54 68 61 74 20 63  omitted.  That c
1eb20 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20  apability.** is 
1eb30 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64  no longer provid
1eb40 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d  ed.  Only built-
1eb50 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  in memory alloca
1eb60 74 6f 72 73 20 63 61 6e 20 62 65 20 75 73 65 64  tors can be used
1eb70 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f  ..**.** Prior to
1eb80 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
1eb90 33 2e 37 2e 31 30 2c 20 74 68 65 20 57 69 6e 64  3.7.10, the Wind
1eba0 6f 77 73 20 4f 53 20 69 6e 74 65 72 66 61 63 65  ows OS interface
1ebb0 20 6c 61 79 65 72 20 63 61 6c 6c 65 64 0a 2a 2a   layer called.**
1ebc0 20 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c   the system mall
1ebd0 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20  oc() and free() 
1ebe0 64 69 72 65 63 74 6c 79 20 77 68 65 6e 20 63 6f  directly when co
1ebf0 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65  nverting.** file
1ec00 6e 61 6d 65 73 20 62 65 74 77 65 65 6e 20 74 68  names between th
1ec10 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67  e UTF-8 encoding
1ec20 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 0a   used by SQLite.
1ec30 2a 2a 20 61 6e 64 20 77 68 61 74 65 76 65 72 20  ** and whatever 
1ec40 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e  filename encodin
1ec50 67 20 69 73 20 75 73 65 64 20 62 79 20 74 68 65  g is used by the
1ec60 20 70 61 72 74 69 63 75 6c 61 72 20 57 69 6e 64   particular Wind
1ec70 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74  ows.** installat
1ec80 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c  ion.  Memory all
1ec90 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 73 20 77  ocation errors w
1eca0 65 72 65 20 64 65 74 65 63 74 65 64 2c 20 62 75  ere detected, bu
1ecb0 74 0a 2a 2a 20 74 68 65 79 20 77 65 72 65 20 72  t.** they were r
1ecc0 65 70 6f 72 74 65 64 20 62 61 63 6b 20 61 73 20  eported back as 
1ecd0 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e  [SQLITE_CANTOPEN
1ece0 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ] or.** [SQLITE_
1ecf0 49 4f 45 52 52 5d 20 72 61 74 68 65 72 20 74 68  IOERR] rather th
1ed00 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  an [SQLITE_NOMEM
1ed10 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69  ]..**.** The poi
1ed20 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 73 20 74  nter arguments t
1ed30 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  o [sqlite3_free(
1ed40 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
1ed50 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75  realloc()].** mu
1ed60 73 74 20 62 65 20 65 69 74 68 65 72 20 4e 55 4c  st be either NUL
1ed70 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74 65  L or else pointe
1ed80 72 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  rs obtained from
1ed90 20 61 20 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f   a prior.** invo
1eda0 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74  cation of [sqlit
1edb0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20  e3_malloc()] or 
1edc0 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
1edd0 28 29 5d 20 74 68 61 74 20 68 61 76 65 0a 2a 2a  ()] that have.**
1ede0 20 6e 6f 74 20 79 65 74 20 62 65 65 6e 20 72 65   not yet been re
1edf0 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  leased..**.** Th
1ee00 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
1ee10 73 74 20 6e 6f 74 20 72 65 61 64 20 6f 72 20 77  st not read or w
1ee20 72 69 74 65 20 61 6e 79 20 70 61 72 74 20 6f 66  rite any part of
1ee30 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d  .** a block of m
1ee40 65 6d 6f 72 79 20 61 66 74 65 72 20 69 74 20 68  emory after it h
1ee50 61 73 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64  as been released
1ee60 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
1ee70 65 33 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b 73  e3_free()] or [s
1ee80 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1ee90 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  ]..*/.SQLITE_API
1eea0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d   void *sqlite3_m
1eeb0 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 53 51 4c 49  alloc(int);.SQLI
1eec0 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c  TE_API void *sql
1eed0 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 73 71  ite3_malloc64(sq
1eee0 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a 53  lite3_uint64);.S
1eef0 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a  QLITE_API void *
1ef00 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1ef10 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c  void*, int);.SQL
1ef20 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71  ITE_API void *sq
1ef30 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28  lite3_realloc64(
1ef40 76 6f 69 64 2a 2c 20 73 71 6c 69 74 65 33 5f 75  void*, sqlite3_u
1ef50 69 6e 74 36 34 29 3b 0a 53 51 4c 49 54 45 5f 41  int64);.SQLITE_A
1ef60 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  PI void sqlite3_
1ef70 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a 53 51 4c  free(void*);.SQL
1ef80 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f  ITE_API sqlite3_
1ef90 75 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d  uint64 sqlite3_m
1efa0 73 69 7a 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  size(void*);../*
1efb0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65  .** CAPI3REF: Me
1efc0 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53  mory Allocator S
1efd0 74 61 74 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20  tatistics.**.** 
1efe0 53 51 4c 69 74 65 20 70 72 6f 76 69 64 65 73 20  SQLite provides 
1eff0 74 68 65 73 65 20 74 77 6f 20 69 6e 74 65 72 66  these two interf
1f000 61 63 65 73 20 66 6f 72 20 72 65 70 6f 72 74 69  aces for reporti
1f010 6e 67 20 6f 6e 20 74 68 65 20 73 74 61 74 75 73  ng on the status
1f020 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  .** of the [sqli
1f030 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b  te3_malloc()], [
1f040 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2c  sqlite3_free()],
1f050 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65   and [sqlite3_re
1f060 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74  alloc()].** rout
1f070 69 6e 65 73 2c 20 77 68 69 63 68 20 66 6f 72 6d  ines, which form
1f080 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65   the built-in me
1f090 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
1f0a0 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a  subsystem..**.**
1f0b0 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d   ^The [sqlite3_m
1f0c0 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 72 6f  emory_used()] ro
1f0d0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
1f0e0 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
1f0f0 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 63  s.** of memory c
1f100 75 72 72 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e  urrently outstan
1f110 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62  ding (malloced b
1f120 75 74 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a  ut not freed)..*
1f130 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  * ^The [sqlite3_
1f140 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
1f150 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75  ()] routine retu
1f160 72 6e 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a  rns the maximum.
1f170 2a 2a 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c  ** value of [sql
1f180 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
1f190 28 29 5d 20 73 69 6e 63 65 20 74 68 65 20 68 69  ()] since the hi
1f1a0 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a  gh-water mark.**
1f1b0 20 77 61 73 20 6c 61 73 74 20 72 65 73 65 74 2e   was last reset.
1f1c0 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65    ^The values re
1f1d0 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
1f1e0 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
1f1f0 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
1f200 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
1f210 65 72 28 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e  er()] include an
1f220 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20 61 64  y overhead.** ad
1f230 64 65 64 20 62 79 20 53 51 4c 69 74 65 20 69 6e  ded by SQLite in
1f240 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74   its implementat
1f250 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ion of [sqlite3_
1f260 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75  malloc()],.** bu
1f270 74 20 6e 6f 74 20 6f 76 65 72 68 65 61 64 20 61  t not overhead a
1f280 64 64 65 64 20 62 79 20 74 68 65 20 61 6e 79 20  dded by the any 
1f290 75 6e 64 65 72 6c 79 69 6e 67 20 73 79 73 74 65  underlying syste
1f2a0 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20 72 6f 75  m library.** rou
1f2b0 74 69 6e 65 73 20 74 68 61 74 20 5b 73 71 6c 69  tines that [sqli
1f2c0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61  te3_malloc()] ma
1f2d0 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54  y call..**.** ^T
1f2e0 68 65 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77  he memory high-w
1f2f0 61 74 65 72 20 6d 61 72 6b 20 69 73 20 72 65 73  ater mark is res
1f300 65 74 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e  et to the curren
1f310 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73  t value of.** [s
1f320 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
1f330 65 64 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c  ed()] if and onl
1f340 79 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  y if the paramet
1f350 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  er to.** [sqlite
1f360 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
1f370 65 72 28 29 5d 20 69 73 20 74 72 75 65 2e 20 20  er()] is true.  
1f380 5e 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72  ^The value retur
1f390 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74  ned.** by [sqlit
1f3a0 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
1f3b0 74 65 72 28 31 29 5d 20 69 73 20 74 68 65 20 68  ter(1)] is the h
1f3c0 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a  igh-water mark.*
1f3d0 2a 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 72  * prior to the r
1f3e0 65 73 65 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  eset..*/.SQLITE_
1f3f0 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  API sqlite3_int6
1f400 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79  4 sqlite3_memory
1f410 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a 53 51 4c  _used(void);.SQL
1f420 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f  ITE_API sqlite3_
1f430 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65  int64 sqlite3_me
1f440 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 69  mory_highwater(i
1f450 6e 74 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a  nt resetFlag);..
1f460 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1f470 50 73 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75  Pseudo-Random Nu
1f480 6d 62 65 72 20 47 65 6e 65 72 61 74 6f 72 0a 2a  mber Generator.*
1f490 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74  *.** SQLite cont
1f4a0 61 69 6e 73 20 61 20 68 69 67 68 2d 71 75 61 6c  ains a high-qual
1f4b0 69 74 79 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f  ity pseudo-rando
1f4c0 6d 20 6e 75 6d 62 65 72 20 67 65 6e 65 72 61 74  m number generat
1f4d0 6f 72 20 28 50 52 4e 47 29 20 75 73 65 64 20 74  or (PRNG) used t
1f4e0 6f 0a 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e 64  o.** select rand
1f4f0 6f 6d 20 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49  om [ROWID | ROWI
1f500 44 73 5d 20 77 68 65 6e 20 69 6e 73 65 72 74 69  Ds] when inserti
1f510 6e 67 20 6e 65 77 20 72 65 63 6f 72 64 73 20 69  ng new records i
1f520 6e 74 6f 20 61 20 74 61 62 6c 65 20 74 68 61 74  nto a table that
1f530 0a 2a 2a 20 61 6c 72 65 61 64 79 20 75 73 65 73  .** already uses
1f540 20 74 68 65 20 6c 61 72 67 65 73 74 20 70 6f 73   the largest pos
1f550 73 69 62 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20  sible [ROWID].  
1f560 54 68 65 20 50 52 4e 47 20 69 73 20 61 6c 73 6f  The PRNG is also
1f570 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65   used for.** the
1f580 20 62 75 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d   build-in random
1f590 28 29 20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f  () and randomblo
1f5a0 62 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  b() SQL function
1f5b0 73 2e 20 20 54 68 69 73 20 69 6e 74 65 72 66 61  s.  This interfa
1f5c0 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70  ce allows.** app
1f5d0 6c 69 63 61 74 69 6f 6e 73 20 74 6f 20 61 63 63  lications to acc
1f5e0 65 73 73 20 74 68 65 20 73 61 6d 65 20 50 52 4e  ess the same PRN
1f5f0 47 20 66 6f 72 20 6f 74 68 65 72 20 70 75 72 70  G for other purp
1f600 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63  oses..**.** ^A c
1f610 61 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74  all to this rout
1f620 69 6e 65 20 73 74 6f 72 65 73 20 4e 20 62 79 74  ine stores N byt
1f630 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73  es of randomness
1f640 20 69 6e 74 6f 20 62 75 66 66 65 72 20 50 2e 0a   into buffer P..
1f650 2a 2a 20 5e 54 68 65 20 50 20 70 61 72 61 6d 65  ** ^The P parame
1f660 74 65 72 20 63 61 6e 20 62 65 20 61 20 4e 55 4c  ter can be a NUL
1f670 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  L pointer..**.**
1f680 20 5e 49 66 20 74 68 69 73 20 72 6f 75 74 69 6e   ^If this routin
1f690 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 70  e has not been p
1f6a0 72 65 76 69 6f 75 73 6c 79 20 63 61 6c 6c 65 64  reviously called
1f6b0 20 6f 72 20 69 66 20 74 68 65 20 70 72 65 76 69   or if the previ
1f6c0 6f 75 73 0a 2a 2a 20 63 61 6c 6c 20 68 61 64 20  ous.** call had 
1f6d0 4e 20 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65 20  N less than one 
1f6e0 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  or a NULL pointe
1f6f0 72 20 66 6f 72 20 50 2c 20 74 68 65 6e 20 74 68  r for P, then th
1f700 65 20 50 52 4e 47 20 69 73 0a 2a 2a 20 73 65 65  e PRNG is.** see
1f710 64 65 64 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d  ded using random
1f720 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 20 66 72  ness obtained fr
1f730 6f 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65  om the xRandomne
1f740 73 73 20 6d 65 74 68 6f 64 20 6f 66 0a 2a 2a 20  ss method of.** 
1f750 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c  the default [sql
1f760 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
1f770 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 65  ..** ^If the pre
1f780 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74 68  vious call to th
1f790 69 73 20 72 6f 75 74 69 6e 65 20 68 61 64 20 61  is routine had a
1f7a0 6e 20 4e 20 6f 66 20 31 20 6f 72 20 6d 6f 72 65  n N of 1 or more
1f7b0 20 61 6e 64 20 61 0a 2a 2a 20 6e 6f 6e 2d 4e 55   and a.** non-NU
1f7c0 4c 4c 20 50 20 74 68 65 6e 20 74 68 65 20 70 73  LL P then the ps
1f7d0 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20  eudo-randomness 
1f7e0 69 73 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20  is generated.** 
1f7f0 69 6e 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77  internally and w
1f800 69 74 68 6f 75 74 20 72 65 63 6f 75 72 73 65 20  ithout recourse 
1f810 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
1f820 76 66 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73  vfs] xRandomness
1f830 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 53  .** method..*/.S
1f840 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73  QLITE_API void s
1f850 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73  qlite3_randomnes
1f860 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50  s(int N, void *P
1f870 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1f880 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65  EF: Compile-Time
1f890 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43   Authorization C
1f8a0 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e  allbacks.**.** ^
1f8b0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 67  This routine reg
1f8c0 69 73 74 65 72 73 20 61 6e 20 61 75 74 68 6f 72  isters an author
1f8d0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 69  izer callback wi
1f8e0 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a  th a particular.
1f8f0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
1f900 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69  nection], suppli
1f910 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ed in the first 
1f920 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68  argument..** ^Th
1f930 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1f940 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
1f950 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   as SQL statemen
1f960 74 73 20 61 72 65 20 62 65 69 6e 67 20 63 6f 6d  ts are being com
1f970 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c  piled.** by [sql
1f980 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
1f990 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 20  or its variants 
1f9a0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1f9b0 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  _v2()],.** [sqli
1f9c0 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
1f9d0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
1f9e0 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 20 20  epare16_v2()].  
1f9f0 5e 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70  ^At various.** p
1fa00 6f 69 6e 74 73 20 64 75 72 69 6e 67 20 74 68 65  oints during the
1fa10 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f   compilation pro
1fa20 63 65 73 73 2c 20 61 73 20 6c 6f 67 69 63 20 69  cess, as logic i
1fa30 73 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 0a  s being created.
1fa40 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61  ** to perform va
1fa50 72 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20 74  rious actions, t
1fa60 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1fa70 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
1fa80 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74  d to.** see if t
1fa90 68 6f 73 65 20 61 63 74 69 6f 6e 73 20 61 72 65  hose actions are
1faa0 20 61 6c 6c 6f 77 65 64 2e 20 20 5e 54 68 65 20   allowed.  ^The 
1fab0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1fac0 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65  ack should.** re
1fad0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
1fae0 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61 63   to allow the ac
1faf0 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47  tion, [SQLITE_IG
1fb00 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f  NORE] to disallo
1fb10 77 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69  w the.** specifi
1fb20 63 20 61 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c  c action but all
1fb30 6f 77 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  ow the SQL state
1fb40 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65  ment to continue
1fb50 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c   to be.** compil
1fb60 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  ed, or [SQLITE_D
1fb70 45 4e 59 5d 20 74 6f 20 63 61 75 73 65 20 74 68  ENY] to cause th
1fb80 65 20 65 6e 74 69 72 65 20 53 51 4c 20 73 74 61  e entire SQL sta
1fb90 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20  tement to be.** 
1fba0 72 65 6a 65 63 74 65 64 20 77 69 74 68 20 61 6e  rejected with an
1fbb0 20 65 72 72 6f 72 2e 20 20 5e 49 66 20 74 68 65   error.  ^If the
1fbc0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1fbd0 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20  back returns.** 
1fbe0 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20  any value other 
1fbf0 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e  than [SQLITE_IGN
1fc00 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b  ORE], [SQLITE_OK
1fc10 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45  ], or [SQLITE_DE
1fc20 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  NY].** then the 
1fc30 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1fc40 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61  _v2()] or equiva
1fc50 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74  lent call that t
1fc60 72 69 67 67 65 72 65 64 0a 2a 2a 20 74 68 65 20  riggered.** the 
1fc70 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20  authorizer will 
1fc80 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72  fail with an err
1fc90 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a  or message..**.*
1fca0 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62  * When the callb
1fcb0 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ack returns [SQL
1fcc0 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65  ITE_OK], that me
1fcd0 61 6e 73 20 74 68 65 20 6f 70 65 72 61 74 69 6f  ans the operatio
1fce0 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 69  n.** requested i
1fcf0 73 20 6f 6b 2e 20 20 5e 57 68 65 6e 20 74 68 65  s ok.  ^When the
1fd00 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
1fd10 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c  s [SQLITE_DENY],
1fd20 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
1fd30 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
1fd40 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c  r equivalent cal
1fd50 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64  l that triggered
1fd60 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a   the.** authoriz
1fd70 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74  er will fail wit
1fd80 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61  h an error messa
1fd90 67 65 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68  ge explaining th
1fda0 61 74 0a 2a 2a 20 61 63 63 65 73 73 20 69 73 20  at.** access is 
1fdb0 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e  denied. .**.** ^
1fdc0 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
1fdd0 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f  ter to the autho
1fde0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
1fdf0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
1fe00 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74  third.** paramet
1fe10 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
1fe20 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
1fe30 28 29 20 69 6e 74 65 72 66 61 63 65 2e 20 5e 54  () interface. ^T
1fe40 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
1fe50 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61  ter.** to the ca
1fe60 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74  llback is an int
1fe70 65 67 65 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50  eger [SQLITE_COP
1fe80 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d  Y | action code]
1fe90 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73 0a   that specifies.
1fea0 2a 2a 20 74 68 65 20 70 61 72 74 69 63 75 6c 61  ** the particula
1feb0 72 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  r action to be a
1fec0 75 74 68 6f 72 69 7a 65 64 2e 20 5e 54 68 65 20  uthorized. ^The 
1fed0 74 68 69 72 64 20 74 68 72 6f 75 67 68 20 73 69  third through si
1fee0 78 74 68 20 70 61 72 61 6d 65 74 65 72 73 0a 2a  xth parameters.*
1fef0 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  * to the callbac
1ff00 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69  k are zero-termi
1ff10 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68  nated strings th
1ff20 61 74 20 63 6f 6e 74 61 69 6e 20 61 64 64 69 74  at contain addit
1ff30 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 6c 73  ional.** details
1ff40 20 61 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f   about the actio
1ff50 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a  n to be authoriz
1ff60 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ed..**.** ^If th
1ff70 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73  e action code is
1ff80 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a   [SQLITE_READ].*
1ff90 2a 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61  * and the callba
1ffa0 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ck returns [SQLI
1ffb0 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20  TE_IGNORE] then 
1ffc0 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
1ffd0 20 73 74 61 74 65 6d 65 6e 74 5d 20 73 74 61 74   statement] stat
1ffe0 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 75  ement is constru
1fff0 63 74 65 64 20 74 6f 20 73 75 62 73 74 69 74 75  cted to substitu
20000 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c  te.** a NULL val
20010 75 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74  ue in place of t
20020 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20  he table column 
20030 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65 0a  that would have.
20040 2a 2a 20 62 65 65 6e 20 72 65 61 64 20 69 66 20  ** been read if 
20050 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20  [SQLITE_OK] had 
20060 62 65 65 6e 20 72 65 74 75 72 6e 65 64 2e 20 20  been returned.  
20070 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  The [SQLITE_IGNO
20080 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61  RE].** return ca
20090 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64 65 6e  n be used to den
200a0 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 75  y an untrusted u
200b0 73 65 72 20 61 63 63 65 73 73 20 74 6f 20 69 6e  ser access to in
200c0 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75  dividual.** colu
200d0 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a  mns of a table..
200e0 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f  ** ^If the actio
200f0 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54  n code is [SQLIT
20100 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20 74 68  E_DELETE] and th
20110 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
20120 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 47  ns.** [SQLITE_IG
20130 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 20 5b  NORE] then the [
20140 44 45 4c 45 54 45 5d 20 6f 70 65 72 61 74 69 6f  DELETE] operatio
20150 6e 20 70 72 6f 63 65 65 64 73 20 62 75 74 20 74  n proceeds but t
20160 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 65 20  he.** [truncate 
20170 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 69 73  optimization] is
20180 20 64 69 73 61 62 6c 65 64 20 61 6e 64 20 61 6c   disabled and al
20190 6c 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74  l rows are delet
201a0 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c 79 2e  ed individually.
201b0 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72  .**.** An author
201c0 69 7a 65 72 20 69 73 20 75 73 65 64 20 77 68 65  izer is used whe
201d0 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  n [sqlite3_prepa
201e0 72 65 20 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a  re | preparing].
201f0 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
20200 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73  s from an untrus
20210 74 65 64 20 73 6f 75 72 63 65 2c 20 74 6f 20 65  ted source, to e
20220 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20 53  nsure that the S
20230 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
20240 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20 61   do not try to a
20250 63 63 65 73 73 20 64 61 74 61 20 74 68 65 79 20  ccess data they 
20260 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20  are not allowed 
20270 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 74 20  to see, or that 
20280 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74  they do not.** t
20290 72 79 20 74 6f 20 65 78 65 63 75 74 65 20 6d 61  ry to execute ma
202a0 6c 69 63 69 6f 75 73 20 73 74 61 74 65 6d 65 6e  licious statemen
202b0 74 73 20 74 68 61 74 20 64 61 6d 61 67 65 20 74  ts that damage t
202c0 68 65 20 64 61 74 61 62 61 73 65 2e 20 20 46 6f  he database.  Fo
202d0 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e  r.** example, an
202e0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79   application may
202f0 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 74 6f   allow a user to
20300 20 65 6e 74 65 72 20 61 72 62 69 74 72 61 72 79   enter arbitrary
20310 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 73 20  .** SQL queries 
20320 66 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e 20 62  for evaluation b
20330 79 20 61 20 64 61 74 61 62 61 73 65 2e 20 20 42  y a database.  B
20340 75 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ut the applicati
20350 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77  on does.** not w
20360 61 6e 74 20 74 68 65 20 75 73 65 72 20 74 6f 20  ant the user to 
20370 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20  be able to make 
20380 61 72 62 69 74 72 61 72 79 20 63 68 61 6e 67 65  arbitrary change
20390 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61  s to the.** data
203a0 62 61 73 65 2e 20 20 41 6e 20 61 75 74 68 6f 72  base.  An author
203b0 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 6e 20  izer could then 
203c0 62 65 20 70 75 74 20 69 6e 20 70 6c 61 63 65 20  be put in place 
203d0 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65  while the.** use
203e0 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 69 73  r-entered SQL is
203f0 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   being [sqlite3_
20400 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72  prepare | prepar
20410 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73 61  ed] that.** disa
20420 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69 6e 67  llows everything
20430 20 65 78 63 65 70 74 20 5b 53 45 4c 45 43 54 5d   except [SELECT]
20440 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a   statements..**.
20450 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** Applications 
20460 74 68 61 74 20 6e 65 65 64 20 74 6f 20 70 72 6f  that need to pro
20470 63 65 73 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e  cess SQL from un
20480 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 73 0a  trusted sources.
20490 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f  ** might also co
204a0 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 6e 67 20  nsider lowering 
204b0 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 74 73 20  resource limits 
204c0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c  using [sqlite3_l
204d0 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c  imit()].** and l
204e0 69 6d 69 74 69 6e 67 20 64 61 74 61 62 61 73 65  imiting database
204f0 20 73 69 7a 65 20 75 73 69 6e 67 20 74 68 65 20   size using the 
20500 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d  [max_page_count]
20510 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20   [PRAGMA].** in 
20520 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e  addition to usin
20530 67 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e  g an authorizer.
20540 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20  .**.** ^(Only a 
20550 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a 65  single authorize
20560 72 20 63 61 6e 20 62 65 20 69 6e 20 70 6c 61 63  r can be in plac
20570 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20  e on a database 
20580 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74  connection.** at
20590 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68 20 63   a time.  Each c
205a0 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
205b0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f 76  et_authorizer ov
205c0 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 70  errides the.** p
205d0 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29 5e 20  revious call.)^ 
205e0 20 5e 44 69 73 61 62 6c 65 20 74 68 65 20 61 75   ^Disable the au
205f0 74 68 6f 72 69 7a 65 72 20 62 79 20 69 6e 73 74  thorizer by inst
20600 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61  alling a NULL ca
20610 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61  llback..** The a
20620 75 74 68 6f 72 69 7a 65 72 20 69 73 20 64 69 73  uthorizer is dis
20630 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
20640 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68  ..**.** The auth
20650 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
20660 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74  must not do anyt
20670 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d  hing that will m
20680 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74  odify.** the dat
20690 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
206a0 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
206b0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
206c0 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74  lback..** Note t
206d0 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  hat [sqlite3_pre
206e0 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b  pare_v2()] and [
206f0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
20700 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69  both modify thei
20710 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  r.** database co
20720 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68  nnections for th
20730 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f  e meaning of "mo
20740 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61  dify" in this pa
20750 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e  ragraph..**.** ^
20760 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72  When [sqlite3_pr
20770 65 70 61 72 65 5f 76 32 28 29 5d 20 69 73 20 75  epare_v2()] is u
20780 73 65 64 20 74 6f 20 70 72 65 70 61 72 65 20 61  sed to prepare a
20790 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a   statement, the.
207a0 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d 69 67  ** statement mig
207b0 68 74 20 62 65 20 72 65 2d 70 72 65 70 61 72 65  ht be re-prepare
207c0 64 20 64 75 72 69 6e 67 20 5b 73 71 6c 69 74 65  d during [sqlite
207d0 33 5f 73 74 65 70 28 29 5d 20 64 75 65 20 74 6f  3_step()] due to
207e0 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68   a .** schema ch
207f0 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20 74 68  ange.  Hence, th
20800 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
20810 6f 75 6c 64 20 65 6e 73 75 72 65 20 74 68 61 74  ould ensure that
20820 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20   the.** correct 
20830 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
20840 61 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20 70  ack remains in p
20850 6c 61 63 65 20 64 75 72 69 6e 67 20 74 68 65 20  lace during the 
20860 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
20870 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68  ..**.** ^Note th
20880 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  at the authorize
20890 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  r callback is in
208a0 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e  voked only durin
208b0 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  g.** [sqlite3_pr
208c0 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20  epare()] or its 
208d0 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74 68 6f  variants.  Autho
208e0 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a  rization is not.
208f0 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 75 72  ** performed dur
20900 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 65 76  ing statement ev
20910 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c  aluation in [sql
20920 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 75 6e  ite3_step()], un
20930 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74 61 74 65  less.** as state
20940 64 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75  d in the previou
20950 73 20 70 61 72 61 67 72 61 70 68 2c 20 73 71 6c  s paragraph, sql
20960 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 76 6f  ite3_step() invo
20970 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70  kes.** sqlite3_p
20980 72 65 70 61 72 65 5f 76 32 28 29 20 74 6f 20 72  repare_v2() to r
20990 65 70 72 65 70 61 72 65 20 61 20 73 74 61 74 65  eprepare a state
209a0 6d 65 6e 74 20 61 66 74 65 72 20 61 20 73 63 68  ment after a sch
209b0 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 53  ema change..*/.S
209c0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
209d0 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
209e0 69 7a 65 72 28 0a 20 20 73 71 6c 69 74 65 33 2a  izer(.  sqlite3*
209f0 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75 74 68 29  ,.  int (*xAuth)
20a00 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74  (void*,int,const
20a10 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61   char*,const cha
20a20 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63  r*,const char*,c
20a30 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20 20 76  onst char*),.  v
20a40 6f 69 64 20 2a 70 55 73 65 72 44 61 74 61 0a 29  oid *pUserData.)
20a50 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
20a60 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 52 65  F: Authorizer Re
20a70 74 75 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a  turn Codes.**.**
20a80 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65   The [sqlite3_se
20a90 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61  t_authorizer | a
20aa0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
20ab0 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73  ck function] mus
20ac0 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69 74 68  t.** return eith
20ad0 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  er [SQLITE_OK] o
20ae0 72 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 74  r one of these t
20af0 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20  wo constants in 
20b00 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e  order.** to sign
20b10 61 6c 20 53 51 4c 69 74 65 20 77 68 65 74 68 65  al SQLite whethe
20b20 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 61 63 74  r or not the act
20b30 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64  ion is permitted
20b40 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73  .  See the.** [s
20b50 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
20b60 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a  rizer | authoriz
20b70 65 72 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  er documentation
20b80 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  ] for additional
20b90 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  .** information.
20ba0 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
20bb0 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 69   SQLITE_IGNORE i
20bc0 73 20 61 6c 73 6f 20 75 73 65 64 20 61 73 20 61  s also used as a
20bd0 20 5b 63 6f 6e 66 6c 69 63 74 20 72 65 73 6f 6c   [conflict resol
20be0 75 74 69 6f 6e 20 6d 6f 64 65 5d 0a 2a 2a 20 72  ution mode].** r
20bf0 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 74 68 65  eturned from the
20c00 20 5b 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 6f   [sqlite3_vtab_o
20c10 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20 69 6e  n_conflict()] in
20c20 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 64 65 66  terface..*/.#def
20c30 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e 59 20  ine SQLITE_DENY 
20c40 20 20 31 20 20 20 2f 2a 20 41 62 6f 72 74 20 74    1   /* Abort t
20c50 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
20c60 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 2a   with an error *
20c70 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
20c80 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20 44  _IGNORE 2   /* D
20c90 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63 65 73  on't allow acces
20ca0 73 2c 20 62 75 74 20 64 6f 6e 27 74 20 67 65 6e  s, but don't gen
20cb0 65 72 61 74 65 20 61 6e 20 65 72 72 6f 72 20 2a  erate an error *
20cc0 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
20cd0 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 41 63  F: Authorizer Ac
20ce0 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a  tion Codes.**.**
20cf0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65   The [sqlite3_se
20d00 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20  t_authorizer()] 
20d10 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74  interface regist
20d20 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66  ers a callback f
20d30 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20  unction.** that 
20d40 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61 75  is invoked to au
20d50 74 68 6f 72 69 7a 65 20 63 65 72 74 61 69 6e 20  thorize certain 
20d60 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 63  SQL statement ac
20d70 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73  tions.  The.** s
20d80 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
20d90 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
20da0 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f  is an integer co
20db0 64 65 20 74 68 61 74 20 73 70 65 63 69 66 69 65  de that specifie
20dc0 73 0a 2a 2a 20 77 68 61 74 20 61 63 74 69 6f 6e  s.** what action
20dd0 20 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f 72   is being author
20de0 69 7a 65 64 2e 20 20 54 68 65 73 65 20 61 72 65  ized.  These are
20df0 20 74 68 65 20 69 6e 74 65 67 65 72 20 61 63 74   the integer act
20e00 69 6f 6e 20 63 6f 64 65 73 20 74 68 61 74 0a 2a  ion codes that.*
20e10 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * the authorizer
20e20 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65   callback may be
20e30 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54   passed..**.** T
20e40 68 65 73 65 20 61 63 74 69 6f 6e 20 63 6f 64 65  hese action code
20e50 20 76 61 6c 75 65 73 20 73 69 67 6e 69 66 79 20   values signify 
20e60 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65  what kind of ope
20e70 72 61 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 0a  ration is to be.
20e80 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20  ** authorized.  
20e90 54 68 65 20 33 72 64 20 61 6e 64 20 34 74 68 20  The 3rd and 4th 
20ea0 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68  parameters to th
20eb0 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a  e authorization.
20ec0 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  ** callback func
20ed0 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61 72  tion will be par
20ee0 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20  ameters or NULL 
20ef0 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69  depending on whi
20f00 63 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 63  ch of these.** c
20f10 6f 64 65 73 20 69 73 20 75 73 65 64 20 61 73 20  odes is used as 
20f20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
20f30 65 74 65 72 2e 20 20 5e 28 54 68 65 20 35 74 68  eter.  ^(The 5th
20f40 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
20f50 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20  e.** authorizer 
20f60 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20  callback is the 
20f70 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61  name of the data
20f80 62 61 73 65 20 28 22 6d 61 69 6e 22 2c 20 22 74  base ("main", "t
20f90 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e 29 20 69  emp",.** etc.) i
20fa0 66 20 61 70 70 6c 69 63 61 62 6c 65 2e 29 5e 20  f applicable.)^ 
20fb0 20 5e 54 68 65 20 36 74 68 20 70 61 72 61 6d 65   ^The 6th parame
20fc0 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f  ter to the autho
20fd0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a  rizer callback.*
20fe0 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  * is the name of
20ff0 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20   the inner-most 
21000 74 72 69 67 67 65 72 20 6f 72 20 76 69 65 77 20  trigger or view 
21010 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e 73 69  that is responsi
21020 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61  ble for.** the a
21030 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 6f 72  ccess attempt or
21040 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 61 63   NULL if this ac
21050 63 65 73 73 20 61 74 74 65 6d 70 74 20 69 73 20  cess attempt is 
21060 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a  directly from.**
21070 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63   top-level SQL c
21080 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a  ode..*/./*******
21090 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
210a0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
210b0 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a  **** 3rd *******
210c0 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a  ***** 4th ******
210d0 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  *****/.#define S
210e0 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 49 4e 44  QLITE_CREATE_IND
210f0 45 58 20 20 20 20 20 20 20 20 20 20 31 20 20 20  EX          1   
21100 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
21110 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
21120 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
21130 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 41 42 4c  LITE_CREATE_TABL
21140 45 20 20 20 20 20 20 20 20 20 20 32 20 20 20 2f  E          2   /
21150 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
21160 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
21170 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
21180 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f  ITE_CREATE_TEMP_
21190 49 4e 44 45 58 20 20 20 20 20 33 20 20 20 2f 2a  INDEX     3   /*
211a0 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
211b0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
211c0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
211d0 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54  TE_CREATE_TEMP_T
211e0 41 42 4c 45 20 20 20 20 20 34 20 20 20 2f 2a 20  ABLE     4   /* 
211f0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
21200 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
21210 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
21220 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 52  E_CREATE_TEMP_TR
21230 49 47 47 45 52 20 20 20 35 20 20 20 2f 2a 20 54  IGGER   5   /* T
21240 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54  rigger Name    T
21250 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
21260 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
21270 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 49 45  _CREATE_TEMP_VIE
21280 57 20 20 20 20 20 20 36 20 20 20 2f 2a 20 56 69  W      6   /* Vi
21290 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55  ew Name       NU
212a0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
212b0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
212c0 43 52 45 41 54 45 5f 54 52 49 47 47 45 52 20 20  CREATE_TRIGGER  
212d0 20 20 20 20 20 20 37 20 20 20 2f 2a 20 54 72 69        7   /* Tri
212e0 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62  gger Name    Tab
212f0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
21300 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
21310 52 45 41 54 45 5f 56 49 45 57 20 20 20 20 20 20  REATE_VIEW      
21320 20 20 20 20 20 38 20 20 20 2f 2a 20 56 69 65 77       8   /* View
21330 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c   Name       NULL
21340 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
21350 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45  define SQLITE_DE
21360 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20  LETE            
21370 20 20 20 20 39 20 20 20 2f 2a 20 54 61 62 6c 65      9   /* Table
21380 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
21390 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
213a0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
213b0 50 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20  P_INDEX         
213c0 20 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 78 20    10   /* Index 
213d0 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
213e0 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
213f0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
21400 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20  _TABLE          
21410 20 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   11   /* Table N
21420 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
21430 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
21440 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
21450 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 20  TEMP_INDEX      
21460 31 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61  12   /* Index Na
21470 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61  me      Table Na
21480 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
21490 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
214a0 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 20 31  EMP_TABLE      1
214b0 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  3   /* Table Nam
214c0 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
214d0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
214e0 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45  e SQLITE_DROP_TE
214f0 4d 50 5f 54 52 49 47 47 45 52 20 20 20 20 31 34  MP_TRIGGER    14
21500 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
21510 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
21520 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
21530 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d   SQLITE_DROP_TEM
21540 50 5f 56 49 45 57 20 20 20 20 20 20 20 31 35 20  P_VIEW       15 
21550 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
21560 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
21570 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
21580 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49 47  SQLITE_DROP_TRIG
21590 47 45 52 20 20 20 20 20 20 20 20 20 31 36 20 20  GER         16  
215a0 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65   /* Trigger Name
215b0 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
215c0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
215d0 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 57 20  QLITE_DROP_VIEW 
215e0 20 20 20 20 20 20 20 20 20 20 20 31 37 20 20 20             17   
215f0 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20  /* View Name    
21600 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
21610 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
21620 4c 49 54 45 5f 49 4e 53 45 52 54 20 20 20 20 20  LITE_INSERT     
21630 20 20 20 20 20 20 20 20 20 20 31 38 20 20 20 2f            18   /
21640 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
21650 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
21660 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
21670 49 54 45 5f 50 52 41 47 4d 41 20 20 20 20 20 20  ITE_PRAGMA      
21680 20 20 20 20 20 20 20 20 20 31 39 20 20 20 2f 2a           19   /*
21690 20 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 20 20   Pragma Name    
216a0 20 31 73 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c   1st arg or NULL
216b0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
216c0 54 45 5f 52 45 41 44 20 20 20 20 20 20 20 20 20  TE_READ         
216d0 20 20 20 20 20 20 20 20 32 30 20 20 20 2f 2a 20          20   /* 
216e0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
216f0 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20  Column Name     
21700 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
21710 45 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20  E_SELECT        
21720 20 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4e         21   /* N
21730 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e  ULL            N
21740 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
21750 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
21760 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 20 20  _TRANSACTION    
21770 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 4f 70        22   /* Op
21780 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 4e 55  eration       NU
21790 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
217a0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
217b0 55 50 44 41 54 45 20 20 20 20 20 20 20 20 20 20  UPDATE          
217c0 20 20 20 20 20 32 33 20 20 20 2f 2a 20 54 61 62       23   /* Tab
217d0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c  le Name      Col
217e0 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a  umn Name     */.
217f0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
21800 54 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20  TTACH           
21810 20 20 20 20 32 34 20 20 20 2f 2a 20 46 69 6c 65      24   /* File
21820 6e 61 6d 65 20 20 20 20 20 20 20 20 4e 55 4c 4c  name        NULL
21830 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
21840 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45  define SQLITE_DE
21850 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20  TACH            
21860 20 20 20 32 35 20 20 20 2f 2a 20 44 61 74 61 62     25   /* Datab
21870 61 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20  ase Name   NULL 
21880 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
21890 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54  efine SQLITE_ALT
218a0 45 52 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20  ER_TABLE        
218b0 20 20 32 36 20 20 20 2f 2a 20 44 61 74 61 62 61    26   /* Databa
218c0 73 65 20 4e 61 6d 65 20 20 20 54 61 62 6c 65 20  se Name   Table 
218d0 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
218e0 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 49 4e  fine SQLITE_REIN
218f0 44 45 58 20 20 20 20 20 20 20 20 20 20 20 20 20  DEX             
21900 20 32 37 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e   27   /* Index N
21910 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
21920 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
21930 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59  ine SQLITE_ANALY
21940 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ZE              
21950 32 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  28   /* Table Na
21960 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
21970 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
21980 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
21990 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 32  _VTABLE        2
219a0 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  9   /* Table Nam
219b0 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61  e      Module Na
219c0 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
219d0 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54  e SQLITE_DROP_VT
219e0 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 33 30  ABLE          30
219f0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
21a00 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d        Module Nam
21a10 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
21a20 20 53 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e   SQLITE_FUNCTION
21a30 20 20 20 20 20 20 20 20 20 20 20 20 20 33 31 20               31 
21a40 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20    /* NULL       
21a50 20 20 20 20 20 46 75 6e 63 74 69 6f 6e 20 4e 61       Function Na
21a60 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20  me   */.#define 
21a70 53 51 4c 49 54 45 5f 53 41 56 45 50 4f 49 4e 54  SQLITE_SAVEPOINT
21a80 20 20 20 20 20 20 20 20 20 20 20 20 33 32 20 20              32  
21a90 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20   /* Operation   
21aa0 20 20 20 20 53 61 76 65 70 6f 69 6e 74 20 4e 61      Savepoint Na
21ab0 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  me  */.#define S
21ac0 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 20 20 20  QLITE_COPY      
21ad0 20 20 20 20 20 20 20 20 20 20 20 20 30 20 20 20              0   
21ae0 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65  /* No longer use
21af0 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
21b00 49 54 45 5f 52 45 43 55 52 53 49 56 45 20 20 20  ITE_RECURSIVE   
21b10 20 20 20 20 20 20 20 20 20 33 33 20 20 20 2f 2a           33   /*
21b20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
21b30 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
21b40 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
21b50 52 45 46 3a 20 54 72 61 63 69 6e 67 20 41 6e 64  REF: Tracing And
21b60 20 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74   Profiling Funct
21b70 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ions.**.** These
21b80 20 72 6f 75 74 69 6e 65 73 20 72 65 67 69 73 74   routines regist
21b90 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  er callback func
21ba0 74 69 6f 6e 73 20 74 68 61 74 20 63 61 6e 20 62  tions that can b
21bb0 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72  e used for.** tr
21bc0 61 63 69 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c  acing and profil
21bd0 69 6e 67 20 74 68 65 20 65 78 65 63 75 74 69 6f  ing the executio
21be0 6e 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65  n of SQL stateme
21bf0 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  nts..**.** ^The 
21c00 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
21c10 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20  n registered by 
21c20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20  sqlite3_trace() 
21c30 69 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a  is invoked at.**
21c40 20 76 61 72 69 6f 75 73 20 74 69 6d 65 73 20 77   various times w
21c50 68 65 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65  hen an SQL state
21c60 6d 65 6e 74 20 69 73 20 62 65 69 6e 67 20 72 75  ment is being ru
21c70 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 74  n by [sqlite3_st
21c80 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73  ep()]..** ^The s
21c90 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 63  qlite3_trace() c
21ca0 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
21cb0 65 64 20 77 69 74 68 20 61 20 55 54 46 2d 38 20  ed with a UTF-8 
21cc0 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65  rendering of the
21cd0 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
21ce0 74 20 74 65 78 74 20 61 73 20 74 68 65 20 73 74  t text as the st
21cf0 61 74 65 6d 65 6e 74 20 66 69 72 73 74 20 62 65  atement first be
21d00 67 69 6e 73 20 65 78 65 63 75 74 69 6e 67 2e 0a  gins executing..
21d10 2a 2a 20 5e 28 41 64 64 69 74 69 6f 6e 61 6c 20  ** ^(Additional 
21d20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20  sqlite3_trace() 
21d30 63 61 6c 6c 62 61 63 6b 73 20 6d 69 67 68 74 20  callbacks might 
21d40 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65 61 63 68  occur.** as each
21d50 20 74 72 69 67 67 65 72 65 64 20 73 75 62 70 72   triggered subpr
21d60 6f 67 72 61 6d 20 69 73 20 65 6e 74 65 72 65 64  ogram is entered
21d70 2e 20 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 73  .  The callbacks
21d80 20 66 6f 72 20 74 72 69 67 67 65 72 73 0a 2a 2a   for triggers.**
21d90 20 63 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d 38   contain a UTF-8
21da0 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61   SQL comment tha
21db0 74 20 69 64 65 6e 74 69 66 69 65 73 20 74 68 65  t identifies the
21dc0 20 74 72 69 67 67 65 72 2e 29 5e 0a 2a 2a 0a 2a   trigger.)^.**.*
21dd0 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 54 52  * The [SQLITE_TR
21de0 41 43 45 5f 53 49 5a 45 5f 4c 49 4d 49 54 5d 20  ACE_SIZE_LIMIT] 
21df0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
21e00 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20  ion can be used 
21e10 74 6f 20 6c 69 6d 69 74 0a 2a 2a 20 74 68 65 20  to limit.** the 
21e20 6c 65 6e 67 74 68 20 6f 66 20 5b 62 6f 75 6e 64  length of [bound
21e30 20 70 61 72 61 6d 65 74 65 72 5d 20 65 78 70 61   parameter] expa
21e40 6e 73 69 6f 6e 20 69 6e 20 74 68 65 20 6f 75 74  nsion in the out
21e50 70 75 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 74  put of sqlite3_t
21e60 72 61 63 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54  race()..**.** ^T
21e70 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  he callback func
21e80 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20  tion registered 
21e90 62 79 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69  by sqlite3_profi
21ea0 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a  le() is invoked.
21eb0 2a 2a 20 61 73 20 65 61 63 68 20 53 51 4c 20 73  ** as each SQL s
21ec0 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65  tatement finishe
21ed0 73 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65  s.  ^The profile
21ee0 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69   callback contai
21ef0 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e  ns.** the origin
21f00 61 6c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78  al statement tex
21f10 74 20 61 6e 64 20 61 6e 20 65 73 74 69 6d 61 74  t and an estimat
21f20 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20  e of wall-clock 
21f30 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c  time.** of how l
21f40 6f 6e 67 20 74 68 61 74 20 73 74 61 74 65 6d 65  ong that stateme
21f50 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 20  nt took to run. 
21f60 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61   ^The profile ca
21f70 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d 65 20 69  llback.** time i
21f80 73 20 69 6e 20 75 6e 69 74 73 20 6f 66 20 6e 61  s in units of na
21f90 6e 6f 73 65 63 6f 6e 64 73 2c 20 68 6f 77 65 76  noseconds, howev
21fa0 65 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 69  er the current i
21fb0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a  mplementation.**
21fc0 20 69 73 20 6f 6e 6c 79 20 63 61 70 61 62 6c 65   is only capable
21fd0 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20   of millisecond 
21fe0 72 65 73 6f 6c 75 74 69 6f 6e 20 73 6f 20 74 68  resolution so th
21ff0 65 20 73 69 78 20 6c 65 61 73 74 20 73 69 67 6e  e six least sign
22000 69 66 69 63 61 6e 74 0a 2a 2a 20 64 69 67 69 74  ificant.** digit
22010 73 20 69 6e 20 74 68 65 20 74 69 6d 65 20 61 72  s in the time ar
22020 65 20 6d 65 61 6e 69 6e 67 6c 65 73 73 2e 20 20  e meaningless.  
22030 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  Future versions 
22040 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 69 67  of SQLite.** mig
22050 68 74 20 70 72 6f 76 69 64 65 20 67 72 65 61 74  ht provide great
22060 65 72 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6f 6e  er resolution on
22070 20 74 68 65 20 70 72 6f 66 69 6c 65 72 20 63 61   the profiler ca
22080 6c 6c 62 61 63 6b 2e 20 20 54 68 65 0a 2a 2a 20  llback.  The.** 
22090 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28  sqlite3_profile(
220a0 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 6f  ) function is co
220b0 6e 73 69 64 65 72 65 64 20 65 78 70 65 72 69 6d  nsidered experim
220c0 65 6e 74 61 6c 20 61 6e 64 20 69 73 0a 2a 2a 20  ental and is.** 
220d0 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67  subject to chang
220e0 65 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 73  e in future vers
220f0 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ions of SQLite..
22100 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  */.SQLITE_API vo
22110 69 64 20 2a 73 71 6c 69 74 65 33 5f 74 72 61 63  id *sqlite3_trac
22120 65 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64  e(sqlite3*, void
22130 28 2a 78 54 72 61 63 65 29 28 76 6f 69 64 2a 2c  (*xTrace)(void*,
22140 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 76 6f  const char*), vo
22150 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  id*);.SQLITE_API
22160 20 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45   SQLITE_EXPERIME
22170 4e 54 41 4c 20 76 6f 69 64 20 2a 73 71 6c 69 74  NTAL void *sqlit
22180 65 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69 74  e3_profile(sqlit
22190 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50  e3*,.   void(*xP
221a0 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f  rofile)(void*,co
221b0 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74 65  nst char*,sqlite
221c0 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a  3_uint64), void*
221d0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
221e0 45 46 3a 20 51 75 65 72 79 20 50 72 6f 67 72 65  EF: Query Progre
221f0 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a  ss Callbacks.**.
22200 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
22210 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72  progress_handler
22220 28 44 2c 4e 2c 58 2c 50 29 20 69 6e 74 65 72 66  (D,N,X,P) interf
22230 61 63 65 20 63 61 75 73 65 73 20 74 68 65 20 63  ace causes the c
22240 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74  allback.** funct
22250 69 6f 6e 20 58 20 74 6f 20 62 65 20 69 6e 76 6f  ion X to be invo
22260 6b 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c 79  ked periodically
22270 20 64 75 72 69 6e 67 20 6c 6f 6e 67 20 72 75 6e   during long run
22280 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  ning calls to.**
22290 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
222a0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ], [sqlite3_step
222b0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
222c0 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 66 6f  _get_table()] fo
222d0 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  r.** database co
222e0 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 20 41 6e 20  nnection D.  An 
222f0 65 78 61 6d 70 6c 65 20 75 73 65 20 66 6f 72 20  example use for 
22300 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63  this.** interfac
22310 65 20 69 73 20 74 6f 20 6b 65 65 70 20 61 20 47  e is to keep a G
22320 55 49 20 75 70 64 61 74 65 64 20 64 75 72 69 6e  UI updated durin
22330 67 20 61 20 6c 61 72 67 65 20 71 75 65 72 79 2e  g a large query.
22340 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 61 72 61  .**.** ^The para
22350 6d 65 74 65 72 20 50 20 69 73 20 70 61 73 73 65  meter P is passe
22360 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65  d through as the
22370 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20   only parameter 
22380 74 6f 20 74 68 65 20 0a 2a 2a 20 63 61 6c 6c 62  to the .** callb
22390 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 2e 20  ack function X. 
223a0 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 20   ^The parameter 
223b0 4e 20 69 73 20 74 68 65 20 61 70 70 72 6f 78 69  N is the approxi
223c0 6d 61 74 65 20 6e 75 6d 62 65 72 20 6f 66 20 0a  mate number of .
223d0 2a 2a 20 5b 76 69 72 74 75 61 6c 20 6d 61 63 68  ** [virtual mach
223e0 69 6e 65 20 69 6e 73 74 72 75 63 74 69 6f 6e 73  ine instructions
223f0 5d 20 74 68 61 74 20 61 72 65 20 65 76 61 6c 75  ] that are evalu
22400 61 74 65 64 20 62 65 74 77 65 65 6e 20 73 75 63  ated between suc
22410 63 65 73 73 69 76 65 0a 2a 2a 20 69 6e 76 6f 63  cessive.** invoc
22420 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 63 61  ations of the ca
22430 6c 6c 62 61 63 6b 20 58 2e 20 20 5e 49 66 20 4e  llback X.  ^If N
22440 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 6f 6e   is less than on
22450 65 20 74 68 65 6e 20 74 68 65 20 70 72 6f 67 72  e then the progr
22460 65 73 73 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 69  ess.** handler i
22470 73 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a  s disabled..**.*
22480 2a 20 5e 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65  * ^Only a single
22490 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
224a0 72 20 6d 61 79 20 62 65 20 64 65 66 69 6e 65 64  r may be defined
224b0 20 61 74 20 6f 6e 65 20 74 69 6d 65 20 70 65 72   at one time per
224c0 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
224d0 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73 65 74 74 69  nnection]; setti
224e0 6e 67 20 61 20 6e 65 77 20 70 72 6f 67 72 65 73  ng a new progres
224f0 73 20 68 61 6e 64 6c 65 72 20 63 61 6e 63 65 6c  s handler cancel
22500 73 20 74 68 65 0a 2a 2a 20 6f 6c 64 20 6f 6e 65  s the.** old one
22510 2e 20 20 5e 53 65 74 74 69 6e 67 20 70 61 72 61  .  ^Setting para
22520 6d 65 74 65 72 20 58 20 74 6f 20 4e 55 4c 4c 20  meter X to NULL 
22530 64 69 73 61 62 6c 65 73 20 74 68 65 20 70 72 6f  disables the pro
22540 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a  gress handler..*
22550 2a 20 5e 54 68 65 20 70 72 6f 67 72 65 73 73 20  * ^The progress 
22560 68 61 6e 64 6c 65 72 20 69 73 20 61 6c 73 6f 20  handler is also 
22570 64 69 73 61 62 6c 65 64 20 62 79 20 73 65 74 74  disabled by sett
22580 69 6e 67 20 4e 20 74 6f 20 61 20 76 61 6c 75 65  ing N to a value
22590 20 6c 65 73 73 0a 2a 2a 20 74 68 61 6e 20 31 2e   less.** than 1.
225a0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70  .**.** ^If the p
225b0 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b  rogress callback
225c0 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
225d0 6f 2c 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e  o, the operation
225e0 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74   is.** interrupt
225f0 65 64 2e 20 20 54 68 69 73 20 66 65 61 74 75 72  ed.  This featur
22600 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  e can be used to
22610 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20   implement a.** 
22620 22 43 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20  "Cancel" button 
22630 6f 6e 20 61 20 47 55 49 20 70 72 6f 67 72 65 73  on a GUI progres
22640 73 20 64 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a  s dialog box..**
22650 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72 65 73 73  .** The progress
22660 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63   handler callbac
22670 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e  k must not do an
22680 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c  ything that will
22690 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64   modify.** the d
226a0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
226b0 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  on that invoked 
226c0 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  the progress han
226d0 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68  dler..** Note th
226e0 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  at [sqlite3_prep
226f0 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73  are_v2()] and [s
22700 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62  qlite3_step()] b
22710 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72  oth modify their
22720 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
22730 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65  nections for the
22740 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64   meaning of "mod
22750 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72  ify" in this par
22760 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 53 51  agraph..**.*/.SQ
22770 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71  LITE_API void sq
22780 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68  lite3_progress_h
22790 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c  andler(sqlite3*,
227a0 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69   int, int(*)(voi
227b0 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  d*), void*);../*
227c0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70  .** CAPI3REF: Op
227d0 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74 61  ening A New Data
227e0 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a  base Connection.
227f0 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
22800 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53 51  tines open an SQ
22810 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 66 69  Lite database fi
22820 6c 65 20 61 73 20 73 70 65 63 69 66 69 65 64 20  le as specified 
22830 62 79 20 74 68 65 20 0a 2a 2a 20 66 69 6c 65 6e  by the .** filen
22840 61 6d 65 20 61 72 67 75 6d 65 6e 74 2e 20 5e 54  ame argument. ^T
22850 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75  he filename argu
22860 6d 65 6e 74 20 69 73 20 69 6e 74 65 72 70 72 65  ment is interpre
22870 74 65 64 20 61 73 20 55 54 46 2d 38 20 66 6f 72  ted as UTF-8 for
22880 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  .** sqlite3_open
22890 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f  () and sqlite3_o
228a0 70 65 6e 5f 76 32 28 29 20 61 6e 64 20 61 73 20  pen_v2() and as 
228b0 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61  UTF-16 in the na
228c0 74 69 76 65 20 62 79 74 65 0a 2a 2a 20 6f 72 64  tive byte.** ord
228d0 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  er for sqlite3_o
228e0 70 65 6e 31 36 28 29 2e 20 5e 28 41 20 5b 64 61  pen16(). ^(A [da
228f0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
22900 6e 5d 20 68 61 6e 64 6c 65 20 69 73 20 75 73 75  n] handle is usu
22910 61 6c 6c 79 0a 2a 2a 20 72 65 74 75 72 6e 65 64  ally.** returned
22920 20 69 6e 20 2a 70 70 44 62 2c 20 65 76 65 6e 20   in *ppDb, even 
22930 69 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75  if an error occu
22940 72 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 65 78  rs.  The only ex
22950 63 65 70 74 69 6f 6e 20 69 73 20 74 68 61 74 0a  ception is that.
22960 2a 2a 20 69 66 20 53 51 4c 69 74 65 20 69 73 20  ** if SQLite is 
22970 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61  unable to alloca
22980 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c  te memory to hol
22990 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20  d the [sqlite3] 
229a0 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c  object,.** a NUL
229b0 4c 20 77 69 6c 6c 20 62 65 20 77 72 69 74 74 65  L will be writte
229c0 6e 20 69 6e 74 6f 20 2a 70 70 44 62 20 69 6e 73  n into *ppDb ins
229d0 74 65 61 64 20 6f 66 20 61 20 70 6f 69 6e 74 65  tead of a pointe
229e0 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  r to the [sqlite
229f0 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e 29 5e 20  3].** object.)^ 
22a00 5e 28 49 66 20 74 68 65 20 64 61 74 61 62 61 73  ^(If the databas
22a10 65 20 69 73 20 6f 70 65 6e 65 64 20 28 61 6e 64  e is opened (and
22a20 2f 6f 72 20 63 72 65 61 74 65 64 29 20 73 75 63  /or created) suc
22a30 63 65 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e 0a  cessfully, then.
22a40 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69  ** [SQLITE_OK] i
22a50 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68  s returned.  Oth
22a60 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72  erwise an [error
22a70 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e   code] is return
22a80 65 64 2e 29 5e 20 5e 54 68 65 0a 2a 2a 20 5b 73  ed.)^ ^The.** [s
22a90 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
22aa0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72   or [sqlite3_err
22ab0 6d 73 67 31 36 28 29 5d 20 72 6f 75 74 69 6e 65  msg16()] routine
22ac0 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  s can be used to
22ad0 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e   obtain.** an En
22ae0 67 6c 69 73 68 20 6c 61 6e 67 75 61 67 65 20 64  glish language d
22af0 65 73 63 72 69 70 74 69 6f 6e 20 6f 66 20 74 68  escription of th
22b00 65 20 65 72 72 6f 72 20 66 6f 6c 6c 6f 77 69 6e  e error followin
22b10 67 20 61 20 66 61 69 6c 75 72 65 20 6f 66 20 61  g a failure of a
22b20 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c  ny.** of the sql
22b30 69 74 65 33 5f 6f 70 65 6e 28 29 20 72 6f 75 74  ite3_open() rout
22b40 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ines..**.** ^The
22b50 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e   default encodin
22b60 67 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 38 20  g will be UTF-8 
22b70 66 6f 72 20 64 61 74 61 62 61 73 65 73 20 63 72  for databases cr
22b80 65 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20 73  eated using.** s
22b90 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72  qlite3_open() or
22ba0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
22bb0 28 29 2e 20 20 5e 54 68 65 20 64 65 66 61 75 6c  ().  ^The defaul
22bc0 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 64  t encoding for d
22bd0 61 74 61 62 61 73 65 73 0a 2a 2a 20 63 72 65 61  atabases.** crea
22be0 74 65 64 20 75 73 69 6e 67 20 73 71 6c 69 74 65  ted using sqlite
22bf0 33 5f 6f 70 65 6e 31 36 28 29 20 77 69 6c 6c 20  3_open16() will 
22c00 62 65 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65  be UTF-16 in the
22c10 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
22c20 65 72 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65  er..**.** Whethe
22c30 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f  r or not an erro
22c40 72 20 6f 63 63 75 72 73 20 77 68 65 6e 20 69 74  r occurs when it
22c50 20 69 73 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f   is opened, reso
22c60 75 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61  urces.** associa
22c70 74 65 64 20 77 69 74 68 20 74 68 65 20 5b 64 61  ted with the [da
22c80 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
22c90 6e 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64  n] handle should
22ca0 20 62 65 20 72 65 6c 65 61 73 65 64 20 62 79 0a   be released by.
22cb0 2a 2a 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f  ** passing it to
22cc0 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28   [sqlite3_close(
22cd0 29 5d 20 77 68 65 6e 20 69 74 20 69 73 20 6e 6f  )] when it is no
22ce0 20 6c 6f 6e 67 65 72 20 72 65 71 75 69 72 65 64   longer required
22cf0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
22d00 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e  te3_open_v2() in
22d10 74 65 72 66 61 63 65 20 77 6f 72 6b 73 20 6c 69  terface works li
22d20 6b 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ke sqlite3_open(
22d30 29 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74  ).** except that
22d40 20 69 74 20 61 63 63 65 70 74 73 20 74 77 6f 20   it accepts two 
22d50 61 64 64 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d  additional param
22d60 65 74 65 72 73 20 66 6f 72 20 61 64 64 69 74 69  eters for additi
22d70 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20  onal control.** 
22d80 6f 76 65 72 20 74 68 65 20 6e 65 77 20 64 61 74  over the new dat
22d90 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
22da0 2e 20 20 5e 28 54 68 65 20 66 6c 61 67 73 20 70  .  ^(The flags p
22db0 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 73  arameter to.** s
22dc0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
22dd0 20 63 61 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66   can take one of
22de0 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e  .** the followin
22df0 67 20 74 68 72 65 65 20 76 61 6c 75 65 73 2c 20  g three values, 
22e00 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69  optionally combi
22e10 6e 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a  ned with the .**
22e20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f   [SQLITE_OPEN_NO
22e30 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f  MUTEX], [SQLITE_
22e40 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c  OPEN_FULLMUTEX],
22e50 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48   [SQLITE_OPEN_SH
22e60 41 52 45 44 43 41 43 48 45 5d 2c 0a 2a 2a 20 5b  AREDCACHE],.** [
22e70 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56  SQLITE_OPEN_PRIV
22e80 41 54 45 43 41 43 48 45 5d 2c 20 61 6e 64 2f 6f  ATECACHE], and/o
22e90 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55  r [SQLITE_OPEN_U
22ea0 52 49 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a  RI] flags:)^.**.
22eb0 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74  ** <dl>.** ^(<dt
22ec0 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45  >[SQLITE_OPEN_RE
22ed0 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20  ADONLY]</dt>.** 
22ee0 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65  <dd>The database
22ef0 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 72 65   is opened in re
22f00 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49  ad-only mode.  I
22f10 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 64  f the database d
22f20 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61  oes not.** alrea
22f30 64 79 20 65 78 69 73 74 2c 20 61 6e 20 65 72 72  dy exist, an err
22f40 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c  or is returned.<
22f50 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c  /dd>)^.**.** ^(<
22f60 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  dt>[SQLITE_OPEN_
22f70 52 45 41 44 57 52 49 54 45 5d 3c 2f 64 74 3e 0a  READWRITE]</dt>.
22f80 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62  ** <dd>The datab
22f90 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f  ase is opened fo
22fa0 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72  r reading and wr
22fb0 69 74 69 6e 67 20 69 66 20 70 6f 73 73 69 62 6c  iting if possibl
22fc0 65 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a 2a 2a  e, or reading.**
22fd0 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 66 69 6c   only if the fil
22fe0 65 20 69 73 20 77 72 69 74 65 20 70 72 6f 74 65  e is write prote
22ff0 63 74 65 64 20 62 79 20 74 68 65 20 6f 70 65 72  cted by the oper
23000 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 49  ating system.  I
23010 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63 61 73 65  n either.** case
23020 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6d 75   the database mu
23030 73 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74  st already exist
23040 2c 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 65  , otherwise an e
23050 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64  rror is returned
23060 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  .</dd>)^.**.** ^
23070 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45  (<dt>[SQLITE_OPE
23080 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b  N_READWRITE] | [
23090 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
230a0 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TE]</dt>.** <dd>
230b0 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  The database is 
230c0 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69  opened for readi
230d0 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 2c 20  ng and writing, 
230e0 61 6e 64 20 69 73 20 63 72 65 61 74 65 64 20 69  and is created i
230f0 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74  f.** it does not
23100 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2e 20   already exist. 
23110 54 68 69 73 20 69 73 20 74 68 65 20 62 65 68 61  This is the beha
23120 76 69 6f 72 20 74 68 61 74 20 69 73 20 61 6c 77  vior that is alw
23130 61 79 73 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20  ays used for.** 
23140 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61  sqlite3_open() a
23150 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  nd sqlite3_open1
23160 36 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c  6().</dd>)^.** <
23170 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  /dl>.**.** If th
23180 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  e 3rd parameter 
23190 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
231a0 76 32 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20  v2() is not one 
231b0 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e  of the.** combin
231c0 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f  ations shown abo
231d0 76 65 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f  ve optionally co
231e0 6d 62 69 6e 65 64 20 77 69 74 68 20 6f 74 68 65  mbined with othe
231f0 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45  r.** [SQLITE_OPE
23200 4e 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 53 51 4c  N_READONLY | SQL
23210 49 54 45 5f 4f 50 45 4e 5f 2a 20 62 69 74 73 5d  ITE_OPEN_* bits]
23220 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68  .** then the beh
23230 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e  avior is undefin
23240 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ed..**.** ^If th
23250 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e  e [SQLITE_OPEN_N
23260 4f 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20  OMUTEX] flag is 
23270 73 65 74 2c 20 74 68 65 6e 20 74 68 65 20 64 61  set, then the da
23280 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
23290 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68  n.** opens in th
232a0 65 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b  e multi-thread [
232b0 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
232c0 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 73  as long as the s
232d0 69 6e 67 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20  ingle-thread.** 
232e0 6d 6f 64 65 20 68 61 73 20 6e 6f 74 20 62 65 65  mode has not bee
232f0 6e 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65  n set at compile
23300 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74  -time or start-t
23310 69 6d 65 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a  ime.  ^If the.**
23320 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55   [SQLITE_OPEN_FU
23330 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73  LLMUTEX] flag is
23340 20 73 65 74 20 74 68 65 6e 20 74 68 65 20 64 61   set then the da
23350 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
23360 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68  n opens.** in th
23370 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68  e serialized [th
23380 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e  reading mode] un
23390 6c 65 73 73 20 73 69 6e 67 6c 65 2d 74 68 72 65  less single-thre
233a0 61 64 20 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f  ad was.** previo
233b0 75 73 6c 79 20 73 65 6c 65 63 74 65 64 20 61 74  usly selected at
233c0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72   compile-time or
233d0 20 73 74 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20   start-time..** 
233e0 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  ^The [SQLITE_OPE
233f0 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d 20 66  N_SHAREDCACHE] f
23400 6c 61 67 20 63 61 75 73 65 73 20 74 68 65 20 64  lag causes the d
23410 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
23420 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 65 6c 69 67  on to be.** elig
23430 69 62 6c 65 20 74 6f 20 75 73 65 20 5b 73 68 61  ible to use [sha
23440 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c  red cache mode],
23450 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77   regardless of w
23460 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68  hether or not sh
23470 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 69 73  ared.** cache is
23480 20 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 20 5b   enabled using [
23490 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73  sqlite3_enable_s
234a0 68 61 72 65 64 5f 63 61 63 68 65 28 29 5d 2e 20  hared_cache()]. 
234b0 20 5e 54 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45   ^The.** [SQLITE
234c0 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43  _OPEN_PRIVATECAC
234d0 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20  HE] flag causes 
234e0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
234f0 6e 65 63 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a  nection to not.*
23500 2a 20 70 61 72 74 69 63 69 70 61 74 65 20 69 6e  * participate in
23510 20 5b 73 68 61 72 65 64 20 63 61 63 68 65 20 6d   [shared cache m
23520 6f 64 65 5d 20 65 76 65 6e 20 69 66 20 69 74 20  ode] even if it 
23530 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a  is enabled..**.*
23540 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61  * ^The fourth pa
23550 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
23560 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20  e3_open_v2() is 
23570 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a  the name of the.
23580 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  ** [sqlite3_vfs]
23590 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66   object that def
235a0 69 6e 65 73 20 74 68 65 20 6f 70 65 72 61 74 69  ines the operati
235b0 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66  ng system interf
235c0 61 63 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ace that.** the 
235d0 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e  new database con
235e0 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75  nection should u
235f0 73 65 2e 20 20 5e 49 66 20 74 68 65 20 66 6f 75  se.  ^If the fou
23600 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  rth parameter is
23610 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  .** a NULL point
23620 65 72 20 74 68 65 6e 20 74 68 65 20 64 65 66 61  er then the defa
23630 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  ult [sqlite3_vfs
23640 5d 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64  ] object is used
23650 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
23660 66 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65  filename is ":me
23670 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 20 70  mory:", then a p
23680 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72  rivate, temporar
23690 79 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61  y in-memory data
236a0 62 61 73 65 0a 2a 2a 20 69 73 20 63 72 65 61 74  base.** is creat
236b0 65 64 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65  ed for the conne
236c0 63 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 69 6e  ction.  ^This in
236d0 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65  -memory database
236e0 20 77 69 6c 6c 20 76 61 6e 69 73 68 20 77 68 65   will vanish whe
236f0 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  n.** the databas
23700 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
23710 63 6c 6f 73 65 64 2e 20 20 46 75 74 75 72 65 20  closed.  Future 
23720 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
23730 74 65 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65  te might.** make
23740 20 75 73 65 20 6f 66 20 61 64 64 69 74 69 6f 6e   use of addition
23750 61 6c 20 73 70 65 63 69 61 6c 20 66 69 6c 65 6e  al special filen
23760 61 6d 65 73 20 74 68 61 74 20 62 65 67 69 6e 20  ames that begin 
23770 77 69 74 68 20 74 68 65 20 22 3a 22 20 63 68 61  with the ":" cha
23780 72 61 63 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73  racter..** It is
23790 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61   recommended tha
237a0 74 20 77 68 65 6e 20 61 20 64 61 74 61 62 61 73  t when a databas
237b0 65 20 66 69 6c 65 6e 61 6d 65 20 61 63 74 75 61  e filename actua
237c0 6c 6c 79 20 64 6f 65 73 20 62 65 67 69 6e 20 77  lly does begin w
237d0 69 74 68 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61  ith.** a ":" cha
237e0 72 61 63 74 65 72 20 79 6f 75 20 73 68 6f 75 6c  racter you shoul
237f0 64 20 70 72 65 66 69 78 20 74 68 65 20 66 69 6c  d prefix the fil
23800 65 6e 61 6d 65 20 77 69 74 68 20 61 20 70 61 74  ename with a pat
23810 68 6e 61 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a  hname such as.**
23820 20 22 2e 2f 22 20 74 6f 20 61 76 6f 69 64 20 61   "./" to avoid a
23830 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20  mbiguity..**.** 
23840 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  ^If the filename
23850 20 69 73 20 61 6e 20 65 6d 70 74 79 20 73 74 72   is an empty str
23860 69 6e 67 2c 20 74 68 65 6e 20 61 20 70 72 69 76  ing, then a priv
23870 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a  ate, temporary.*
23880 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62 61  * on-disk databa
23890 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65 61 74  se will be creat
238a0 65 64 2e 20 20 5e 54 68 69 73 20 70 72 69 76 61  ed.  ^This priva
238b0 74 65 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c  te database will
238c0 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63   be.** automatic
238d0 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 61 73 20  ally deleted as 
238e0 73 6f 6f 6e 20 61 73 20 74 68 65 20 64 61 74 61  soon as the data
238f0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
23900 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a  is closed..**.**
23910 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73   [[URI filenames
23920 20 69 6e 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   in sqlite3_open
23930 28 29 5d 5d 20 3c 68 33 3e 55 52 49 20 46 69 6c  ()]] <h3>URI Fil
23940 65 6e 61 6d 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a  enames</h3>.**.*
23950 2a 20 5e 49 66 20 5b 55 52 49 20 66 69 6c 65 6e  * ^If [URI filen
23960 61 6d 65 5d 20 69 6e 74 65 72 70 72 65 74 61 74  ame] interpretat
23970 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2c 20  ion is enabled, 
23980 61 6e 64 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  and the filename
23990 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 62 65 67   argument.** beg
239a0 69 6e 73 20 77 69 74 68 20 22 66 69 6c 65 3a 22  ins with "file:"
239b0 2c 20 74 68 65 6e 20 74 68 65 20 66 69 6c 65 6e  , then the filen
239c0 61 6d 65 20 69 73 20 69 6e 74 65 72 70 72 65 74  ame is interpret
239d0 65 64 20 61 73 20 61 20 55 52 49 2e 20 5e 55 52  ed as a URI. ^UR
239e0 49 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 6e  I.** filename in
239f0 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20  terpretation is 
23a00 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65 20 5b  enabled if the [
23a10 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d  SQLITE_OPEN_URI]
23a20 20 66 6c 61 67 20 69 73 0a 2a 2a 20 73 65 74 20   flag is.** set 
23a30 69 6e 20 74 68 65 20 66 6f 75 72 74 68 20 61 72  in the fourth ar
23a40 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
23a50 33 5f 6f 70 65 6e 5f 76 32 28 29 2c 20 6f 72 20  3_open_v2(), or 
23a60 69 66 20 69 74 20 68 61 73 0a 2a 2a 20 62 65 65  if it has.** bee
23a70 6e 20 65 6e 61 62 6c 65 64 20 67 6c 6f 62 61 6c  n enabled global
23a80 6c 79 20 75 73 69 6e 67 20 74 68 65 20 5b 53 51  ly using the [SQ
23a90 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d  LITE_CONFIG_URI]
23aa0 20 6f 70 74 69 6f 6e 20 77 69 74 68 20 74 68 65   option with the
23ab0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
23ac0 66 69 67 28 29 5d 20 6d 65 74 68 6f 64 20 6f 72  fig()] method or
23ad0 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   by the [SQLITE_
23ae0 55 53 45 5f 55 52 49 5d 20 63 6f 6d 70 69 6c 65  USE_URI] compile
23af0 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a  -time option..**
23b00 20 41 73 20 6f 66 20 53 51 4c 69 74 65 20 76 65   As of SQLite ve
23b10 72 73 69 6f 6e 20 33 2e 37 2e 37 2c 20 55 52 49  rsion 3.7.7, URI
23b20 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70   filename interp
23b30 72 65 74 61 74 69 6f 6e 20 69 73 20 74 75 72 6e  retation is turn
23b40 65 64 20 6f 66 66 0a 2a 2a 20 62 79 20 64 65 66  ed off.** by def
23b50 61 75 6c 74 2c 20 62 75 74 20 66 75 74 75 72 65  ault, but future
23b60 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c   releases of SQL
23b70 69 74 65 20 6d 69 67 68 74 20 65 6e 61 62 6c 65  ite might enable
23b80 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a   URI filename.**
23b90 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20   interpretation 
23ba0 62 79 20 64 65 66 61 75 6c 74 2e 20 20 53 65 65  by default.  See
23bb0 20 22 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73   "[URI filenames
23bc0 5d 22 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  ]" for additiona
23bd0 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  l.** information
23be0 2e 0a 2a 2a 0a 2a 2a 20 55 52 49 20 66 69 6c 65  ..**.** URI file
23bf0 6e 61 6d 65 73 20 61 72 65 20 70 61 72 73 65 64  names are parsed
23c00 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 52 46   according to RF
23c10 43 20 33 39 38 36 2e 20 5e 49 66 20 74 68 65 20  C 3986. ^If the 
23c20 55 52 49 20 63 6f 6e 74 61 69 6e 73 20 61 6e 0a  URI contains an.
23c30 2a 2a 20 61 75 74 68 6f 72 69 74 79 2c 20 74 68  ** authority, th
23c40 65 6e 20 69 74 20 6d 75 73 74 20 62 65 20 65 69  en it must be ei
23c50 74 68 65 72 20 61 6e 20 65 6d 70 74 79 20 73 74  ther an empty st
23c60 72 69 6e 67 20 6f 72 20 74 68 65 20 73 74 72 69  ring or the stri
23c70 6e 67 20 0a 2a 2a 20 22 6c 6f 63 61 6c 68 6f 73  ng .** "localhos
23c80 74 22 2e 20 5e 49 66 20 74 68 65 20 61 75 74 68  t". ^If the auth
23c90 6f 72 69 74 79 20 69 73 20 6e 6f 74 20 61 6e 20  ority is not an 
23ca0 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20  empty string or 
23cb0 22 6c 6f 63 61 6c 68 6f 73 74 22 2c 20 61 6e 20  "localhost", an 
23cc0 0a 2a 2a 20 65 72 72 6f 72 20 69 73 20 72 65 74  .** error is ret
23cd0 75 72 6e 65 64 20 74 6f 20 74 68 65 20 63 61 6c  urned to the cal
23ce0 6c 65 72 2e 20 5e 54 68 65 20 66 72 61 67 6d 65  ler. ^The fragme
23cf0 6e 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20  nt component of 
23d00 61 20 55 52 49 2c 20 69 66 20 0a 2a 2a 20 70 72  a URI, if .** pr
23d10 65 73 65 6e 74 2c 20 69 73 20 69 67 6e 6f 72 65  esent, is ignore
23d20 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65  d..**.** ^SQLite
23d30 20 75 73 65 73 20 74 68 65 20 70 61 74 68 20 63   uses the path c
23d40 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 74 68 65 20  omponent of the 
23d50 55 52 49 20 61 73 20 74 68 65 20 6e 61 6d 65 20  URI as the name 
23d60 6f 66 20 74 68 65 20 64 69 73 6b 20 66 69 6c 65  of the disk file
23d70 0a 2a 2a 20 77 68 69 63 68 20 63 6f 6e 74 61 69  .** which contai
23d80 6e 73 20 74 68 65 20 64 61 74 61 62 61 73 65 2e  ns the database.
23d90 20 5e 49 66 20 74 68 65 20 70 61 74 68 20 62 65   ^If the path be
23da0 67 69 6e 73 20 77 69 74 68 20 61 20 27 2f 27 20  gins with a '/' 
23db0 63 68 61 72 61 63 74 65 72 2c 20 0a 2a 2a 20 74  character, .** t
23dc0 68 65 6e 20 69 74 20 69 73 20 69 6e 74 65 72 70  hen it is interp
23dd0 72 65 74 65 64 20 61 73 20 61 6e 20 61 62 73 6f  reted as an abso
23de0 6c 75 74 65 20 70 61 74 68 2e 20 5e 49 66 20 74  lute path. ^If t
23df0 68 65 20 70 61 74 68 20 64 6f 65 73 20 6e 6f 74  he path does not
23e00 20 62 65 67 69 6e 20 0a 2a 2a 20 77 69 74 68 20   begin .** with 
23e10 61 20 27 2f 27 20 28 6d 65 61 6e 69 6e 67 20 74  a '/' (meaning t
23e20 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 74  hat the authorit
23e30 79 20 73 65 63 74 69 6f 6e 20 69 73 20 6f 6d 69  y section is omi
23e40 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 55 52  tted from the UR
23e50 49 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 70  I).** then the p
23e60 61 74 68 20 69 73 20 69 6e 74 65 72 70 72 65 74  ath is interpret
23e70 65 64 20 61 73 20 61 20 72 65 6c 61 74 69 76 65  ed as a relative
23e80 20 70 61 74 68 2e 20 0a 2a 2a 20 5e 28 4f 6e 20   path. .** ^(On 
23e90 77 69 6e 64 6f 77 73 2c 20 74 68 65 20 66 69 72  windows, the fir
23ea0 73 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20  st component of 
23eb0 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68  an absolute path
23ec0 20 0a 2a 2a 20 69 73 20 61 20 64 72 69 76 65 20   .** is a drive 
23ed0 73 70 65 63 69 66 69 63 61 74 69 6f 6e 20 28 65  specification (e
23ee0 2e 67 2e 20 22 43 3a 22 29 2e 29 5e 0a 2a 2a 0a  .g. "C:").)^.**.
23ef0 2a 2a 20 5b 5b 63 6f 72 65 20 55 52 49 20 71 75  ** [[core URI qu
23f00 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 5d 5d  ery parameters]]
23f10 0a 2a 2a 20 54 68 65 20 71 75 65 72 79 20 63 6f  .** The query co
23f20 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49  mponent of a URI
23f30 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 70 61 72   may contain par
23f40 61 6d 65 74 65 72 73 20 74 68 61 74 20 61 72 65  ameters that are
23f50 20 69 6e 74 65 72 70 72 65 74 65 64 0a 2a 2a 20   interpreted.** 
23f60 65 69 74 68 65 72 20 62 79 20 53 51 4c 69 74 65  either by SQLite
23f70 20 69 74 73 65 6c 66 2c 20 6f 72 20 62 79 20 61   itself, or by a
23f80 20 5b 56 46 53 20 7c 20 63 75 73 74 6f 6d 20 56   [VFS | custom V
23f90 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
23fa0 6e 5d 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 61 6e  n]..** SQLite an
23fb0 64 20 69 74 73 20 62 75 69 6c 74 2d 69 6e 20 5b  d its built-in [
23fc0 56 46 53 65 73 5d 20 69 6e 74 65 72 70 72 65 74  VFSes] interpret
23fd0 20 74 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e   the.** followin
23fe0 67 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  g query paramete
23ff0 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  rs:.**.** <ul>.*
24000 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 76 66 73 3c  *   <li> <b>vfs<
24010 2f 62 3e 3a 20 5e 54 68 65 20 22 76 66 73 22 20  /b>: ^The "vfs" 
24020 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65  parameter may be
24030 20 75 73 65 64 20 74 6f 20 73 70 65 63 69 66 79   used to specify
24040 20 74 68 65 20 6e 61 6d 65 20 6f 66 0a 2a 2a 20   the name of.** 
24050 20 20 20 20 61 20 56 46 53 20 6f 62 6a 65 63 74      a VFS object
24060 20 74 68 61 74 20 70 72 6f 76 69 64 65 73 20 74   that provides t
24070 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  he operating sys
24080 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68  tem interface th
24090 61 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 20 20 20  at should.**    
240a0 20 62 65 20 75 73 65 64 20 74 6f 20 61 63 63 65   be used to acce
240b0 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ss the database 
240c0 66 69 6c 65 20 6f 6e 20 64 69 73 6b 2e 20 5e 49  file on disk. ^I
240d0 66 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73  f this option is
240e0 20 73 65 74 20 74 6f 0a 2a 2a 20 20 20 20 20 61   set to.**     a
240f0 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 74  n empty string t
24100 68 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 6f  he default VFS o
24110 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e 20 5e  bject is used. ^
24120 53 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e  Specifying an un
24130 6b 6e 6f 77 6e 0a 2a 2a 20 20 20 20 20 56 46 53  known.**     VFS
24140 20 69 73 20 61 6e 20 65 72 72 6f 72 2e 20 5e 49   is an error. ^I
24150 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  f sqlite3_open_v
24160 32 28 29 20 69 73 20 75 73 65 64 20 61 6e 64 20  2() is used and 
24170 74 68 65 20 76 66 73 20 6f 70 74 69 6f 6e 20 69  the vfs option i
24180 73 0a 2a 2a 20 20 20 20 20 70 72 65 73 65 6e 74  s.**     present
24190 2c 20 74 68 65 6e 20 74 68 65 20 56 46 53 20 73  , then the VFS s
241a0 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
241b0 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 70 72 65  option takes pre
241c0 63 65 64 65 6e 63 65 20 6f 76 65 72 0a 2a 2a 20  cedence over.** 
241d0 20 20 20 20 74 68 65 20 76 61 6c 75 65 20 70 61      the value pa
241e0 73 73 65 64 20 61 73 20 74 68 65 20 66 6f 75 72  ssed as the four
241f0 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
24200 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
24210 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20  )..**.**   <li> 
24220 3c 62 3e 6d 6f 64 65 3c 2f 62 3e 3a 20 5e 28 54  <b>mode</b>: ^(T
24230 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65  he mode paramete
24240 72 20 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20  r may be set to 
24250 65 69 74 68 65 72 20 22 72 6f 22 2c 20 22 72 77  either "ro", "rw
24260 22 2c 0a 2a 2a 20 20 20 20 20 22 72 77 63 22 2c  ",.**     "rwc",
24270 20 6f 72 20 22 6d 65 6d 6f 72 79 22 2e 20 41 74   or "memory". At
24280 74 65 6d 70 74 69 6e 67 20 74 6f 20 73 65 74 20  tempting to set 
24290 69 74 20 74 6f 20 61 6e 79 20 6f 74 68 65 72 20  it to any other 
242a0 76 61 6c 75 65 20 69 73 0a 2a 2a 20 20 20 20 20  value is.**     
242b0 61 6e 20 65 72 72 6f 72 29 5e 2e 20 0a 2a 2a 20  an error)^. .** 
242c0 20 20 20 20 5e 49 66 20 22 72 6f 22 20 69 73 20      ^If "ro" is 
242d0 73 70 65 63 69 66 69 65 64 2c 20 74 68 65 6e 20  specified, then 
242e0 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  the database is 
242f0 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d  opened for read-
24300 6f 6e 6c 79 20 0a 2a 2a 20 20 20 20 20 61 63 63  only .**     acc
24310 65 73 73 2c 20 6a 75 73 74 20 61 73 20 69 66 20  ess, just as if 
24320 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  the [SQLITE_OPEN
24330 5f 52 45 41 44 4f 4e 4c 59 5d 20 66 6c 61 67 20  _READONLY] flag 
24340 68 61 64 20 62 65 65 6e 20 73 65 74 20 69 6e 20  had been set in 
24350 74 68 65 20 0a 2a 2a 20 20 20 20 20 74 68 69 72  the .**     thir
24360 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  d argument to sq
24370 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
24380 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20 6f 70   ^If the mode op
24390 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 20 0a  tion is set to .
243a0 2a 2a 20 20 20 20 20 22 72 77 22 2c 20 74 68 65  **     "rw", the
243b0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  n the database i
243c0 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61  s opened for rea
243d0 64 2d 77 72 69 74 65 20 28 62 75 74 20 6e 6f 74  d-write (but not
243e0 20 63 72 65 61 74 65 29 20 0a 2a 2a 20 20 20 20   create) .**    
243f0 20 61 63 63 65 73 73 2c 20 61 73 20 69 66 20 53   access, as if S
24400 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
24410 52 49 54 45 20 28 62 75 74 20 6e 6f 74 20 53 51  RITE (but not SQ
24420 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
24430 29 20 68 61 64 20 0a 2a 2a 20 20 20 20 20 62 65  ) had .**     be
24440 65 6e 20 73 65 74 2e 20 5e 56 61 6c 75 65 20 22  en set. ^Value "
24450 72 77 63 22 20 69 73 20 65 71 75 69 76 61 6c 65  rwc" is equivale
24460 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 62 6f  nt to setting bo
24470 74 68 20 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54  th .**     SQLIT
24480 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
24490 20 61 6e 64 20 53 51 4c 49 54 45 5f 4f 50 45 4e   and SQLITE_OPEN
244a0 5f 43 52 45 41 54 45 2e 20 20 5e 49 66 20 74 68  _CREATE.  ^If th
244b0 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73  e mode option is
244c0 0a 2a 2a 20 20 20 20 20 73 65 74 20 74 6f 20 22  .**     set to "
244d0 6d 65 6d 6f 72 79 22 20 74 68 65 6e 20 61 20 70  memory" then a p
244e0 75 72 65 20 5b 69 6e 2d 6d 65 6d 6f 72 79 20 64  ure [in-memory d
244f0 61 74 61 62 61 73 65 5d 20 74 68 61 74 20 6e 65  atabase] that ne
24500 76 65 72 20 72 65 61 64 73 0a 2a 2a 20 20 20 20  ver reads.**    
24510 20 6f 72 20 77 72 69 74 65 73 20 66 72 6f 6d 20   or writes from 
24520 64 69 73 6b 20 69 73 20 75 73 65 64 2e 20 5e 49  disk is used. ^I
24530 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20 74 6f  t is an error to
24540 20 73 70 65 63 69 66 79 20 61 20 76 61 6c 75 65   specify a value
24550 20 66 6f 72 0a 2a 2a 20 20 20 20 20 74 68 65 20   for.**     the 
24560 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72 20 74  mode parameter t
24570 68 61 74 20 69 73 20 6c 65 73 73 20 72 65 73 74  hat is less rest
24580 72 69 63 74 69 76 65 20 74 68 61 6e 20 74 68 61  rictive than tha
24590 74 20 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a  t specified by.*
245a0 2a 20 20 20 20 20 74 68 65 20 66 6c 61 67 73 20  *     the flags 
245b0 70 61 73 73 65 64 20 69 6e 20 74 68 65 20 74 68  passed in the th
245c0 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
245d0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
245e0 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e  ()..**.**   <li>
245f0 20 3c 62 3e 63 61 63 68 65 3c 2f 62 3e 3a 20 5e   <b>cache</b>: ^
24600 54 68 65 20 63 61 63 68 65 20 70 61 72 61 6d 65  The cache parame
24610 74 65 72 20 6d 61 79 20 62 65 20 73 65 74 20 74  ter may be set t
24620 6f 20 65 69 74 68 65 72 20 22 73 68 61 72 65 64  o either "shared
24630 22 20 6f 72 0a 2a 2a 20 20 20 20 20 22 70 72 69  " or.**     "pri
24640 76 61 74 65 22 2e 20 5e 53 65 74 74 69 6e 67 20  vate". ^Setting 
24650 69 74 20 74 6f 20 22 73 68 61 72 65 64 22 20 69  it to "shared" i
24660 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20  s equivalent to 
24670 73 65 74 74 69 6e 67 20 74 68 65 0a 2a 2a 20 20  setting the.**  
24680 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53     SQLITE_OPEN_S
24690 48 41 52 45 44 43 41 43 48 45 20 62 69 74 20 69  HAREDCACHE bit i
246a0 6e 20 74 68 65 20 66 6c 61 67 73 20 61 72 67 75  n the flags argu
246b0 6d 65 6e 74 20 70 61 73 73 65 64 20 74 6f 0a 2a  ment passed to.*
246c0 2a 20 20 20 20 20 73 71 6c 69 74 65 33 5f 6f 70  *     sqlite3_op
246d0 65 6e 5f 76 32 28 29 2e 20 5e 53 65 74 74 69 6e  en_v2(). ^Settin
246e0 67 20 74 68 65 20 63 61 63 68 65 20 70 61 72 61  g the cache para
246f0 6d 65 74 65 72 20 74 6f 20 22 70 72 69 76 61 74  meter to "privat
24700 65 22 20 69 73 20 0a 2a 2a 20 20 20 20 20 65 71  e" is .**     eq
24710 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74  uivalent to sett
24720 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f 4f  ing the SQLITE_O
24730 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45  PEN_PRIVATECACHE
24740 20 62 69 74 2e 0a 2a 2a 20 20 20 20 20 5e 49 66   bit..**     ^If
24750 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
24760 28 29 20 69 73 20 75 73 65 64 20 61 6e 64 20 74  () is used and t
24770 68 65 20 22 63 61 63 68 65 22 20 70 61 72 61 6d  he "cache" param
24780 65 74 65 72 20 69 73 20 70 72 65 73 65 6e 74 20  eter is present 
24790 69 6e 0a 2a 2a 20 20 20 20 20 61 20 55 52 49 20  in.**     a URI 
247a0 66 69 6c 65 6e 61 6d 65 2c 20 69 74 73 20 76 61  filename, its va
247b0 6c 75 65 20 6f 76 65 72 72 69 64 65 73 20 61 6e  lue overrides an
247c0 79 20 62 65 68 61 76 69 6f 72 20 72 65 71 75 65  y behavior reque
247d0 73 74 65 64 20 62 79 20 73 65 74 74 69 6e 67 0a  sted by setting.
247e0 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50  **     SQLITE_OP
247f0 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 20  EN_PRIVATECACHE 
24800 6f 72 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53  or SQLITE_OPEN_S
24810 48 41 52 45 44 43 41 43 48 45 20 66 6c 61 67 2e  HAREDCACHE flag.
24820 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e  .**.**  <li> <b>
24830 70 73 6f 77 3c 2f 62 3e 3a 20 5e 54 68 65 20 70  psow</b>: ^The p
24840 73 6f 77 20 70 61 72 61 6d 65 74 65 72 20 69 6e  sow parameter in
24850 64 69 63 61 74 65 73 20 77 68 65 74 68 65 72 20  dicates whether 
24860 6f 72 20 6e 6f 74 20 74 68 65 0a 2a 2a 20 20 20  or not the.**   
24870 20 20 5b 70 6f 77 65 72 73 61 66 65 20 6f 76 65    [powersafe ove
24880 72 77 72 69 74 65 5d 20 70 72 6f 70 65 72 74 79  rwrite] property
24890 20 64 6f 65 73 20 6f 72 20 64 6f 65 73 20 6e 6f   does or does no
248a0 74 20 61 70 70 6c 79 20 74 6f 20 74 68 65 0a 2a  t apply to the.*
248b0 2a 20 20 20 20 20 73 74 6f 72 61 67 65 20 6d 65  *     storage me
248c0 64 69 61 20 6f 6e 20 77 68 69 63 68 20 74 68 65  dia on which the
248d0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 72   database file r
248e0 65 73 69 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 20 3c  esides..**.**  <
248f0 6c 69 3e 20 3c 62 3e 6e 6f 6c 6f 63 6b 3c 2f 62  li> <b>nolock</b
24900 3e 3a 20 5e 54 68 65 20 6e 6f 6c 6f 63 6b 20 70  >: ^The nolock p
24910 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 62 6f  arameter is a bo
24920 6f 6c 65 61 6e 20 71 75 65 72 79 20 70 61 72 61  olean query para
24930 6d 65 74 65 72 0a 2a 2a 20 20 20 20 20 77 68 69  meter.**     whi
24940 63 68 20 69 66 20 73 65 74 20 64 69 73 61 62 6c  ch if set disabl
24950 65 73 20 66 69 6c 65 20 6c 6f 63 6b 69 6e 67 20  es file locking 
24960 69 6e 20 72 6f 6c 6c 62 61 63 6b 20 6a 6f 75 72  in rollback jour
24970 6e 61 6c 20 6d 6f 64 65 73 2e 20 20 54 68 69 73  nal modes.  This
24980 0a 2a 2a 20 20 20 20 20 69 73 20 75 73 65 66 75  .**     is usefu
24990 6c 20 66 6f 72 20 61 63 63 65 73 73 69 6e 67 20  l for accessing 
249a0 61 20 64 61 74 61 62 61 73 65 20 6f 6e 20 61 20  a database on a 
249b0 66 69 6c 65 73 79 73 74 65 6d 20 74 68 61 74 20  filesystem that 
249c0 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 20 20 20 20  does not.**     
249d0 73 75 70 70 6f 72 74 20 6c 6f 63 6b 69 6e 67 2e  support locking.
249e0 20 20 43 61 75 74 69 6f 6e 3a 20 20 44 61 74 61    Caution:  Data
249f0 62 61 73 65 20 63 6f 72 72 75 70 74 69 6f 6e 20  base corruption 
24a00 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 66 20  might result if 
24a10 74 77 6f 0a 2a 2a 20 20 20 20 20 6f 72 20 6d 6f  two.**     or mo
24a20 72 65 20 70 72 6f 63 65 73 73 65 73 20 77 72 69  re processes wri
24a30 74 65 20 74 6f 20 74 68 65 20 73 61 6d 65 20 64  te to the same d
24a40 61 74 61 62 61 73 65 20 61 6e 64 20 61 6e 79 20  atabase and any 
24a50 6f 6e 65 20 6f 66 20 74 68 6f 73 65 0a 2a 2a 20  one of those.** 
24a60 20 20 20 20 70 72 6f 63 65 73 73 65 73 20 75 73      processes us
24a70 65 73 20 6e 6f 6c 6f 63 6b 3d 31 2e 0a 2a 2a 0a  es nolock=1..**.
24a80 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 69 6d 6d 75  **  <li> <b>immu
24a90 74 61 62 6c 65 3c 2f 62 3e 3a 20 5e 54 68 65 20  table</b>: ^The 
24aa0 69 6d 6d 75 74 61 62 6c 65 20 70 61 72 61 6d 65  immutable parame
24ab0 74 65 72 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e  ter is a boolean
24ac0 20 71 75 65 72 79 0a 2a 2a 20 20 20 20 20 70 61   query.**     pa
24ad0 72 61 6d 65 74 65 72 20 74 68 61 74 20 69 6e 64  rameter that ind
24ae0 69 63 61 74 65 73 20 74 68 61 74 20 74 68 65 20  icates that the 
24af0 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 73  database file is
24b00 20 73 74 6f 72 65 64 20 6f 6e 0a 2a 2a 20 20 20   stored on.**   
24b10 20 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 64 69    read-only medi
24b20 61 2e 20 20 5e 57 68 65 6e 20 69 6d 6d 75 74 61  a.  ^When immuta
24b30 62 6c 65 20 69 73 20 73 65 74 2c 20 53 51 4c 69  ble is set, SQLi
24b40 74 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20  te assumes that 
24b50 74 68 65 0a 2a 2a 20 20 20 20 20 64 61 74 61 62  the.**     datab
24b60 61 73 65 20 66 69 6c 65 20 63 61 6e 6e 6f 74 20  ase file cannot 
24b70 62 65 20 63 68 61 6e 67 65 64 2c 20 65 76 65 6e  be changed, even
24b80 20 62 79 20 61 20 70 72 6f 63 65 73 73 20 77 69   by a process wi
24b90 74 68 20 68 69 67 68 65 72 0a 2a 2a 20 20 20 20  th higher.**    
24ba0 20 70 72 69 76 69 6c 65 67 65 2c 20 61 6e 64 20   privilege, and 
24bb0 73 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20  so the database 
24bc0 69 73 20 6f 70 65 6e 65 64 20 72 65 61 64 2d 6f  is opened read-o
24bd0 6e 6c 79 20 61 6e 64 20 61 6c 6c 20 6c 6f 63 6b  nly and all lock
24be0 69 6e 67 0a 2a 2a 20 20 20 20 20 61 6e 64 20 63  ing.**     and c
24bf0 68 61 6e 67 65 20 64 65 74 65 63 74 69 6f 6e 20  hange detection 
24c00 69 73 20 64 69 73 61 62 6c 65 64 2e 20 20 43 61  is disabled.  Ca
24c10 75 74 69 6f 6e 3a 20 53 65 74 74 69 6e 67 20 74  ution: Setting t
24c20 68 65 20 69 6d 6d 75 74 61 62 6c 65 0a 2a 2a 20  he immutable.** 
24c30 20 20 20 20 70 72 6f 70 65 72 74 79 20 6f 6e 20      property on 
24c40 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  a database file 
24c50 74 68 61 74 20 64 6f 65 73 20 69 6e 20 66 61 63  that does in fac
24c60 74 20 63 68 61 6e 67 65 20 63 61 6e 20 72 65 73  t change can res
24c70 75 6c 74 0a 2a 2a 20 20 20 20 20 69 6e 20 69 6e  ult.**     in in
24c80 63 6f 72 72 65 63 74 20 71 75 65 72 79 20 72 65  correct query re
24c90 73 75 6c 74 73 20 61 6e 64 2f 6f 72 20 5b 53 51  sults and/or [SQ
24ca0 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 20 65 72  LITE_CORRUPT] er
24cb0 72 6f 72 73 2e 0a 2a 2a 20 20 20 20 20 53 65 65  rors..**     See
24cc0 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 49   also: [SQLITE_I
24cd0 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 5d 2e  OCAP_IMMUTABLE].
24ce0 0a 2a 2a 20 20 20 20 20 20 20 0a 2a 2a 20 3c 2f  .**       .** </
24cf0 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53 70 65 63 69  ul>.**.** ^Speci
24d00 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e  fying an unknown
24d10 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68   parameter in th
24d20 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e  e query componen
24d30 74 20 6f 66 20 61 20 55 52 49 20 69 73 20 6e 6f  t of a URI is no
24d40 74 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 2e 20 20  t an.** error.  
24d50 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  Future versions 
24d60 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20  of SQLite might 
24d70 75 6e 64 65 72 73 74 61 6e 64 20 61 64 64 69 74  understand addit
24d80 69 6f 6e 61 6c 20 71 75 65 72 79 0a 2a 2a 20 70  ional query.** p
24d90 61 72 61 6d 65 74 65 72 73 2e 20 20 53 65 65 20  arameters.  See 
24da0 22 5b 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  "[query paramete
24db0 72 73 20 77 69 74 68 20 73 70 65 63 69 61 6c 20  rs with special 
24dc0 6d 65 61 6e 69 6e 67 20 74 6f 20 53 51 4c 69 74  meaning to SQLit
24dd0 65 5d 22 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74  e]" for.** addit
24de0 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f  ional informatio
24df0 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66  n..**.** [[URI f
24e00 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73  ilename examples
24e10 5d 5d 20 3c 68 33 3e 55 52 49 20 66 69 6c 65 6e  ]] <h3>URI filen
24e20 61 6d 65 20 65 78 61 6d 70 6c 65 73 3c 2f 68 33  ame examples</h3
24e30 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61 62 6c 65 20 62  >.**.** <table b
24e40 6f 72 64 65 72 3d 22 31 22 20 61 6c 69 67 6e 3d  order="1" align=
24e50 63 65 6e 74 65 72 20 63 65 6c 6c 70 61 64 64 69  center cellpaddi
24e60 6e 67 3d 35 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68  ng=5>.** <tr><th
24e70 3e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20  > URI filenames 
24e80 3c 74 68 3e 20 52 65 73 75 6c 74 73 0a 2a 2a 20  <th> Results.** 
24e90 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61  <tr><td> file:da
24ea0 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20  ta.db <td> .**  
24eb0 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65          Open the
24ec0 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20   file "data.db" 
24ed0 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 64  in the current d
24ee0 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 20 3c 74 72  irectory..** <tr
24ef0 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65  ><td> file:/home
24f00 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3c 62 72  /fred/data.db<br
24f10 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69  >.**          fi
24f20 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f 66 72 65 64 2f  le:///home/fred/
24f30 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 0a 2a 2a  data.db <br> .**
24f40 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f            file:/
24f50 2f 6c 6f 63 61 6c 68 6f 73 74 2f 68 6f 6d 65 2f  /localhost/home/
24f60 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72  fred/data.db <br
24f70 3e 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20  > <td> .**      
24f80 20 20 20 20 4f 70 65 6e 20 74 68 65 20 64 61 74      Open the dat
24f90 61 62 61 73 65 20 66 69 6c 65 20 22 2f 68 6f 6d  abase file "/hom
24fa0 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e  e/fred/data.db".
24fb0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c  .** <tr><td> fil
24fc0 65 3a 2f 2f 64 61 72 6b 73 74 61 72 2f 68 6f 6d  e://darkstar/hom
24fd0 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c  e/fred/data.db <
24fe0 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  td> .**         
24ff0 20 41 6e 20 65 72 72 6f 72 2e 20 22 64 61 72 6b   An error. "dark
25000 73 74 61 72 22 20 69 73 20 6e 6f 74 20 61 20 72  star" is not a r
25010 65 63 6f 67 6e 69 7a 65 64 20 61 75 74 68 6f 72  ecognized author
25020 69 74 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 20  ity..** <tr><td 
25030 73 74 79 6c 65 3d 22 77 68 69 74 65 2d 73 70 61  style="white-spa
25040 63 65 3a 6e 6f 77 72 61 70 22 3e 20 0a 2a 2a 20  ce:nowrap"> .** 
25050 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f           file://
25060 2f 43 3a 2f 44 6f 63 75 6d 65 6e 74 73 25 32 30  /C:/Documents%20
25070 61 6e 64 25 32 30 53 65 74 74 69 6e 67 73 2f 66  and%20Settings/f
25080 72 65 64 2f 44 65 73 6b 74 6f 70 2f 64 61 74 61  red/Desktop/data
25090 2e 64 62 0a 2a 2a 20 20 20 20 20 3c 74 64 3e 20  .db.**     <td> 
250a0 57 69 6e 64 6f 77 73 20 6f 6e 6c 79 3a 20 4f 70  Windows only: Op
250b0 65 6e 20 74 68 65 20 66 69 6c 65 20 22 64 61 74  en the file "dat
250c0 61 2e 64 62 22 20 6f 6e 20 66 72 65 64 27 73 20  a.db" on fred's 
250d0 64 65 73 6b 74 6f 70 20 6f 6e 20 64 72 69 76 65  desktop on drive
250e0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 43 3a 2e  .**          C:.
250f0 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 25   Note that the %
25100 32 30 20 65 73 63 61 70 69 6e 67 20 69 6e 20 74  20 escaping in t
25110 68 69 73 20 65 78 61 6d 70 6c 65 20 69 73 20 6e  his example is n
25120 6f 74 20 73 74 72 69 63 74 6c 79 20 0a 2a 2a 20  ot strictly .** 
25130 20 20 20 20 20 20 20 20 20 6e 65 63 65 73 73 61           necessa
25140 72 79 20 2d 20 73 70 61 63 65 20 63 68 61 72 61  ry - space chara
25150 63 74 65 72 73 20 63 61 6e 20 62 65 20 75 73 65  cters can be use
25160 64 20 6c 69 74 65 72 61 6c 6c 79 0a 2a 2a 20 20  d literally.**  
25170 20 20 20 20 20 20 20 20 69 6e 20 55 52 49 20 66          in URI f
25180 69 6c 65 6e 61 6d 65 73 2e 0a 2a 2a 20 3c 74 72  ilenames..** <tr
25190 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e  ><td> file:data.
251a0 64 62 3f 6d 6f 64 65 3d 72 6f 26 63 61 63 68 65  db?mode=ro&cache
251b0 3d 70 72 69 76 61 74 65 20 3c 74 64 3e 20 0a 2a  =private <td> .*
251c0 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20  *          Open 
251d0 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 69  file "data.db" i
251e0 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 69  n the current di
251f0 72 65 63 74 6f 72 79 20 66 6f 72 20 72 65 61 64  rectory for read
25200 2d 6f 6e 6c 79 20 61 63 63 65 73 73 2e 0a 2a 2a  -only access..**
25210 20 20 20 20 20 20 20 20 20 20 52 65 67 61 72 64            Regard
25220 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20  less of whether 
25230 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 2d 63 61  or not shared-ca
25240 63 68 65 20 6d 6f 64 65 20 69 73 20 65 6e 61 62  che mode is enab
25250 6c 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20  led by.**       
25260 20 20 20 64 65 66 61 75 6c 74 2c 20 75 73 65 20     default, use 
25270 61 20 70 72 69 76 61 74 65 20 63 61 63 68 65 2e  a private cache.
25280 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c  .** <tr><td> fil
25290 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74  e:/home/fred/dat
252a0 61 2e 64 62 3f 76 66 73 3d 75 6e 69 78 2d 64 6f  a.db?vfs=unix-do
252b0 74 66 69 6c 65 20 3c 74 64 3e 0a 2a 2a 20 20 20  tfile <td>.**   
252c0 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65         Open file
252d0 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74   "/home/fred/dat
252e0 61 2e 64 62 22 2e 20 55 73 65 20 74 68 65 20 73  a.db". Use the s
252f0 70 65 63 69 61 6c 20 56 46 53 20 22 75 6e 69 78  pecial VFS "unix
25300 2d 64 6f 74 66 69 6c 65 22 0a 2a 2a 20 20 20 20  -dotfile".**    
25310 20 20 20 20 20 20 74 68 61 74 20 75 73 65 73 20        that uses 
25320 64 6f 74 2d 66 69 6c 65 73 20 69 6e 20 70 6c 61  dot-files in pla
25330 63 65 20 6f 66 20 70 6f 73 69 78 20 61 64 76 69  ce of posix advi
25340 73 6f 72 79 20 6c 6f 63 6b 69 6e 67 2e 0a 2a 2a  sory locking..**
25350 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64   <tr><td> file:d
25360 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 65 61 64  ata.db?mode=read
25370 6f 6e 6c 79 20 3c 74 64 3e 20 0a 2a 2a 20 20 20  only <td> .**   
25380 20 20 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e         An error.
25390 20 22 72 65 61 64 6f 6e 6c 79 22 20 69 73 20 6e   "readonly" is n
253a0 6f 74 20 61 20 76 61 6c 69 64 20 6f 70 74 69 6f  ot a valid optio
253b0 6e 20 66 6f 72 20 74 68 65 20 22 6d 6f 64 65 22  n for the "mode"
253c0 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 3c   parameter..** <
253d0 2f 74 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55  /table>.**.** ^U
253e0 52 49 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65  RI hexadecimal e
253f0 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 73 20  scape sequences 
25400 28 25 48 48 29 20 61 72 65 20 73 75 70 70 6f 72  (%HH) are suppor
25410 74 65 64 20 77 69 74 68 69 6e 20 74 68 65 20 70  ted within the p
25420 61 74 68 20 61 6e 64 0a 2a 2a 20 71 75 65 72 79  ath and.** query
25430 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61   components of a
25440 20 55 52 49 2e 20 41 20 68 65 78 61 64 65 63 69   URI. A hexadeci
25450 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65  mal escape seque
25460 6e 63 65 20 63 6f 6e 73 69 73 74 73 20 6f 66 20  nce consists of 
25470 61 0a 2a 2a 20 70 65 72 63 65 6e 74 20 73 69 67  a.** percent sig
25480 6e 20 2d 20 22 25 22 20 2d 20 66 6f 6c 6c 6f 77  n - "%" - follow
25490 65 64 20 62 79 20 65 78 61 63 74 6c 79 20 74 77  ed by exactly tw
254a0 6f 20 68 65 78 61 64 65 63 69 6d 61 6c 20 64 69  o hexadecimal di
254b0 67 69 74 73 20 0a 2a 2a 20 73 70 65 63 69 66 79  gits .** specify
254c0 69 6e 67 20 61 6e 20 6f 63 74 65 74 20 76 61 6c  ing an octet val
254d0 75 65 2e 20 5e 42 65 66 6f 72 65 20 74 68 65 20  ue. ^Before the 
254e0 70 61 74 68 20 6f 72 20 71 75 65 72 79 20 63 6f  path or query co
254f0 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61 0a 2a 2a  mponents of a.**
25500 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 61 72   URI filename ar
25510 65 20 69 6e 74 65 72 70 72 65 74 65 64 2c 20 74  e interpreted, t
25520 68 65 79 20 61 72 65 20 65 6e 63 6f 64 65 64 20  hey are encoded 
25530 75 73 69 6e 67 20 55 54 46 2d 38 20 61 6e 64 20  using UTF-8 and 
25540 61 6c 6c 20 0a 2a 2a 20 68 65 78 61 64 65 63 69  all .** hexadeci
25550 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65  mal escape seque
25560 6e 63 65 73 20 72 65 70 6c 61 63 65 64 20 62 79  nces replaced by
25570 20 61 20 73 69 6e 67 6c 65 20 62 79 74 65 20 63   a single byte c
25580 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 0a 2a 2a  ontaining the.**
25590 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6f   corresponding o
255a0 63 74 65 74 2e 20 49 66 20 74 68 69 73 20 70 72  ctet. If this pr
255b0 6f 63 65 73 73 20 67 65 6e 65 72 61 74 65 73 20  ocess generates 
255c0 61 6e 20 69 6e 76 61 6c 69 64 20 55 54 46 2d 38  an invalid UTF-8
255d0 20 65 6e 63 6f 64 69 6e 67 2c 0a 2a 2a 20 74 68   encoding,.** th
255e0 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
255f0 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c  defined..**.** <
25600 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77  b>Note to Window
25610 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68  s users:</b>  Th
25620 65 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20  e encoding used 
25630 66 6f 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  for the filename
25640 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20   argument.** of 
25650 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61  sqlite3_open() a
25660 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  nd sqlite3_open_
25670 76 32 28 29 20 6d 75 73 74 20 62 65 20 55 54 46  v2() must be UTF
25680 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65 76 65 72  -8, not whatever
25690 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20 69 73 20  .** codepage is 
256a0 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65  currently define
256b0 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f  d.  Filenames co
256c0 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61  ntaining interna
256d0 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63  tional.** charac
256e0 74 65 72 73 20 6d 75 73 74 20 62 65 20 63 6f 6e  ters must be con
256f0 76 65 72 74 65 64 20 74 6f 20 55 54 46 2d 38 20  verted to UTF-8 
25700 70 72 69 6f 72 20 74 6f 20 70 61 73 73 69 6e 67  prior to passing
25710 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71   them into.** sq
25720 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20  lite3_open() or 
25730 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
25740 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65  )..**.** <b>Note
25750 20 74 6f 20 57 69 6e 64 6f 77 73 20 52 75 6e 74   to Windows Runt
25760 69 6d 65 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20  ime users:</b>  
25770 54 68 65 20 74 65 6d 70 6f 72 61 72 79 20 64 69  The temporary di
25780 72 65 63 74 6f 72 79 20 6d 75 73 74 20 62 65 20  rectory must be 
25790 73 65 74 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20  set.** prior to 
257a0 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f  calling sqlite3_
257b0 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65  open() or sqlite
257c0 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20 4f 74  3_open_v2().  Ot
257d0 68 65 72 77 69 73 65 2c 20 76 61 72 69 6f 75 73  herwise, various
257e0 0a 2a 2a 20 66 65 61 74 75 72 65 73 20 74 68 61  .** features tha
257f0 74 20 72 65 71 75 69 72 65 20 74 68 65 20 75 73  t require the us
25800 65 20 6f 66 20 74 65 6d 70 6f 72 61 72 79 20 66  e of temporary f
25810 69 6c 65 73 20 6d 61 79 20 66 61 69 6c 2e 0a 2a  iles may fail..*
25820 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
25830 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 72  sqlite3_temp_dir
25840 65 63 74 6f 72 79 5d 0a 2a 2f 0a 53 51 4c 49 54  ectory].*/.SQLIT
25850 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
25860 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20  3_open(.  const 
25870 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20  char *filename, 
25880 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69    /* Database fi
25890 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a  lename (UTF-8) *
258a0 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70  /.  sqlite3 **pp
258b0 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f  Db          /* O
258c0 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61  UT: SQLite db ha
258d0 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54  ndle */.);.SQLIT
258e0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
258f0 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73  3_open16(.  cons
25900 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65  t void *filename
25910 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  ,   /* Database 
25920 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31 36  filename (UTF-16
25930 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a  ) */.  sqlite3 *
25940 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f  *ppDb          /
25950 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62  * OUT: SQLite db
25960 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 53 51   handle */.);.SQ
25970 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
25980 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 20  ite3_open_v2(.  
25990 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65  const char *file
259a0 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62  name,   /* Datab
259b0 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54  ase filename (UT
259c0 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65  F-8) */.  sqlite
259d0 33 20 2a 2a 70 70 44 62 2c 20 20 20 20 20 20 20  3 **ppDb,       
259e0 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65    /* OUT: SQLite
259f0 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20   db handle */.  
25a00 69 6e 74 20 66 6c 61 67 73 2c 20 20 20 20 20 20  int flags,      
25a10 20 20 20 20 20 20 20 20 2f 2a 20 46 6c 61 67 73          /* Flags
25a20 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
25a30 20 2a 7a 56 66 73 20 20 20 20 20 20 20 20 2f 2a   *zVfs        /*
25a40 20 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d 6f 64   Name of VFS mod
25a50 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a 29 3b  ule to use */.);
25a60 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
25a70 3a 20 4f 62 74 61 69 6e 20 56 61 6c 75 65 73 20  : Obtain Values 
25a80 46 6f 72 20 55 52 49 20 50 61 72 61 6d 65 74 65  For URI Paramete
25a90 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61  rs.**.** These a
25aa0 72 65 20 75 74 69 6c 69 74 79 20 72 6f 75 74 69  re utility routi
25ab0 6e 65 73 2c 20 75 73 65 66 75 6c 20 74 6f 20 56  nes, useful to V
25ac0 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
25ad0 6e 73 2c 20 74 68 61 74 20 63 68 65 63 6b 0a 2a  ns, that check.*
25ae0 2a 20 74 6f 20 73 65 65 20 69 66 20 61 20 64 61  * to see if a da
25af0 74 61 62 61 73 65 20 66 69 6c 65 20 77 61 73 20  tabase file was 
25b00 61 20 55 52 49 20 74 68 61 74 20 63 6f 6e 74 61  a URI that conta
25b10 69 6e 65 64 20 61 20 73 70 65 63 69 66 69 63 20  ined a specific 
25b20 71 75 65 72 79 20 0a 2a 2a 20 70 61 72 61 6d 65  query .** parame
25b30 74 65 72 2c 20 61 6e 64 20 69 66 20 73 6f 20 6f  ter, and if so o
25b40 62 74 61 69 6e 73 20 74 68 65 20 76 61 6c 75 65  btains the value
25b50 20 6f 66 20 74 68 61 74 20 71 75 65 72 79 20 70   of that query p
25b60 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
25b70 49 66 20 46 20 69 73 20 74 68 65 20 64 61 74 61  If F is the data
25b80 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 70 6f  base filename po
25b90 69 6e 74 65 72 20 70 61 73 73 65 64 20 69 6e 74  inter passed int
25ba0 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 20 6d 65  o the xOpen() me
25bb0 74 68 6f 64 20 6f 66 20 0a 2a 2a 20 61 20 56 46  thod of .** a VF
25bc0 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
25bd0 20 77 68 65 6e 20 74 68 65 20 66 6c 61 67 73 20   when the flags 
25be0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70  parameter to xOp
25bf0 65 6e 28 29 20 68 61 73 20 6f 6e 65 20 6f 72 20  en() has one or 
25c00 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20 74 68 65 20  .** more of the 
25c10 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49  [SQLITE_OPEN_URI
25c20 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45  ] or [SQLITE_OPE
25c30 4e 5f 4d 41 49 4e 5f 44 42 5d 20 62 69 74 73 20  N_MAIN_DB] bits 
25c40 73 65 74 20 61 6e 64 0a 2a 2a 20 50 20 69 73 20  set and.** P is 
25c50 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
25c60 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 2c  query parameter,
25c70 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33   then.** sqlite3
25c80 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46  _uri_parameter(F
25c90 2c 50 29 20 72 65 74 75 72 6e 73 20 74 68 65 20  ,P) returns the 
25ca0 76 61 6c 75 65 20 6f 66 20 74 68 65 20 50 0a 2a  value of the P.*
25cb0 2a 20 70 61 72 61 6d 65 74 65 72 20 69 66 20 69  * parameter if i
25cc0 74 20 65 78 69 73 74 73 20 6f 72 20 61 20 4e 55  t exists or a NU
25cd0 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 50 20  LL pointer if P 
25ce0 64 6f 65 73 20 6e 6f 74 20 61 70 70 65 61 72 20  does not appear 
25cf0 61 73 20 61 20 0a 2a 2a 20 71 75 65 72 79 20 70  as a .** query p
25d00 61 72 61 6d 65 74 65 72 20 6f 6e 20 46 2e 20 20  arameter on F.  
25d10 49 66 20 50 20 69 73 20 61 20 71 75 65 72 79 20  If P is a query 
25d20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 46 0a 2a  parameter of F.*
25d30 2a 20 68 61 73 20 6e 6f 20 65 78 70 6c 69 63 69  * has no explici
25d40 74 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 73 71  t value, then sq
25d50 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65  lite3_uri_parame
25d60 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73  ter(F,P) returns
25d70 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  .** a pointer to
25d80 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
25d90 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
25da0 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28  te3_uri_boolean(
25db0 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 20 61  F,P,B) routine a
25dc0 73 73 75 6d 65 73 20 74 68 61 74 20 50 20 69 73  ssumes that P is
25dd0 20 61 20 62 6f 6f 6c 65 61 6e 0a 2a 2a 20 70 61   a boolean.** pa
25de0 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74 75  rameter and retu
25df0 72 6e 73 20 74 72 75 65 20 28 31 29 20 6f 72 20  rns true (1) or 
25e00 66 61 6c 73 65 20 28 30 29 20 61 63 63 6f 72 64  false (0) accord
25e10 69 6e 67 20 74 6f 20 74 68 65 20 76 61 6c 75 65  ing to the value
25e20 0a 2a 2a 20 6f 66 20 50 2e 20 20 54 68 65 20 73  .** of P.  The s
25e30 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65  qlite3_uri_boole
25e40 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e  an(F,P,B) routin
25e50 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28  e returns true (
25e60 31 29 20 69 66 20 74 68 65 0a 2a 2a 20 76 61 6c  1) if the.** val
25e70 75 65 20 6f 66 20 71 75 65 72 79 20 70 61 72 61  ue of query para
25e80 6d 65 74 65 72 20 50 20 69 73 20 6f 6e 65 20 6f  meter P is one o
25e90 66 20 22 79 65 73 22 2c 20 22 74 72 75 65 22 2c  f "yes", "true",
25ea0 20 6f 72 20 22 6f 6e 22 20 69 6e 20 61 6e 79 0a   or "on" in any.
25eb0 2a 2a 20 63 61 73 65 20 6f 72 20 69 66 20 74 68  ** case or if th
25ec0 65 20 76 61 6c 75 65 20 62 65 67 69 6e 73 20 77  e value begins w
25ed0 69 74 68 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 6e  ith a non-zero n
25ee0 75 6d 62 65 72 2e 20 20 54 68 65 20 0a 2a 2a 20  umber.  The .** 
25ef0 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c  sqlite3_uri_bool
25f00 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69  ean(F,P,B) routi
25f10 6e 65 73 20 72 65 74 75 72 6e 73 20 66 61 6c 73  nes returns fals
25f20 65 20 28 30 29 20 69 66 20 74 68 65 20 76 61 6c  e (0) if the val
25f30 75 65 20 6f 66 0a 2a 2a 20 71 75 65 72 79 20 70  ue of.** query p
25f40 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f 6e  arameter P is on
25f50 65 20 6f 66 20 22 6e 6f 22 2c 20 22 66 61 6c 73  e of "no", "fals
25f60 65 22 2c 20 6f 72 20 22 6f 66 66 22 20 69 6e 20  e", or "off" in 
25f70 61 6e 79 20 63 61 73 65 20 6f 72 0a 2a 2a 20 69  any case or.** i
25f80 66 20 74 68 65 20 76 61 6c 75 65 20 62 65 67 69  f the value begi
25f90 6e 73 20 77 69 74 68 20 61 20 6e 75 6d 65 72 69  ns with a numeri
25fa0 63 20 7a 65 72 6f 2e 20 20 49 66 20 50 20 69 73  c zero.  If P is
25fb0 20 6e 6f 74 20 61 20 71 75 65 72 79 0a 2a 2a 20   not a query.** 
25fc0 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46 20 6f  parameter on F o
25fd0 72 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 6f  r if the value o
25fe0 66 20 50 20 69 73 20 64 6f 65 73 20 6e 6f 74 20  f P is does not 
25ff0 6d 61 74 63 68 20 61 6e 79 20 6f 66 20 74 68 65  match any of the
26000 0a 2a 2a 20 61 62 6f 76 65 2c 20 74 68 65 6e 20  .** above, then 
26010 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c  sqlite3_uri_bool
26020 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 72  ean(F,P,B) retur
26030 6e 73 20 28 42 21 3d 30 29 2e 0a 2a 2a 0a 2a 2a  ns (B!=0)..**.**
26040 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69   The sqlite3_uri
26050 5f 69 6e 74 36 34 28 46 2c 50 2c 44 29 20 72 6f  _int64(F,P,D) ro
26060 75 74 69 6e 65 20 63 6f 6e 76 65 72 74 73 20 74  utine converts t
26070 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69 6e  he value of P in
26080 74 6f 20 61 0a 2a 2a 20 36 34 2d 62 69 74 20 73  to a.** 64-bit s
26090 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e  igned integer an
260a0 64 20 72 65 74 75 72 6e 73 20 74 68 61 74 20 69  d returns that i
260b0 6e 74 65 67 65 72 2c 20 6f 72 20 44 20 69 66 20  nteger, or D if 
260c0 50 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 65 78  P does not.** ex
260d0 69 73 74 2e 20 20 49 66 20 74 68 65 20 76 61 6c  ist.  If the val
260e0 75 65 20 6f 66 20 50 20 69 73 20 73 6f 6d 65 74  ue of P is somet
260f0 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20  hing other than 
26100 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 65 6e  an integer, then
26110 0a 2a 2a 20 7a 65 72 6f 20 69 73 20 72 65 74 75  .** zero is retu
26120 72 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 49 66 20  rned..** .** If 
26130 46 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  F is a NULL poin
26140 74 65 72 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ter, then sqlite
26150 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28  3_uri_parameter(
26160 46 2c 50 29 20 72 65 74 75 72 6e 73 20 4e 55 4c  F,P) returns NUL
26170 4c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33  L and.** sqlite3
26180 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50  _uri_boolean(F,P
26190 2c 42 29 20 72 65 74 75 72 6e 73 20 42 2e 20 20  ,B) returns B.  
261a0 49 66 20 46 20 69 73 20 6e 6f 74 20 61 20 4e 55  If F is not a NU
261b0 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64 0a 2a  LL pointer and.*
261c0 2a 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62  * is not a datab
261d0 61 73 65 20 66 69 6c 65 20 70 61 74 68 6e 61 6d  ase file pathnam
261e0 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 53  e pointer that S
261f0 51 4c 69 74 65 20 70 61 73 73 65 64 20 69 6e 74  QLite passed int
26200 6f 20 74 68 65 20 78 4f 70 65 6e 0a 2a 2a 20 56  o the xOpen.** V
26210 46 53 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20  FS method, then 
26220 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20  the behavior of 
26230 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20  this routine is 
26240 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72  undefined and pr
26250 6f 62 61 62 6c 79 0a 2a 2a 20 75 6e 64 65 73 69  obably.** undesi
26260 72 61 62 6c 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45  rable..*/.SQLITE
26270 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20  _API const char 
26280 2a 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72  *sqlite3_uri_par
26290 61 6d 65 74 65 72 28 63 6f 6e 73 74 20 63 68 61  ameter(const cha
262a0 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 2c 20 63 6f  r *zFilename, co
262b0 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61 6d  nst char *zParam
262c0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
262d0 74 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f  t sqlite3_uri_bo
262e0 6f 6c 65 61 6e 28 63 6f 6e 73 74 20 63 68 61 72  olean(const char
262f0 20 2a 7a 46 69 6c 65 2c 20 63 6f 6e 73 74 20 63   *zFile, const c
26300 68 61 72 20 2a 7a 50 61 72 61 6d 2c 20 69 6e 74  har *zParam, int
26310 20 62 44 65 66 61 75 6c 74 29 3b 0a 53 51 4c 49   bDefault);.SQLI
26320 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69  TE_API sqlite3_i
26330 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75 72 69  nt64 sqlite3_uri
26340 5f 69 6e 74 36 34 28 63 6f 6e 73 74 20 63 68 61  _int64(const cha
26350 72 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c  r*, const char*,
26360 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b   sqlite3_int64);
26370 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  .../*.** CAPI3RE
26380 46 3a 20 45 72 72 6f 72 20 43 6f 64 65 73 20 41  F: Error Codes A
26390 6e 64 20 4d 65 73 73 61 67 65 73 0a 2a 2a 0a 2a  nd Messages.**.*
263a0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
263b0 72 72 63 6f 64 65 28 29 20 69 6e 74 65 72 66 61  rrcode() interfa
263c0 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ce returns the n
263d0 75 6d 65 72 69 63 20 5b 72 65 73 75 6c 74 20 63  umeric [result c
263e0 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65  ode] or.** [exte
263f0 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
26400 5d 20 66 6f 72 20 74 68 65 20 6d 6f 73 74 20 72  ] for the most r
26410 65 63 65 6e 74 20 66 61 69 6c 65 64 20 73 71 6c  ecent failed sql
26420 69 74 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c 0a  ite3_* API call.
26430 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ** associated wi
26440 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  th a [database c
26450 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 49 66 20 61  onnection]. If a
26460 20 70 72 69 6f 72 20 41 50 49 20 63 61 6c 6c 20   prior API call 
26470 66 61 69 6c 65 64 0a 2a 2a 20 62 75 74 20 74 68  failed.** but th
26480 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 41 50  e most recent AP
26490 49 20 63 61 6c 6c 20 73 75 63 63 65 65 64 65 64  I call succeeded
264a0 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  , the return val
264b0 75 65 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74  ue from.** sqlit
264c0 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69 73 20  e3_errcode() is 
264d0 75 6e 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65  undefined.  ^The
264e0 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65   sqlite3_extende
264f0 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20 69  d_errcode().** i
26500 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 65 20  nterface is the 
26510 73 61 6d 65 20 65 78 63 65 70 74 20 74 68 61 74  same except that
26520 20 69 74 20 61 6c 77 61 79 73 20 72 65 74 75 72   it always retur
26530 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65 78 74 65  ns the .** [exte
26540 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
26550 5d 20 65 76 65 6e 20 77 68 65 6e 20 65 78 74 65  ] even when exte
26560 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
26570 73 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65  s are.** disable
26580 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
26590 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 20 61  lite3_errmsg() a
265a0 6e 64 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  nd sqlite3_errms
265b0 67 31 36 28 29 20 72 65 74 75 72 6e 20 45 6e 67  g16() return Eng
265c0 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a  lish-language.**
265d0 20 74 65 78 74 20 74 68 61 74 20 64 65 73 63 72   text that descr
265e0 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2c 20  ibes the error, 
265f0 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20  as either UTF-8 
26600 6f 72 20 55 54 46 2d 31 36 20 72 65 73 70 65 63  or UTF-16 respec
26610 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 6d  tively..** ^(Mem
26620 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  ory to hold the 
26630 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74  error message st
26640 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20  ring is managed 
26650 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54  internally..** T
26660 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
26670 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20  oes not need to 
26680 77 6f 72 72 79 20 61 62 6f 75 74 20 66 72 65 65  worry about free
26690 69 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2e 0a  ing the result..
266a0 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20  ** However, the 
266b0 65 72 72 6f 72 20 73 74 72 69 6e 67 20 6d 69 67  error string mig
266c0 68 74 20 62 65 20 6f 76 65 72 77 72 69 74 74 65  ht be overwritte
266d0 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65 64  n or deallocated
266e0 20 62 79 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e   by.** subsequen
266f0 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72  t calls to other
26700 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
26710 65 20 66 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a 2a  e functions.)^.*
26720 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
26730 33 5f 65 72 72 73 74 72 28 29 20 69 6e 74 65 72  3_errstr() inter
26740 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
26750 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67   English-languag
26760 65 20 74 65 78 74 0a 2a 2a 20 74 68 61 74 20 64  e text.** that d
26770 65 73 63 72 69 62 65 73 20 74 68 65 20 5b 72 65  escribes the [re
26780 73 75 6c 74 20 63 6f 64 65 5d 2c 20 61 73 20 55  sult code], as U
26790 54 46 2d 38 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72  TF-8..** ^(Memor
267a0 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72  y to hold the er
267b0 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69  ror message stri
267c0 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e  ng is managed in
267d0 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 61 6e 64 20  ternally.** and 
267e0 6d 75 73 74 20 6e 6f 74 20 62 65 20 66 72 65 65  must not be free
267f0 64 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61  d by the applica
26800 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a 2a 2a 20 57 68  tion)^..**.** Wh
26810 65 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65  en the serialize
26820 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  d [threading mod
26830 65 5d 20 69 73 20 69 6e 20 75 73 65 2c 20 69 74  e] is in use, it
26840 20 6d 69 67 68 74 20 62 65 20 74 68 65 0a 2a 2a   might be the.**
26850 20 63 61 73 65 20 74 68 61 74 20 61 20 73 65 63   case that a sec
26860 6f 6e 64 20 65 72 72 6f 72 20 6f 63 63 75 72 73  ond error occurs
26870 20 6f 6e 20 61 20 73 65 70 61 72 61 74 65 20 74   on a separate t
26880 68 72 65 61 64 20 69 6e 20 62 65 74 77 65 65 6e  hread in between
26890 0a 2a 2a 20 74 68 65 20 74 69 6d 65 20 6f 66 20  .** the time of 
268a0 74 68 65 20 66 69 72 73 74 20 65 72 72 6f 72 20  the first error 
268b0 61 6e 64 20 74 68 65 20 63 61 6c 6c 20 74 6f 20  and the call to 
268c0 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73  these interfaces
268d0 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 61 74 20 68  ..** When that h
268e0 61 70 70 65 6e 73 2c 20 74 68 65 20 73 65 63 6f  appens, the seco
268f0 6e 64 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 65  nd error will be
26900 20 72 65 70 6f 72 74 65 64 20 73 69 6e 63 65 20   reported since 
26910 74 68 65 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61  these.** interfa
26920 63 65 73 20 61 6c 77 61 79 73 20 72 65 70 6f 72  ces always repor
26930 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  t the most recen
26940 74 20 72 65 73 75 6c 74 2e 20 20 54 6f 20 61 76  t result.  To av
26950 6f 69 64 0a 2a 2a 20 74 68 69 73 2c 20 65 61 63  oid.** this, eac
26960 68 20 74 68 72 65 61 64 20 63 61 6e 20 6f 62 74  h thread can obt
26970 61 69 6e 20 65 78 63 6c 75 73 69 76 65 20 75 73  ain exclusive us
26980 65 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61  e of the [databa
26990 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
269a0 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e 67 20  .** by invoking 
269b0 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65  [sqlite3_mutex_e
269c0 6e 74 65 72 5d 28 5b 73 71 6c 69 74 65 33 5f 64  nter]([sqlite3_d
269d0 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 62 65 66  b_mutex](D)) bef
269e0 6f 72 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a  ore beginning.**
269f0 20 74 6f 20 75 73 65 20 44 20 61 6e 64 20 69 6e   to use D and in
26a00 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  voking [sqlite3_
26a10 6d 75 74 65 78 5f 6c 65 61 76 65 5d 28 5b 73 71  mutex_leave]([sq
26a20 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28  lite3_db_mutex](
26a30 44 29 29 20 61 66 74 65 72 0a 2a 2a 20 61 6c 6c  D)) after.** all
26a40 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 69 6e   calls to the in
26a50 74 65 72 66 61 63 65 73 20 6c 69 73 74 65 64 20  terfaces listed 
26a60 68 65 72 65 20 61 72 65 20 63 6f 6d 70 6c 65 74  here are complet
26a70 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20  ed..**.** If an 
26a80 69 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73 20  interface fails 
26a90 77 69 74 68 20 53 51 4c 49 54 45 5f 4d 49 53 55  with SQLITE_MISU
26aa0 53 45 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74  SE, that means t
26ab0 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  he interface.** 
26ac0 77 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e 63 6f  was invoked inco
26ad0 72 72 65 63 74 6c 79 20 62 79 20 74 68 65 20 61  rrectly by the a
26ae0 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49 6e 20  pplication.  In 
26af0 74 68 61 74 20 63 61 73 65 2c 20 74 68 65 0a 2a  that case, the.*
26b00 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64  * error code and
26b10 20 6d 65 73 73 61 67 65 20 6d 61 79 20 6f 72 20   message may or 
26b20 6d 61 79 20 6e 6f 74 20 62 65 20 73 65 74 2e 0a  may not be set..
26b30 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
26b40 74 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64  t sqlite3_errcod
26b50 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a  e(sqlite3 *db);.
26b60 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
26b70 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
26b80 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20  errcode(sqlite3 
26b90 2a 64 62 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  *db);.SQLITE_API
26ba0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c   const char *sql
26bb0 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71 6c 69  ite3_errmsg(sqli
26bc0 74 65 33 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  te3*);.SQLITE_AP
26bd0 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  I const void *sq
26be0 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 73  lite3_errmsg16(s
26bf0 71 6c 69 74 65 33 2a 29 3b 0a 53 51 4c 49 54 45  qlite3*);.SQLITE
26c00 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20  _API const char 
26c10 2a 73 71 6c 69 74 65 33 5f 65 72 72 73 74 72 28  *sqlite3_errstr(
26c20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
26c30 49 33 52 45 46 3a 20 53 51 4c 20 53 74 61 74 65  I3REF: SQL State
26c40 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b  ment Object.** K
26c50 45 59 57 4f 52 44 53 3a 20 7b 70 72 65 70 61 72  EYWORDS: {prepar
26c60 65 64 20 73 74 61 74 65 6d 65 6e 74 7d 20 7b 70  ed statement} {p
26c70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
26c80 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  ts}.**.** An ins
26c90 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
26ca0 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20  ject represents 
26cb0 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61  a single SQL sta
26cc0 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54 68 69 73 20  tement..** This 
26cd0 6f 62 6a 65 63 74 20 69 73 20 76 61 72 69 6f 75  object is variou
26ce0 73 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 61 20 22  sly known as a "
26cf0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
26d00 6e 74 22 20 6f 72 20 61 0a 2a 2a 20 22 63 6f 6d  nt" or a.** "com
26d10 70 69 6c 65 64 20 53 51 4c 20 73 74 61 74 65 6d  piled SQL statem
26d20 65 6e 74 22 20 6f 72 20 73 69 6d 70 6c 79 20 61  ent" or simply a
26d30 73 20 61 20 22 73 74 61 74 65 6d 65 6e 74 22 2e  s a "statement".
26d40 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 66 65 20  .**.** The life 
26d50 6f 66 20 61 20 73 74 61 74 65 6d 65 6e 74 20 6f  of a statement o
26d60 62 6a 65 63 74 20 67 6f 65 73 20 73 6f 6d 65 74  bject goes somet
26d70 68 69 6e 67 20 6c 69 6b 65 20 74 68 69 73 3a 0a  hing like this:.
26d80 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c  **.** <ol>.** <l
26d90 69 3e 20 43 72 65 61 74 65 20 74 68 65 20 6f 62  i> Create the ob
26da0 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  ject using [sqli
26db0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
26dc0 5d 20 6f 72 20 61 20 72 65 6c 61 74 65 64 0a 2a  ] or a related.*
26dd0 2a 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 2e  *      function.
26de0 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76 61  .** <li> Bind va
26df0 6c 75 65 73 20 74 6f 20 5b 68 6f 73 74 20 70 61  lues to [host pa
26e00 72 61 6d 65 74 65 72 73 5d 20 75 73 69 6e 67 20  rameters] using 
26e10 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
26e20 5f 2a 28 29 0a 2a 2a 20 20 20 20 20 20 69 6e 74  _*().**      int
26e30 65 72 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e  erfaces..** <li>
26e40 20 52 75 6e 20 74 68 65 20 53 51 4c 20 62 79 20   Run the SQL by 
26e50 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
26e60 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72 20  _step()] one or 
26e70 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c  more times..** <
26e80 6c 69 3e 20 52 65 73 65 74 20 74 68 65 20 73 74  li> Reset the st
26e90 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73  atement using [s
26ea0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
26eb0 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20  then go back.** 
26ec0 20 20 20 20 20 74 6f 20 73 74 65 70 20 32 2e 20       to step 2. 
26ed0 20 44 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f 72   Do this zero or
26ee0 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20   more times..** 
26ef0 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20 74 68 65  <li> Destroy the
26f00 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73   object using [s
26f10 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
26f20 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a  )]..** </ol>.**.
26f30 2a 2a 20 52 65 66 65 72 20 74 6f 20 64 6f 63 75  ** Refer to docu
26f40 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e 20 69 6e 64  mentation on ind
26f50 69 76 69 64 75 61 6c 20 6d 65 74 68 6f 64 73 20  ividual methods 
26f60 61 62 6f 76 65 20 66 6f 72 20 61 64 64 69 74 69  above for additi
26f70 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  onal.** informat
26f80 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ion..*/.typedef 
26f90 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 73  struct sqlite3_s
26fa0 74 6d 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  tmt sqlite3_stmt
26fb0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
26fc0 46 3a 20 52 75 6e 2d 74 69 6d 65 20 4c 69 6d 69  F: Run-time Limi
26fd0 74 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20  ts.**.** ^(This 
26fe0 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73  interface allows
26ff0 20 74 68 65 20 73 69 7a 65 20 6f 66 20 76 61 72   the size of var
27000 69 6f 75 73 20 63 6f 6e 73 74 72 75 63 74 73 20  ious constructs 
27010 74 6f 20 62 65 20 6c 69 6d 69 74 65 64 0a 2a 2a  to be limited.**
27020 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e   on a connection
27030 20 62 79 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62   by connection b
27040 61 73 69 73 2e 20 20 54 68 65 20 66 69 72 73 74  asis.  The first
27050 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
27060 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  e.** [database c
27070 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 68 6f 73 65  onnection] whose
27080 20 6c 69 6d 69 74 20 69 73 20 74 6f 20 62 65 20   limit is to be 
27090 73 65 74 20 6f 72 20 71 75 65 72 69 65 64 2e 20  set or queried. 
270a0 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70   The.** second p
270b0 61 72 61 6d 65 74 65 72 20 69 73 20 6f 6e 65 20  arameter is one 
270c0 6f 66 20 74 68 65 20 5b 6c 69 6d 69 74 20 63 61  of the [limit ca
270d0 74 65 67 6f 72 69 65 73 5d 20 74 68 61 74 20 64  tegories] that d
270e0 65 66 69 6e 65 20 61 0a 2a 2a 20 63 6c 61 73 73  efine a.** class
270f0 20 6f 66 20 63 6f 6e 73 74 72 75 63 74 73 20 74   of constructs t
27100 6f 20 62 65 20 73 69 7a 65 20 6c 69 6d 69 74 65  o be size limite
27110 64 2e 20 20 54 68 65 20 74 68 69 72 64 20 70 61  d.  The third pa
27120 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a  rameter is the.*
27130 2a 20 6e 65 77 20 6c 69 6d 69 74 20 66 6f 72 20  * new limit for 
27140 74 68 61 74 20 63 6f 6e 73 74 72 75 63 74 2e 29  that construct.)
27150 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ^.**.** ^If the 
27160 6e 65 77 20 6c 69 6d 69 74 20 69 73 20 61 20 6e  new limit is a n
27170 65 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2c 20  egative number, 
27180 74 68 65 20 6c 69 6d 69 74 20 69 73 20 75 6e 63  the limit is unc
27190 68 61 6e 67 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72  hanged..** ^(For
271a0 20 65 61 63 68 20 6c 69 6d 69 74 20 63 61 74 65   each limit cate
271b0 67 6f 72 79 20 53 51 4c 49 54 45 5f 4c 49 4d 49  gory SQLITE_LIMI
271c0 54 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 20 74 68  T_<i>NAME</i> th
271d0 65 72 65 20 69 73 20 61 20 0a 2a 2a 20 5b 6c 69  ere is a .** [li
271e0 6d 69 74 73 20 7c 20 68 61 72 64 20 75 70 70 65  mits | hard uppe
271f0 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73 65 74 20  r bound].** set 
27200 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  at compile-time 
27210 62 79 20 61 20 43 20 70 72 65 70 72 6f 63 65 73  by a C preproces
27220 73 6f 72 20 6d 61 63 72 6f 20 63 61 6c 6c 65 64  sor macro called
27230 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 53 51  .** [limits | SQ
27240 4c 49 54 45 5f 4d 41 58 5f 3c 69 3e 4e 41 4d 45  LITE_MAX_<i>NAME
27250 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28 54 68 65 20 22  </i>]..** (The "
27260 5f 4c 49 4d 49 54 5f 22 20 69 6e 20 74 68 65 20  _LIMIT_" in the 
27270 6e 61 6d 65 20 69 73 20 63 68 61 6e 67 65 64 20  name is changed 
27280 74 6f 20 22 5f 4d 41 58 5f 22 2e 29 29 5e 0a 2a  to "_MAX_".))^.*
27290 2a 20 5e 41 74 74 65 6d 70 74 73 20 74 6f 20 69  * ^Attempts to i
272a0 6e 63 72 65 61 73 65 20 61 20 6c 69 6d 69 74 20  ncrease a limit 
272b0 61 62 6f 76 65 20 69 74 73 20 68 61 72 64 20 75  above its hard u
272c0 70 70 65 72 20 62 6f 75 6e 64 20 61 72 65 0a 2a  pper bound are.*
272d0 2a 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63  * silently trunc
272e0 61 74 65 64 20 74 6f 20 74 68 65 20 68 61 72 64  ated to the hard
272f0 20 75 70 70 65 72 20 62 6f 75 6e 64 2e 0a 2a 2a   upper bound..**
27300 0a 2a 2a 20 5e 52 65 67 61 72 64 6c 65 73 73 20  .** ^Regardless 
27310 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
27320 74 20 74 68 65 20 6c 69 6d 69 74 20 77 61 73 20  t the limit was 
27330 63 68 61 6e 67 65 64 2c 20 74 68 65 20 0a 2a 2a  changed, the .**
27340 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28   [sqlite3_limit(
27350 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
27360 75 72 6e 73 20 74 68 65 20 70 72 69 6f 72 20 76  urns the prior v
27370 61 6c 75 65 20 6f 66 20 74 68 65 20 6c 69 6d 69  alue of the limi
27380 74 2e 0a 2a 2a 20 5e 48 65 6e 63 65 2c 20 74 6f  t..** ^Hence, to
27390 20 66 69 6e 64 20 74 68 65 20 63 75 72 72 65 6e   find the curren
273a0 74 20 76 61 6c 75 65 20 6f 66 20 61 20 6c 69 6d  t value of a lim
273b0 69 74 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67  it without chang
273c0 69 6e 67 20 69 74 2c 0a 2a 2a 20 73 69 6d 70 6c  ing it,.** simpl
273d0 79 20 69 6e 76 6f 6b 65 20 74 68 69 73 20 69 6e  y invoke this in
273e0 74 65 72 66 61 63 65 20 77 69 74 68 20 74 68 65  terface with the
273f0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
27400 20 73 65 74 20 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a   set to -1..**.*
27410 2a 20 52 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74  * Run-time limit
27420 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66  s are intended f
27430 6f 72 20 75 73 65 20 69 6e 20 61 70 70 6c 69 63  or use in applic
27440 61 74 69 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61  ations that mana
27450 67 65 0a 2a 2a 20 62 6f 74 68 20 74 68 65 69 72  ge.** both their
27460 20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61   own internal da
27470 74 61 62 61 73 65 20 61 6e 64 20 61 6c 73 6f 20  tabase and also 
27480 64 61 74 61 62 61 73 65 73 20 74 68 61 74 20 61  databases that a
27490 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a  re controlled.**
274a0 20 62 79 20 75 6e 74 72 75 73 74 65 64 20 65 78   by untrusted ex
274b0 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20  ternal sources. 
274c0 20 41 6e 20 65 78 61 6d 70 6c 65 20 61 70 70 6c   An example appl
274d0 69 63 61 74 69 6f 6e 20 6d 69 67 68 74 20 62 65  ication might be
274e0 20 61 0a 2a 2a 20 77 65 62 20 62 72 6f 77 73 65   a.** web browse
274f0 72 20 74 68 61 74 20 68 61 73 20 69 74 73 20 6f  r that has its o
27500 77 6e 20 64 61 74 61 62 61 73 65 73 20 66 6f 72  wn databases for
27510 20 73 74 6f 72 69 6e 67 20 68 69 73 74 6f 72 79   storing history
27520 20 61 6e 64 0a 2a 2a 20 73 65 70 61 72 61 74 65   and.** separate
27530 20 64 61 74 61 62 61 73 65 73 20 63 6f 6e 74 72   databases contr
27540 6f 6c 6c 65 64 20 62 79 20 4a 61 76 61 53 63 72  olled by JavaScr
27550 69 70 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  ipt applications
27560 20 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f   downloaded.** o
27570 66 66 20 74 68 65 20 49 6e 74 65 72 6e 65 74 2e  ff the Internet.
27580 20 20 54 68 65 20 69 6e 74 65 72 6e 61 6c 20 64    The internal d
27590 61 74 61 62 61 73 65 73 20 63 61 6e 20 62 65 20  atabases can be 
275a0 67 69 76 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72  given the.** lar
275b0 67 65 2c 20 64 65 66 61 75 6c 74 20 6c 69 6d 69  ge, default limi
275c0 74 73 2e 20 20 44 61 74 61 62 61 73 65 73 20 6d  ts.  Databases m
275d0 61 6e 61 67 65 64 20 62 79 20 65 78 74 65 72 6e  anaged by extern
275e0 61 6c 20 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a  al sources can.*
275f0 2a 20 62 65 20 67 69 76 65 6e 20 6d 75 63 68 20  * be given much 
27600 73 6d 61 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64  smaller limits d
27610 65 73 69 67 6e 65 64 20 74 6f 20 70 72 65 76 65  esigned to preve
27620 6e 74 20 61 20 64 65 6e 69 61 6c 20 6f 66 20 73  nt a denial of s
27630 65 72 76 69 63 65 0a 2a 2a 20 61 74 74 61 63 6b  ervice.** attack
27640 2e 20 20 44 65 76 65 6c 6f 70 65 72 73 20 6d 69  .  Developers mi
27650 67 68 74 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f  ght also want to
27660 20 75 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65   use the [sqlite
27670 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
27680 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  ()].** interface
27690 20 74 6f 20 66 75 72 74 68 65 72 20 63 6f 6e 74   to further cont
276a0 72 6f 6c 20 75 6e 74 72 75 73 74 65 64 20 53 51  rol untrusted SQ
276b0 4c 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20  L.  The size of 
276c0 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
276d0 63 72 65 61 74 65 64 20 62 79 20 61 6e 20 75 6e  created by an un
276e0 74 72 75 73 74 65 64 20 73 63 72 69 70 74 20 63  trusted script c
276f0 61 6e 20 62 65 20 63 6f 6e 74 61 69 6e 65 64 20  an be contained 
27700 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61  using the.** [ma
27710 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50  x_page_count] [P
27720 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65  RAGMA]..**.** Ne
27730 77 20 72 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74  w run-time limit
27740 20 63 61 74 65 67 6f 72 69 65 73 20 6d 61 79 20   categories may 
27750 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
27760 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a  re releases..*/.
27770 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
27780 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c  qlite3_limit(sql
27790 69 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69  ite3*, int id, i
277a0 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a  nt newVal);../*.
277b0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e  ** CAPI3REF: Run
277c0 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43 61 74 65  -Time Limit Cate
277d0 67 6f 72 69 65 73 0a 2a 2a 20 4b 45 59 57 4f 52  gories.** KEYWOR
277e0 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65 67  DS: {limit categ
277f0 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74 20 63 61 74  ory} {*limit cat
27800 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54  egories}.**.** T
27810 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 64  hese constants d
27820 65 66 69 6e 65 20 76 61 72 69 6f 75 73 20 70 65  efine various pe
27830 72 66 6f 72 6d 61 6e 63 65 20 6c 69 6d 69 74 73  rformance limits
27840 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20  .** that can be 
27850 6c 6f 77 65 72 65 64 20 61 74 20 72 75 6e 2d 74  lowered at run-t
27860 69 6d 65 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ime using [sqlit
27870 65 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20  e3_limit()]..** 
27880 54 68 65 20 73 79 6e 6f 70 73 69 73 20 6f 66 20  The synopsis of 
27890 74 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20  the meanings of 
278a0 74 68 65 20 76 61 72 69 6f 75 73 20 6c 69 6d 69  the various limi
278b0 74 73 20 69 73 20 73 68 6f 77 6e 20 62 65 6c 6f  ts is shown belo
278c0 77 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c  w..** Additional
278d0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20   information is 
278e0 61 76 61 69 6c 61 62 6c 65 20 61 74 20 5b 6c 69  available at [li
278f0 6d 69 74 73 20 7c 20 4c 69 6d 69 74 73 20 69 6e  mits | Limits in
27900 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20   SQLite]..**.** 
27910 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  <dl>.** [[SQLITE
27920 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 5d 20  _LIMIT_LENGTH]] 
27930 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
27940 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a  IT_LENGTH</dt>.*
27950 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
27960 6d 20 73 69 7a 65 20 6f 66 20 61 6e 79 20 73 74  m size of any st
27970 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20  ring or BLOB or 
27980 74 61 62 6c 65 20 72 6f 77 2c 20 69 6e 20 62 79  table row, in by
27990 74 65 73 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  tes.<dd>)^.**.**
279a0 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
279b0 53 51 4c 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c  SQL_LENGTH]] ^(<
279c0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
279d0 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a  SQL_LENGTH</dt>.
279e0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
279f0 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20  um length of an 
27a00 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 69  SQL statement, i
27a10 6e 20 62 79 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a  n bytes.</dd>)^.
27a20 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
27a30 49 4d 49 54 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e 28  IMIT_COLUMN]] ^(
27a40 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
27a50 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20  _COLUMN</dt>.** 
27a60 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
27a70 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
27a80 73 20 69 6e 20 61 20 74 61 62 6c 65 20 64 65 66  s in a table def
27a90 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68  inition or in th
27aa0 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65 74 20  e.** result set 
27ab0 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 6f 72  of a [SELECT] or
27ac0 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d   the maximum num
27ad0 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
27ae0 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72  n an index.** or
27af0 20 69 6e 20 61 6e 20 4f 52 44 45 52 20 42 59 20   in an ORDER BY 
27b00 6f 72 20 47 52 4f 55 50 20 42 59 20 63 6c 61 75  or GROUP BY clau
27b10 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  se.</dd>)^.**.**
27b20 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
27b30 45 58 50 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c  EXPR_DEPTH]] ^(<
27b40 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
27b50 45 58 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a  EXPR_DEPTH</dt>.
27b60 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
27b70 75 6d 20 64 65 70 74 68 20 6f 66 20 74 68 65 20  um depth of the 
27b80 70 61 72 73 65 20 74 72 65 65 20 6f 6e 20 61 6e  parse tree on an
27b90 79 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64  y expression.</d
27ba0 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
27bb0 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55  ITE_LIMIT_COMPOU
27bc0 4e 44 5f 53 45 4c 45 43 54 5d 5d 20 5e 28 3c 64  ND_SELECT]] ^(<d
27bd0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  t>SQLITE_LIMIT_C
27be0 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f  OMPOUND_SELECT</
27bf0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
27c00 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
27c10 20 74 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70   terms in a comp
27c20 6f 75 6e 64 20 53 45 4c 45 43 54 20 73 74 61 74  ound SELECT stat
27c30 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ement.</dd>)^.**
27c40 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
27c50 49 54 5f 56 44 42 45 5f 4f 50 5d 5d 20 5e 28 3c  IT_VDBE_OP]] ^(<
27c60 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
27c70 56 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20  VDBE_OP</dt>.** 
27c80 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
27c90 6e 75 6d 62 65 72 20 6f 66 20 69 6e 73 74 72 75  number of instru
27ca0 63 74 69 6f 6e 73 20 69 6e 20 61 20 76 69 72 74  ctions in a virt
27cb0 75 61 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f 67  ual machine prog
27cc0 72 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69  ram.** used to i
27cd0 6d 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20  mplement an SQL 
27ce0 73 74 61 74 65 6d 65 6e 74 2e 20 20 54 68 69 73  statement.  This
27cf0 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 63 75   limit is not cu
27d00 72 72 65 6e 74 6c 79 0a 2a 2a 20 65 6e 66 6f 72  rrently.** enfor
27d10 63 65 64 2c 20 74 68 6f 75 67 68 20 74 68 61 74  ced, though that
27d20 20 6d 69 67 68 74 20 62 65 20 61 64 64 65 64 20   might be added 
27d30 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72  in some future r
27d40 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c  elease of.** SQL
27d50 69 74 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ite.</dd>)^.**.*
27d60 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
27d70 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 5d 20  _FUNCTION_ARG]] 
27d80 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
27d90 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c  IT_FUNCTION_ARG<
27da0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
27db0 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
27dc0 66 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61  f arguments on a
27dd0 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29   function.</dd>)
27de0 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
27df0 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 5d  _LIMIT_ATTACHED]
27e00 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
27e10 49 4d 49 54 5f 41 54 54 41 43 48 45 44 3c 2f 64  IMIT_ATTACHED</d
27e20 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
27e30 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
27e40 5b 41 54 54 41 43 48 20 7c 20 61 74 74 61 63 68  [ATTACH | attach
27e50 65 64 20 64 61 74 61 62 61 73 65 73 5d 2e 29 5e  ed databases].)^
27e60 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
27e70 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f  LITE_LIMIT_LIKE_
27e80 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 5d 5d  PATTERN_LENGTH]]
27e90 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  .** ^(<dt>SQLITE
27ea0 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54  _LIMIT_LIKE_PATT
27eb0 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a  ERN_LENGTH</dt>.
27ec0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
27ed0 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65  um length of the
27ee0 20 70 61 74 74 65 72 6e 20 61 72 67 75 6d 65 6e   pattern argumen
27ef0 74 20 74 6f 20 74 68 65 20 5b 4c 49 4b 45 5d 20  t to the [LIKE] 
27f00 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65  or.** [GLOB] ope
27f10 72 61 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a  rators.</dd>)^.*
27f20 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
27f30 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d  MIT_VARIABLE_NUM
27f40 42 45 52 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53  BER]].** ^(<dt>S
27f50 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49  QLITE_LIMIT_VARI
27f60 41 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e  ABLE_NUMBER</dt>
27f70 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
27f80 6d 75 6d 20 69 6e 64 65 78 20 6e 75 6d 62 65 72  mum index number
27f90 20 6f 66 20 61 6e 79 20 5b 70 61 72 61 6d 65 74   of any [paramet
27fa0 65 72 5d 20 69 6e 20 61 6e 20 53 51 4c 20 73 74  er] in an SQL st
27fb0 61 74 65 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a  atement.)^.**.**
27fc0 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
27fd0 54 52 49 47 47 45 52 5f 44 45 50 54 48 5d 5d 20  TRIGGER_DEPTH]] 
27fe0 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
27ff0 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48  IT_TRIGGER_DEPTH
28000 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
28010 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f   maximum depth o
28020 66 20 72 65 63 75 72 73 69 6f 6e 20 66 6f 72 20  f recursion for 
28030 74 72 69 67 67 65 72 73 2e 3c 2f 64 64 3e 29 5e  triggers.</dd>)^
28040 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
28050 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52  LIMIT_WORKER_THR
28060 45 41 44 53 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  EADS]] ^(<dt>SQL
28070 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52  ITE_LIMIT_WORKER
28080 5f 54 48 52 45 41 44 53 3c 2f 64 74 3e 0a 2a 2a  _THREADS</dt>.**
28090 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
280a0 20 6e 75 6d 62 65 72 20 6f 66 20 61 75 78 69 6c   number of auxil
280b0 69 61 72 79 20 77 6f 72 6b 65 72 20 74 68 72 65  iary worker thre
280c0 61 64 73 20 74 68 61 74 20 61 20 73 69 6e 67 6c  ads that a singl
280d0 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
280e0 74 61 74 65 6d 65 6e 74 5d 20 6d 61 79 20 73 74  tatement] may st
280f0 61 72 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c  art.</dd>)^.** <
28100 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  /dl>.*/.#define 
28110 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e  SQLITE_LIMIT_LEN
28120 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20  GTH             
28130 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65         0.#define
28140 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51   SQLITE_LIMIT_SQ
28150 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20  L_LENGTH        
28160 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e          1.#defin
28170 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  e SQLITE_LIMIT_C
28180 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20 20 20 20  OLUMN           
28190 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69           2.#defi
281a0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
281b0 45 58 50 52 5f 44 45 50 54 48 20 20 20 20 20 20  EXPR_DEPTH      
281c0 20 20 20 20 20 20 20 20 20 20 33 0a 23 64 65 66            3.#def
281d0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
281e0 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54  _COMPOUND_SELECT
281f0 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65             4.#de
28200 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
28210 54 5f 56 44 42 45 5f 4f 50 20 20 20 20 20 20 20  T_VDBE_OP       
28220 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 64              5.#d
28230 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
28240 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20  IT_FUNCTION_ARG 
28250 20 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 23               6.#
28260 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
28270 4d 49 54 5f 41 54 54 41 43 48 45 44 20 20 20 20  MIT_ATTACHED    
28280 20 20 20 20 20 20 20 20 20 20 20 20 20 20 37 0a                7.
28290 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
282a0 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52  IMIT_LIKE_PATTER
282b0 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 38  N_LENGTH       8
282c0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
282d0 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e  LIMIT_VARIABLE_N
282e0 55 4d 42 45 52 20 20 20 20 20 20 20 20 20 20 20  UMBER           
282f0 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  9.#define SQLITE
28300 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44  _LIMIT_TRIGGER_D
28310 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20  EPTH            
28320 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  10.#define SQLIT
28330 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54  E_LIMIT_WORKER_T
28340 48 52 45 41 44 53 20 20 20 20 20 20 20 20 20 20  HREADS          
28350 20 31 31 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   11../*.** CAPI3
28360 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41  REF: Compiling A
28370 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a  n SQL Statement.
28380 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51  ** KEYWORDS: {SQ
28390 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70  L statement comp
283a0 69 6c 65 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65  iler}.**.** To e
283b0 78 65 63 75 74 65 20 61 6e 20 53 51 4c 20 71 75  xecute an SQL qu
283c0 65 72 79 2c 20 69 74 20 6d 75 73 74 20 66 69 72  ery, it must fir
283d0 73 74 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 69  st be compiled i
283e0 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f 64 65 0a  nto a byte-code.
283f0 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 69 6e 67  ** program using
28400 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 72 6f   one of these ro
28410 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  utines..**.** Th
28420 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
28430 2c 20 22 64 62 22 2c 20 69 73 20 61 20 5b 64 61  , "db", is a [da
28440 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
28450 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  n] obtained from
28460 20 61 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63 63   a.** prior succ
28470 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b  essful call to [
28480 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
28490 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
284a0 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  2()] or.** [sqli
284b0 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20  te3_open16()].  
284c0 54 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  The database con
284d0 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  nection must not
284e0 20 68 61 76 65 20 62 65 65 6e 20 63 6c 6f 73 65   have been close
284f0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63  d..**.** The sec
28500 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a  ond argument, "z
28510 53 71 6c 22 2c 20 69 73 20 74 68 65 20 73 74 61  Sql", is the sta
28520 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d  tement to be com
28530 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a  piled, encoded.*
28540 2a 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d  * as either UTF-
28550 38 20 6f 72 20 55 54 46 2d 31 36 2e 20 20 54 68  8 or UTF-16.  Th
28560 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  e sqlite3_prepar
28570 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  e() and sqlite3_
28580 70 72 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20  prepare_v2().** 
28590 69 6e 74 65 72 66 61 63 65 73 20 75 73 65 20 55  interfaces use U
285a0 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69 74 65  TF-8, and sqlite
285b0 33 5f 70 72 65 70 61 72 65 31 36 28 29 20 61 6e  3_prepare16() an
285c0 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  d sqlite3_prepar
285d0 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20  e16_v2().** use 
285e0 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49  UTF-16..**.** ^I
285f0 66 20 74 68 65 20 6e 42 79 74 65 20 61 72 67 75  f the nByte argu
28600 6d 65 6e 74 20 69 73 20 6c 65 73 73 20 74 68 61  ment is less tha
28610 6e 20 7a 65 72 6f 2c 20 74 68 65 6e 20 7a 53 71  n zero, then zSq
28620 6c 20 69 73 20 72 65 61 64 20 75 70 20 74 6f 20  l is read up to 
28630 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72  the.** first zer
28640 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 5e 49  o terminator. ^I
28650 66 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e  f nByte is non-n
28660 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 69 74  egative, then it
28670 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a   is the maximum.
28680 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 20 62 79  ** number of  by
28690 74 65 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53  tes read from zS
286a0 71 6c 2e 20 20 5e 57 68 65 6e 20 6e 42 79 74 65  ql.  ^When nByte
286b0 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
286c0 2c 20 74 68 65 0a 2a 2a 20 7a 53 71 6c 20 73 74  , the.** zSql st
286d0 72 69 6e 67 20 65 6e 64 73 20 61 74 20 65 69 74  ring ends at eit
286e0 68 65 72 20 74 68 65 20 66 69 72 73 74 20 27 5c  her the first '\
286f0 30 30 30 27 20 6f 72 20 27 5c 75 30 30 30 30 27  000' or '\u0000'
28700 20 63 68 61 72 61 63 74 65 72 20 6f 72 0a 2a 2a   character or.**
28710 20 74 68 65 20 6e 42 79 74 65 2d 74 68 20 62 79   the nByte-th by
28720 74 65 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f  te, whichever co
28730 6d 65 73 20 66 69 72 73 74 2e 20 49 66 20 74 68  mes first. If th
28740 65 20 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a  e caller knows.*
28750 2a 20 74 68 61 74 20 74 68 65 20 73 75 70 70 6c  * that the suppl
28760 69 65 64 20 73 74 72 69 6e 67 20 69 73 20 6e 75  ied string is nu
28770 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20 74 68  l-terminated, th
28780 65 6e 20 74 68 65 72 65 20 69 73 20 61 20 73 6d  en there is a sm
28790 61 6c 6c 0a 2a 2a 20 70 65 72 66 6f 72 6d 61 6e  all.** performan
287a0 63 65 20 61 64 76 61 6e 74 61 67 65 20 74 6f 20  ce advantage to 
287b0 62 65 20 67 61 69 6e 65 64 20 62 79 20 70 61 73  be gained by pas
287c0 73 69 6e 67 20 61 6e 20 6e 42 79 74 65 20 70 61  sing an nByte pa
287d0 72 61 6d 65 74 65 72 20 74 68 61 74 0a 2a 2a 20  rameter that.** 
287e0 69 73 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20  is equal to the 
287f0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
28800 69 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72  in the input str
28810 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67  ing <i>including
28820 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d  </i>.** the nul-
28830 74 65 72 6d 69 6e 61 74 6f 72 20 62 79 74 65 73  terminator bytes
28840 20 61 73 20 74 68 69 73 20 73 61 76 65 73 20 53   as this saves S
28850 51 4c 69 74 65 20 66 72 6f 6d 20 68 61 76 69 6e  QLite from havin
28860 67 20 74 6f 0a 2a 2a 20 6d 61 6b 65 20 61 20 63  g to.** make a c
28870 6f 70 79 20 6f 66 20 74 68 65 20 69 6e 70 75 74  opy of the input
28880 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e   string..**.** ^
28890 49 66 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74  If pzTail is not
288a0 20 4e 55 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61   NULL then *pzTa
288b0 69 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f  il is made to po
288c0 69 6e 74 20 74 6f 20 74 68 65 20 66 69 72 73 74  int to the first
288d0 20 62 79 74 65 0a 2a 2a 20 70 61 73 74 20 74 68   byte.** past th
288e0 65 20 65 6e 64 20 6f 66 20 74 68 65 20 66 69 72  e end of the fir
288f0 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  st SQL statement
28900 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73 65   in zSql.  These
28910 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a   routines only.*
28920 2a 20 63 6f 6d 70 69 6c 65 20 74 68 65 20 66 69  * compile the fi
28930 72 73 74 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  rst statement in
28940 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69   zSql, so *pzTai
28950 6c 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69  l is left pointi
28960 6e 67 20 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65  ng to.** what re
28970 6d 61 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64  mains uncompiled
28980 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74  ..**.** ^*ppStmt
28990 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e   is left pointin
289a0 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20  g to a compiled 
289b0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
289c0 65 6e 74 5d 20 74 68 61 74 20 63 61 6e 20 62 65  ent] that can be
289d0 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 75 73 69  .** executed usi
289e0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ng [sqlite3_step
289f0 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 72 65 20  ()].  ^If there 
28a00 69 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70  is an error, *pp
28a10 53 74 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20 74  Stmt is set.** t
28a20 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65  o NULL.  ^If the
28a30 20 69 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74   input text cont
28a40 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66 20  ains no SQL (if 
28a50 74 68 65 20 69 6e 70 75 74 20 69 73 20 61 6e 20  the input is an 
28a60 65 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20  empty.** string 
28a70 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68  or a comment) th
28a80 65 6e 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65  en *ppStmt is se
28a90 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68  t to NULL..** Th
28aa0 65 20 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64  e calling proced
28ab0 75 72 65 20 69 73 20 72 65 73 70 6f 6e 73 69 62  ure is responsib
28ac0 6c 65 20 66 6f 72 20 64 65 6c 65 74 69 6e 67 20  le for deleting 
28ad0 74 68 65 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20  the compiled.** 
28ae0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 75 73  SQL statement us
28af0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  ing [sqlite3_fin
28b00 61 6c 69 7a 65 28 29 5d 20 61 66 74 65 72 20 69  alize()] after i
28b10 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77  t has finished w
28b20 69 74 68 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d  ith it..** ppStm
28b30 74 20 6d 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c  t may not be NUL
28b40 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63  L..**.** ^On suc
28b50 63 65 73 73 2c 20 74 68 65 20 73 71 6c 69 74 65  cess, the sqlite
28b60 33 5f 70 72 65 70 61 72 65 28 29 20 66 61 6d 69  3_prepare() fami
28b70 6c 79 20 6f 66 20 72 6f 75 74 69 6e 65 73 20 72  ly of routines r
28b80 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b  eturn [SQLITE_OK
28b90 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 20  ];.** otherwise 
28ba0 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  an [error code] 
28bb0 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
28bc0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70  ** The sqlite3_p
28bd0 72 65 70 61 72 65 5f 76 32 28 29 20 61 6e 64 20  repare_v2() and 
28be0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
28bf0 36 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65  6_v2() interface
28c00 73 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65  s are.** recomme
28c10 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77  nded for all new
28c20 20 70 72 6f 67 72 61 6d 73 2e 20 54 68 65 20 74   programs. The t
28c30 77 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72 66 61  wo older interfa
28c40 63 65 73 20 61 72 65 20 72 65 74 61 69 6e 65 64  ces are retained
28c50 0a 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61 72 64  .** for backward
28c60 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c  s compatibility,
28c70 20 62 75 74 20 74 68 65 69 72 20 75 73 65 20 69   but their use i
28c80 73 20 64 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a  s discouraged..*
28c90 2a 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69  * ^In the "v2" i
28ca0 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 70  nterfaces, the p
28cb0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
28cc0 74 0a 2a 2a 20 74 68 61 74 20 69 73 20 72 65 74  t.** that is ret
28cd0 75 72 6e 65 64 20 28 74 68 65 20 5b 73 71 6c 69  urned (the [sqli
28ce0 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74  te3_stmt] object
28cf0 29 20 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70  ) contains a cop
28d00 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67  y of the.** orig
28d10 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e 20 54  inal SQL text. T
28d20 68 69 73 20 63 61 75 73 65 73 20 74 68 65 20 5b  his causes the [
28d30 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
28d40 69 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20  interface to.** 
28d50 62 65 68 61 76 65 20 64 69 66 66 65 72 65 6e 74  behave different
28d60 6c 79 20 69 6e 20 74 68 72 65 65 20 77 61 79 73  ly in three ways
28d70 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20  :.**.** <ol>.** 
28d80 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  <li>.** ^If the 
28d90 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 20  database schema 
28da0 63 68 61 6e 67 65 73 2c 20 69 6e 73 74 65 61 64  changes, instead
28db0 20 6f 66 20 72 65 74 75 72 6e 69 6e 67 20 5b 53   of returning [S
28dc0 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 61 73  QLITE_SCHEMA] as
28dd0 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73   it.** always us
28de0 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74  ed to do, [sqlit
28df0 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20  e3_step()] will 
28e00 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65  automatically re
28e10 63 6f 6d 70 69 6c 65 20 74 68 65 20 53 51 4c 0a  compile the SQL.
28e20 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64  ** statement and
28e30 20 74 72 79 20 74 6f 20 72 75 6e 20 69 74 20 61   try to run it a
28e40 67 61 69 6e 2e 20 41 73 20 6d 61 6e 79 20 61 73  gain. As many as
28e50 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 53 43 48   [SQLITE_MAX_SCH
28e60 45 4d 41 5f 52 45 54 52 59 5d 0a 2a 2a 20 72 65  EMA_RETRY].** re
28e70 74 72 69 65 73 20 77 69 6c 6c 20 6f 63 63 75 72  tries will occur
28e80 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f   before sqlite3_
28e90 73 74 65 70 28 29 20 67 69 76 65 73 20 75 70 20  step() gives up 
28ea0 61 6e 64 20 72 65 74 75 72 6e 73 20 61 6e 20 65  and returns an e
28eb0 72 72 6f 72 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a  rror..** </li>.*
28ec0 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68  *.** <li>.** ^Wh
28ed0 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75  en an error occu
28ee0 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  rs, [sqlite3_ste
28ef0 70 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  p()] will return
28f00 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 74 61   one of the deta
28f10 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63  iled.** [error c
28f20 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64  odes] or [extend
28f30 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e  ed error codes].
28f40 20 20 5e 54 68 65 20 6c 65 67 61 63 79 20 62 65    ^The legacy be
28f50 68 61 76 69 6f 72 20 77 61 73 20 74 68 61 74 0a  havior was that.
28f60 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
28f70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72  ()] would only r
28f80 65 74 75 72 6e 20 61 20 67 65 6e 65 72 69 63 20  eturn a generic 
28f90 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72  [SQLITE_ERROR] r
28fa0 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e  esult code.** an
28fb0 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  d the applicatio
28fc0 6e 20 77 6f 75 6c 64 20 68 61 76 65 20 74 6f 20  n would have to 
28fd0 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64 20 63 61  make a second ca
28fe0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  ll to [sqlite3_r
28ff0 65 73 65 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72  eset()].** in or
29000 64 65 72 20 74 6f 20 66 69 6e 64 20 74 68 65 20  der to find the 
29010 75 6e 64 65 72 6c 79 69 6e 67 20 63 61 75 73 65  underlying cause
29020 20 6f 66 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e   of the problem.
29030 20 57 69 74 68 20 74 68 65 20 22 76 32 22 20 70   With the "v2" p
29040 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66  repare.** interf
29050 61 63 65 73 2c 20 74 68 65 20 75 6e 64 65 72 6c  aces, the underl
29060 79 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72 20  ying reason for 
29070 74 68 65 20 65 72 72 6f 72 20 69 73 20 72 65 74  the error is ret
29080 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c  urned immediatel
29090 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a  y..** </li>.**.*
290a0 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68  * <li>.** ^If th
290b0 65 20 73 70 65 63 69 66 69 63 20 76 61 6c 75 65  e specific value
290c0 20 62 6f 75 6e 64 20 74 6f 20 5b 70 61 72 61 6d   bound to [param
290d0 65 74 65 72 20 7c 20 68 6f 73 74 20 70 61 72 61  eter | host para
290e0 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20 0a 2a  meter] in the .*
290f0 2a 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 6d  * WHERE clause m
29100 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74  ight influence t
29110 68 65 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65  he choice of que
29120 72 79 20 70 6c 61 6e 20 66 6f 72 20 61 20 73 74  ry plan for a st
29130 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e  atement,.** then
29140 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77   the statement w
29150 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63  ill be automatic
29160 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 64 2c  ally recompiled,
29170 20 61 73 20 69 66 20 74 68 65 72 65 20 68 61 64   as if there had
29180 20 62 65 65 6e 20 0a 2a 2a 20 61 20 73 63 68 65   been .** a sche
29190 6d 61 20 63 68 61 6e 67 65 2c 20 6f 6e 20 74 68  ma change, on th
291a0 65 20 66 69 72 73 74 20 20 5b 73 71 6c 69 74 65  e first  [sqlite
291b0 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 66  3_step()] call f
291c0 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 63 68 61  ollowing any cha
291d0 6e 67 65 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73  nge.** to the [s
291e0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
291f0 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20   | bindings] of 
29200 74 68 61 74 20 5b 70 61 72 61 6d 65 74 65 72 5d  that [parameter]
29210 2e 20 0a 2a 2a 20 5e 54 68 65 20 73 70 65 63 69  . .** ^The speci
29220 66 69 63 20 76 61 6c 75 65 20 6f 66 20 57 48 45  fic value of WHE
29230 52 45 2d 63 6c 61 75 73 65 20 5b 70 61 72 61 6d  RE-clause [param
29240 65 74 65 72 5d 20 6d 69 67 68 74 20 69 6e 66 6c  eter] might infl
29250 75 65 6e 63 65 20 74 68 65 20 0a 2a 2a 20 63 68  uence the .** ch
29260 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c  oice of query pl
29270 61 6e 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  an if the parame
29280 74 65 72 20 69 73 20 74 68 65 20 6c 65 66 74 2d  ter is the left-
29290 68 61 6e 64 20 73 69 64 65 20 6f 66 20 61 20 5b  hand side of a [
292a0 4c 49 4b 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f  LIKE].** or [GLO
292b0 42 5d 20 6f 70 65 72 61 74 6f 72 20 6f 72 20 69  B] operator or i
292c0 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
292d0 69 73 20 63 6f 6d 70 61 72 65 64 20 74 6f 20 61  is compared to a
292e0 6e 20 69 6e 64 65 78 65 64 20 63 6f 6c 75 6d 6e  n indexed column
292f0 0a 2a 2a 20 61 6e 64 20 74 68 65 20 5b 53 51 4c  .** and the [SQL
29300 49 54 45 5f 45 4e 41 42 4c 45 5f 53 54 41 54 33  ITE_ENABLE_STAT3
29310 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
29320 70 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64  ption is enabled
29330 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f  ..** </li>.** </
29340 6f 6c 3e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ol>.*/.SQLITE_AP
29350 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72  I int sqlite3_pr
29360 65 70 61 72 65 28 0a 20 20 73 71 6c 69 74 65 33  epare(.  sqlite3
29370 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
29380 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
29390 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
293a0 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  har *zSql,      
293b0 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
293c0 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64  t, UTF-8 encoded
293d0 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
293e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
293f0 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
29400 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
29410 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
29420 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
29430 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
29440 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
29450 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c  st char **pzTail
29460 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
29470 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
29480 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
29490 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  /.);.SQLITE_API 
294a0 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70  int sqlite3_prep
294b0 61 72 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65  are_v2(.  sqlite
294c0 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
294d0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
294e0 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
294f0 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20  char *zSql,     
29500 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
29510 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  nt, UTF-8 encode
29520 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
29530 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
29540 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
29550 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
29560 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
29570 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
29580 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
29590 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
295a0 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69  nst char **pzTai
295b0 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
295c0 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
295d0 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
295e0 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  */.);.SQLITE_API
295f0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65   int sqlite3_pre
29600 70 61 72 65 31 36 28 0a 20 20 73 71 6c 69 74 65  pare16(.  sqlite
29610 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
29620 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
29630 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
29640 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20  void *zSql,     
29650 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
29660 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64  nt, UTF-16 encod
29670 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
29680 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
29690 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
296a0 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
296b0 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  es. */.  sqlite3
296c0 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
296d0 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
296e0 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
296f0 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61  onst void **pzTa
29700 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
29710 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
29720 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
29730 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50   */.);.SQLITE_AP
29740 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72  I int sqlite3_pr
29750 65 70 61 72 65 31 36 5f 76 32 28 0a 20 20 73 71  epare16_v2(.  sq
29760 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
29770 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
29780 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
29790 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20  nst void *zSql, 
297a0 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
297b0 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65  tement, UTF-16 e
297c0 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
297d0 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
297e0 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
297f0 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
29800 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
29810 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
29820 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
29830 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
29840 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a  .  const void **
29850 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
29860 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
29870 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
29880 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a  zSql */.);../*.*
29890 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 74 72  * CAPI3REF: Retr
298a0 69 65 76 69 6e 67 20 53 74 61 74 65 6d 65 6e 74  ieving Statement
298b0 20 53 51 4c 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73   SQL.**.** ^This
298c0 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62   interface can b
298d0 65 20 75 73 65 64 20 74 6f 20 72 65 74 72 69 65  e used to retrie
298e0 76 65 20 61 20 73 61 76 65 64 20 63 6f 70 79 20  ve a saved copy 
298f0 6f 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a  of the original.
29900 2a 2a 20 53 51 4c 20 74 65 78 74 20 75 73 65 64  ** SQL text used
29910 20 74 6f 20 63 72 65 61 74 65 20 61 20 5b 70 72   to create a [pr
29920 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
29930 5d 20 69 66 20 74 68 61 74 20 73 74 61 74 65 6d  ] if that statem
29940 65 6e 74 20 77 61 73 0a 2a 2a 20 63 6f 6d 70 69  ent was.** compi
29950 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72  led using either
29960 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
29970 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69  e_v2()] or [sqli
29980 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
29990 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ()]..*/.SQLITE_A
299a0 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  PI const char *s
299b0 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 74  qlite3_sql(sqlit
299c0 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
299d0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
299e0 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41  : Determine If A
299f0 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20  n SQL Statement 
29a00 57 72 69 74 65 73 20 54 68 65 20 44 61 74 61 62  Writes The Datab
29a10 61 73 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ase.**.** ^The s
29a20 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64  qlite3_stmt_read
29a30 6f 6e 6c 79 28 58 29 20 69 6e 74 65 72 66 61 63  only(X) interfac
29a40 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28  e returns true (
29a50 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 0a 2a 2a 20  non-zero) if.** 
29a60 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20  and only if the 
29a70 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
29a80 65 6e 74 5d 20 58 20 6d 61 6b 65 73 20 6e 6f 20  ent] X makes no 
29a90 64 69 72 65 63 74 20 63 68 61 6e 67 65 73 20 74  direct changes t
29aa0 6f 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74  o.** the content
29ab0 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
29ac0 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74   file..**.** Not
29ad0 65 20 74 68 61 74 20 5b 61 70 70 6c 69 63 61 74  e that [applicat
29ae0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
29af0 66 75 6e 63 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a  functions] or.**
29b00 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73   [virtual tables
29b10 5d 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 74  ] might change t
29b20 68 65 20 64 61 74 61 62 61 73 65 20 69 6e 64 69  he database indi
29b30 72 65 63 74 6c 79 20 61 73 20 61 20 73 69 64 65  rectly as a side
29b40 20 65 66 66 65 63 74 2e 20 20 0a 2a 2a 20 5e 28   effect.  .** ^(
29b50 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 66 20  For example, if 
29b60 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  an application d
29b70 65 66 69 6e 65 73 20 61 20 66 75 6e 63 74 69 6f  efines a functio
29b80 6e 20 22 65 76 61 6c 28 29 22 20 74 68 61 74 20  n "eval()" that 
29b90 0a 2a 2a 20 63 61 6c 6c 73 20 5b 73 71 6c 69 74  .** calls [sqlit
29ba0 65 33 5f 65 78 65 63 28 29 5d 2c 20 74 68 65 6e  e3_exec()], then
29bb0 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53   the following S
29bc0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 6f 75  QL statement wou
29bd0 6c 64 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65  ld.** change the
29be0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74   database file t
29bf0 68 72 6f 75 67 68 20 73 69 64 65 2d 65 66 66 65  hrough side-effe
29c00 63 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  cts:.**.** <bloc
29c10 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
29c20 20 20 20 53 45 4c 45 43 54 20 65 76 61 6c 28 27     SELECT eval('
29c30 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 31 27 29  DELETE FROM t1')
29c40 20 46 52 4f 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70   FROM t2;.** </p
29c50 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
29c60 0a 2a 2a 0a 2a 2a 20 42 75 74 20 62 65 63 61 75  .**.** But becau
29c70 73 65 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20  se the [SELECT] 
29c80 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e  statement does n
29c90 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 64 61  ot change the da
29ca0 74 61 62 61 73 65 20 66 69 6c 65 0a 2a 2a 20 64  tabase file.** d
29cb0 69 72 65 63 74 6c 79 2c 20 73 71 6c 69 74 65 33  irectly, sqlite3
29cc0 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29  _stmt_readonly()
29cd0 20 77 6f 75 6c 64 20 73 74 69 6c 6c 20 72 65 74   would still ret
29ce0 75 72 6e 20 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a  urn true.)^.**.*
29cf0 2a 20 5e 54 72 61 6e 73 61 63 74 69 6f 6e 20 63  * ^Transaction c
29d00 6f 6e 74 72 6f 6c 20 73 74 61 74 65 6d 65 6e 74  ontrol statement
29d10 73 20 73 75 63 68 20 61 73 20 5b 42 45 47 49 4e  s such as [BEGIN
29d20 5d 2c 20 5b 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f  ], [COMMIT], [RO
29d30 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56  LLBACK],.** [SAV
29d40 45 50 4f 49 4e 54 5d 2c 20 61 6e 64 20 5b 52 45  EPOINT], and [RE
29d50 4c 45 41 53 45 5d 20 63 61 75 73 65 20 73 71 6c  LEASE] cause sql
29d60 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e  ite3_stmt_readon
29d70 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74  ly() to return t
29d80 72 75 65 2c 0a 2a 2a 20 73 69 6e 63 65 20 74 68  rue,.** since th
29d90 65 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 65  e statements the
29da0 6d 73 65 6c 76 65 73 20 64 6f 20 6e 6f 74 20 61  mselves do not a
29db0 63 74 75 61 6c 6c 79 20 6d 6f 64 69 66 79 20 74  ctually modify t
29dc0 68 65 20 64 61 74 61 62 61 73 65 20 62 75 74 0a  he database but.
29dd0 2a 2a 20 72 61 74 68 65 72 20 74 68 65 79 20 63  ** rather they c
29de0 6f 6e 74 72 6f 6c 20 74 68 65 20 74 69 6d 69 6e  ontrol the timin
29df0 67 20 6f 66 20 77 68 65 6e 20 6f 74 68 65 72 20  g of when other 
29e00 73 74 61 74 65 6d 65 6e 74 73 20 6d 6f 64 69 66  statements modif
29e10 79 20 74 68 65 20 0a 2a 2a 20 64 61 74 61 62 61  y the .** databa
29e20 73 65 2e 20 20 5e 54 68 65 20 5b 41 54 54 41 43  se.  ^The [ATTAC
29e30 48 5d 20 61 6e 64 20 5b 44 45 54 41 43 48 5d 20  H] and [DETACH] 
29e40 73 74 61 74 65 6d 65 6e 74 73 20 61 6c 73 6f 20  statements also 
29e50 63 61 75 73 65 0a 2a 2a 20 73 71 6c 69 74 65 33  cause.** sqlite3
29e60 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29  _stmt_readonly()
29e70 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65 20   to return true 
29e80 73 69 6e 63 65 2c 20 77 68 69 6c 65 20 74 68 6f  since, while tho
29e90 73 65 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  se statements.**
29ea0 20 63 68 61 6e 67 65 20 74 68 65 20 63 6f 6e 66   change the conf
29eb0 69 67 75 72 61 74 69 6f 6e 20 6f 66 20 61 20 64  iguration of a d
29ec0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
29ed0 6f 6e 2c 20 74 68 65 79 20 64 6f 20 6e 6f 74 20  on, they do not 
29ee0 6d 61 6b 65 20 0a 2a 2a 20 63 68 61 6e 67 65 73  make .** changes
29ef0 20 74 6f 20 74 68 65 20 63 6f 6e 74 65 6e 74 20   to the content 
29f00 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
29f10 66 69 6c 65 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a  files on disk..*
29f20 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
29f30 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65   sqlite3_stmt_re
29f40 61 64 6f 6e 6c 79 28 73 71 6c 69 74 65 33 5f 73  adonly(sqlite3_s
29f50 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
29f60 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
29f70 74 65 72 6d 69 6e 65 20 49 66 20 41 20 50 72 65  termine If A Pre
29f80 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20  pared Statement 
29f90 48 61 73 20 42 65 65 6e 20 52 65 73 65 74 0a 2a  Has Been Reset.*
29fa0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
29fb0 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 20 69  3_stmt_busy(S) i
29fc0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
29fd0 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29   true (non-zero)
29fe0 20 69 66 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70   if the.** [prep
29ff0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2a000 53 20 68 61 73 20 62 65 65 6e 20 73 74 65 70 70  S has been stepp
2a010 65 64 20 61 74 20 6c 65 61 73 74 20 6f 6e 63 65  ed at least once
2a020 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69   using .** [sqli
2a030 74 65 33 5f 73 74 65 70 28 53 29 5d 20 62 75 74  te3_step(S)] but
2a040 20 68 61 73 20 6e 6f 74 20 72 75 6e 20 74 6f 20   has not run to 
2a050 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 6e 64 2f 6f  completion and/o
2a060 72 20 68 61 73 20 6e 6f 74 20 0a 2a 2a 20 62 65  r has not .** be
2a070 65 6e 20 72 65 73 65 74 20 75 73 69 6e 67 20 5b  en reset using [
2a080 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
2a090 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  ].  ^The sqlite3
2a0a0 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 0a 2a 2a  _stmt_busy(S).**
2a0b0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2a0c0 6e 73 20 66 61 6c 73 65 20 69 66 20 53 20 69 73  ns false if S is
2a0d0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
2a0e0 20 20 49 66 20 53 20 69 73 20 6e 6f 74 20 61 20    If S is not a 
2a0f0 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  .** NULL pointer
2a100 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 6f   and is not a po
2a110 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c 69 64  inter to a valid
2a120 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2a130 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2c  ment].** object,
2a140 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
2a150 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20  or is undefined 
2a160 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 75 6e 64  and probably und
2a170 65 73 69 72 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20  esirable..**.** 
2a180 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63  This interface c
2a190 61 6e 20 62 65 20 75 73 65 64 20 69 6e 20 63 6f  an be used in co
2a1a0 6d 62 69 6e 61 74 69 6f 6e 20 5b 73 71 6c 69 74  mbination [sqlit
2a1b0 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 29 5d 0a  e3_next_stmt()].
2a1c0 2a 2a 20 74 6f 20 6c 6f 63 61 74 65 20 61 6c 6c  ** to locate all
2a1d0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2a1e0 65 6e 74 73 20 61 73 73 6f 63 69 61 74 65 64 20  ents associated 
2a1f0 77 69 74 68 20 61 20 64 61 74 61 62 61 73 65 20  with a database 
2a200 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  .** connection t
2a210 68 61 74 20 61 72 65 20 69 6e 20 6e 65 65 64 20  hat are in need 
2a220 6f 66 20 62 65 69 6e 67 20 72 65 73 65 74 2e 20  of being reset. 
2a230 20 54 68 69 73 20 63 61 6e 20 62 65 20 75 73 65   This can be use
2a240 64 2c 0a 2a 2a 20 66 6f 72 20 65 78 61 6d 70 6c  d,.** for exampl
2a250 65 2c 20 69 6e 20 64 69 61 67 6e 6f 73 74 69 63  e, in diagnostic
2a260 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 73 65 61   routines to sea
2a270 72 63 68 20 66 6f 72 20 70 72 65 70 61 72 65 64  rch for prepared
2a280 20 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20   .** statements 
2a290 74 68 61 74 20 61 72 65 20 68 6f 6c 64 69 6e 67  that are holding
2a2a0 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 6f   a transaction o
2a2b0 70 65 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  pen..*/.SQLITE_A
2a2c0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  PI int sqlite3_s
2a2d0 74 6d 74 5f 62 75 73 79 28 73 71 6c 69 74 65 33  tmt_busy(sqlite3
2a2e0 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _stmt*);../*.** 
2a2f0 43 41 50 49 33 52 45 46 3a 20 44 79 6e 61 6d 69  CAPI3REF: Dynami
2a300 63 61 6c 6c 79 20 54 79 70 65 64 20 56 61 6c 75  cally Typed Valu
2a310 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57  e Object.** KEYW
2a320 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63 74 65 64  ORDS: {protected
2a330 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 20   sqlite3_value} 
2a340 7b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  {unprotected sql
2a350 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a  ite3_value}.**.*
2a360 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 74 68  * SQLite uses th
2a370 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  e sqlite3_value 
2a380 6f 62 6a 65 63 74 20 74 6f 20 72 65 70 72 65 73  object to repres
2a390 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a  ent all values.*
2a3a0 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 73 74  * that can be st
2a3b0 6f 72 65 64 20 69 6e 20 61 20 64 61 74 61 62 61  ored in a databa
2a3c0 73 65 20 74 61 62 6c 65 2e 20 53 51 4c 69 74 65  se table. SQLite
2a3d0 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 74 79   uses dynamic ty
2a3e0 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 68 65 20  ping.** for the 
2a3f0 76 61 6c 75 65 73 20 69 74 20 73 74 6f 72 65 73  values it stores
2a400 2e 20 20 5e 56 61 6c 75 65 73 20 73 74 6f 72 65  .  ^Values store
2a410 64 20 69 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c  d in sqlite3_val
2a420 75 65 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 63 61  ue objects.** ca
2a430 6e 20 62 65 20 69 6e 74 65 67 65 72 73 2c 20 66  n be integers, f
2a440 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61  loating point va
2a450 6c 75 65 73 2c 20 73 74 72 69 6e 67 73 2c 20 42  lues, strings, B
2a460 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a  LOBs, or NULL..*
2a470 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33 5f  *.** An sqlite3_
2a480 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61 79  value object may
2a490 20 62 65 20 65 69 74 68 65 72 20 22 70 72 6f 74   be either "prot
2a4a0 65 63 74 65 64 22 20 6f 72 20 22 75 6e 70 72 6f  ected" or "unpro
2a4b0 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65  tected"..** Some
2a4c0 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75   interfaces requ
2a4d0 69 72 65 20 61 20 70 72 6f 74 65 63 74 65 64 20  ire a protected 
2a4e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20  sqlite3_value.  
2a4f0 4f 74 68 65 72 20 69 6e 74 65 72 66 61 63 65 73  Other interfaces
2a500 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70 74 20  .** will accept 
2a510 65 69 74 68 65 72 20 61 20 70 72 6f 74 65 63 74  either a protect
2a520 65 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65  ed or an unprote
2a530 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2a540 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e 74  ue..** Every int
2a550 65 72 66 61 63 65 20 74 68 61 74 20 61 63 63 65  erface that acce
2a560 70 74 73 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  pts sqlite3_valu
2a570 65 20 61 72 67 75 6d 65 6e 74 73 20 73 70 65 63  e arguments spec
2a580 69 66 69 65 73 0a 2a 2a 20 77 68 65 74 68 65 72  ifies.** whether
2a590 20 6f 72 20 6e 6f 74 20 69 74 20 72 65 71 75 69   or not it requi
2a5a0 72 65 73 20 61 20 70 72 6f 74 65 63 74 65 64 20  res a protected 
2a5b0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a  sqlite3_value..*
2a5c0 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73 20 22  *.** The terms "
2a5d0 70 72 6f 74 65 63 74 65 64 22 20 61 6e 64 20 22  protected" and "
2a5e0 75 6e 70 72 6f 74 65 63 74 65 64 22 20 72 65 66  unprotected" ref
2a5f0 65 72 20 74 6f 20 77 68 65 74 68 65 72 20 6f 72  er to whether or
2a600 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20   not.** a mutex 
2a610 69 73 20 68 65 6c 64 2e 20 20 41 6e 20 69 6e 74  is held.  An int
2a620 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 73 20 68  ernal mutex is h
2a630 65 6c 64 20 66 6f 72 20 61 20 70 72 6f 74 65 63  eld for a protec
2a640 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  ted.** sqlite3_v
2a650 61 6c 75 65 20 6f 62 6a 65 63 74 20 62 75 74 20  alue object but 
2a660 6e 6f 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64  no mutex is held
2a670 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63   for an unprotec
2a680 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  ted.** sqlite3_v
2a690 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20 49 66  alue object.  If
2a6a0 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
2a6b0 6c 65 64 20 74 6f 20 62 65 20 73 69 6e 67 6c 65  led to be single
2a6c0 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 28 77 69  -threaded.** (wi
2a6d0 74 68 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  th [SQLITE_THREA
2a6e0 44 53 41 46 45 3d 30 5d 20 61 6e 64 20 77 69 74  DSAFE=0] and wit
2a6f0 68 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61  h [sqlite3_threa
2a700 64 73 61 66 65 28 29 5d 20 72 65 74 75 72 6e 69  dsafe()] returni
2a710 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53  ng 0).** or if S
2a720 51 4c 69 74 65 20 69 73 20 72 75 6e 20 69 6e 20  QLite is run in 
2a730 6f 6e 65 20 6f 66 20 72 65 64 75 63 65 64 20 6d  one of reduced m
2a740 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b  utex modes .** [
2a750 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
2a760 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f 72 20 5b  NGLETHREAD] or [
2a770 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
2a780 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68  LTITHREAD].** th
2a790 65 6e 20 74 68 65 72 65 20 69 73 20 6e 6f 20 64  en there is no d
2a7a0 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65  istinction betwe
2a7b0 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64  en protected and
2a7c0 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20   unprotected.** 
2a7d0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
2a7e0 6a 65 63 74 73 20 61 6e 64 20 74 68 65 79 20 63  jects and they c
2a7f0 61 6e 20 62 65 20 75 73 65 64 20 69 6e 74 65 72  an be used inter
2a800 63 68 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77  changeably.  How
2a810 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78  ever,.** for max
2a820 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74 61 62  imum code portab
2a830 69 6c 69 74 79 20 69 74 20 69 73 20 72 65 63 6f  ility it is reco
2a840 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70  mmended that app
2a850 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69  lications.** sti
2a860 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74  ll make the dist
2a870 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20  inction between 
2a880 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e  protected and un
2a890 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
2a8a0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
2a8b0 74 73 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74  ts even when not
2a8c0 20 73 74 72 69 63 74 6c 79 20 72 65 71 75 69 72   strictly requir
2a8d0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
2a8e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
2a8f0 65 63 74 73 20 74 68 61 74 20 61 72 65 20 70 61  ects that are pa
2a900 73 73 65 64 20 61 73 20 70 61 72 61 6d 65 74 65  ssed as paramete
2a910 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69  rs into the.** i
2a920 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
2a930 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   [application-de
2a940 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
2a950 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74 65 63 74  ons] are protect
2a960 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  ed..** ^The sqli
2a970 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
2a980 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
2a990 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2a9a0 76 61 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 72  value()] is unpr
2a9b0 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72  otected..** Unpr
2a9c0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2a9d0 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d 61  value objects ma
2a9e0 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77  y only be used w
2a9f0 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ith.** [sqlite3_
2aa00 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20  result_value()] 
2aa10 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  and [sqlite3_bin
2aa20 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54  d_value()]..** T
2aa30 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
2aa40 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33  e_blob | sqlite3
2aa50 5f 76 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 66  _value_type()] f
2aa60 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65  amily of.** inte
2aa70 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20 70  rfaces require p
2aa80 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2aa90 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a  _value objects..
2aaa0 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
2aab0 74 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76 61  t Mem sqlite3_va
2aac0 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  lue;../*.** CAPI
2aad0 33 52 45 46 3a 20 53 51 4c 20 46 75 6e 63 74 69  3REF: SQL Functi
2aae0 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63  on Context Objec
2aaf0 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74  t.**.** The cont
2ab00 65 78 74 20 69 6e 20 77 68 69 63 68 20 61 6e 20  ext in which an 
2ab10 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78 65  SQL function exe
2ab20 63 75 74 65 73 20 69 73 20 73 74 6f 72 65 64 20  cutes is stored 
2ab30 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33  in an.** sqlite3
2ab40 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e  _context object.
2ab50 20 20 5e 41 20 70 6f 69 6e 74 65 72 20 74 6f 20    ^A pointer to 
2ab60 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  an sqlite3_conte
2ab70 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20  xt object.** is 
2ab80 61 6c 77 61 79 73 20 66 69 72 73 74 20 70 61 72  always first par
2ab90 61 6d 65 74 65 72 20 74 6f 20 5b 61 70 70 6c 69  ameter to [appli
2aba0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
2abb0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a  QL functions]..*
2abc0 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
2abd0 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
2abe0 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
2abf0 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20  ation will pass 
2ac00 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  this.** pointer 
2ac10 74 68 72 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c  through into cal
2ac20 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  ls to [sqlite3_r
2ac30 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69  esult_int | sqli
2ac40 74 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a  te3_result()],.*
2ac50 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65  * [sqlite3_aggre
2ac60 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c  gate_context()],
2ac70 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64   [sqlite3_user_d
2ac80 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ata()],.** [sqli
2ac90 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68  te3_context_db_h
2aca0 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74  andle()], [sqlit
2acb0 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29  e3_get_auxdata()
2acc0 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71  ],.** and/or [sq
2acd0 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
2ace0 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  a()]..*/.typedef
2acf0 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
2ad00 63 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 33 5f  context sqlite3_
2ad10 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20  context;../*.** 
2ad20 43 41 50 49 33 52 45 46 3a 20 42 69 6e 64 69 6e  CAPI3REF: Bindin
2ad30 67 20 56 61 6c 75 65 73 20 54 6f 20 50 72 65 70  g Values To Prep
2ad40 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 73 0a  ared Statements.
2ad50 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68 6f  ** KEYWORDS: {ho
2ad60 73 74 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 68  st parameter} {h
2ad70 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 7d 20  ost parameters} 
2ad80 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20  {host parameter 
2ad90 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  name}.** KEYWORD
2ada0 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65  S: {SQL paramete
2adb0 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65  r} {SQL paramete
2adc0 72 73 7d 20 7b 70 61 72 61 6d 65 74 65 72 20 62  rs} {parameter b
2add0 69 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20 5e 28  inding}.**.** ^(
2ade0 49 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  In the SQL state
2adf0 6d 65 6e 74 20 74 65 78 74 20 69 6e 70 75 74 20  ment text input 
2ae00 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  to [sqlite3_prep
2ae10 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 69 74  are_v2()] and it
2ae20 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c  s variants,.** l
2ae30 69 74 65 72 61 6c 73 20 6d 61 79 20 62 65 20 72  iterals may be r
2ae40 65 70 6c 61 63 65 64 20 62 79 20 61 20 5b 70 61  eplaced by a [pa
2ae50 72 61 6d 65 74 65 72 5d 20 74 68 61 74 20 6d 61  rameter] that ma
2ae60 74 63 68 65 73 20 6f 6e 65 20 6f 66 20 66 6f 6c  tches one of fol
2ae70 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61  lowing.** templa
2ae80 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  tes:.**.** <ul>.
2ae90 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c  ** <li>  ?.** <l
2aea0 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e  i>  ?NNN.** <li>
2aeb0 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20    :VVV.** <li>  
2aec0 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56  @VVV.** <li>  $V
2aed0 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  VV.** </ul>.**.*
2aee0 2a 20 49 6e 20 74 68 65 20 74 65 6d 70 6c 61 74  * In the templat
2aef0 65 73 20 61 62 6f 76 65 2c 20 4e 4e 4e 20 72 65  es above, NNN re
2af00 70 72 65 73 65 6e 74 73 20 61 6e 20 69 6e 74 65  presents an inte
2af10 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20  ger literal,.** 
2af20 61 6e 64 20 56 56 56 20 72 65 70 72 65 73 65 6e  and VVV represen
2af30 74 73 20 61 6e 20 61 6c 70 68 61 6e 75 6d 65 72  ts an alphanumer
2af40 69 63 20 69 64 65 6e 74 69 66 69 65 72 2e 29 5e  ic identifier.)^
2af50 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20 6f 66    ^The values of
2af60 20 74 68 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65   these.** parame
2af70 74 65 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65  ters (also calle
2af80 64 20 22 68 6f 73 74 20 70 61 72 61 6d 65 74 65  d "host paramete
2af90 72 20 6e 61 6d 65 73 22 20 6f 72 20 22 53 51 4c  r names" or "SQL
2afa0 20 70 61 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a   parameters").**
2afb0 20 63 61 6e 20 62 65 20 73 65 74 20 75 73 69 6e   can be set usin
2afc0 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  g the sqlite3_bi
2afd0 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20  nd_*() routines 
2afe0 64 65 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a  defined here..**
2aff0 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61  .** ^The first a
2b000 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73  rgument to the s
2b010 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
2b020 72 6f 75 74 69 6e 65 73 20 69 73 20 61 6c 77 61  routines is alwa
2b030 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20  ys.** a pointer 
2b040 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
2b050 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65 74  stmt] object ret
2b060 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73  urned from.** [s
2b070 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2b080 32 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69  2()] or its vari
2b090 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ants..**.** ^The
2b0a0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
2b0b0 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66   is the index of
2b0c0 20 74 68 65 20 53 51 4c 20 70 61 72 61 6d 65 74   the SQL paramet
2b0d0 65 72 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a 2a  er to be set..**
2b0e0 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 53   ^The leftmost S
2b0f0 51 4c 20 70 61 72 61 6d 65 74 65 72 20 68 61 73  QL parameter has
2b100 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e 20   an index of 1. 
2b110 20 5e 57 68 65 6e 20 74 68 65 20 73 61 6d 65 20   ^When the same 
2b120 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61 72  named.** SQL par
2b130 61 6d 65 74 65 72 20 69 73 20 75 73 65 64 20 6d  ameter is used m
2b140 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73  ore than once, s
2b150 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71  econd and subseq
2b160 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e  uent.** occurren
2b170 63 65 73 20 68 61 76 65 20 74 68 65 20 73 61 6d  ces have the sam
2b180 65 20 69 6e 64 65 78 20 61 73 20 74 68 65 20 66  e index as the f
2b190 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63 65 2e  irst occurrence.
2b1a0 0a 2a 2a 20 5e 54 68 65 20 69 6e 64 65 78 20 66  .** ^The index f
2b1b0 6f 72 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74  or named paramet
2b1c0 65 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65  ers can be looke
2b1d0 64 20 75 70 20 75 73 69 6e 67 20 74 68 65 0a 2a  d up using the.*
2b1e0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
2b1f0 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
2b200 29 5d 20 41 50 49 20 69 66 20 64 65 73 69 72 65  )] API if desire
2b210 64 2e 20 20 5e 54 68 65 20 69 6e 64 65 78 0a 2a  d.  ^The index.*
2b220 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72  * for "?NNN" par
2b230 61 6d 65 74 65 72 73 20 69 73 20 74 68 65 20 76  ameters is the v
2b240 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20  alue of NNN..** 
2b250 5e 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d  ^The NNN value m
2b260 75 73 74 20 62 65 20 62 65 74 77 65 65 6e 20 31  ust be between 1
2b270 20 61 6e 64 20 74 68 65 20 5b 73 71 6c 69 74 65   and the [sqlite
2b280 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 70 61  3_limit()].** pa
2b290 72 61 6d 65 74 65 72 20 5b 53 51 4c 49 54 45 5f  rameter [SQLITE_
2b2a0 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e  LIMIT_VARIABLE_N
2b2b0 55 4d 42 45 52 5d 20 28 64 65 66 61 75 6c 74 20  UMBER] (default 
2b2c0 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a  value: 999)..**.
2b2d0 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61 72  ** ^The third ar
2b2e0 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 76 61  gument is the va
2b2f0 6c 75 65 20 74 6f 20 62 69 6e 64 20 74 6f 20 74  lue to bind to t
2b300 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  he parameter..**
2b310 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 70   ^If the third p
2b320 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
2b330 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 20  te3_bind_text() 
2b340 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  or sqlite3_bind_
2b350 74 65 78 74 31 36 28 29 0a 2a 2a 20 6f 72 20 73  text16().** or s
2b360 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
2b370 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  () is a NULL poi
2b380 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20 66 6f  nter then the fo
2b390 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 0a 2a  urth parameter.*
2b3a0 2a 20 69 73 20 69 67 6e 6f 72 65 64 20 61 6e 64  * is ignored and
2b3b0 20 74 68 65 20 65 6e 64 20 72 65 73 75 6c 74 20   the end result 
2b3c0 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 73  is the same as s
2b3d0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c  qlite3_bind_null
2b3e0 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74  ()..**.** ^(In t
2b3f0 68 6f 73 65 20 72 6f 75 74 69 6e 65 73 20 74 68  hose routines th
2b400 61 74 20 68 61 76 65 20 61 20 66 6f 75 72 74 68  at have a fourth
2b410 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 73 20 76   argument, its v
2b420 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e  alue is the.** n
2b430 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
2b440 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e  n the parameter.
2b450 20 20 54 6f 20 62 65 20 63 6c 65 61 72 3a 20 74    To be clear: t
2b460 68 65 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a  he value is the.
2b470 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e  ** number of <u>
2b480 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65  bytes</u> in the
2b490 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20   value, not the 
2b4a0 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63  number of charac
2b4b0 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74  ters.)^.** ^If t
2b4c0 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
2b4d0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ter to sqlite3_b
2b4e0 69 6e 64 5f 74 65 78 74 28 29 20 6f 72 20 73 71  ind_text() or sq
2b4f0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
2b500 36 28 29 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69  6().** is negati
2b510 76 65 2c 20 74 68 65 6e 20 74 68 65 20 6c 65 6e  ve, then the len
2b520 67 74 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e  gth of the strin
2b530 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  g is.** the numb
2b540 65 72 20 6f 66 20 62 79 74 65 73 20 75 70 20 74  er of bytes up t
2b550 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f  o the first zero
2b560 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 20   terminator..** 
2b570 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  If the fourth pa
2b580 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
2b590 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69  e3_bind_blob() i
2b5a0 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  s negative, then
2b5b0 0a 2a 2a 20 74 68 65 20 62 65 68 61 76 69 6f 72  .** the behavior
2b5c0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
2b5d0 2a 20 49 66 20 61 20 6e 6f 6e 2d 6e 65 67 61 74  * If a non-negat
2b5e0 69 76 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  ive fourth param
2b5f0 65 74 65 72 20 69 73 20 70 72 6f 76 69 64 65 64  eter is provided
2b600 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
2b610 5f 74 65 78 74 28 29 0a 2a 2a 20 6f 72 20 73 71  _text().** or sq
2b620 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
2b630 36 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62  6() or sqlite3_b
2b640 69 6e 64 5f 74 65 78 74 36 34 28 29 20 74 68 65  ind_text64() the
2b650 6e 0a 2a 2a 20 74 68 61 74 20 70 61 72 61 6d 65  n.** that parame
2b660 74 65 72 20 6d 75 73 74 20 62 65 20 74 68 65 20  ter must be the 
2b670 62 79 74 65 20 6f 66 66 73 65 74 0a 2a 2a 20 77  byte offset.** w
2b680 68 65 72 65 20 74 68 65 20 4e 55 4c 20 74 65 72  here the NUL ter
2b690 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64 20 6f 63  minator would oc
2b6a0 63 75 72 20 61 73 73 75 6d 69 6e 67 20 74 68 65  cur assuming the
2b6b0 20 73 74 72 69 6e 67 20 77 65 72 65 20 4e 55 4c   string were NUL
2b6c0 0a 2a 2a 20 74 65 72 6d 69 6e 61 74 65 64 2e 20  .** terminated. 
2b6d0 20 49 66 20 61 6e 79 20 4e 55 4c 20 63 68 61 72   If any NUL char
2b6e0 61 63 74 65 72 73 20 6f 63 63 75 72 20 61 74 20  acters occur at 
2b6f0 62 79 74 65 20 6f 66 66 73 65 74 73 20 6c 65 73  byte offsets les
2b700 73 20 74 68 61 6e 20 0a 2a 2a 20 74 68 65 20 76  s than .** the v
2b710 61 6c 75 65 20 6f 66 20 74 68 65 20 66 6f 75 72  alue of the four
2b720 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 68 65  th parameter the
2b730 6e 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20  n the resulting 
2b740 73 74 72 69 6e 67 20 76 61 6c 75 65 20 77 69 6c  string value wil
2b750 6c 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 65 6d 62  l.** contain emb
2b760 65 64 64 65 64 20 4e 55 4c 73 2e 20 20 54 68 65  edded NULs.  The
2b770 20 72 65 73 75 6c 74 20 6f 66 20 65 78 70 72 65   result of expre
2b780 73 73 69 6f 6e 73 20 69 6e 76 6f 6c 76 69 6e 67  ssions involving
2b790 20 73 74 72 69 6e 67 73 0a 2a 2a 20 77 69 74 68   strings.** with
2b7a0 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 69   embedded NULs i
2b7b0 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  s undefined..**.
2b7c0 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61 72  ** ^The fifth ar
2b7d0 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 42 4c  gument to the BL
2b7e0 4f 42 20 61 6e 64 20 73 74 72 69 6e 67 20 62 69  OB and string bi
2b7f0 6e 64 69 6e 67 20 69 6e 74 65 72 66 61 63 65 73  nding interfaces
2b800 0a 2a 2a 20 69 73 20 61 20 64 65 73 74 72 75 63  .** is a destruc
2b810 74 6f 72 20 75 73 65 64 20 74 6f 20 64 69 73 70  tor used to disp
2b820 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20  ose of the BLOB 
2b830 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66 74  or.** string aft
2b840 65 72 20 53 51 4c 69 74 65 20 68 61 73 20 66 69  er SQLite has fi
2b850 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 20  nished with it. 
2b860 20 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f 72   ^The destructor
2b870 20 69 73 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 6f   is called.** to
2b880 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20   dispose of the 
2b890 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 20 65  BLOB or string e
2b8a0 76 65 6e 20 69 66 20 74 68 65 20 63 61 6c 6c 20  ven if the call 
2b8b0 74 6f 20 62 69 6e 64 20 41 50 49 20 66 61 69 6c  to bind API fail
2b8c0 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69  s..** ^If the fi
2b8d0 66 74 68 20 61 72 67 75 6d 65 6e 74 20 69 73 0a  fth argument is.
2b8e0 2a 2a 20 74 68 65 20 73 70 65 63 69 61 6c 20 76  ** the special v
2b8f0 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53 54 41  alue [SQLITE_STA
2b900 54 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74  TIC], then SQLit
2b910 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74  e assumes that t
2b920 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  he.** informatio
2b930 6e 20 69 73 20 69 6e 20 73 74 61 74 69 63 2c 20  n is in static, 
2b940 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 63 65 20  unmanaged space 
2b950 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  and does not nee
2b960 64 20 74 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a  d to be freed..*
2b970 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74 68 20  * ^If the fifth 
2b980 61 72 67 75 6d 65 6e 74 20 68 61 73 20 74 68 65  argument has the
2b990 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54   value [SQLITE_T
2b9a0 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a  RANSIENT], then.
2b9b0 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20  ** SQLite makes 
2b9c0 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20  its own private 
2b9d0 63 6f 70 79 20 6f 66 20 74 68 65 20 64 61 74 61  copy of the data
2b9e0 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65   immediately, be
2b9f0 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69  fore.** the sqli
2ba00 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75  te3_bind_*() rou
2ba10 74 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a  tine returns..**
2ba20 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74 68 20 61  .** ^The sixth a
2ba30 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
2ba40 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29  e3_bind_text64()
2ba50 20 6d 75 73 74 20 62 65 20 6f 6e 65 20 6f 66 0a   must be one of.
2ba60 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d  ** [SQLITE_UTF8]
2ba70 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d  , [SQLITE_UTF16]
2ba80 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42  , [SQLITE_UTF16B
2ba90 45 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55  E], or [SQLITE_U
2baa0 54 46 31 36 4c 45 5d 0a 2a 2a 20 74 6f 20 73 70  TF16LE].** to sp
2bab0 65 63 69 66 79 20 74 68 65 20 65 6e 63 6f 64 69  ecify the encodi
2bac0 6e 67 20 6f 66 20 74 68 65 20 74 65 78 74 20 69  ng of the text i
2bad0 6e 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  n the third para
2bae0 6d 65 74 65 72 2e 20 20 49 66 0a 2a 2a 20 74 68  meter.  If.** th
2baf0 65 20 73 69 78 74 68 20 61 72 67 75 6d 65 6e 74  e sixth argument
2bb00 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
2bb10 5f 74 65 78 74 36 34 28 29 20 69 73 20 6e 6f 74  _text64() is not
2bb20 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 61   one of the.** a
2bb30 6c 6c 6f 77 65 64 20 76 61 6c 75 65 73 20 73 68  llowed values sh
2bb40 6f 77 6e 20 61 62 6f 76 65 2c 20 6f 72 20 69 66  own above, or if
2bb50 20 74 68 65 20 74 65 78 74 20 65 6e 63 6f 64 69   the text encodi
2bb60 6e 67 20 69 73 20 64 69 66 66 65 72 65 6e 74 0a  ng is different.
2bb70 2a 2a 20 66 72 6f 6d 20 74 68 65 20 65 6e 63 6f  ** from the enco
2bb80 64 69 6e 67 20 73 70 65 63 69 66 69 65 64 20 62  ding specified b
2bb90 79 20 74 68 65 20 73 69 78 74 68 20 70 61 72 61  y the sixth para
2bba0 6d 65 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20  meter, then the 
2bbb0 62 65 68 61 76 69 6f 72 0a 2a 2a 20 69 73 20 75  behavior.** is u
2bbc0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
2bbd0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e  ^The sqlite3_bin
2bbe0 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75  d_zeroblob() rou
2bbf0 74 69 6e 65 20 62 69 6e 64 73 20 61 20 42 4c 4f  tine binds a BLO
2bc00 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74 68  B of length N th
2bc10 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20  at.** is filled 
2bc20 77 69 74 68 20 7a 65 72 6f 65 73 2e 20 20 5e 41  with zeroes.  ^A
2bc30 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73 20 61   zeroblob uses a
2bc40 20 66 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66   fixed amount of
2bc50 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74   memory.** (just
2bc60 20 61 6e 20 69 6e 74 65 67 65 72 20 74 6f 20 68   an integer to h
2bc70 6f 6c 64 20 69 74 73 20 73 69 7a 65 29 20 77 68  old its size) wh
2bc80 69 6c 65 20 69 74 20 69 73 20 62 65 69 6e 67 20  ile it is being 
2bc90 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65  processed..** Ze
2bca0 72 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e 74 65  roblobs are inte
2bcb0 6e 64 65 64 20 74 6f 20 73 65 72 76 65 20 61 73  nded to serve as
2bcc0 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f   placeholders fo
2bcd0 72 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a  r BLOBs whose.**
2bce0 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74 65   content is late
2bcf0 72 20 77 72 69 74 74 65 6e 20 75 73 69 6e 67 0a  r written using.
2bd00 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  ** [sqlite3_blob
2bd10 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e  _open | incremen
2bd20 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f  tal BLOB I/O] ro
2bd30 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65  utines..** ^A ne
2bd40 67 61 74 69 76 65 20 76 61 6c 75 65 20 66 6f 72  gative value for
2bd50 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65   the zeroblob re
2bd60 73 75 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d  sults in a zero-
2bd70 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a  length BLOB..**.
2bd80 2a 2a 20 5e 49 66 20 61 6e 79 20 6f 66 20 74 68  ** ^If any of th
2bd90 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
2bda0 28 29 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  () routines are 
2bdb0 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55  called with a NU
2bdc0 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f  LL pointer.** fo
2bdd0 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  r the [prepared 
2bde0 73 74 61 74 65 6d 65 6e 74 5d 20 6f 72 20 77 69  statement] or wi
2bdf0 74 68 20 61 20 70 72 65 70 61 72 65 64 20 73 74  th a prepared st
2be00 61 74 65 6d 65 6e 74 20 66 6f 72 20 77 68 69 63  atement for whic
2be10 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74  h.** [sqlite3_st
2be20 65 70 28 29 5d 20 68 61 73 20 62 65 65 6e 20 63  ep()] has been c
2be30 61 6c 6c 65 64 20 6d 6f 72 65 20 72 65 63 65 6e  alled more recen
2be40 74 6c 79 20 74 68 61 6e 20 5b 73 71 6c 69 74 65  tly than [sqlite
2be50 33 5f 72 65 73 65 74 28 29 5d 2c 0a 2a 2a 20 74  3_reset()],.** t
2be60 68 65 6e 20 74 68 65 20 63 61 6c 6c 20 77 69 6c  hen the call wil
2be70 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  l return [SQLITE
2be80 5f 4d 49 53 55 53 45 5d 2e 20 20 49 66 20 61 6e  _MISUSE].  If an
2be90 79 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 28  y sqlite3_bind_(
2bea0 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 69 73 20  ).** routine is 
2beb0 70 61 73 73 65 64 20 61 20 5b 70 72 65 70 61 72  passed a [prepar
2bec0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
2bed0 61 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61  at has been fina
2bee0 6c 69 7a 65 64 2c 20 74 68 65 0a 2a 2a 20 72 65  lized, the.** re
2bef0 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65  sult is undefine
2bf00 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 68  d and probably h
2bf10 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42  armful..**.** ^B
2bf20 69 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f 74 20  indings are not 
2bf30 63 6c 65 61 72 65 64 20 62 79 20 74 68 65 20 5b  cleared by the [
2bf40 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2bf50 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e   routine..** ^Un
2bf60 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73  bound parameters
2bf70 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64   are interpreted
2bf80 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   as NULL..**.** 
2bf90 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e  ^The sqlite3_bin
2bfa0 64 5f 2a 20 72 6f 75 74 69 6e 65 73 20 72 65 74  d_* routines ret
2bfb0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  urn [SQLITE_OK] 
2bfc0 6f 6e 20 73 75 63 63 65 73 73 20 6f 72 20 61 6e  on success or an
2bfd0 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  .** [error code]
2bfe0 20 69 66 20 61 6e 79 74 68 69 6e 67 20 67 6f 65   if anything goe
2bff0 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51  s wrong..** ^[SQ
2c000 4c 49 54 45 5f 54 4f 4f 42 49 47 5d 20 6d 69 67  LITE_TOOBIG] mig
2c010 68 74 20 62 65 20 72 65 74 75 72 6e 65 64 20 69  ht be returned i
2c020 66 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 20  f the size of a 
2c030 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 0a 2a  string or BLOB.*
2c040 2a 20 65 78 63 65 65 64 73 20 6c 69 6d 69 74 73  * exceeds limits
2c050 20 69 6d 70 6f 73 65 64 20 62 79 20 5b 73 71 6c   imposed by [sql
2c060 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c  ite3_limit]([SQL
2c070 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48  ITE_LIMIT_LENGTH
2c080 5d 29 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45  ]) or.** [SQLITE
2c090 5f 4d 41 58 5f 4c 45 4e 47 54 48 5d 2e 0a 2a 2a  _MAX_LENGTH]..**
2c0a0 20 5e 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d   ^[SQLITE_RANGE]
2c0b0 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20   is returned if 
2c0c0 74 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  the parameter.**
2c0d0 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66   index is out of
2c0e0 20 72 61 6e 67 65 2e 20 20 5e 5b 53 51 4c 49 54   range.  ^[SQLIT
2c0f0 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75  E_NOMEM] is retu
2c100 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28 29  rned if malloc()
2c110 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53 65   fails..**.** Se
2c120 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
2c130 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2c140 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71  count()],.** [sq
2c150 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2c160 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e  eter_name()], an
2c170 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  d [sqlite3_bind_
2c180 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
2c190 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  )]..*/.SQLITE_AP
2c1a0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  I int sqlite3_bi
2c1b0 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  nd_blob(sqlite3_
2c1c0 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
2c1d0 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20  t void*, int n, 
2c1e0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
2c1f0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2c200 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
2c210 62 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  b64(sqlite3_stmt
2c220 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f  *, int, const vo
2c230 69 64 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e  id*, sqlite3_uin
2c240 74 36 34 2c 0a 20 20 20 20 20 20 20 20 20 20 20  t64,.           
2c250 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69               voi
2c260 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51  d(*)(void*));.SQ
2c270 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
2c280 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65  ite3_bind_double
2c290 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2c2a0 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 53 51  int, double);.SQ
2c2b0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
2c2c0 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71  ite3_bind_int(sq
2c2d0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2c2e0 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41  , int);.SQLITE_A
2c2f0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  PI int sqlite3_b
2c300 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 65  ind_int64(sqlite
2c310 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71  3_stmt*, int, sq
2c320 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 53 51  lite3_int64);.SQ
2c330 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
2c340 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73  ite3_bind_null(s
2c350 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2c360 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  t);.SQLITE_API i
2c370 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
2c380 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  text(sqlite3_stm
2c390 74 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61  t*,int,const cha
2c3a0 72 2a 2c 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76  r*,int,void(*)(v
2c3b0 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41  oid*));.SQLITE_A
2c3c0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  PI int sqlite3_b
2c3d0 69 6e 64 5f 74 65 78 74 31 36 28 73 71 6c 69 74  ind_text16(sqlit
2c3e0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
2c3f0 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c  onst void*, int,
2c400 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
2c410 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
2c420 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
2c430 78 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d  xt64(sqlite3_stm
2c440 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63  t*, int, const c
2c450 68 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69  har*, sqlite3_ui
2c460 6e 74 36 34 2c 0a 20 20 20 20 20 20 20 20 20 20  nt64,.          
2c470 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76                 v
2c480 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 2c 20 75  oid(*)(void*), u
2c490 6e 73 69 67 6e 65 64 20 63 68 61 72 20 65 6e 63  nsigned char enc
2c4a0 6f 64 69 6e 67 29 3b 0a 53 51 4c 49 54 45 5f 41  oding);.SQLITE_A
2c4b0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  PI int sqlite3_b
2c4c0 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69 74 65  ind_value(sqlite
2c4d0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
2c4e0 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  nst sqlite3_valu
2c4f0 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  e*);.SQLITE_API 
2c500 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
2c510 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65  _zeroblob(sqlite
2c520 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e  3_stmt*, int, in
2c530 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  t n);../*.** CAP
2c540 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66  I3REF: Number Of
2c550 20 53 51 4c 20 50 61 72 61 6d 65 74 65 72 73 0a   SQL Parameters.
2c560 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74  **.** ^This rout
2c570 69 6e 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ine can be used 
2c580 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62  to find the numb
2c590 65 72 20 6f 66 20 5b 53 51 4c 20 70 61 72 61 6d  er of [SQL param
2c5a0 65 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b  eters].** in a [
2c5b0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2c5c0 6e 74 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d 65  nt].  SQL parame
2c5d0 74 65 72 73 20 61 72 65 20 74 6f 6b 65 6e 73 20  ters are tokens 
2c5e0 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22  of the.** form "
2c5f0 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41  ?", "?NNN", ":AA
2c600 41 22 2c 20 22 24 41 41 41 22 2c 20 6f 72 20 22  A", "$AAA", or "
2c610 40 41 41 41 22 20 74 68 61 74 20 73 65 72 76 65  @AAA" that serve
2c620 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64   as.** placehold
2c630 65 72 73 20 66 6f 72 20 76 61 6c 75 65 73 20 74  ers for values t
2c640 68 61 74 20 61 72 65 20 5b 73 71 6c 69 74 65 33  hat are [sqlite3
2c650 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75  _bind_blob | bou
2c660 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61  nd].** to the pa
2c670 72 61 6d 65 74 65 72 73 20 61 74 20 61 20 6c 61  rameters at a la
2c680 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20  ter time..**.** 
2c690 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20 61  ^(This routine a
2c6a0 63 74 75 61 6c 6c 79 20 72 65 74 75 72 6e 73 20  ctually returns 
2c6b0 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65  the index of the
2c6c0 20 6c 61 72 67 65 73 74 20 28 72 69 67 68 74 6d   largest (rightm
2c6d0 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74 65  ost).** paramete
2c6e0 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d 73  r. For all forms
2c6f0 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74 68   except ?NNN, th
2c700 69 73 20 77 69 6c 6c 20 63 6f 72 72 65 73 70 6f  is will correspo
2c710 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d  nd to the.** num
2c720 62 65 72 20 6f 66 20 75 6e 69 71 75 65 20 70 61  ber of unique pa
2c730 72 61 6d 65 74 65 72 73 2e 20 20 49 66 20 70 61  rameters.  If pa
2c740 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20  rameters of the 
2c750 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72 65 20 75 73  ?NNN form are us
2c760 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61 79  ed,.** there may
2c770 20 62 65 20 67 61 70 73 20 69 6e 20 74 68 65 20   be gaps in the 
2c780 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65  list.)^.**.** Se
2c790 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
2c7a0 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74  _bind_blob|sqlit
2c7b0 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b  e3_bind()],.** [
2c7c0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
2c7d0 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20  ameter_name()], 
2c7e0 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
2c7f0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
2c800 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49  ndex()]..*/.SQLI
2c810 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
2c820 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2c830 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f  r_count(sqlite3_
2c840 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  stmt*);../*.** C
2c850 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66  API3REF: Name Of
2c860 20 41 20 48 6f 73 74 20 50 61 72 61 6d 65 74 65   A Host Paramete
2c870 72 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  r.**.** ^The sql
2c880 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
2c890 74 65 72 5f 6e 61 6d 65 28 50 2c 4e 29 20 69 6e  ter_name(P,N) in
2c8a0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a  terface returns.
2c8b0 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  ** the name of t
2c8c0 68 65 20 4e 2d 74 68 20 5b 53 51 4c 20 70 61 72  he N-th [SQL par
2c8d0 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20 5b  ameter] in the [
2c8e0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2c8f0 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20  nt] P..** ^(SQL 
2c900 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68  parameters of th
2c910 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72  e form "?NNN" or
2c920 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41   ":AAA" or "@AAA
2c930 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 68  " or "$AAA".** h
2c940 61 76 65 20 61 20 6e 61 6d 65 20 77 68 69 63 68  ave a name which
2c950 20 69 73 20 74 68 65 20 73 74 72 69 6e 67 20 22   is the string "
2c960 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20  ?NNN" or ":AAA" 
2c970 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41  or "@AAA" or "$A
2c980 41 41 22 0a 2a 2a 20 72 65 73 70 65 63 74 69 76  AA".** respectiv
2c990 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72  ely..** In other
2c9a0 20 77 6f 72 64 73 2c 20 74 68 65 20 69 6e 69 74   words, the init
2c9b0 69 61 6c 20 22 3a 22 20 6f 72 20 22 24 22 20 6f  ial ":" or "$" o
2c9c0 72 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20  r "@" or "?".** 
2c9d0 69 73 20 69 6e 63 6c 75 64 65 64 20 61 73 20 70  is included as p
2c9e0 61 72 74 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e  art of the name.
2c9f0 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65 74 65 72  )^.** ^Parameter
2ca00 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f  s of the form "?
2ca10 22 20 77 69 74 68 6f 75 74 20 61 20 66 6f 6c 6c  " without a foll
2ca20 6f 77 69 6e 67 20 69 6e 74 65 67 65 72 20 68 61  owing integer ha
2ca30 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e  ve no name.** an
2ca40 64 20 61 72 65 20 72 65 66 65 72 72 65 64 20 74  d are referred t
2ca50 6f 20 61 73 20 22 6e 61 6d 65 6c 65 73 73 22 20  o as "nameless" 
2ca60 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 70 61  or "anonymous pa
2ca70 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a  rameters"..**.**
2ca80 20 5e 54 68 65 20 66 69 72 73 74 20 68 6f 73 74   ^The first host
2ca90 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61   parameter has a
2caa0 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f  n index of 1, no
2cab0 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  t 0..**.** ^If t
2cac0 68 65 20 76 61 6c 75 65 20 4e 20 69 73 20 6f 75  he value N is ou
2cad0 74 20 6f 66 20 72 61 6e 67 65 20 6f 72 20 69 66  t of range or if
2cae0 20 74 68 65 20 4e 2d 74 68 20 70 61 72 61 6d 65   the N-th parame
2caf0 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65  ter is.** namele
2cb00 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73  ss, then NULL is
2cb10 20 72 65 74 75 72 6e 65 64 2e 20 20 5e 54 68 65   returned.  ^The
2cb20 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
2cb30 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69 6e   is.** always in
2cb40 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20   UTF-8 encoding 
2cb50 65 76 65 6e 20 69 66 20 74 68 65 20 6e 61 6d 65  even if the name
2cb60 64 20 70 61 72 61 6d 65 74 65 72 20 77 61 73 0a  d parameter was.
2cb70 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70  ** originally sp
2cb80 65 63 69 66 69 65 64 20 61 73 20 55 54 46 2d 31  ecified as UTF-1
2cb90 36 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72  6 in [sqlite3_pr
2cba0 65 70 61 72 65 31 36 28 29 5d 20 6f 72 0a 2a 2a  epare16()] or.**
2cbb0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2cbc0 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a  e16_v2()]..**.**
2cbd0 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
2cbe0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71  te3_bind_blob|sq
2cbf0 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a  lite3_bind()],.*
2cc00 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
2cc10 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
2cc20 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
2cc30 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
2cc40 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a  er_index()]..*/.
2cc50 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
2cc60 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 62   char *sqlite3_b
2cc70 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
2cc80 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
2cc90 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  , int);../*.** C
2cca0 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78 20 4f  API3REF: Index O
2ccb0 66 20 41 20 50 61 72 61 6d 65 74 65 72 20 57 69  f A Parameter Wi
2ccc0 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d 65 0a  th A Given Name.
2ccd0 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68  **.** ^Return th
2cce0 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 51  e index of an SQ
2ccf0 4c 20 70 61 72 61 6d 65 74 65 72 20 67 69 76 65  L parameter give
2cd00 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54 68  n its name.  ^Th
2cd10 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75 65  e.** index value
2cd20 20 72 65 74 75 72 6e 65 64 20 69 73 20 73 75 69   returned is sui
2cd30 74 61 62 6c 65 20 66 6f 72 20 75 73 65 20 61 73  table for use as
2cd40 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70   the second.** p
2cd50 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
2cd60 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73  ite3_bind_blob|s
2cd70 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20  qlite3_bind()]. 
2cd80 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72   ^A zero.** is r
2cd90 65 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61  eturned if no ma
2cda0 74 63 68 69 6e 67 20 70 61 72 61 6d 65 74 65 72  tching parameter
2cdb0 20 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68 65   is found.  ^The
2cdc0 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61   parameter.** na
2cdd0 6d 65 20 6d 75 73 74 20 62 65 20 67 69 76 65 6e  me must be given
2cde0 20 69 6e 20 55 54 46 2d 38 20 65 76 65 6e 20 69   in UTF-8 even i
2cdf0 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73  f the original s
2ce00 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20  tatement.** was 
2ce10 70 72 65 70 61 72 65 64 20 66 72 6f 6d 20 55 54  prepared from UT
2ce20 46 2d 31 36 20 74 65 78 74 20 75 73 69 6e 67 20  F-16 text using 
2ce30 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2ce40 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  16_v2()]..**.** 
2ce50 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
2ce60 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c  e3_bind_blob|sql
2ce70 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a  ite3_bind()],.**
2ce80 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
2ce90 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29  arameter_count()
2cea0 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  ], and.** [sqlit
2ceb0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2cec0 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53  r_index()]..*/.S
2ced0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
2cee0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2cef0 65 74 65 72 5f 69 6e 64 65 78 28 73 71 6c 69 74  eter_index(sqlit
2cf00 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20  e3_stmt*, const 
2cf10 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f  char *zName);../
2cf20 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
2cf30 65 73 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67  eset All Binding
2cf40 73 20 4f 6e 20 41 20 50 72 65 70 61 72 65 64 20  s On A Prepared 
2cf50 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20  Statement.**.** 
2cf60 5e 43 6f 6e 74 72 61 72 79 20 74 6f 20 74 68 65  ^Contrary to the
2cf70 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61   intuition of ma
2cf80 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ny, [sqlite3_res
2cf90 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20 72  et()] does not r
2cfa0 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71 6c  eset.** the [sql
2cfb0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c  ite3_bind_blob |
2cfc0 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20   bindings] on a 
2cfd0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2cfe0 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74 68  ent]..** ^Use th
2cff0 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 72 65  is routine to re
2d000 73 65 74 20 61 6c 6c 20 68 6f 73 74 20 70 61 72  set all host par
2d010 61 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e  ameters to NULL.
2d020 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
2d030 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 65 61 72  nt sqlite3_clear
2d040 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65  _bindings(sqlite
2d050 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  3_stmt*);../*.**
2d060 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65   CAPI3REF: Numbe
2d070 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20  r Of Columns In 
2d080 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a  A Result Set.**.
2d090 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20 6e  ** ^Return the n
2d0a0 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
2d0b0 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73   in the result s
2d0c0 65 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  et returned by t
2d0d0 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
2d0e0 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 54 68 69  statement]. ^Thi
2d0f0 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  s routine return
2d100 73 20 30 20 69 66 20 70 53 74 6d 74 20 69 73 20  s 0 if pStmt is 
2d110 61 6e 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d  an SQL.** statem
2d120 65 6e 74 20 74 68 61 74 20 64 6f 65 73 20 6e 6f  ent that does no
2d130 74 20 72 65 74 75 72 6e 20 64 61 74 61 20 28 66  t return data (f
2d140 6f 72 20 65 78 61 6d 70 6c 65 20 61 6e 20 5b 55  or example an [U
2d150 50 44 41 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53  PDATE])..**.** S
2d160 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
2d170 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29 5d 0a  3_data_count()].
2d180 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
2d190 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
2d1a0 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73  _count(sqlite3_s
2d1b0 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
2d1c0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
2d1d0 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20  lumn Names In A 
2d1e0 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a  Result Set.**.**
2d1f0 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
2d200 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65   return the name
2d210 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20 70   assigned to a p
2d220 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e  articular column
2d230 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75 6c  .** in the resul
2d240 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45  t set of a [SELE
2d250 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  CT] statement.  
2d260 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ^The sqlite3_col
2d270 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e  umn_name().** in
2d280 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
2d290 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a  a pointer to a z
2d2a0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
2d2b0 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61  TF-8 string.** a
2d2c0 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
2d2d0 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 74 75 72  n_name16() retur
2d2e0 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
2d2f0 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
2d300 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69  d.** UTF-16 stri
2d310 6e 67 2e 20 20 5e 54 68 65 20 66 69 72 73 74 20  ng.  ^The first 
2d320 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
2d330 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2d340 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d  ment].** that im
2d350 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b 53 45  plements the [SE
2d360 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e  LECT] statement.
2d370 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72   ^The second par
2d380 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a  ameter is the.**
2d390 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20   column number. 
2d3a0 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63   ^The leftmost c
2d3b0 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20  olumn is number 
2d3c0 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65  0..**.** ^The re
2d3d0 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 70 6f  turned string po
2d3e0 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20 75  inter is valid u
2d3f0 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68 65 20  ntil either the 
2d400 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2d410 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72  ent].** is destr
2d420 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  oyed by [sqlite3
2d430 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20  _finalize()] or 
2d440 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d  until the statem
2d450 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63  ent is automatic
2d460 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72  ally.** reprepar
2d470 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20  ed by the first 
2d480 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
2d490 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70  _step()] for a p
2d4a0 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a  articular run.**
2d4b0 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 6e 65   or until the ne
2d4c0 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71  xt call to.** sq
2d4d0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
2d4e0 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  e() or sqlite3_c
2d4f0 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f  olumn_name16() o
2d500 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d  n the same colum
2d510 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c  n..**.** ^If sql
2d520 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61  ite3_malloc() fa
2d530 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65 20 70  ils during the p
2d540 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 69 74  rocessing of eit
2d550 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28  her routine.** (
2d560 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 72 69  for example duri
2d570 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20  ng a conversion 
2d580 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 54  from UTF-8 to UT
2d590 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20  F-16) then a.** 
2d5a0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20  NULL pointer is 
2d5b0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
2d5c0 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 72  ^The name of a r
2d5d0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20  esult column is 
2d5e0 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65  the value of the
2d5f0 20 22 41 53 22 20 63 6c 61 75 73 65 20 66 6f 72   "AS" clause for
2d600 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c  .** that column,
2d610 20 69 66 20 74 68 65 72 65 20 69 73 20 61 6e 20   if there is an 
2d620 41 53 20 63 6c 61 75 73 65 2e 20 20 49 66 20 74  AS clause.  If t
2d630 68 65 72 65 20 69 73 20 6e 6f 20 41 53 20 63 6c  here is no AS cl
2d640 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ause.** then the
2d650 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c   name of the col
2d660 75 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 66 69  umn is unspecifi
2d670 65 64 20 61 6e 64 20 6d 61 79 20 63 68 61 6e 67  ed and may chang
2d680 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65  e from.** one re
2d690 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20  lease of SQLite 
2d6a0 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a  to the next..*/.
2d6b0 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
2d6c0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
2d6d0 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74  olumn_name(sqlit
2d6e0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29  e3_stmt*, int N)
2d6f0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  ;.SQLITE_API con
2d700 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
2d710 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73  _column_name16(s
2d720 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2d730 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  t N);../*.** CAP
2d740 49 33 52 45 46 3a 20 53 6f 75 72 63 65 20 4f 66  I3REF: Source Of
2d750 20 44 61 74 61 20 49 6e 20 41 20 51 75 65 72 79   Data In A Query
2d760 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 54   Result.**.** ^T
2d770 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 70 72  hese routines pr
2d780 6f 76 69 64 65 20 61 20 6d 65 61 6e 73 20 74 6f  ovide a means to
2d790 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64   determine the d
2d7a0 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20  atabase, table, 
2d7b0 61 6e 64 0a 2a 2a 20 74 61 62 6c 65 20 63 6f 6c  and.** table col
2d7c0 75 6d 6e 20 74 68 61 74 20 69 73 20 74 68 65 20  umn that is the 
2d7d0 6f 72 69 67 69 6e 20 6f 66 20 61 20 70 61 72 74  origin of a part
2d7e0 69 63 75 6c 61 72 20 72 65 73 75 6c 74 20 63 6f  icular result co
2d7f0 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c 45  lumn in.** [SELE
2d800 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a  CT] statement..*
2d810 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74  * ^The name of t
2d820 68 65 20 64 61 74 61 62 61 73 65 20 6f 72 20 74  he database or t
2d830 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63  able or column c
2d840 61 6e 20 62 65 20 72 65 74 75 72 6e 65 64 20 61  an be returned a
2d850 73 0a 2a 2a 20 65 69 74 68 65 72 20 61 20 55 54  s.** either a UT
2d860 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 73 74  F-8 or UTF-16 st
2d870 72 69 6e 67 2e 20 20 5e 54 68 65 20 5f 64 61 74  ring.  ^The _dat
2d880 61 62 61 73 65 5f 20 72 6f 75 74 69 6e 65 73 20  abase_ routines 
2d890 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61  return.** the da
2d8a0 74 61 62 61 73 65 20 6e 61 6d 65 2c 20 74 68 65  tabase name, the
2d8b0 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65   _table_ routine
2d8c0 73 20 72 65 74 75 72 6e 20 74 68 65 20 74 61 62  s return the tab
2d8d0 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20  le name, and.** 
2d8e0 74 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74  the origin_ rout
2d8f0 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20  ines return the 
2d900 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20  column name..** 
2d910 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74  ^The returned st
2d920 72 69 6e 67 20 69 73 20 76 61 6c 69 64 20 75 6e  ring is valid un
2d930 74 69 6c 20 74 68 65 20 5b 70 72 65 70 61 72 65  til the [prepare
2d940 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 20  d statement] is 
2d950 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69  destroyed.** usi
2d960 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ng [sqlite3_fina
2d970 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c  lize()] or until
2d980 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
2d990 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a  s automatically.
2d9a0 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20 62 79  ** reprepared by
2d9b0 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20   the first call 
2d9c0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
2d9d0 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69 63  ()] for a partic
2d9e0 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75  ular run.** or u
2d9f0 6e 74 69 6c 20 74 68 65 20 73 61 6d 65 20 69 6e  ntil the same in
2da00 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 65 71  formation is req
2da10 75 65 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20  uested.** again 
2da20 69 6e 20 61 20 64 69 66 66 65 72 65 6e 74 20 65  in a different e
2da30 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e  ncoding..**.** ^
2da40 54 68 65 20 6e 61 6d 65 73 20 72 65 74 75 72 6e  The names return
2da50 65 64 20 61 72 65 20 74 68 65 20 6f 72 69 67 69  ed are the origi
2da60 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e  nal un-aliased n
2da70 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64  ames of the.** d
2da80 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20  atabase, table, 
2da90 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a  and column..**.*
2daa0 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67  * ^The first arg
2dab0 75 6d 65 6e 74 20 74 6f 20 74 68 65 73 65 20 69  ument to these i
2dac0 6e 74 65 72 66 61 63 65 73 20 69 73 20 61 20 5b  nterfaces is a [
2dad0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2dae0 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65 20 66  nt]..** ^These f
2daf0 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20  unctions return 
2db00 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75  information abou
2db10 74 20 74 68 65 20 4e 74 68 20 72 65 73 75 6c 74  t the Nth result
2db20 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64   column returned
2db30 20 62 79 0a 2a 2a 20 74 68 65 20 73 74 61 74 65   by.** the state
2db40 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e 20 69 73  ment, where N is
2db50 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63   the second func
2db60 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  tion argument..*
2db70 2a 20 5e 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74  * ^The left-most
2db80 20 63 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c 75 6d   column is colum
2db90 6e 20 30 20 66 6f 72 20 74 68 65 73 65 20 72 6f  n 0 for these ro
2dba0 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49  utines..**.** ^I
2dbb0 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  f the Nth column
2dbc0 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
2dbd0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 6e   statement is an
2dbe0 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a 2a   expression or.*
2dbf0 2a 20 73 75 62 71 75 65 72 79 20 61 6e 64 20 69  * subquery and i
2dc00 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76  s not a column v
2dc10 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f  alue, then all o
2dc20 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  f these function
2dc30 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c  s return.** NULL
2dc40 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  .  ^These routin
2dc50 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 72 65 74  e might also ret
2dc60 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65  urn NULL if a me
2dc70 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
2dc80 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73 2e  error.** occurs.
2dc90 20 20 5e 4f 74 68 65 72 77 69 73 65 2c 20 74 68    ^Otherwise, th
2dca0 65 79 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61  ey return the na
2dcb0 6d 65 20 6f 66 20 74 68 65 20 61 74 74 61 63 68  me of the attach
2dcc0 65 64 20 64 61 74 61 62 61 73 65 2c 20 74 61 62  ed database, tab
2dcd0 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d 6e  le,.** or column
2dce0 20 74 68 61 74 20 71 75 65 72 79 20 72 65 73 75   that query resu
2dcf0 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78  lt column was ex
2dd00 74 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a  tracted from..**
2dd10 0a 2a 2a 20 5e 41 73 20 77 69 74 68 20 61 6c 6c  .** ^As with all
2dd20 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 41 50   other SQLite AP
2dd30 49 73 2c 20 74 68 6f 73 65 20 77 68 6f 73 65 20  Is, those whose 
2dd40 6e 61 6d 65 73 20 65 6e 64 20 77 69 74 68 20 22  names end with "
2dd50 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54  16" return.** UT
2dd60 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 73 74 72  F-16 encoded str
2dd70 69 6e 67 73 20 61 6e 64 20 74 68 65 20 6f 74 68  ings and the oth
2dd80 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74  er functions ret
2dd90 75 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a  urn UTF-8..**.**
2dda0 20 5e 54 68 65 73 65 20 41 50 49 73 20 61 72 65   ^These APIs are
2ddb0 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20   only available 
2ddc0 69 66 20 74 68 65 20 6c 69 62 72 61 72 79 20 77  if the library w
2ddd0 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  as compiled with
2dde0 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
2ddf0 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45  ENABLE_COLUMN_ME
2de00 54 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72 6f  TADATA] C-prepro
2de10 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a 2a  cessor symbol..*
2de20 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d  *.** If two or m
2de30 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c  ore threads call
2de40 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20   one or more of 
2de50 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  these routines a
2de60 67 61 69 6e 73 74 20 74 68 65 20 73 61 6d 65 0a  gainst the same.
2de70 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 61 74  ** prepared stat
2de80 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e  ement and column
2de90 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d   at the same tim
2dea0 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c  e then the resul
2deb0 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69  ts are.** undefi
2dec0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77  ned..**.** If tw
2ded0 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64  o or more thread
2dee0 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f  s call one or mo
2def0 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  re.** [sqlite3_c
2df00 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e  olumn_database_n
2df10 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74  ame | column met
2df20 61 64 61 74 61 20 69 6e 74 65 72 66 61 63 65 73  adata interfaces
2df30 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d  ].** for the sam
2df40 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
2df50 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73 75 6c  ement] and resul
2df60 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74  t column.** at t
2df70 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65  he same time the
2df80 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  n the results ar
2df90 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a  e undefined..*/.
2dfa0 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
2dfb0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
2dfc0 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e  olumn_database_n
2dfd0 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
2dfe0 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41  *,int);.SQLITE_A
2dff0 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  PI const void *s
2e000 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61  qlite3_column_da
2e010 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 73 71  tabase_name16(sq
2e020 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
2e030 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  ;.SQLITE_API con
2e040 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
2e050 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61  _column_table_na
2e060 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
2e070 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50  ,int);.SQLITE_AP
2e080 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  I const void *sq
2e090 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62  lite3_column_tab
2e0a0 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65  le_name16(sqlite
2e0b0 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51  3_stmt*,int);.SQ
2e0c0 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63  LITE_API const c
2e0d0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
2e0e0 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28  umn_origin_name(
2e0f0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
2e100 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  t);.SQLITE_API c
2e110 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
2e120 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e  e3_column_origin
2e130 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
2e140 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a  stmt*,int);../*.
2e150 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 63  ** CAPI3REF: Dec
2e160 6c 61 72 65 64 20 44 61 74 61 74 79 70 65 20 4f  lared Datatype O
2e170 66 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74  f A Query Result
2e180 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 72  .**.** ^(The fir
2e190 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  st parameter is 
2e1a0 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
2e1b0 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68  ement]..** If th
2e1c0 69 73 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  is statement is 
2e1d0 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  a [SELECT] state
2e1e0 6d 65 6e 74 20 61 6e 64 20 74 68 65 20 4e 74 68  ment and the Nth
2e1f0 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a   column of the.*
2e200 2a 20 72 65 74 75 72 6e 65 64 20 72 65 73 75 6c  * returned resul
2e210 74 20 73 65 74 20 6f 66 20 74 68 61 74 20 5b 53  t set of that [S
2e220 45 4c 45 43 54 5d 20 69 73 20 61 20 74 61 62 6c  ELECT] is a tabl
2e230 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e  e column (not an
2e240 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f  .** expression o
2e250 72 20 73 75 62 71 75 65 72 79 29 20 74 68 65 6e  r subquery) then
2e260 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 79   the declared ty
2e270 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 0a  pe of the table.
2e280 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65 74  ** column is ret
2e290 75 72 6e 65 64 2e 29 5e 20 20 5e 49 66 20 74 68  urned.)^  ^If th
2e2a0 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20  e Nth column of 
2e2b0 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 69  the result set i
2e2c0 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69  s an.** expressi
2e2d0 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 2c 20  on or subquery, 
2e2e0 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  then a NULL poin
2e2f0 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ter is returned.
2e300 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65  .** ^The returne
2e310 64 20 73 74 72 69 6e 67 20 69 73 20 61 6c 77 61  d string is alwa
2e320 79 73 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64  ys UTF-8 encoded
2e330 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65 78  ..**.** ^(For ex
2e340 61 6d 70 6c 65 2c 20 67 69 76 65 6e 20 74 68 65  ample, given the
2e350 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61   database schema
2e360 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54  :.**.** CREATE T
2e370 41 42 4c 45 20 74 31 28 63 31 20 56 41 52 49 41  ABLE t1(c1 VARIA
2e380 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74  NT);.**.** and t
2e390 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61  he following sta
2e3a0 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d  tement to be com
2e3b0 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c  piled:.**.** SEL
2e3c0 45 43 54 20 63 31 20 2b 20 31 2c 20 63 31 20 46  ECT c1 + 1, c1 F
2e3d0 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68  ROM t1;.**.** th
2e3e0 69 73 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64  is routine would
2e3f0 20 72 65 74 75 72 6e 20 74 68 65 20 73 74 72 69   return the stri
2e400 6e 67 20 22 56 41 52 49 41 4e 54 22 20 66 6f 72  ng "VARIANT" for
2e410 20 74 68 65 20 73 65 63 6f 6e 64 20 72 65 73 75   the second resu
2e420 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d  lt.** column (i=
2e430 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20  =1), and a NULL 
2e440 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65 20  pointer for the 
2e450 66 69 72 73 74 20 72 65 73 75 6c 74 20 63 6f 6c  first result col
2e460 75 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a 2a 2a  umn (i==0).)^.**
2e470 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73  .** ^SQLite uses
2e480 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d   dynamic run-tim
2e490 65 20 74 79 70 69 6e 67 2e 20 20 5e 53 6f 20 6a  e typing.  ^So j
2e4a0 75 73 74 20 62 65 63 61 75 73 65 20 61 20 63 6f  ust because a co
2e4b0 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c 61  lumn.** is decla
2e4c0 72 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61  red to contain a
2e4d0 20 70 61 72 74 69 63 75 6c 61 72 20 74 79 70 65   particular type
2e4e0 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20 74   does not mean t
2e4f0 68 61 74 20 74 68 65 0a 2a 2a 20 64 61 74 61 20  hat the.** data 
2e500 73 74 6f 72 65 64 20 69 6e 20 74 68 61 74 20 63  stored in that c
2e510 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68 65 20  olumn is of the 
2e520 64 65 63 6c 61 72 65 64 20 74 79 70 65 2e 20 20  declared type.  
2e530 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74 72  SQLite is.** str
2e540 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20 62 75 74  ongly typed, but
2e550 20 74 68 65 20 74 79 70 69 6e 67 20 69 73 20 64   the typing is d
2e560 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61 74 69  ynamic not stati
2e570 63 2e 20 20 5e 54 79 70 65 0a 2a 2a 20 69 73 20  c.  ^Type.** is 
2e580 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
2e590 69 6e 64 69 76 69 64 75 61 6c 20 76 61 6c 75 65  individual value
2e5a0 73 2c 20 6e 6f 74 20 77 69 74 68 20 74 68 65 20  s, not with the 
2e5b0 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75 73  containers.** us
2e5c0 65 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73 65  ed to hold those
2e5d0 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a 53 51 4c 49   values..*/.SQLI
2e5e0 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61  TE_API const cha
2e5f0 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
2e600 6e 5f 64 65 63 6c 74 79 70 65 28 73 71 6c 69 74  n_decltype(sqlit
2e610 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53  e3_stmt*,int);.S
2e620 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
2e630 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
2e640 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36 28  lumn_decltype16(
2e650 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
2e660 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
2e670 52 45 46 3a 20 45 76 61 6c 75 61 74 65 20 41 6e  REF: Evaluate An
2e680 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a   SQL Statement.*
2e690 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b 70 72  *.** After a [pr
2e6a0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2e6b0 5d 20 68 61 73 20 62 65 65 6e 20 70 72 65 70 61  ] has been prepa
2e6c0 72 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72  red using either
2e6d0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
2e6e0 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73  pare_v2()] or [s
2e6f0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2e700 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66  _v2()] or one of
2e710 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69   the legacy.** i
2e720 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74  nterfaces [sqlit
2e730 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72  e3_prepare()] or
2e740 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2e750 65 31 36 28 29 5d 2c 20 74 68 69 73 20 66 75 6e  e16()], this fun
2e760 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65  ction.** must be
2e770 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d   called one or m
2e780 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65 76 61  ore times to eva
2e790 6c 75 61 74 65 20 74 68 65 20 73 74 61 74 65 6d  luate the statem
2e7a0 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64  ent..**.** The d
2e7b0 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20 62 65  etails of the be
2e7c0 68 61 76 69 6f 72 20 6f 66 20 74 68 65 20 73 71  havior of the sq
2e7d0 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 74  lite3_step() int
2e7e0 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a  erface depend.**
2e7f0 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68 65 20   on whether the 
2e800 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20 70 72  statement was pr
2e810 65 70 61 72 65 64 20 75 73 69 6e 67 20 74 68 65  epared using the
2e820 20 6e 65 77 65 72 20 22 76 32 22 20 69 6e 74 65   newer "v2" inte
2e830 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  rface.** [sqlite
2e840 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
2e850 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  and [sqlite3_pre
2e860 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20  pare16_v2()] or 
2e870 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61 63 79  the older legacy
2e880 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 5b 73  .** interface [s
2e890 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
2e8a0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70  ] and [sqlite3_p
2e8b0 72 65 70 61 72 65 31 36 28 29 5d 2e 20 20 54 68  repare16()].  Th
2e8c0 65 20 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20  e use of the.** 
2e8d0 6e 65 77 20 22 76 32 22 20 69 6e 74 65 72 66 61  new "v2" interfa
2e8e0 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  ce is recommende
2e8f0 64 20 66 6f 72 20 6e 65 77 20 61 70 70 6c 69 63  d for new applic
2e900 61 74 69 6f 6e 73 20 62 75 74 20 74 68 65 20 6c  ations but the l
2e910 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61  egacy.** interfa
2e920 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65  ce will continue
2e930 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64   to be supported
2e940 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20  ..**.** ^In the 
2e950 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65  legacy interface
2e960 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  , the return val
2e970 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74 68 65  ue will be eithe
2e980 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c  r [SQLITE_BUSY],
2e990 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45  .** [SQLITE_DONE
2e9a0 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c  ], [SQLITE_ROW],
2e9b0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c   [SQLITE_ERROR],
2e9c0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55   or [SQLITE_MISU
2e9d0 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68  SE]..** ^With th
2e9e0 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
2e9f0 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f 74 68  , any of the oth
2ea00 65 72 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73  er [result codes
2ea10 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65  ] or.** [extende
2ea20 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20  d result codes] 
2ea30 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e 65  might be returne
2ea40 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a  d as well..**.**
2ea50 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20   ^[SQLITE_BUSY] 
2ea60 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 64  means that the d
2ea70 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20 77  atabase engine w
2ea80 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 63 71  as unable to acq
2ea90 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61 74 61  uire the.** data
2eaa0 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65  base locks it ne
2eab0 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f  eds to do its jo
2eac0 62 2e 20 20 5e 49 66 20 74 68 65 20 73 74 61 74  b.  ^If the stat
2ead0 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d  ement is a [COMM
2eae0 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73  IT].** or occurs
2eaf0 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 20 65   outside of an e
2eb00 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74  xplicit transact
2eb10 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63 61  ion, then you ca
2eb20 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a 20 73  n retry the.** s
2eb30 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 74 68  tatement.  If th
2eb40 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e  e statement is n
2eb50 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e  ot a [COMMIT] an
2eb60 64 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20  d occurs within 
2eb70 61 6e 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20 74  an.** explicit t
2eb80 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e 20  ransaction then 
2eb90 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62  you should rollb
2eba0 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74  ack the transact
2ebb0 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f  ion before.** co
2ebc0 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  ntinuing..**.** 
2ebd0 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d  ^[SQLITE_DONE] m
2ebe0 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 73 74  eans that the st
2ebf0 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e 69  atement has fini
2ec00 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a 2a  shed executing.*
2ec10 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20  * successfully. 
2ec20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
2ec30 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61  should not be ca
2ec40 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68  lled again on th
2ec50 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61  is virtual.** ma
2ec60 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66 69  chine without fi
2ec70 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c  rst calling [sql
2ec80 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 6f  ite3_reset()] to
2ec90 20 72 65 73 65 74 20 74 68 65 20 76 69 72 74 75   reset the virtu
2eca0 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61  al.** machine ba
2ecb0 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61  ck to its initia
2ecc0 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e  l state..**.** ^
2ecd0 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  If the SQL state
2ece0 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65 63 75  ment being execu
2ecf0 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e 79 20  ted returns any 
2ed00 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49  data, then [SQLI
2ed10 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65  TE_ROW].** is re
2ed20 74 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d 65  turned each time
2ed30 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64 61   a new row of da
2ed40 74 61 20 69 73 20 72 65 61 64 79 20 66 6f 72 20  ta is ready for 
2ed50 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20 74 68  processing by th
2ed60 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65  e.** caller. The
2ed70 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20 61   values may be a
2ed80 63 63 65 73 73 65 64 20 75 73 69 6e 67 20 74 68  ccessed using th
2ed90 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73  e [column access
2eda0 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20   functions]..** 
2edb0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69  sqlite3_step() i
2edc0 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 74  s called again t
2edd0 6f 20 72 65 74 72 69 65 76 65 20 74 68 65 20 6e  o retrieve the n
2ede0 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74 61 2e  ext row of data.
2edf0 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f  .**.** ^[SQLITE_
2ee00 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61  ERROR] means tha
2ee10 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72  t a run-time err
2ee20 6f 72 20 28 73 75 63 68 20 61 73 20 61 20 63 6f  or (such as a co
2ee30 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c  nstraint.** viol
2ee40 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 75 72  ation) has occur
2ee50 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f 73 74  red.  sqlite3_st
2ee60 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20  ep() should not 
2ee70 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20  be called again 
2ee80 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f  on.** the VM. Mo
2ee90 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d  re information m
2eea0 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79 20 63  ay be found by c
2eeb0 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
2eec0 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57  errmsg()]..** ^W
2eed0 69 74 68 20 74 68 65 20 6c 65 67 61 63 79 20 69  ith the legacy i
2eee0 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f 72 65  nterface, a more
2eef0 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20   specific error 
2ef00 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d 70 6c  code (for exampl
2ef10 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e  e,.** [SQLITE_IN
2ef20 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54  TERRUPT], [SQLIT
2ef30 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49  E_SCHEMA], [SQLI
2ef40 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64  TE_CORRUPT], and
2ef50 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61   so forth).** ca
2ef60 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20 62 79  n be obtained by
2ef70 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
2ef80 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 74 68  3_reset()] on th
2ef90 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
2efa0 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20  tatement].  ^In 
2efb0 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
2efc0 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20  ce,.** the more 
2efd0 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63  specific error c
2efe0 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 64 20  ode is returned 
2eff0 64 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c 69  directly by sqli
2f000 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a  te3_step()..**.*
2f010 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  * [SQLITE_MISUSE
2f020 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  ] means that the
2f030 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 61   this routine wa
2f040 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f  s called inappro
2f050 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72  priately..** Per
2f060 68 61 70 73 20 69 74 20 77 61 73 20 63 61 6c 6c  haps it was call
2f070 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65  ed on a [prepare
2f080 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
2f090 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79  t has.** already
2f0a0 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66   been [sqlite3_f
2f0b0 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69  inalize | finali
2f0c0 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74  zed] or on one t
2f0d0 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 65 76 69  hat had.** previ
2f0e0 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20 5b  ously returned [
2f0f0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72  SQLITE_ERROR] or
2f100 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20   [SQLITE_DONE]. 
2f110 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20   Or it could.** 
2f120 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74  be the case that
2f130 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
2f140 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
2f150 20 62 65 69 6e 67 20 75 73 65 64 20 62 79 20 74   being used by t
2f160 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68  wo or.** more th
2f170 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d  reads at the sam
2f180 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65  e moment in time
2f190 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20  ..**.** For all 
2f1a0 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
2f1b0 74 65 20 75 70 20 74 6f 20 61 6e 64 20 69 6e 63  te up to and inc
2f1c0 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e 31 2c  luding 3.6.23.1,
2f1d0 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73   a call to.** [s
2f1e0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
2f1f0 77 61 73 20 72 65 71 75 69 72 65 64 20 61 66 74  was required aft
2f200 65 72 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  er sqlite3_step(
2f210 29 20 72 65 74 75 72 6e 65 64 20 61 6e 79 74 68  ) returned anyth
2f220 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 74 68 61  ing.** other tha
2f230 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 62  n [SQLITE_ROW] b
2f240 65 66 6f 72 65 20 61 6e 79 20 73 75 62 73 65 71  efore any subseq
2f250 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 20  uent invocation 
2f260 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74  of.** sqlite3_st
2f270 65 70 28 29 2e 20 20 46 61 69 6c 75 72 65 20 74  ep().  Failure t
2f280 6f 20 72 65 73 65 74 20 74 68 65 20 70 72 65 70  o reset the prep
2f290 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 75  ared statement u
2f2a0 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  sing .** [sqlite
2f2b0 33 5f 72 65 73 65 74 28 29 5d 20 77 6f 75 6c 64  3_reset()] would
2f2c0 20 72 65 73 75 6c 74 20 69 6e 20 61 6e 20 5b 53   result in an [S
2f2d0 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 72 65  QLITE_MISUSE] re
2f2e0 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c  turn from.** sql
2f2f0 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 42 75  ite3_step().  Bu
2f300 74 20 61 66 74 65 72 20 76 65 72 73 69 6f 6e 20  t after version 
2f310 33 2e 36 2e 32 33 2e 31 2c 20 73 71 6c 69 74 65  3.6.23.1, sqlite
2f320 33 5f 73 74 65 70 28 29 20 62 65 67 61 6e 0a 2a  3_step() began.*
2f330 2a 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  * calling [sqlit
2f340 65 33 5f 72 65 73 65 74 28 29 5d 20 61 75 74 6f  e3_reset()] auto
2f350 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20 74 68 69  matically in thi
2f360 73 20 63 69 72 63 75 6d 73 74 61 6e 63 65 20 72  s circumstance r
2f370 61 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20 72 65  ather.** than re
2f380 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f  turning [SQLITE_
2f390 4d 49 53 55 53 45 5d 2e 20 20 54 68 69 73 20 69  MISUSE].  This i
2f3a0 73 20 6e 6f 74 20 63 6f 6e 73 69 64 65 72 65 64  s not considered
2f3b0 20 61 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79   a compatibility
2f3c0 0a 2a 2a 20 62 72 65 61 6b 20 62 65 63 61 75 73  .** break becaus
2f3d0 65 20 61 6e 79 20 61 70 70 6c 69 63 61 74 69 6f  e any applicatio
2f3e0 6e 20 74 68 61 74 20 65 76 65 72 20 72 65 63 65  n that ever rece
2f3f0 69 76 65 73 20 61 6e 20 53 51 4c 49 54 45 5f 4d  ives an SQLITE_M
2f400 49 53 55 53 45 20 65 72 72 6f 72 0a 2a 2a 20 69  ISUSE error.** i
2f410 73 20 62 72 6f 6b 65 6e 20 62 79 20 64 65 66 69  s broken by defi
2f420 6e 69 74 69 6f 6e 2e 20 20 54 68 65 20 5b 53 51  nition.  The [SQ
2f430 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 52 45  LITE_OMIT_AUTORE
2f440 53 45 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  SET] compile-tim
2f450 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20  e option.** can 
2f460 62 65 20 75 73 65 64 20 74 6f 20 72 65 73 74 6f  be used to resto
2f470 72 65 20 74 68 65 20 6c 65 67 61 63 79 20 62 65  re the legacy be
2f480 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62  havior..**.** <b
2f490 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 63 65  >Goofy Interface
2f4a0 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74   Alert:</b> In t
2f4b0 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66  he legacy interf
2f4c0 61 63 65 2c 20 74 68 65 20 73 71 6c 69 74 65 33  ace, the sqlite3
2f4d0 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50 49 20 61  _step().** API a
2f4e0 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 61 20  lways returns a 
2f4f0 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20 63 6f  generic error co
2f500 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  de, [SQLITE_ERRO
2f510 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e  R], following an
2f520 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65 72  y.** error other
2f530 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55   than [SQLITE_BU
2f540 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  SY] and [SQLITE_
2f550 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75  MISUSE].  You mu
2f560 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69  st call.** [sqli
2f570 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20  te3_reset()] or 
2f580 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
2f590 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f  e()] in order to
2f5a0 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65   find one of the
2f5b0 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 5b 65 72  .** specific [er
2f5c0 72 6f 72 20 63 6f 64 65 73 5d 20 74 68 61 74 20  ror codes] that 
2f5d0 62 65 74 74 65 72 20 64 65 73 63 72 69 62 65 73  better describes
2f5e0 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57   the error..** W
2f5f0 65 20 61 64 6d 69 74 20 74 68 61 74 20 74 68 69  e admit that thi
2f600 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65 73  s is a goofy des
2f610 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c 65  ign.  The proble
2f620 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78 65 64  m has been fixed
2f630 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76 32  .** with the "v2
2f640 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49 66  " interface.  If
2f650 20 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c 6c   you prepare all
2f660 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74 61   of your SQL sta
2f670 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67  tements.** using
2f680 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33   either [sqlite3
2f690 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
2f6a0 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
2f6b0 72 65 31 36 5f 76 32 28 29 5d 20 69 6e 73 74 65  re16_v2()] inste
2f6c0 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67  ad.** of the leg
2f6d0 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  acy [sqlite3_pre
2f6e0 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  pare()] and [sql
2f6f0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
2f700 5d 20 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a  ] interfaces,.**
2f710 20 74 68 65 6e 20 74 68 65 20 6d 6f 72 65 20 73   then the more s
2f720 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63  pecific [error c
2f730 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75 72 6e  odes] are return
2f740 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62  ed directly.** b
2f750 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  y sqlite3_step()
2f760 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68  .  The use of th
2f770 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
2f780 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e   is recommended.
2f790 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
2f7a0 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  nt sqlite3_step(
2f7b0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
2f7c0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2f7d0 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   Number of colum
2f7e0 6e 73 20 69 6e 20 61 20 72 65 73 75 6c 74 20 73  ns in a result s
2f7f0 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  et.**.** ^The sq
2f800 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
2f810 28 50 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  (P) interface re
2f820 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
2f830 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74   of columns in t
2f840 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 72 6f  he.** current ro
2f850 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  w of the result 
2f860 73 65 74 20 6f 66 20 5b 70 72 65 70 61 72 65 64  set of [prepared
2f870 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a   statement] P..*
2f880 2a 20 5e 49 66 20 70 72 65 70 61 72 65 64 20 73  * ^If prepared s
2f890 74 61 74 65 6d 65 6e 74 20 50 20 64 6f 65 73 20  tatement P does 
2f8a0 6e 6f 74 20 68 61 76 65 20 72 65 73 75 6c 74 73  not have results
2f8b0 20 72 65 61 64 79 20 74 6f 20 72 65 74 75 72 6e   ready to return
2f8c0 0a 2a 2a 20 28 76 69 61 20 63 61 6c 6c 73 20 74  .** (via calls t
2f8d0 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  o the [sqlite3_c
2f8e0 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20 73 71 6c 69  olumn_int | sqli
2f8f0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 5d 20  te3_column_*()] 
2f900 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  of.** interfaces
2f910 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 64  ) then sqlite3_d
2f920 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 65 74  ata_count(P) ret
2f930 75 72 6e 73 20 30 2e 0a 2a 2a 20 5e 54 68 65 20  urns 0..** ^The 
2f940 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
2f950 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20 61 6c  nt(P) routine al
2f960 73 6f 20 72 65 74 75 72 6e 73 20 30 20 69 66 20  so returns 0 if 
2f970 50 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  P is a NULL poin
2f980 74 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ter..** ^The sql
2f990 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
2f9a0 50 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  P) routine retur
2f9b0 6e 73 20 30 20 69 66 20 74 68 65 20 70 72 65 76  ns 0 if the prev
2f9c0 69 6f 75 73 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  ious call to.** 
2f9d0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 28 50  [sqlite3_step](P
2f9e0 29 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49  ) returned [SQLI
2f9f0 54 45 5f 44 4f 4e 45 5d 2e 20 20 5e 54 68 65 20  TE_DONE].  ^The 
2fa00 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
2fa10 6e 74 28 50 29 0a 2a 2a 20 77 69 6c 6c 20 72 65  nt(P).** will re
2fa20 74 75 72 6e 20 6e 6f 6e 2d 7a 65 72 6f 20 69 66  turn non-zero if
2fa30 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74   previous call t
2fa40 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 5d  o [sqlite3_step]
2fa50 28 50 29 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  (P) returned.** 
2fa60 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 65 78  [SQLITE_ROW], ex
2fa70 63 65 70 74 20 69 6e 20 74 68 65 20 63 61 73 65  cept in the case
2fa80 20 6f 66 20 74 68 65 20 5b 50 52 41 47 4d 41 20   of the [PRAGMA 
2fa90 69 6e 63 72 65 6d 65 6e 74 61 6c 5f 76 61 63 75  incremental_vacu
2faa0 75 6d 5d 0a 2a 2a 20 77 68 65 72 65 20 69 74 20  um].** where it 
2fab0 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 7a  always returns z
2fac0 65 72 6f 20 73 69 6e 63 65 20 65 61 63 68 20 73  ero since each s
2fad0 74 65 70 20 6f 66 20 74 68 61 74 20 6d 75 6c 74  tep of that mult
2fae0 69 2d 73 74 65 70 0a 2a 2a 20 70 72 61 67 6d 61  i-step.** pragma
2faf0 20 72 65 74 75 72 6e 73 20 30 20 63 6f 6c 75 6d   returns 0 colum
2fb00 6e 73 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a  ns of data..**.*
2fb10 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
2fb20 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e  ite3_column_coun
2fb30 74 28 29 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  t()].*/.SQLITE_A
2fb40 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 64  PI int sqlite3_d
2fb50 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65  ata_count(sqlite
2fb60 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
2fb70 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2fb80 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74   Fundamental Dat
2fb90 61 74 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52  atypes.** KEYWOR
2fba0 44 53 3a 20 53 51 4c 49 54 45 5f 54 45 58 54 0a  DS: SQLITE_TEXT.
2fbb0 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72 79 20 76 61  **.** ^(Every va
2fbc0 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 20 68 61  lue in SQLite ha
2fbd0 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 20 66 75  s one of five fu
2fbe0 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 61 74 79  ndamental dataty
2fbf0 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  pes:.**.** <ul>.
2fc00 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73  ** <li> 64-bit s
2fc10 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a  igned integer.**
2fc20 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49 45 45   <li> 64-bit IEE
2fc30 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  E floating point
2fc40 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20   number.** <li> 
2fc50 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42  string.** <li> B
2fc60 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c  LOB.** <li> NULL
2fc70 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a  .** </ul>)^.**.*
2fc80 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
2fc90 73 20 61 72 65 20 63 6f 64 65 73 20 66 6f 72 20  s are codes for 
2fca0 65 61 63 68 20 6f 66 20 74 68 6f 73 65 20 74 79  each of those ty
2fcb0 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  pes..**.** Note 
2fcc0 74 68 61 74 20 74 68 65 20 53 51 4c 49 54 45 5f  that the SQLITE_
2fcd0 54 45 58 54 20 63 6f 6e 73 74 61 6e 74 20 77 61  TEXT constant wa
2fce0 73 20 61 6c 73 6f 20 75 73 65 64 20 69 6e 20 53  s also used in S
2fcf0 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 0a  QLite version 2.
2fd00 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74  ** for a complet
2fd10 65 6c 79 20 64 69 66 66 65 72 65 6e 74 20 6d 65  ely different me
2fd20 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61 72 65  aning.  Software
2fd30 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69   that links agai
2fd40 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69  nst both.** SQLi
2fd50 74 65 20 76 65 72 73 69 6f 6e 20 32 20 61 6e 64  te version 2 and
2fd60 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
2fd70 33 20 73 68 6f 75 6c 64 20 75 73 65 20 53 51 4c  3 should use SQL
2fd80 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a  ITE3_TEXT, not.*
2fd90 2a 20 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a  * SQLITE_TEXT..*
2fda0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
2fdb0 5f 49 4e 54 45 47 45 52 20 20 31 0a 23 64 65 66  _INTEGER  1.#def
2fdc0 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54  ine SQLITE_FLOAT
2fdd0 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
2fde0 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a  LITE_BLOB     4.
2fdf0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
2fe00 55 4c 4c 20 20 20 20 20 35 0a 23 69 66 64 65 66  ULL     5.#ifdef
2fe10 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 20 75   SQLITE_TEXT.# u
2fe20 6e 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54  ndef SQLITE_TEXT
2fe30 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20  .#else.# define 
2fe40 53 51 4c 49 54 45 5f 54 45 58 54 20 20 20 20 20  SQLITE_TEXT     
2fe50 33 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 6e 65  3.#endif.#define
2fe60 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20 20 20   SQLITE3_TEXT   
2fe70 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33    3../*.** CAPI3
2fe80 52 45 46 3a 20 52 65 73 75 6c 74 20 56 61 6c 75  REF: Result Valu
2fe90 65 73 20 46 72 6f 6d 20 41 20 51 75 65 72 79 0a  es From A Query.
2fea0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f  ** KEYWORDS: {co
2feb0 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63  lumn access func
2fec0 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  tions}.**.** The
2fed0 73 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 6d  se routines form
2fee0 20 74 68 65 20 22 72 65 73 75 6c 74 20 73 65 74   the "result set
2fef0 22 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  " interface..**.
2ff00 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
2ff10 65 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d  es return inform
2ff20 61 74 69 6f 6e 20 61 62 6f 75 74 20 61 20 73 69  ation about a si
2ff30 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  ngle column of t
2ff40 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65  he current.** re
2ff50 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 20 71 75  sult row of a qu
2ff60 65 72 79 2e 20 20 5e 49 6e 20 65 76 65 72 79 20  ery.  ^In every 
2ff70 63 61 73 65 20 74 68 65 20 66 69 72 73 74 20 61  case the first a
2ff80 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
2ff90 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b  nter.** to the [
2ffa0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2ffb0 6e 74 5d 20 74 68 61 74 20 69 73 20 62 65 69 6e  nt] that is bein
2ffc0 67 20 65 76 61 6c 75 61 74 65 64 20 28 74 68 65  g evaluated (the
2ffd0 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d   [sqlite3_stmt*]
2ffe0 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 72 65 74  .** that was ret
2fff0 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  urned from [sqli
30000 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
30010 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 20  ] or one of its 
30020 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64  variants).** and
30030 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
30040 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65  ment is the inde
30050 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20  x of the column 
30060 66 6f 72 20 77 68 69 63 68 20 69 6e 66 6f 72 6d  for which inform
30070 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20  ation.** should 
30080 62 65 20 72 65 74 75 72 6e 65 64 2e 20 5e 54 68  be returned. ^Th
30090 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d  e leftmost colum
300a0 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  n of the result 
300b0 73 65 74 20 68 61 73 20 74 68 65 20 69 6e 64 65  set has the inde
300c0 78 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d  x 0..** ^The num
300d0 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
300e0 6e 20 74 68 65 20 72 65 73 75 6c 74 20 63 61 6e  n the result can
300f0 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75   be determined u
30100 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
30110 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d  _column_count()]
30120 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53  ..**.** If the S
30130 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65  QL statement doe
30140 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20  s not currently 
30150 70 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c 69 64  point to a valid
30160 20 72 6f 77 2c 20 6f 72 20 69 66 20 74 68 65 0a   row, or if the.
30170 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20  ** column index 
30180 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c  is out of range,
30190 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 75   the result is u
301a0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65  ndefined..** The
301b0 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79 20  se routines may 
301c0 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77  only be called w
301d0 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63  hen the most rec
301e0 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  ent call to.** [
301f0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
30200 68 61 73 20 72 65 74 75 72 6e 65 64 20 5b 53 51  has returned [SQ
30210 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65  LITE_ROW] and ne
30220 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ither.** [sqlite
30230 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b  3_reset()] nor [
30240 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
30250 28 29 5d 20 68 61 76 65 20 62 65 65 6e 20 63 61  ()] have been ca
30260 6c 6c 65 64 20 73 75 62 73 65 71 75 65 6e 74 6c  lled subsequentl
30270 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20  y..** If any of 
30280 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  these routines a
30290 72 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20  re called after 
302a0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
302b0 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
302c0 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20  _finalize()] or 
302d0 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73  after [sqlite3_s
302e0 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72  tep()] has retur
302f0 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67  ned.** something
30300 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
30310 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65  ITE_ROW], the re
30320 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
30330 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69  ned..** If [sqli
30340 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b  te3_step()] or [
30350 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
30360 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   or [sqlite3_fin
30370 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20  alize()].** are 
30380 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64 69  called from a di
30390 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 20 77  fferent thread w
303a0 68 69 6c 65 20 61 6e 79 20 6f 66 20 74 68 65 73  hile any of thes
303b0 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72  e routines.** ar
303c0 65 20 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20  e pending, then 
303d0 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
303e0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
303f0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f   ^The sqlite3_co
30400 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75 74  lumn_type() rout
30410 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a  ine returns the.
30420 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47  ** [SQLITE_INTEG
30430 45 52 20 7c 20 64 61 74 61 74 79 70 65 20 63 6f  ER | datatype co
30440 64 65 5d 20 66 6f 72 20 74 68 65 20 69 6e 69 74  de] for the init
30450 69 61 6c 20 64 61 74 61 20 74 79 70 65 0a 2a 2a  ial data type.**
30460 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 63   of the result c
30470 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65 20 72 65 74  olumn.  ^The ret
30480 75 72 6e 65 64 20 76 61 6c 75 65 20 69 73 20 6f  urned value is o
30490 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e  ne of [SQLITE_IN
304a0 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  TEGER],.** [SQLI
304b0 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49  TE_FLOAT], [SQLI
304c0 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54  TE_TEXT], [SQLIT
304d0 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c  E_BLOB], or [SQL
304e0 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20  ITE_NULL].  The 
304f0 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65  value.** returne
30500 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
30510 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 6f 6e  umn_type() is on
30520 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66  ly meaningful if
30530 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76   no type.** conv
30540 65 72 73 69 6f 6e 73 20 68 61 76 65 20 6f 63 63  ersions have occ
30550 75 72 72 65 64 20 61 73 20 64 65 73 63 72 69 62  urred as describ
30560 65 64 20 62 65 6c 6f 77 2e 20 20 41 66 74 65 72  ed below.  After
30570 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69   a type conversi
30580 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65  on,.** the value
30590 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
305a0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
305b0 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  () is undefined.
305c0 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 65 72 73    Future.** vers
305d0 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d  ions of SQLite m
305e0 61 79 20 63 68 61 6e 67 65 20 74 68 65 20 62 65  ay change the be
305f0 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65  havior of sqlite
30600 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a  3_column_type().
30610 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74  ** following a t
30620 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a  ype conversion..
30630 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  **.** ^If the re
30640 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f  sult is a BLOB o
30650 72 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 74  r UTF-8 string t
30660 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hen the sqlite3_
30670 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a  column_bytes().*
30680 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  * routine return
30690 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
306a0 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c  bytes in that BL
306b0 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a  OB or string..**
306c0 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
306d0 69 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69  is a UTF-16 stri
306e0 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ng, then sqlite3
306f0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
30700 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20  converts.** the 
30710 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 38 20  string to UTF-8 
30720 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73  and then returns
30730 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
30740 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ytes..** ^If the
30750 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d   result is a num
30760 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20  eric value then 
30770 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
30780 79 74 65 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b  ytes() uses.** [
30790 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
307a0 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74  ()] to convert t
307b0 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55  hat value to a U
307c0 54 46 2d 38 20 73 74 72 69 6e 67 20 61 6e 64 20  TF-8 string and 
307d0 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e  returns.** the n
307e0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
307f0 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a  n that string..*
30800 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
30810 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73   is NULL, then s
30820 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
30830 74 65 73 28 29 20 72 65 74 75 72 6e 73 20 7a 65  tes() returns ze
30840 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ro..**.** ^If th
30850 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c  e result is a BL
30860 4f 42 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72  OB or UTF-16 str
30870 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c  ing then the sql
30880 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
30890 73 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  s16().** routine
308a0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
308b0 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
308c0 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72  that BLOB or str
308d0 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ing..** ^If the 
308e0 72 65 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d  result is a UTF-
308f0 38 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73  8 string, then s
30900 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
30910 74 65 73 31 36 28 29 20 63 6f 6e 76 65 72 74 73  tes16() converts
30920 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74  .** the string t
30930 6f 20 55 54 46 2d 31 36 20 61 6e 64 20 74 68 65  o UTF-16 and the
30940 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
30950 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a  mber of bytes..*
30960 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
30970 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61   is a numeric va
30980 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33  lue then sqlite3
30990 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
309a0 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74  ) uses.** [sqlit
309b0 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74  e3_snprintf()] t
309c0 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76  o convert that v
309d0 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 31 36  alue to a UTF-16
309e0 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75   string and retu
309f0 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65  rns.** the numbe
30a00 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
30a10 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49  at string..** ^I
30a20 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
30a30 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74  NULL, then sqlit
30a40 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
30a50 36 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  6() returns zero
30a60 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 76 61 6c  ..**.** ^The val
30a70 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ues returned by 
30a80 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
30a90 62 79 74 65 73 28 29 5d 20 61 6e 64 20 0a 2a 2a  bytes()] and .**
30aa0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
30ab0 5f 62 79 74 65 73 31 36 28 29 5d 20 64 6f 20 6e  _bytes16()] do n
30ac0 6f 74 20 69 6e 63 6c 75 64 65 20 74 68 65 20 7a  ot include the z
30ad0 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 73 20  ero terminators 
30ae0 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66  at the end.** of
30af0 20 74 68 65 20 73 74 72 69 6e 67 2e 20 20 5e 46   the string.  ^F
30b00 6f 72 20 63 6c 61 72 69 74 79 3a 20 74 68 65 20  or clarity: the 
30b10 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20  values returned 
30b20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  by.** [sqlite3_c
30b30 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61  olumn_bytes()] a
30b40 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  nd [sqlite3_colu
30b50 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 61 72  mn_bytes16()] ar
30b60 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  e the number of.
30b70 2a 2a 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  ** bytes in the 
30b80 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20  string, not the 
30b90 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63  number of charac
30ba0 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72  ters..**.** ^Str
30bb0 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79  ings returned by
30bc0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
30bd0 74 65 78 74 28 29 20 61 6e 64 20 73 71 6c 69 74  text() and sqlit
30be0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
30bf0 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d 70 74  (),.** even empt
30c00 79 20 73 74 72 69 6e 67 73 2c 20 61 72 65 20 61  y strings, are a
30c10 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69  lways zero-termi
30c20 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 72 65 74  nated.  ^The ret
30c30 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f  urn.** value fro
30c40 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  m sqlite3_column
30c50 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a 65  _blob() for a ze
30c60 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 20 69  ro-length BLOB i
30c70 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
30c80 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f 62 6a  ..**.** ^The obj
30c90 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 20  ect returned by 
30ca0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
30cb0 76 61 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a  value()] is an.*
30cc0 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  * [unprotected s
30cd0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
30ce0 6a 65 63 74 2e 20 20 41 6e 20 75 6e 70 72 6f 74  ject.  An unprot
30cf0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
30d00 6c 75 65 20 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61  lue object.** ma
30d10 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77  y only be used w
30d20 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  ith [sqlite3_bin
30d30 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b  d_value()] and [
30d40 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
30d50 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74  alue()]..** If t
30d60 68 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  he [unprotected 
30d70 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
30d80 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62  bject returned b
30d90 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  y.** [sqlite3_co
30da0 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73  lumn_value()] is
30db0 20 75 73 65 64 20 69 6e 20 61 6e 79 20 6f 74 68   used in any oth
30dc0 65 72 20 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e  er way, includin
30dd0 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f  g calls.** to ro
30de0 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c  utines like [sql
30df0 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29  ite3_value_int()
30e00 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ], [sqlite3_valu
30e10 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72  e_text()],.** or
30e20 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
30e30 62 79 74 65 73 28 29 5d 2c 20 74 68 65 6e 20 74  bytes()], then t
30e40 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75  he behavior is u
30e50 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
30e60 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
30e70 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72  ttempt to conver
30e80 74 20 74 68 65 20 76 61 6c 75 65 20 77 68 65 72  t the value wher
30e90 65 20 61 70 70 72 6f 70 72 69 61 74 65 2e 20 20  e appropriate.  
30ea0 5e 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c  ^For.** example,
30eb0 20 69 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c   if the internal
30ec0 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20   representation 
30ed0 69 73 20 46 4c 4f 41 54 20 61 6e 64 20 61 20 74  is FLOAT and a t
30ee0 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73  ext result.** is
30ef0 20 72 65 71 75 65 73 74 65 64 2c 20 5b 73 71 6c   requested, [sql
30f00 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d  ite3_snprintf()]
30f10 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61   is used interna
30f20 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d 20 74  lly to perform t
30f30 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e  he.** conversion
30f40 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20   automatically. 
30f50 20 5e 28 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67   ^(The following
30f60 20 74 61 62 6c 65 20 64 65 74 61 69 6c 73 20 74   table details t
30f70 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a  he conversions.*
30f80 2a 20 74 68 61 74 20 61 72 65 20 61 70 70 6c 69  * that are appli
30f90 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ed:.**.** <block
30fa0 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65  quote>.** <table
30fb0 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20   border="1">.** 
30fc0 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61  <tr><th> Interna
30fd0 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 52  l<br>Type <th> R
30fe0 65 71 75 65 73 74 65 64 3c 62 72 3e 54 79 70 65  equested<br>Type
30ff0 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f   <th>  Conversio
31000 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  n.**.** <tr><td>
31010 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49    NULL    <td> I
31020 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 52 65  NTEGER   <td> Re
31030 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72  sult is 0.** <tr
31040 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
31050 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
31060 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 2e 30  d> Result is 0.0
31070 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
31080 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58  LL    <td>   TEX
31090 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  T    <td> Result
310a0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
310b0 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  er.** <tr><td>  
310c0 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 42  NULL    <td>   B
310d0 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52 65 73 75  LOB    <td> Resu
310e0 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  lt is a NULL poi
310f0 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  nter.** <tr><td>
31100 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20   INTEGER  <td>  
31110 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f  FLOAT    <td> Co
31120 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e 74 65 67  nvert from integ
31130 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c  er to float.** <
31140 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20  tr><td> INTEGER 
31150 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
31160 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65  <td> ASCII rende
31170 72 69 6e 67 20 6f 66 20 74 68 65 20 69 6e 74 65  ring of the inte
31180 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ger.** <tr><td> 
31190 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20  INTEGER  <td>   
311a0 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d  BLOB    <td> Sam
311b0 65 20 61 73 20 49 4e 54 45 47 45 52 2d 3e 54 45  e as INTEGER->TE
311c0 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  XT.** <tr><td>  
311d0 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e 54  FLOAT   <td> INT
311e0 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53  EGER   <td> [CAS
311f0 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a  T] to INTEGER.**
31200 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54   <tr><td>  FLOAT
31210 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20     <td>   TEXT  
31220 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e    <td> ASCII ren
31230 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6c  dering of the fl
31240 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  oat.** <tr><td> 
31250 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20   FLOAT   <td>   
31260 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 5b 43 41  BLOB    <td> [CA
31270 53 54 5d 20 74 6f 20 42 4c 4f 42 0a 2a 2a 20 3c  ST] to BLOB.** <
31280 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20  tr><td>  TEXT   
31290 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20   <td> INTEGER   
312a0 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49  <td> [CAST] to I
312b0 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74  NTEGER.** <tr><t
312c0 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  d>  TEXT    <td>
312d0 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
312e0 5b 43 41 53 54 5d 20 74 6f 20 52 45 41 4c 0a 2a  [CAST] to REAL.*
312f0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54  * <tr><td>  TEXT
31300 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20      <td>   BLOB 
31310 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67     <td> No chang
31320 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42  e.** <tr><td>  B
31330 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 45  LOB    <td> INTE
31340 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54  GER   <td> [CAST
31350 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20  ] to INTEGER.** 
31360 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20  <tr><td>  BLOB  
31370 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
31380 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20   <td> [CAST] to 
31390 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  REAL.** <tr><td>
313a0 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20    BLOB    <td>  
313b0 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 64   TEXT    <td> Ad
313c0 64 20 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  d a zero termina
313d0 74 6f 72 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a  tor if needed.**
313e0 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62   </table>.** </b
313f0 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a  lockquote>)^.**.
31400 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 61 62 6f  ** The table abo
31410 76 65 20 6d 61 6b 65 73 20 72 65 66 65 72 65 6e  ve makes referen
31420 63 65 20 74 6f 20 73 74 61 6e 64 61 72 64 20 43  ce to standard C
31430 20 6c 69 62 72 61 72 79 20 66 75 6e 63 74 69 6f   library functio
31440 6e 73 20 61 74 6f 69 28 29 0a 2a 2a 20 61 6e 64  ns atoi().** and
31450 20 61 74 6f 66 28 29 2e 20 20 53 51 4c 69 74 65   atof().  SQLite
31460 20 64 6f 65 73 20 6e 6f 74 20 72 65 61 6c 6c 79   does not really
31470 20 75 73 65 20 74 68 65 73 65 20 66 75 6e 63 74   use these funct
31480 69 6f 6e 73 2e 20 20 49 74 20 68 61 73 20 69 74  ions.  It has it
31490 73 0a 2a 2a 20 6f 77 6e 20 65 71 75 69 76 61 6c  s.** own equival
314a0 65 6e 74 20 69 6e 74 65 72 6e 61 6c 20 72 6f 75  ent internal rou
314b0 74 69 6e 65 73 2e 20 20 54 68 65 20 61 74 6f 69  tines.  The atoi
314c0 28 29 20 61 6e 64 20 61 74 6f 66 28 29 20 6e 61  () and atof() na
314d0 6d 65 73 20 61 72 65 0a 2a 2a 20 75 73 65 64 20  mes are.** used 
314e0 69 6e 20 74 68 65 20 74 61 62 6c 65 20 66 6f 72  in the table for
314f0 20 62 72 65 76 69 74 79 20 61 6e 64 20 62 65 63   brevity and bec
31500 61 75 73 65 20 74 68 65 79 20 61 72 65 20 66 61  ause they are fa
31510 6d 69 6c 69 61 72 20 74 6f 20 6d 6f 73 74 0a 2a  miliar to most.*
31520 2a 20 43 20 70 72 6f 67 72 61 6d 6d 65 72 73 2e  * C programmers.
31530 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
31540 20 77 68 65 6e 20 74 79 70 65 20 63 6f 6e 76 65   when type conve
31550 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f  rsions occur, po
31560 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20  inters returned 
31570 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c  by prior.** call
31580 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  s to sqlite3_col
31590 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69  umn_blob(), sqli
315a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
315b0 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c  ), and/or.** sql
315c0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
315d0 31 36 28 29 20 6d 61 79 20 62 65 20 69 6e 76 61  16() may be inva
315e0 6c 69 64 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65  lidated..** Type
315f0 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64   conversions and
31600 20 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69 64   pointer invalid
31610 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63  ations might occ
31620 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c  ur.** in the fol
31630 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a  lowing cases:.**
31640 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
31650 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e   The initial con
31660 74 65 6e 74 20 69 73 20 61 20 42 4c 4f 42 20 61  tent is a BLOB a
31670 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
31680 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20  n_text() or.**  
31690 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75      sqlite3_colu
316a0 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63  mn_text16() is c
316b0 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74  alled.  A zero-t
316c0 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a  erminator might.
316d0 2a 2a 20 20 20 20 20 20 6e 65 65 64 20 74 6f 20  **      need to 
316e0 62 65 20 61 64 64 65 64 20 74 6f 20 74 68 65 20  be added to the 
316f0 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20  string.</li>.** 
31700 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c  <li> The initial
31710 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d   content is UTF-
31720 38 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74  8 text and sqlit
31730 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
31740 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73  6() or.**      s
31750 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
31760 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64  xt16() is called
31770 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d  .  The content m
31780 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64  ust be converted
31790 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d  .**      to UTF-
317a0 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e  16.</li>.** <li>
317b0 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e   The initial con
317c0 74 65 6e 74 20 69 73 20 55 54 46 2d 31 36 20 74  tent is UTF-16 t
317d0 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  ext and sqlite3_
317e0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f  column_bytes() o
317f0 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65  r.**      sqlite
31800 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
31810 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20  is called.  The 
31820 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20  content must be 
31830 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20  converted.**    
31840 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e    to UTF-8.</li>
31850 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
31860 5e 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65 74  ^Conversions bet
31870 77 65 65 6e 20 55 54 46 2d 31 36 62 65 20 61 6e  ween UTF-16be an
31880 64 20 55 54 46 2d 31 36 6c 65 20 61 72 65 20 61  d UTF-16le are a
31890 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c  lways done in pl
318a0 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f  ace and do.** no
318b0 74 20 69 6e 76 61 6c 69 64 61 74 65 20 61 20 70  t invalidate a p
318c0 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74 68  rior pointer, th
318d0 6f 75 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74  ough of course t
318e0 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
318f0 65 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74  e buffer.** that
31900 20 74 68 65 20 70 72 69 6f 72 20 70 6f 69 6e 74   the prior point
31910 65 72 20 72 65 66 65 72 65 6e 63 65 73 20 77 69  er references wi
31920 6c 6c 20 68 61 76 65 20 62 65 65 6e 20 6d 6f 64  ll have been mod
31930 69 66 69 65 64 2e 20 20 4f 74 68 65 72 20 6b 69  ified.  Other ki
31940 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72  nds.** of conver
31950 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e  sion are done in
31960 20 70 6c 61 63 65 20 77 68 65 6e 20 69 74 20 69   place when it i
31970 73 20 70 6f 73 73 69 62 6c 65 2c 20 62 75 74 20  s possible, but 
31980 73 6f 6d 65 74 69 6d 65 73 20 74 68 65 79 0a 2a  sometimes they.*
31990 2a 20 61 72 65 20 6e 6f 74 20 70 6f 73 73 69 62  * are not possib
319a0 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f 73 65 20  le and in those 
319b0 63 61 73 65 73 20 70 72 69 6f 72 20 70 6f 69 6e  cases prior poin
319c0 74 65 72 73 20 61 72 65 20 69 6e 76 61 6c 69 64  ters are invalid
319d0 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ated..**.** The 
319e0 73 61 66 65 73 74 20 61 6e 64 20 65 61 73 69 65  safest and easie
319f0 73 74 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 70  st to remember p
31a00 6f 6c 69 63 79 20 69 73 20 74 6f 20 69 6e 76 6f  olicy is to invo
31a10 6b 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  ke these routine
31a20 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74  s.** in one of t
31a30 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79  he following way
31a40 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
31a50 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f    <li>sqlite3_co
31a60 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c  lumn_text() foll
31a70 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  owed by sqlite3_
31a80 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f  column_bytes()</
31a90 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69  li>.**  <li>sqli
31aa0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
31ab0 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71  ) followed by sq
31ac0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
31ad0 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c  es()</li>.**  <l
31ae0 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  i>sqlite3_column
31af0 5f 74 65 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77  _text16() follow
31b00 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
31b10 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f  lumn_bytes16()</
31b20 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  li>.** </ul>.**.
31b30 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  ** In other word
31b40 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20 63 61  s, you should ca
31b50 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ll sqlite3_colum
31b60 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a 20 73 71 6c  n_text(),.** sql
31b70 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
31b80 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  (), or sqlite3_c
31b90 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66  olumn_text16() f
31ba0 69 72 73 74 20 74 6f 20 66 6f 72 63 65 20 74 68  irst to force th
31bb0 65 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f  e result.** into
31bc0 20 74 68 65 20 64 65 73 69 72 65 64 20 66 6f 72   the desired for
31bd0 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65  mat, then invoke
31be0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
31bf0 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 73 71  bytes() or.** sq
31c00 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
31c10 65 73 31 36 28 29 20 74 6f 20 66 69 6e 64 20 74  es16() to find t
31c20 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 72  he size of the r
31c30 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d  esult.  Do not m
31c40 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73  ix calls.** to s
31c50 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
31c60 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  xt() or sqlite3_
31c70 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69  column_blob() wi
31c80 74 68 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73  th calls to.** s
31c90 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
31ca0 74 65 73 31 36 28 29 2c 20 61 6e 64 20 64 6f 20  tes16(), and do 
31cb0 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f  not mix calls to
31cc0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
31cd0 74 65 78 74 31 36 28 29 0a 2a 2a 20 77 69 74 68  text16().** with
31ce0 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
31cf0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
31d00 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f 69  ..**.** ^The poi
31d10 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 61  nters returned a
31d20 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 61  re valid until a
31d30 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   type conversion
31d40 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20 64 65   occurs as.** de
31d50 73 63 72 69 62 65 64 20 61 62 6f 76 65 2c 20 6f  scribed above, o
31d60 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33  r until [sqlite3
31d70 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c  _step()] or [sql
31d80 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
31d90 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  .** [sqlite3_fin
31da0 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c  alize()] is call
31db0 65 64 2e 20 20 5e 54 68 65 20 6d 65 6d 6f 72 79  ed.  ^The memory
31dc0 20 73 70 61 63 65 20 75 73 65 64 20 74 6f 20 68   space used to h
31dd0 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61  old strings.** a
31de0 6e 64 20 42 4c 4f 42 73 20 69 73 20 66 72 65 65  nd BLOBs is free
31df0 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e  d automatically.
31e00 20 20 44 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20    Do <b>not</b> 
31e10 70 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65 72  pass the pointer
31e20 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72  s returned.** fr
31e30 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  om [sqlite3_colu
31e40 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c  mn_blob()], [sql
31e50 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
31e60 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 0a 2a  ()], etc. into.*
31e70 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  * [sqlite3_free(
31e80 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61  )]..**.** ^(If a
31e90 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
31ea0 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  on error occurs 
31eb0 64 75 72 69 6e 67 20 74 68 65 20 65 76 61 6c 75  during the evalu
31ec0 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20  ation of any.** 
31ed0 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
31ee0 73 2c 20 61 20 64 65 66 61 75 6c 74 20 76 61 6c  s, a default val
31ef0 75 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  ue is returned. 
31f00 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c   The default val
31f10 75 65 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20  ue.** is either 
31f20 74 68 65 20 69 6e 74 65 67 65 72 20 30 2c 20 74  the integer 0, t
31f30 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  he floating poin
31f40 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72  t number 0.0, or
31f50 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74   a NULL.** point
31f60 65 72 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20  er.  Subsequent 
31f70 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
31f80 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 77 69 6c  3_errcode()] wil
31f90 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c  l return.** [SQL
31fa0 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f  ITE_NOMEM].)^.*/
31fb0 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
31fc0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
31fd0 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69  column_blob(sqli
31fe0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
31ff0 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  Col);.SQLITE_API
32000 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c   int sqlite3_col
32010 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 74 65  umn_bytes(sqlite
32020 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
32030 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  l);.SQLITE_API i
32040 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
32050 6e 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65  n_bytes16(sqlite
32060 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
32070 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 64  l);.SQLITE_API d
32080 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f  ouble sqlite3_co
32090 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69  lumn_double(sqli
320a0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
320b0 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  Col);.SQLITE_API
320c0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c   int sqlite3_col
320d0 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f  umn_int(sqlite3_
320e0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
320f0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c  ;.SQLITE_API sql
32100 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
32110 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28  e3_column_int64(
32120 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
32130 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45  nt iCol);.SQLITE
32140 5f 41 50 49 20 63 6f 6e 73 74 20 75 6e 73 69 67  _API const unsig
32150 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65  ned char *sqlite
32160 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71  3_column_text(sq
32170 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
32180 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41   iCol);.SQLITE_A
32190 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  PI const void *s
321a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
321b0 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  xt16(sqlite3_stm
321c0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53  t*, int iCol);.S
321d0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
321e0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
321f0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
32200 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49   int iCol);.SQLI
32210 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 76  TE_API sqlite3_v
32220 61 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f 63 6f  alue *sqlite3_co
32230 6c 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74  lumn_value(sqlit
32240 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
32250 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ol);../*.** CAPI
32260 33 52 45 46 3a 20 44 65 73 74 72 6f 79 20 41 20  3REF: Destroy A 
32270 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
32280 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20  nt Object.**.** 
32290 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e  ^The sqlite3_fin
322a0 61 6c 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e  alize() function
322b0 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 64 65   is called to de
322c0 6c 65 74 65 20 61 20 5b 70 72 65 70 61 72 65 64  lete a [prepared
322d0 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20   statement]..** 
322e0 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63  ^If the most rec
322f0 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f  ent evaluation o
32300 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
32310 65 6e 63 6f 75 6e 74 65 72 65 64 20 6e 6f 20 65  encountered no e
32320 72 72 6f 72 73 0a 2a 2a 20 6f 72 20 69 66 20 74  rrors.** or if t
32330 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
32340 6e 65 76 65 72 20 62 65 65 6e 20 65 76 61 6c 75  never been evalu
32350 61 74 65 64 2c 20 74 68 65 6e 20 73 71 6c 69 74  ated, then sqlit
32360 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 72 65  e3_finalize() re
32370 74 75 72 6e 73 0a 2a 2a 20 53 51 4c 49 54 45 5f  turns.** SQLITE_
32380 4f 4b 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 73  OK.  ^If the mos
32390 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74  t recent evaluat
323a0 69 6f 6e 20 6f 66 20 73 74 61 74 65 6d 65 6e 74  ion of statement
323b0 20 53 20 66 61 69 6c 65 64 2c 20 74 68 65 6e 0a   S failed, then.
323c0 2a 2a 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  ** sqlite3_final
323d0 69 7a 65 28 53 29 20 72 65 74 75 72 6e 73 20 74  ize(S) returns t
323e0 68 65 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b  he appropriate [
323f0 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 0a 2a  error code] or.*
32400 2a 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f  * [extended erro
32410 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  r code]..**.** ^
32420 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  The sqlite3_fina
32430 6c 69 7a 65 28 53 29 20 72 6f 75 74 69 6e 65 20  lize(S) routine 
32440 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 74  can be called at
32450 20 61 6e 79 20 70 6f 69 6e 74 20 64 75 72 69 6e   any point durin
32460 67 0a 2a 2a 20 74 68 65 20 6c 69 66 65 20 63 79  g.** the life cy
32470 63 6c 65 20 6f 66 20 5b 70 72 65 70 61 72 65 64  cle of [prepared
32480 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 3a 0a 2a   statement] S:.*
32490 2a 20 62 65 66 6f 72 65 20 73 74 61 74 65 6d 65  * before stateme
324a0 6e 74 20 53 20 69 73 20 65 76 65 72 20 65 76 61  nt S is ever eva
324b0 6c 75 61 74 65 64 2c 20 61 66 74 65 72 0a 2a 2a  luated, after.**
324c0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 63 61 6c   one or more cal
324d0 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  ls to [sqlite3_r
324e0 65 73 65 74 28 29 5d 2c 20 6f 72 20 61 66 74 65  eset()], or afte
324f0 72 20 61 6e 79 20 63 61 6c 6c 0a 2a 2a 20 74 6f  r any call.** to
32500 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
32510 5d 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20  ] regardless of 
32520 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
32530 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73  he statement has
32540 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65 78  .** completed ex
32550 65 63 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  ecution..**.** ^
32560 49 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33  Invoking sqlite3
32570 5f 66 69 6e 61 6c 69 7a 65 28 29 20 6f 6e 20 61  _finalize() on a
32580 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73   NULL pointer is
32590 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f   a harmless no-o
325a0 70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70  p..**.** The app
325b0 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 66 69  lication must fi
325c0 6e 61 6c 69 7a 65 20 65 76 65 72 79 20 5b 70 72  nalize every [pr
325d0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
325e0 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 61 76  ] in order to av
325f0 6f 69 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 20  oid.** resource 
32600 6c 65 61 6b 73 2e 20 20 49 74 20 69 73 20 61 20  leaks.  It is a 
32610 67 72 69 65 76 6f 75 73 20 65 72 72 6f 72 20 66  grievous error f
32620 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  or the applicati
32630 6f 6e 20 74 6f 20 74 72 79 20 74 6f 20 75 73 65  on to try to use
32640 0a 2a 2a 20 61 20 70 72 65 70 61 72 65 64 20 73  .** a prepared s
32650 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69  tatement after i
32660 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c  t has been final
32670 69 7a 65 64 2e 20 20 41 6e 79 20 75 73 65 20 6f  ized.  Any use o
32680 66 20 61 20 70 72 65 70 61 72 65 64 0a 2a 2a 20  f a prepared.** 
32690 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20  statement after 
326a0 69 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61  it has been fina
326b0 6c 69 7a 65 64 20 63 61 6e 20 72 65 73 75 6c 74  lized can result
326c0 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 61 6e   in undefined an
326d0 64 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65  d.** undesirable
326e0 20 62 65 68 61 76 69 6f 72 20 73 75 63 68 20 61   behavior such a
326f0 73 20 73 65 67 66 61 75 6c 74 73 20 61 6e 64 20  s segfaults and 
32700 68 65 61 70 20 63 6f 72 72 75 70 74 69 6f 6e 2e  heap corruption.
32710 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
32720 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  nt sqlite3_final
32730 69 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ize(sqlite3_stmt
32740 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
32750 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74   CAPI3REF: Reset
32760 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74   A Prepared Stat
32770 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a  ement Object.**.
32780 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
32790 65 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20  eset() function 
327a0 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73  is called to res
327b0 65 74 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  et a [prepared s
327c0 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a  tatement].** obj
327d0 65 63 74 20 62 61 63 6b 20 74 6f 20 69 74 73 20  ect back to its 
327e0 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72  initial state, r
327f0 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78  eady to be re-ex
32800 65 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20  ecuted..** ^Any 
32810 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61  SQL statement va
32820 72 69 61 62 6c 65 73 20 74 68 61 74 20 68 61 64  riables that had
32830 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f   values bound to
32840 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74   them using.** t
32850 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  he [sqlite3_bind
32860 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f  _blob | sqlite3_
32870 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65  bind_*() API] re
32880 74 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65  tain their value
32890 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74  s..** Use [sqlit
328a0 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67  e3_clear_binding
328b0 73 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68  s()] to reset th
328c0 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a  e bindings..**.*
328d0 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  * ^The [sqlite3_
328e0 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66  reset(S)] interf
328f0 61 63 65 20 72 65 73 65 74 73 20 74 68 65 20 5b  ace resets the [
32900 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
32910 6e 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74 6f  nt] S.** back to
32920 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f   the beginning o
32930 66 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a  f its program..*
32940 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73  *.** ^If the mos
32950 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f  t recent call to
32960 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
32970 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70  )] for the.** [p
32980 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
32990 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b 53  t] S returned [S
329a0 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53  QLITE_ROW] or [S
329b0 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20  QLITE_DONE],.** 
329c0 6f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 73  or if [sqlite3_s
329d0 74 65 70 28 53 29 5d 20 68 61 73 20 6e 65 76 65  tep(S)] has neve
329e0 72 20 62 65 66 6f 72 65 20 62 65 65 6e 20 63 61  r before been ca
329f0 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68  lled on S,.** th
32a00 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  en [sqlite3_rese
32a10 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b 53  t(S)] returns [S
32a20 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a  QLITE_OK]..**.**
32a30 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65   ^If the most re
32a40 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  cent call to [sq
32a50 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66  lite3_step(S)] f
32a60 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  or the.** [prepa
32a70 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
32a80 20 69 6e 64 69 63 61 74 65 64 20 61 6e 20 65 72   indicated an er
32a90 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 71  ror, then.** [sq
32aa0 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20  lite3_reset(S)] 
32ab0 72 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f  returns an appro
32ac0 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f  priate [error co
32ad0 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  de]..**.** ^The 
32ae0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
32af0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65  )] interface doe
32b00 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65  s not change the
32b10 20 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 6e   values.** of an
32b20 79 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  y [sqlite3_bind_
32b30 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f  blob|bindings] o
32b40 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  n the [prepared 
32b50 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f  statement] S..*/
32b60 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
32b70 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73 71  sqlite3_reset(sq
32b80 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
32b90 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
32ba0 52 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20 52  REF: Create Or R
32bb0 65 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e 63  edefine SQL Func
32bc0 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  tions.** KEYWORD
32bd0 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65  S: {function cre
32be0 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a  ation routines}.
32bf0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70  ** KEYWORDS: {ap
32c00 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
32c10 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a  d SQL function}.
32c20 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70  ** KEYWORDS: {ap
32c30 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
32c40 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d  d SQL functions}
32c50 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75  .**.** ^These fu
32c60 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 63 74  nctions (collect
32c70 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 22  ively known as "
32c80 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f  function creatio
32c90 6e 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a 2a 20  n routines").** 
32ca0 61 72 65 20 75 73 65 64 20 74 6f 20 61 64 64 20  are used to add 
32cb0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72  SQL functions or
32cc0 20 61 67 67 72 65 67 61 74 65 73 20 6f 72 20 74   aggregates or t
32cd0 6f 20 72 65 64 65 66 69 6e 65 20 74 68 65 20 62  o redefine the b
32ce0 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 65 78  ehavior.** of ex
32cf0 69 73 74 69 6e 67 20 53 51 4c 20 66 75 6e 63 74  isting SQL funct
32d00 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74  ions or aggregat
32d10 65 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 64 69  es.  The only di
32d20 66 66 65 72 65 6e 63 65 73 20 62 65 74 77 65 65  fferences betwee
32d30 6e 0a 2a 2a 20 74 68 65 73 65 20 72 6f 75 74 69  n.** these routi
32d40 6e 65 73 20 61 72 65 20 74 68 65 20 74 65 78 74  nes are the text
32d50 20 65 6e 63 6f 64 69 6e 67 20 65 78 70 65 63 74   encoding expect
32d60 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 73 65  ed for.** the se
32d70 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 28  cond parameter (
32d80 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
32d90 66 75 6e 63 74 69 6f 6e 20 62 65 69 6e 67 20 63  function being c
32da0 72 65 61 74 65 64 29 0a 2a 2a 20 61 6e 64 20 74  reated).** and t
32db0 68 65 20 70 72 65 73 65 6e 63 65 20 6f 72 20 61  he presence or a
32dc0 62 73 65 6e 63 65 20 6f 66 20 61 20 64 65 73 74  bsence of a dest
32dd0 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20  ructor callback 
32de0 66 6f 72 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69  for.** the appli
32df0 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e  cation data poin
32e00 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ter..**.** ^The 
32e10 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
32e20 69 73 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  is the [database
32e30 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20   connection] to 
32e40 77 68 69 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a  which the SQL.**
32e50 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20   function is to 
32e60 62 65 20 61 64 64 65 64 2e 20 20 5e 49 66 20 61  be added.  ^If a
32e70 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73  n application us
32e80 65 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65  es more than one
32e90 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e   database.** con
32ea0 6e 65 63 74 69 6f 6e 20 74 68 65 6e 20 61 70 70  nection then app
32eb0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
32ec0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6d   SQL functions m
32ed0 75 73 74 20 62 65 20 61 64 64 65 64 0a 2a 2a 20  ust be added.** 
32ee0 74 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 65  to each database
32ef0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 65 70 61   connection sepa
32f00 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54  rately..**.** ^T
32f10 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
32f20 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20  ter is the name 
32f30 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  of the SQL funct
32f40 69 6f 6e 20 74 6f 20 62 65 20 63 72 65 61 74 65  ion to be create
32f50 64 20 6f 72 0a 2a 2a 20 72 65 64 65 66 69 6e 65  d or.** redefine
32f60 64 2e 20 20 5e 54 68 65 20 6c 65 6e 67 74 68 20  d.  ^The length 
32f70 6f 66 20 74 68 65 20 6e 61 6d 65 20 69 73 20 6c  of the name is l
32f80 69 6d 69 74 65 64 20 74 6f 20 32 35 35 20 62 79  imited to 255 by
32f90 74 65 73 20 69 6e 20 61 20 55 54 46 2d 38 0a 2a  tes in a UTF-8.*
32fa0 2a 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e  * representation
32fb0 2c 20 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74  , exclusive of t
32fc0 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  he zero-terminat
32fd0 6f 72 2e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20  or.  ^Note that 
32fe0 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 6c 65 6e 67  the name.** leng
32ff0 74 68 20 6c 69 6d 69 74 20 69 73 20 69 6e 20 55  th limit is in U
33000 54 46 2d 38 20 62 79 74 65 73 2c 20 6e 6f 74 20  TF-8 bytes, not 
33010 63 68 61 72 61 63 74 65 72 73 20 6e 6f 72 20 55  characters nor U
33020 54 46 2d 31 36 20 62 79 74 65 73 2e 20 20 0a 2a  TF-16 bytes.  .*
33030 2a 20 5e 41 6e 79 20 61 74 74 65 6d 70 74 20 74  * ^Any attempt t
33040 6f 20 63 72 65 61 74 65 20 61 20 66 75 6e 63 74  o create a funct
33050 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67 65  ion with a longe
33060 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72  r name.** will r
33070 65 73 75 6c 74 20 69 6e 20 5b 53 51 4c 49 54 45  esult in [SQLITE
33080 5f 4d 49 53 55 53 45 5d 20 62 65 69 6e 67 20 72  _MISUSE] being r
33090 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  eturned..**.** ^
330a0 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  The third parame
330b0 74 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20 69 73  ter (nArg).** is
330c0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61   the number of a
330d0 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 74 68  rguments that th
330e0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f  e SQL function o
330f0 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 74  r.** aggregate t
33100 61 6b 65 73 2e 20 5e 49 66 20 74 68 69 73 20 70  akes. ^If this p
33110 61 72 61 6d 65 74 65 72 20 69 73 20 2d 31 2c 20  arameter is -1, 
33120 74 68 65 6e 20 74 68 65 20 53 51 4c 20 66 75 6e  then the SQL fun
33130 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72  ction or.** aggr
33140 65 67 61 74 65 20 6d 61 79 20 74 61 6b 65 20 61  egate may take a
33150 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67  ny number of arg
33160 75 6d 65 6e 74 73 20 62 65 74 77 65 65 6e 20 30  uments between 0
33170 20 61 6e 64 20 74 68 65 20 6c 69 6d 69 74 0a 2a   and the limit.*
33180 2a 20 73 65 74 20 62 79 20 5b 73 71 6c 69 74 65  * set by [sqlite
33190 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45  3_limit]([SQLITE
331a0 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f  _LIMIT_FUNCTION_
331b0 41 52 47 5d 29 2e 20 20 49 66 20 74 68 65 20 74  ARG]).  If the t
331c0 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65  hird.** paramete
331d0 72 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 2d  r is less than -
331e0 31 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61  1 or greater tha
331f0 6e 20 31 32 37 20 74 68 65 6e 20 74 68 65 20 62  n 127 then the b
33200 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75 6e  ehavior is.** un
33210 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  defined..**.** ^
33220 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  The fourth param
33230 65 74 65 72 2c 20 65 54 65 78 74 52 65 70 2c 20  eter, eTextRep, 
33240 73 70 65 63 69 66 69 65 73 20 77 68 61 74 0a 2a  specifies what.*
33250 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c  * [SQLITE_UTF8 |
33260 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20   text encoding] 
33270 74 68 69 73 20 53 51 4c 20 66 75 6e 63 74 69 6f  this SQL functio
33280 6e 20 70 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a  n prefers for.**
33290 20 69 74 73 20 70 61 72 61 6d 65 74 65 72 73 2e   its parameters.
332a0 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f    The applicatio
332b0 6e 20 73 68 6f 75 6c 64 20 73 65 74 20 74 68 69  n should set thi
332c0 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  s parameter to.*
332d0 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c  * [SQLITE_UTF16L
332e0 45 5d 20 69 66 20 74 68 65 20 66 75 6e 63 74 69  E] if the functi
332f0 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  on implementatio
33300 6e 20 69 6e 76 6f 6b 65 73 20 0a 2a 2a 20 5b 73  n invokes .** [s
33310 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
33320 74 31 36 6c 65 28 29 5d 20 6f 6e 20 61 6e 20 69  t16le()] on an i
33330 6e 70 75 74 2c 20 6f 72 20 5b 53 51 4c 49 54 45  nput, or [SQLITE
33340 5f 55 54 46 31 36 42 45 5d 20 69 66 20 74 68 65  _UTF16BE] if the
33350 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
33360 6f 6e 20 69 6e 76 6f 6b 65 73 20 5b 73 71 6c 69  on invokes [sqli
33370 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
33380 62 65 28 29 5d 20 6f 6e 20 61 6e 20 69 6e 70 75  be()] on an inpu
33390 74 2c 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45  t, or.** [SQLITE
333a0 5f 55 54 46 31 36 5d 20 69 66 20 5b 73 71 6c 69  _UTF16] if [sqli
333b0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
333c0 28 29 5d 20 69 73 20 75 73 65 64 2c 20 6f 72 20  ()] is used, or 
333d0 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 0a 2a 2a  [SQLITE_UTF8].**
333e0 20 6f 74 68 65 72 77 69 73 65 2e 20 20 5e 54 68   otherwise.  ^Th
333f0 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74  e same SQL funct
33400 69 6f 6e 20 6d 61 79 20 62 65 20 72 65 67 69 73  ion may be regis
33410 74 65 72 65 64 20 6d 75 6c 74 69 70 6c 65 20 74  tered multiple t
33420 69 6d 65 73 20 75 73 69 6e 67 0a 2a 2a 20 64 69  imes using.** di
33430 66 66 65 72 65 6e 74 20 70 72 65 66 65 72 72 65  fferent preferre
33440 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73  d text encodings
33450 2c 20 77 69 74 68 20 64 69 66 66 65 72 65 6e 74  , with different
33460 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
33470 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 65 6e 63   for.** each enc
33480 6f 64 69 6e 67 2e 0a 2a 2a 20 5e 57 68 65 6e 20  oding..** ^When 
33490 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65  multiple impleme
334a0 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ntations of the 
334b0 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 61 72  same function ar
334c0 65 20 61 76 61 69 6c 61 62 6c 65 2c 20 53 51 4c  e available, SQL
334d0 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 63 6b  ite.** will pick
334e0 20 74 68 65 20 6f 6e 65 20 74 68 61 74 20 69 6e   the one that in
334f0 76 6f 6c 76 65 73 20 74 68 65 20 6c 65 61 73 74  volves the least
33500 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20   amount of data 
33510 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a  conversion..**.*
33520 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61  * ^The fourth pa
33530 72 61 6d 65 74 65 72 20 6d 61 79 20 6f 70 74 69  rameter may opti
33540 6f 6e 61 6c 6c 79 20 62 65 20 4f 52 65 64 20 77  onally be ORed w
33550 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 45 54 45  ith [SQLITE_DETE
33560 52 4d 49 4e 49 53 54 49 43 5d 0a 2a 2a 20 74 6f  RMINISTIC].** to
33570 20 73 69 67 6e 61 6c 20 74 68 61 74 20 74 68 65   signal that the
33580 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 61   function will a
33590 6c 77 61 79 73 20 72 65 74 75 72 6e 20 74 68 65  lways return the
335a0 20 73 61 6d 65 20 72 65 73 75 6c 74 20 67 69 76   same result giv
335b0 65 6e 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 69  en.** the same i
335c0 6e 70 75 74 73 20 77 69 74 68 69 6e 20 61 20 73  nputs within a s
335d0 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d  ingle SQL statem
335e0 65 6e 74 2e 20 20 4d 6f 73 74 20 53 51 4c 20 66  ent.  Most SQL f
335f0 75 6e 63 74 69 6f 6e 73 20 61 72 65 0a 2a 2a 20  unctions are.** 
33600 64 65 74 65 72 6d 69 6e 69 73 74 69 63 2e 20 20  deterministic.  
33610 54 68 65 20 62 75 69 6c 74 2d 69 6e 20 5b 72 61  The built-in [ra
33620 6e 64 6f 6d 28 29 5d 20 53 51 4c 20 66 75 6e 63  ndom()] SQL func
33630 74 69 6f 6e 20 69 73 20 61 6e 20 65 78 61 6d 70  tion is an examp
33640 6c 65 20 6f 66 20 61 0a 2a 2a 20 66 75 6e 63 74  le of a.** funct
33650 69 6f 6e 20 74 68 61 74 20 69 73 20 6e 6f 74 20  ion that is not 
33660 64 65 74 65 72 6d 69 6e 69 73 74 69 63 2e 20 20  deterministic.  
33670 54 68 65 20 53 51 4c 69 74 65 20 71 75 65 72 79  The SQLite query
33680 20 70 6c 61 6e 6e 65 72 20 69 73 20 61 62 6c 65   planner is able
33690 20 74 6f 0a 2a 2a 20 70 65 72 66 6f 72 6d 20 61   to.** perform a
336a0 64 64 69 74 69 6f 6e 61 6c 20 6f 70 74 69 6d 69  dditional optimi
336b0 7a 61 74 69 6f 6e 73 20 6f 6e 20 64 65 74 65 72  zations on deter
336c0 6d 69 6e 69 73 74 69 63 20 66 75 6e 63 74 69 6f  ministic functio
336d0 6e 73 2c 20 73 6f 20 75 73 65 0a 2a 2a 20 6f 66  ns, so use.** of
336e0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 44 45 54   the [SQLITE_DET
336f0 45 52 4d 49 4e 49 53 54 49 43 5d 20 66 6c 61 67  ERMINISTIC] flag
33700 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
33710 77 68 65 72 65 20 70 6f 73 73 69 62 6c 65 2e 0a  where possible..
33720 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 66 74  **.** ^(The fift
33730 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  h parameter is a
33740 6e 20 61 72 62 69 74 72 61 72 79 20 70 6f 69 6e  n arbitrary poin
33750 74 65 72 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d  ter.  The implem
33760 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a  entation of the.
33770 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20  ** function can 
33780 67 61 69 6e 20 61 63 63 65 73 73 20 74 6f 20 74  gain access to t
33790 68 69 73 20 70 6f 69 6e 74 65 72 20 75 73 69 6e  his pointer usin
337a0 67 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f  g [sqlite3_user_
337b0 64 61 74 61 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a  data()].)^.**.**
337c0 20 5e 54 68 65 20 73 69 78 74 68 2c 20 73 65 76   ^The sixth, sev
337d0 65 6e 74 68 20 61 6e 64 20 65 69 67 68 74 68 20  enth and eighth 
337e0 70 61 72 61 6d 65 74 65 72 73 2c 20 78 46 75 6e  parameters, xFun
337f0 63 2c 20 78 53 74 65 70 20 61 6e 64 20 78 46 69  c, xStep and xFi
33800 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e  nal, are.** poin
33810 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61  ters to C-langua
33820 67 65 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61  ge functions tha
33830 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20  t implement the 
33840 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a  SQL function or.
33850 2a 2a 20 61 67 67 72 65 67 61 74 65 2e 20 5e 41  ** aggregate. ^A
33860 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63   scalar SQL func
33870 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e  tion requires an
33880 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
33890 6f 66 20 74 68 65 20 78 46 75 6e 63 0a 2a 2a 20  of the xFunc.** 
338a0 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 3b 20 4e  callback only; N
338b0 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 6d 75 73  ULL pointers mus
338c0 74 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74  t be passed as t
338d0 68 65 20 78 53 74 65 70 20 61 6e 64 20 78 46 69  he xStep and xFi
338e0 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  nal.** parameter
338f0 73 2e 20 5e 41 6e 20 61 67 67 72 65 67 61 74 65  s. ^An aggregate
33900 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65   SQL function re
33910 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d  quires an implem
33920 65 6e 74 61 74 69 6f 6e 20 6f 66 20 78 53 74 65  entation of xSte
33930 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20  p.** and xFinal 
33940 61 6e 64 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  and NULL pointer
33950 20 6d 75 73 74 20 62 65 20 70 61 73 73 65 64 20   must be passed 
33960 66 6f 72 20 78 46 75 6e 63 2e 20 5e 54 6f 20 64  for xFunc. ^To d
33970 65 6c 65 74 65 20 61 6e 20 65 78 69 73 74 69 6e  elete an existin
33980 67 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f  g.** SQL functio
33990 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2c 20  n or aggregate, 
339a0 70 61 73 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  pass NULL pointe
339b0 72 73 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 65  rs for all three
339c0 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c   function.** cal
339d0 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28  lbacks..**.** ^(
339e0 49 66 20 74 68 65 20 6e 69 6e 74 68 20 70 61 72  If the ninth par
339f0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
33a00 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
33a10 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 4e 55  n_v2() is not NU
33a20 4c 4c 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69  LL,.** then it i
33a30 73 20 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72  s destructor for
33a40 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
33a50 20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e 20 0a   data pointer. .
33a60 2a 2a 20 54 68 65 20 64 65 73 74 72 75 63 74 6f  ** The destructo
33a70 72 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65  r is invoked whe
33a80 6e 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69  n the function i
33a90 73 20 64 65 6c 65 74 65 64 2c 20 65 69 74 68 65  s deleted, eithe
33aa0 72 20 62 79 20 62 65 69 6e 67 0a 2a 2a 20 6f 76  r by being.** ov
33ab0 65 72 6c 6f 61 64 65 64 20 6f 72 20 77 68 65 6e  erloaded or when
33ac0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
33ad0 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e  nnection closes.
33ae0 29 5e 0a 2a 2a 20 5e 54 68 65 20 64 65 73 74 72  )^.** ^The destr
33af0 75 63 74 6f 72 20 69 73 20 61 6c 73 6f 20 69 6e  uctor is also in
33b00 76 6f 6b 65 64 20 69 66 20 74 68 65 20 63 61 6c  voked if the cal
33b10 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  l to.** sqlite3_
33b20 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f  create_function_
33b30 76 32 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e  v2() fails..** ^
33b40 57 68 65 6e 20 74 68 65 20 64 65 73 74 72 75 63  When the destruc
33b50 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20  tor callback of 
33b60 74 68 65 20 74 65 6e 74 68 20 70 61 72 61 6d 65  the tenth parame
33b70 74 65 72 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20  ter is invoked, 
33b80 69 74 0a 2a 2a 20 69 73 20 70 61 73 73 65 64 20  it.** is passed 
33b90 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
33ba0 74 20 77 68 69 63 68 20 69 73 20 61 20 63 6f 70  t which is a cop
33bb0 79 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  y of the applica
33bc0 74 69 6f 6e 20 64 61 74 61 20 0a 2a 2a 20 70 6f  tion data .** po
33bd0 69 6e 74 65 72 20 77 68 69 63 68 20 77 61 73 20  inter which was 
33be0 74 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65  the fifth parame
33bf0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  ter to sqlite3_c
33c00 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76  reate_function_v
33c10 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69  2()..**.** ^It i
33c20 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 72  s permitted to r
33c30 65 67 69 73 74 65 72 20 6d 75 6c 74 69 70 6c 65  egister multiple
33c40 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
33c50 20 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20   of the same.** 
33c60 66 75 6e 63 74 69 6f 6e 73 20 77 69 74 68 20 74  functions with t
33c70 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74  he same name but
33c80 20 77 69 74 68 20 65 69 74 68 65 72 20 64 69 66   with either dif
33c90 66 65 72 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f  fering numbers o
33ca0 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f  f.** arguments o
33cb0 72 20 64 69 66 66 65 72 69 6e 67 20 70 72 65 66  r differing pref
33cc0 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64  erred text encod
33cd0 69 6e 67 73 2e 20 20 5e 53 51 4c 69 74 65 20 77  ings.  ^SQLite w
33ce0 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20 69  ill use.** the i
33cf0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74 68  mplementation th
33d00 61 74 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20  at most closely 
33d10 6d 61 74 63 68 65 73 20 74 68 65 20 77 61 79 20  matches the way 
33d20 69 6e 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20  in which the.** 
33d30 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  SQL function is 
33d40 75 73 65 64 2e 20 20 5e 41 20 66 75 6e 63 74 69  used.  ^A functi
33d50 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  on implementatio
33d60 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d 6e 65 67  n with a non-neg
33d70 61 74 69 76 65 0a 2a 2a 20 6e 41 72 67 20 70 61  ative.** nArg pa
33d80 72 61 6d 65 74 65 72 20 69 73 20 61 20 62 65 74  rameter is a bet
33d90 74 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61  ter match than a
33da0 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
33db0 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 0a 2a 2a  entation with.**
33dc0 20 61 20 6e 65 67 61 74 69 76 65 20 6e 41 72 67   a negative nArg
33dd0 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77  .  ^A function w
33de0 68 65 72 65 20 74 68 65 20 70 72 65 66 65 72 72  here the preferr
33df0 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  ed text encoding
33e00 0a 2a 2a 20 6d 61 74 63 68 65 73 20 74 68 65 20  .** matches the 
33e10 64 61 74 61 62 61 73 65 20 65 6e 63 6f 64 69 6e  database encodin
33e20 67 20 69 73 20 61 20 62 65 74 74 65 72 0a 2a 2a  g is a better.**
33e30 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75   match than a fu
33e40 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65  nction where the
33e50 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66   encoding is dif
33e60 66 65 72 65 6e 74 2e 20 20 0a 2a 2a 20 5e 41 20  ferent.  .** ^A 
33e70 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74  function where t
33e80 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66  he encoding diff
33e90 65 72 65 6e 63 65 20 69 73 20 62 65 74 77 65 65  erence is betwee
33ea0 6e 20 55 54 46 31 36 6c 65 20 61 6e 64 20 55 54  n UTF16le and UT
33eb0 46 31 36 62 65 0a 2a 2a 20 69 73 20 61 20 63 6c  F16be.** is a cl
33ec0 6f 73 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20  oser match than 
33ed0 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65  a function where
33ee0 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69   the encoding di
33ef0 66 66 65 72 65 6e 63 65 20 69 73 0a 2a 2a 20 62  fference is.** b
33f00 65 74 77 65 65 6e 20 55 54 46 38 20 61 6e 64 20  etween UTF8 and 
33f10 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75  UTF16..**.** ^Bu
33f20 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73  ilt-in functions
33f30 20 6d 61 79 20 62 65 20 6f 76 65 72 6c 6f 61 64   may be overload
33f40 65 64 20 62 79 20 6e 65 77 20 61 70 70 6c 69 63  ed by new applic
33f50 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
33f60 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  nctions..**.** ^
33f70 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  An application-d
33f80 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
33f90 69 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20  is permitted to 
33fa0 63 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 53 51  call other.** SQ
33fb0 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 2e  Lite interfaces.
33fc0 20 20 48 6f 77 65 76 65 72 2c 20 73 75 63 68 20    However, such 
33fd0 63 61 6c 6c 73 20 6d 75 73 74 20 6e 6f 74 0a 2a  calls must not.*
33fe0 2a 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61  * close the data
33ff0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
34000 6e 6f 72 20 66 69 6e 61 6c 69 7a 65 20 6f 72 20  nor finalize or 
34010 72 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72  reset the prepar
34020 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  ed.** statement 
34030 69 6e 20 77 68 69 63 68 20 74 68 65 20 66 75 6e  in which the fun
34040 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67  ction is running
34050 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
34060 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
34070 74 65 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73  te_function(.  s
34080 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f  qlite3 *db,.  co
34090 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74  nst char *zFunct
340a0 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e  ionName,.  int n
340b0 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74  Arg,.  int eText
340c0 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70  Rep,.  void *pAp
340d0 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e  p,.  void (*xFun
340e0 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  c)(sqlite3_conte
340f0 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
34100 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
34110 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65   (*xStep)(sqlite
34120 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
34130 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
34140 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c  .  void (*xFinal
34150 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
34160 74 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  t*).);.SQLITE_AP
34170 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  I int sqlite3_cr
34180 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
34190 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a  .  sqlite3 *db,.
341a0 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46    const void *zF
341b0 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69  unctionName,.  i
341c0 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65  nt nArg,.  int e
341d0 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20  TextRep,.  void 
341e0 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a  *pApp,.  void (*
341f0 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63  xFunc)(sqlite3_c
34200 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
34210 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
34220 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71  void (*xStep)(sq
34230 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
34240 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
34250 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  **),.  void (*xF
34260 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f  inal)(sqlite3_co
34270 6e 74 65 78 74 2a 29 0a 29 3b 0a 53 51 4c 49 54  ntext*).);.SQLIT
34280 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
34290 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
342a0 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20  n_v2(.  sqlite3 
342b0 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61  *db,.  const cha
342c0 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65  r *zFunctionName
342d0 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20  ,.  int nArg,.  
342e0 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20  int eTextRep,.  
342f0 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f  void *pApp,.  vo
34300 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69  id (*xFunc)(sqli
34310 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
34320 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
34330 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65  ),.  void (*xSte
34340 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  p)(sqlite3_conte
34350 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
34360 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
34370 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74   (*xFinal)(sqlit
34380 65 33 5f 63 6f 6e 74 65 78 74 2a 29 2c 0a 20 20  e3_context*),.  
34390 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28  void(*xDestroy)(
343a0 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  void*).);../*.**
343b0 20 43 41 50 49 33 52 45 46 3a 20 54 65 78 74 20   CAPI3REF: Text 
343c0 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a 20  Encodings.**.** 
343d0 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 20 64  These constant d
343e0 65 66 69 6e 65 20 69 6e 74 65 67 65 72 20 63 6f  efine integer co
343f0 64 65 73 20 74 68 61 74 20 72 65 70 72 65 73 65  des that represe
34400 6e 74 20 74 68 65 20 76 61 72 69 6f 75 73 0a 2a  nt the various.*
34410 2a 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73  * text encodings
34420 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 51   supported by SQ
34430 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  Lite..*/.#define
34440 20 53 51 4c 49 54 45 5f 55 54 46 38 20 20 20 20   SQLITE_UTF8    
34450 20 20 20 20 20 20 20 31 20 20 20 20 2f 2a 20 49         1    /* I
34460 4d 50 3a 20 52 2d 33 37 35 31 34 2d 33 35 35 36  MP: R-37514-3556
34470 36 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  6 */.#define SQL
34480 49 54 45 5f 55 54 46 31 36 4c 45 20 20 20 20 20  ITE_UTF16LE     
34490 20 20 20 32 20 20 20 20 2f 2a 20 49 4d 50 3a 20     2    /* IMP: 
344a0 52 2d 30 33 33 37 31 2d 33 37 36 33 37 20 2a 2f  R-03371-37637 */
344b0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
344c0 55 54 46 31 36 42 45 20 20 20 20 20 20 20 20 33  UTF16BE        3
344d0 20 20 20 20 2f 2a 20 49 4d 50 3a 20 52 2d 35 31      /* IMP: R-51
344e0 39 37 31 2d 33 34 31 35 34 20 2a 2f 0a 23 64 65  971-34154 */.#de
344f0 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31  fine SQLITE_UTF1
34500 36 20 20 20 20 20 20 20 20 20 20 34 20 20 20 20  6          4    
34510 2f 2a 20 55 73 65 20 6e 61 74 69 76 65 20 62 79  /* Use native by
34520 74 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66  te order */.#def
34530 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59 20 20  ine SQLITE_ANY  
34540 20 20 20 20 20 20 20 20 20 20 35 20 20 20 20 2f            5    /
34550 2a 20 44 65 70 72 65 63 61 74 65 64 20 2a 2f 0a  * Deprecated */.
34560 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
34570 54 46 31 36 5f 41 4c 49 47 4e 45 44 20 20 38 20  TF16_ALIGNED  8 
34580 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72     /* sqlite3_cr
34590 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f  eate_collation o
345a0 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  nly */../*.** CA
345b0 50 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e  PI3REF: Function
345c0 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65   Flags.**.** The
345d0 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 6d 61 79  se constants may
345e0 20 62 65 20 4f 52 65 64 20 74 6f 67 65 74 68 65   be ORed togethe
345f0 72 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b  r with the .** [
34600 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 70 72  SQLITE_UTF8 | pr
34610 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63  eferred text enc
34620 6f 64 69 6e 67 5d 20 61 73 20 74 68 65 20 66 6f  oding] as the fo
34630 75 72 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  urth argument.**
34640 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65   to [sqlite3_cre
34650 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c  ate_function()],
34660 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
34670 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 2c 20  _function16()], 
34680 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  or.** [sqlite3_c
34690 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76  reate_function_v
346a0 32 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  2()]..*/.#define
346b0 20 53 51 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e   SQLITE_DETERMIN
346c0 49 53 54 49 43 20 20 20 20 30 78 38 30 30 0a 0a  ISTIC    0x800..
346d0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
346e0 44 65 70 72 65 63 61 74 65 64 20 46 75 6e 63 74  Deprecated Funct
346f0 69 6f 6e 73 0a 2a 2a 20 44 45 50 52 45 43 41 54  ions.** DEPRECAT
34700 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66  ED.**.** These f
34710 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 5b 64 65  unctions are [de
34720 70 72 65 63 61 74 65 64 5d 2e 20 20 49 6e 20 6f  precated].  In o
34730 72 64 65 72 20 74 6f 20 6d 61 69 6e 74 61 69 6e  rder to maintain
34740 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f  .** backwards co
34750 6d 70 61 74 69 62 69 6c 69 74 79 20 77 69 74 68  mpatibility with
34760 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20 74 68 65   older code, the
34770 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 63 6f 6e  se functions con
34780 74 69 6e 75 65 20 0a 2a 2a 20 74 6f 20 62 65 20  tinue .** to be 
34790 73 75 70 70 6f 72 74 65 64 2e 20 20 48 6f 77 65  supported.  Howe
347a0 76 65 72 2c 20 6e 65 77 20 61 70 70 6c 69 63 61  ver, new applica
347b0 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 61 76 6f  tions should avo
347c0 69 64 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66  id.** the use of
347d0 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
347e0 2e 20 20 54 6f 20 68 65 6c 70 20 65 6e 63 6f 75  .  To help encou
347f0 72 61 67 65 20 70 65 6f 70 6c 65 20 74 6f 20 61  rage people to a
34800 76 6f 69 64 0a 2a 2a 20 75 73 69 6e 67 20 74 68  void.** using th
34810 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2c 20 77  ese functions, w
34820 65 20 61 72 65 20 6e 6f 74 20 67 6f 69 6e 67 20  e are not going 
34830 74 6f 20 74 65 6c 6c 20 79 6f 75 20 77 68 61 74  to tell you what
34840 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a 23 69 66   they do..*/.#if
34850 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54  ndef SQLITE_OMIT
34860 5f 44 45 50 52 45 43 41 54 45 44 0a 53 51 4c 49  _DEPRECATED.SQLI
34870 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45  TE_API SQLITE_DE
34880 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c  PRECATED int sql
34890 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
348a0 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e  ount(sqlite3_con
348b0 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41  text*);.SQLITE_A
348c0 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43  PI SQLITE_DEPREC
348d0 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33  ATED int sqlite3
348e0 5f 65 78 70 69 72 65 64 28 73 71 6c 69 74 65 33  _expired(sqlite3
348f0 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f  _stmt*);.SQLITE_
34900 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45  API SQLITE_DEPRE
34910 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65  CATED int sqlite
34920 33 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e 64 69  3_transfer_bindi
34930 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ngs(sqlite3_stmt
34940 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  *, sqlite3_stmt*
34950 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51  );.SQLITE_API SQ
34960 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
34970 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62  int sqlite3_glob
34980 61 6c 5f 72 65 63 6f 76 65 72 28 76 6f 69 64 29  al_recover(void)
34990 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c  ;.SQLITE_API SQL
349a0 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 76  ITE_DEPRECATED v
349b0 6f 69 64 20 73 71 6c 69 74 65 33 5f 74 68 72 65  oid sqlite3_thre
349c0 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64 29  ad_cleanup(void)
349d0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c  ;.SQLITE_API SQL
349e0 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69  ITE_DEPRECATED i
349f0 6e 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  nt sqlite3_memor
34a00 79 5f 61 6c 61 72 6d 28 76 6f 69 64 28 2a 29 28  y_alarm(void(*)(
34a10 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e  void*,sqlite3_in
34a20 74 36 34 2c 69 6e 74 29 2c 0a 20 20 20 20 20 20  t64,int),.      
34a30 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
34a40 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e  void*,sqlite3_in
34a50 74 36 34 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a  t64);.#endif../*
34a60 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62  .** CAPI3REF: Ob
34a70 74 61 69 6e 69 6e 67 20 53 51 4c 20 46 75 6e 63  taining SQL Func
34a80 74 69 6f 6e 20 50 61 72 61 6d 65 74 65 72 20 56  tion Parameter V
34a90 61 6c 75 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20  alues.**.** The 
34aa0 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c 65  C-language imple
34ab0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c  mentation of SQL
34ac0 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61   functions and a
34ad0 67 67 72 65 67 61 74 65 73 20 75 73 65 73 0a 2a  ggregates uses.*
34ae0 2a 20 74 68 69 73 20 73 65 74 20 6f 66 20 69 6e  * this set of in
34af0 74 65 72 66 61 63 65 20 72 6f 75 74 69 6e 65 73  terface routines
34b00 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 70   to access the p
34b10 61 72 61 6d 65 74 65 72 20 76 61 6c 75 65 73 20  arameter values 
34b20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74 69  on.** the functi
34b30 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2e  on or aggregate.
34b40 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63  .**.** The xFunc
34b50 20 28 66 6f 72 20 73 63 61 6c 61 72 20 66 75 6e   (for scalar fun
34b60 63 74 69 6f 6e 73 29 20 6f 72 20 78 53 74 65 70  ctions) or xStep
34b70 20 28 66 6f 72 20 61 67 67 72 65 67 61 74 65 73   (for aggregates
34b80 29 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20  ) parameters.** 
34b90 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  to [sqlite3_crea
34ba0 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61  te_function()] a
34bb0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  nd [sqlite3_crea
34bc0 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d  te_function16()]
34bd0 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c 62  .** define callb
34be0 61 63 6b 73 20 74 68 61 74 20 69 6d 70 6c 65 6d  acks that implem
34bf0 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63  ent the SQL func
34c00 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67  tions and aggreg
34c10 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20 33 72 64  ates..** The 3rd
34c20 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
34c30 65 73 65 20 63 61 6c 6c 62 61 63 6b 73 20 69 73  ese callbacks is
34c40 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
34c50 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f  nters to.** [pro
34c60 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
34c70 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20  alue] objects.  
34c80 54 68 65 72 65 20 69 73 20 6f 6e 65 20 5b 73 71  There is one [sq
34c90 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
34ca0 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20  ect for.** each 
34cb0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
34cc0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20   SQL function.  
34cd0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
34ce0 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78  re used to.** ex
34cf0 74 72 61 63 74 20 76 61 6c 75 65 73 20 66 72 6f  tract values fro
34d00 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  m the [sqlite3_v
34d10 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  alue] objects..*
34d20 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
34d30 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69  nes work only wi
34d40 74 68 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71  th [protected sq
34d50 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
34d60 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74  ects..** Any att
34d70 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65 73  empt to use thes
34d80 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e  e routines on an
34d90 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
34da0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20  lite3_value].** 
34db0 6f 62 6a 65 63 74 20 72 65 73 75 6c 74 73 20 69  object results i
34dc0 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61  n undefined beha
34dd0 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  vior..**.** ^The
34de0 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b  se routines work
34df0 20 6a 75 73 74 20 6c 69 6b 65 20 74 68 65 20 63   just like the c
34e00 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63 6f  orresponding [co
34e10 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63  lumn access func
34e20 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 74  tions].** except
34e30 20 74 68 61 74 20 74 68 65 73 65 20 72 6f 75 74   that these rout
34e40 69 6e 65 73 20 74 61 6b 65 20 61 20 73 69 6e 67  ines take a sing
34e50 6c 65 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71  le [protected sq
34e60 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
34e70 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69  ect.** pointer i
34e80 6e 73 74 65 61 64 20 6f 66 20 61 20 5b 73 71 6c  nstead of a [sql
34e90 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e  ite3_stmt*] poin
34ea0 74 65 72 20 61 6e 64 20 61 6e 20 69 6e 74 65 67  ter and an integ
34eb0 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72  er column number
34ec0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
34ed0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
34ee0 36 28 29 20 69 6e 74 65 72 66 61 63 65 20 65 78  6() interface ex
34ef0 74 72 61 63 74 73 20 61 20 55 54 46 2d 31 36 20  tracts a UTF-16 
34f00 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65  string.** in the
34f10 20 6e 61 74 69 76 65 20 62 79 74 65 2d 6f 72 64   native byte-ord
34f20 65 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20 6d  er of the host m
34f30 61 63 68 69 6e 65 2e 20 20 5e 54 68 65 0a 2a 2a  achine.  ^The.**
34f40 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
34f50 65 78 74 31 36 62 65 28 29 20 61 6e 64 20 73 71  ext16be() and sq
34f60 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
34f70 31 36 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65  16le() interface
34f80 73 0a 2a 2a 20 65 78 74 72 61 63 74 20 55 54 46  s.** extract UTF
34f90 2d 31 36 20 73 74 72 69 6e 67 73 20 61 73 20 62  -16 strings as b
34fa0 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69  ig-endian and li
34fb0 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73 70  ttle-endian resp
34fc0 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ectively..**.** 
34fd0 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61  ^(The sqlite3_va
34fe0 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65  lue_numeric_type
34ff0 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74  () interface att
35000 65 6d 70 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a  empts to apply.*
35010 2a 20 6e 75 6d 65 72 69 63 20 61 66 66 69 6e 69  * numeric affini
35020 74 79 20 74 6f 20 74 68 65 20 76 61 6c 75 65 2e  ty to the value.
35030 20 20 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61    This means tha
35040 74 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 0a  t an attempt is.
35050 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65  ** made to conve
35060 72 74 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20  rt the value to 
35070 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 20 66 6c  an integer or fl
35080 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49  oating point.  I
35090 66 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e 76  f.** such a conv
350a0 65 72 73 69 6f 6e 20 69 73 20 70 6f 73 73 69 62  ersion is possib
350b0 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f 73 73 20  le without loss 
350c0 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28  of information (
350d0 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64  in other.** word
350e0 73 2c 20 69 66 20 74 68 65 20 76 61 6c 75 65 20  s, if the value 
350f0 69 73 20 61 20 73 74 72 69 6e 67 20 74 68 61 74  is a string that
35100 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75   looks like a nu
35110 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68  mber).** then th
35120 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20  e conversion is 
35130 70 65 72 66 6f 72 6d 65 64 2e 20 20 4f 74 68 65  performed.  Othe
35140 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73  rwise no convers
35150 69 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a 20 54  ion occurs..** T
35160 68 65 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47  he [SQLITE_INTEG
35170 45 52 20 7c 20 64 61 74 61 74 79 70 65 5d 20 61  ER | datatype] a
35180 66 74 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20  fter conversion 
35190 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a  is returned.)^.*
351a0 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61 79 20  *.** Please pay 
351b0 70 61 72 74 69 63 75 6c 61 72 20 61 74 74 65 6e  particular atten
351c0 74 69 6f 6e 20 74 6f 20 74 68 65 20 66 61 63 74  tion to the fact
351d0 20 74 68 61 74 20 74 68 65 20 70 6f 69 6e 74 65   that the pointe
351e0 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72  r returned.** fr
351f0 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  om [sqlite3_valu
35200 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69  e_blob()], [sqli
35210 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29  te3_value_text()
35220 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ], or.** [sqlite
35230 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29  3_value_text16()
35240 5d 20 63 61 6e 20 62 65 20 69 6e 76 61 6c 69 64  ] can be invalid
35250 61 74 65 64 20 62 79 20 61 20 73 75 62 73 65 71  ated by a subseq
35260 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  uent call to.** 
35270 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
35280 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65  ytes()], [sqlite
35290 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28  3_value_bytes16(
352a0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  )], [sqlite3_val
352b0 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f  ue_text()],.** o
352c0 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  r [sqlite3_value
352d0 5f 74 65 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a  _text16()]..**.*
352e0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
352f0 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
35300 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68  from the same th
35310 72 65 61 64 20 61 73 0a 2a 2a 20 74 68 65 20 53  read as.** the S
35320 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74  QL function that
35330 20 73 75 70 70 6c 69 65 64 20 74 68 65 20 5b 73   supplied the [s
35340 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70  qlite3_value*] p
35350 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a 53 51  arameters..*/.SQ
35360 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76  LITE_API const v
35370 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c  oid *sqlite3_val
35380 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  ue_blob(sqlite3_
35390 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f  value*);.SQLITE_
353a0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
353b0 76 61 6c 75 65 5f 62 79 74 65 73 28 73 71 6c 69  value_bytes(sqli
353c0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c  te3_value*);.SQL
353d0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
353e0 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31  te3_value_bytes1
353f0 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  6(sqlite3_value*
35400 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 64 6f  );.SQLITE_API do
35410 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 76 61 6c  uble sqlite3_val
35420 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65  ue_double(sqlite
35430 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54  3_value*);.SQLIT
35440 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
35450 33 5f 76 61 6c 75 65 5f 69 6e 74 28 73 71 6c 69  3_value_int(sqli
35460 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c  te3_value*);.SQL
35470 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f  ITE_API sqlite3_
35480 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 76 61  int64 sqlite3_va
35490 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c 69 74 65  lue_int64(sqlite
354a0 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54  3_value*);.SQLIT
354b0 45 5f 41 50 49 20 63 6f 6e 73 74 20 75 6e 73 69  E_API const unsi
354c0 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74  gned char *sqlit
354d0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 73 71  e3_value_text(sq
354e0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53  lite3_value*);.S
354f0 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
35500 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61  void *sqlite3_va
35510 6c 75 65 5f 74 65 78 74 31 36 28 73 71 6c 69 74  lue_text16(sqlit
35520 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49  e3_value*);.SQLI
35530 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69  TE_API const voi
35540 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  d *sqlite3_value
35550 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65  _text16le(sqlite
35560 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54  3_value*);.SQLIT
35570 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64  E_API const void
35580 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   *sqlite3_value_
35590 74 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 33  text16be(sqlite3
355a0 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45  _value*);.SQLITE
355b0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
355c0 5f 76 61 6c 75 65 5f 74 79 70 65 28 73 71 6c 69  _value_type(sqli
355d0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c  te3_value*);.SQL
355e0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
355f0 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69  te3_value_numeri
35600 63 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76  c_type(sqlite3_v
35610 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  alue*);../*.** C
35620 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20  API3REF: Obtain 
35630 41 67 67 72 65 67 61 74 65 20 46 75 6e 63 74 69  Aggregate Functi
35640 6f 6e 20 43 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a  on Context.**.**
35650 20 49 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   Implementations
35660 20 6f 66 20 61 67 67 72 65 67 61 74 65 20 53 51   of aggregate SQ
35670 4c 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 20  L functions use 
35680 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  this.** routine 
35690 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f  to allocate memo
356a0 72 79 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 74  ry for storing t
356b0 68 65 69 72 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a  heir state..**.*
356c0 2a 20 5e 54 68 65 20 66 69 72 73 74 20 74 69 6d  * ^The first tim
356d0 65 20 74 68 65 20 73 71 6c 69 74 65 33 5f 61 67  e the sqlite3_ag
356e0 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
356f0 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20 69 73 20  C,N) routine is 
35700 63 61 6c 6c 65 64 20 0a 2a 2a 20 66 6f 72 20 61  called .** for a
35710 20 70 61 72 74 69 63 75 6c 61 72 20 61 67 67 72   particular aggr
35720 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 2c 20  egate function, 
35730 53 51 4c 69 74 65 0a 2a 2a 20 61 6c 6c 6f 63 61  SQLite.** alloca
35740 74 65 73 20 4e 20 6f 66 20 6d 65 6d 6f 72 79 2c  tes N of memory,
35750 20 7a 65 72 6f 65 73 20 6f 75 74 20 74 68 61 74   zeroes out that
35760 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74   memory, and ret
35770 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a  urns a pointer.*
35780 2a 20 74 6f 20 74 68 65 20 6e 65 77 20 6d 65 6d  * to the new mem
35790 6f 72 79 2e 20 5e 4f 6e 20 73 65 63 6f 6e 64 20  ory. ^On second 
357a0 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20 63  and subsequent c
357b0 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  alls to.** sqlit
357c0 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
357d0 74 65 78 74 28 29 20 66 6f 72 20 74 68 65 20 73  text() for the s
357e0 61 6d 65 20 61 67 67 72 65 67 61 74 65 20 66 75  ame aggregate fu
357f0 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 2c  nction instance,
35800 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 62 75 66  .** the same buf
35810 66 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  fer is returned.
35820 20 20 53 71 6c 69 74 65 33 5f 61 67 67 72 65 67    Sqlite3_aggreg
35830 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 69 73  ate_context() is
35840 20 6e 6f 72 6d 61 6c 6c 79 0a 2a 2a 20 63 61 6c   normally.** cal
35850 6c 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 63  led once for eac
35860 68 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20  h invocation of 
35870 74 68 65 20 78 53 74 65 70 20 63 61 6c 6c 62 61  the xStep callba
35880 63 6b 20 61 6e 64 20 74 68 65 6e 20 6f 6e 65 0a  ck and then one.
35890 2a 2a 20 6c 61 73 74 20 74 69 6d 65 20 77 68 65  ** last time whe
358a0 6e 20 74 68 65 20 78 46 69 6e 61 6c 20 63 61 6c  n the xFinal cal
358b0 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
358c0 2e 20 20 5e 28 57 68 65 6e 20 6e 6f 20 72 6f 77  .  ^(When no row
358d0 73 20 6d 61 74 63 68 0a 2a 2a 20 61 6e 20 61 67  s match.** an ag
358e0 67 72 65 67 61 74 65 20 71 75 65 72 79 2c 20 74  gregate query, t
358f0 68 65 20 78 53 74 65 70 28 29 20 63 61 6c 6c 62  he xStep() callb
35900 61 63 6b 20 6f 66 20 74 68 65 20 61 67 67 72 65  ack of the aggre
35910 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  gate function.**
35920 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
35930 69 73 20 6e 65 76 65 72 20 63 61 6c 6c 65 64 20  is never called 
35940 61 6e 64 20 78 46 69 6e 61 6c 28 29 20 69 73 20  and xFinal() is 
35950 63 61 6c 6c 65 64 20 65 78 61 63 74 6c 79 20 6f  called exactly o
35960 6e 63 65 2e 0a 2a 2a 20 49 6e 20 74 68 6f 73 65  nce..** In those
35970 20 63 61 73 65 73 2c 20 73 71 6c 69 74 65 33 5f   cases, sqlite3_
35980 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
35990 74 28 29 20 6d 69 67 68 74 20 62 65 20 63 61 6c  t() might be cal
359a0 6c 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 66  led for the.** f
359b0 69 72 73 74 20 74 69 6d 65 20 66 72 6f 6d 20 77  irst time from w
359c0 69 74 68 69 6e 20 78 46 69 6e 61 6c 28 29 2e 29  ithin xFinal().)
359d0 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ^.**.** ^The sql
359e0 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
359f0 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74  ontext(C,N) rout
35a00 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 4e 55  ine returns a NU
35a10 4c 4c 20 70 6f 69 6e 74 65 72 20 0a 2a 2a 20 77  LL pointer .** w
35a20 68 65 6e 20 66 69 72 73 74 20 63 61 6c 6c 65 64  hen first called
35a30 20 69 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68   if N is less th
35a40 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a  an or equal to z
35a50 65 72 6f 20 6f 72 20 69 66 20 61 20 6d 65 6d 6f  ero or if a memo
35a60 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 65  ry.** allocate e
35a70 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a  rror occurs..**.
35a80 2a 2a 20 5e 28 54 68 65 20 61 6d 6f 75 6e 74 20  ** ^(The amount 
35a90 6f 66 20 73 70 61 63 65 20 61 6c 6c 6f 63 61 74  of space allocat
35aa0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 61 67  ed by sqlite3_ag
35ab0 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
35ac0 43 2c 4e 29 20 69 73 0a 2a 2a 20 64 65 74 65 72  C,N) is.** deter
35ad0 6d 69 6e 65 64 20 62 79 20 74 68 65 20 4e 20 70  mined by the N p
35ae0 61 72 61 6d 65 74 65 72 20 6f 6e 20 66 69 72 73  arameter on firs
35af0 74 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  t successful cal
35b00 6c 2e 20 20 43 68 61 6e 67 69 6e 67 20 74 68 65  l.  Changing the
35b10 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 4e 20 69  .** value of N i
35b20 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  n subsequent cal
35b30 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 61 67 67  l to sqlite3_agg
35b40 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
35b50 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 73   within.** the s
35b60 61 6d 65 20 61 67 67 72 65 67 61 74 65 20 66 75  ame aggregate fu
35b70 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 20  nction instance 
35b80 77 69 6c 6c 20 6e 6f 74 20 72 65 73 69 7a 65 20  will not resize 
35b90 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c  the memory.** al
35ba0 6c 6f 63 61 74 69 6f 6e 2e 29 5e 20 20 57 69 74  location.)^  Wit
35bb0 68 69 6e 20 74 68 65 20 78 46 69 6e 61 6c 20 63  hin the xFinal c
35bc0 61 6c 6c 62 61 63 6b 2c 20 69 74 20 69 73 20 63  allback, it is c
35bd0 75 73 74 6f 6d 61 72 79 20 74 6f 20 73 65 74 0a  ustomary to set.
35be0 2a 2a 20 4e 3d 30 20 69 6e 20 63 61 6c 6c 73 20  ** N=0 in calls 
35bf0 74 6f 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  to sqlite3_aggre
35c00 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e  gate_context(C,N
35c10 29 20 73 6f 20 74 68 61 74 20 6e 6f 20 0a 2a 2a  ) so that no .**
35c20 20 70 6f 69 6e 74 6c 65 73 73 20 6d 65 6d 6f 72   pointless memor
35c30 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 6f 63  y allocations oc
35c40 63 75 72 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69  cur..**.** ^SQLi
35c50 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  te automatically
35c60 20 66 72 65 65 73 20 74 68 65 20 6d 65 6d 6f 72   frees the memor
35c70 79 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 0a  y allocated by .
35c80 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  ** sqlite3_aggre
35c90 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77  gate_context() w
35ca0 68 65 6e 20 74 68 65 20 61 67 67 72 65 67 61 74  hen the aggregat
35cb0 65 20 71 75 65 72 79 20 63 6f 6e 63 6c 75 64 65  e query conclude
35cc0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  s..**.** The fir
35cd0 73 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73  st parameter mus
35ce0 74 20 62 65 20 61 20 63 6f 70 79 20 6f 66 20 74  t be a copy of t
35cf0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  he.** [sqlite3_c
35d00 6f 6e 74 65 78 74 20 7c 20 53 51 4c 20 66 75 6e  ontext | SQL fun
35d10 63 74 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74  ction context] t
35d20 68 61 74 20 69 73 20 74 68 65 20 66 69 72 73 74  hat is the first
35d30 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f   parameter.** to
35d40 20 74 68 65 20 78 53 74 65 70 20 6f 72 20 78 46   the xStep or xF
35d50 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 72 6f  inal callback ro
35d60 75 74 69 6e 65 20 74 68 61 74 20 69 6d 70 6c 65  utine that imple
35d70 6d 65 6e 74 73 20 74 68 65 20 61 67 67 72 65 67  ments the aggreg
35d80 61 74 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e  ate.** function.
35d90 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
35da0 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  ine must be call
35db0 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65  ed from the same
35dc0 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68   thread in which
35dd0 0a 2a 2a 20 74 68 65 20 61 67 67 72 65 67 61 74  .** the aggregat
35de0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  e SQL function i
35df0 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51  s running..*/.SQ
35e00 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73  LITE_API void *s
35e10 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
35e20 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69 74 65 33  _context(sqlite3
35e30 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e  _context*, int n
35e40 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  Bytes);../*.** C
35e50 41 50 49 33 52 45 46 3a 20 55 73 65 72 20 44 61  API3REF: User Da
35e60 74 61 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73  ta For Functions
35e70 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
35e80 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 20  te3_user_data() 
35e90 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
35ea0 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74  s a copy of.** t
35eb0 68 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20  he pointer that 
35ec0 77 61 73 20 74 68 65 20 70 55 73 65 72 44 61 74  was the pUserDat
35ed0 61 20 70 61 72 61 6d 65 74 65 72 20 28 74 68 65  a parameter (the
35ee0 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 29 0a   5th parameter).
35ef0 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ** of the [sqlit
35f00 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
35f10 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71  on()].** and [sq
35f20 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
35f30 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69  ction16()] routi
35f40 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61  nes that origina
35f50 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65  lly.** registere
35f60 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  d the applicatio
35f70 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n defined functi
35f80 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  on..**.** This r
35f90 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63  outine must be c
35fa0 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73  alled from the s
35fb0 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68  ame thread in wh
35fc0 69 63 68 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69  ich.** the appli
35fd0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
35fe0 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
35ff0 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ng..*/.SQLITE_AP
36000 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  I void *sqlite3_
36010 75 73 65 72 5f 64 61 74 61 28 73 71 6c 69 74 65  user_data(sqlite
36020 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a  3_context*);../*
36030 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61  .** CAPI3REF: Da
36040 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f  tabase Connectio
36050 6e 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a  n For Functions.
36060 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
36070 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61  e3_context_db_ha
36080 6e 64 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65  ndle() interface
36090 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20   returns a copy 
360a0 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65  of.** the pointe
360b0 72 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61  r to the [databa
360c0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28  se connection] (
360d0 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 65  the 1st paramete
360e0 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71  r).** of the [sq
360f0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
36100 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20  ction()].** and 
36110 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
36120 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f  function16()] ro
36130 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67  utines that orig
36140 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74  inally.** regist
36150 65 72 65 64 20 74 68 65 20 61 70 70 6c 69 63 61  ered the applica
36160 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e  tion defined fun
36170 63 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45  ction..*/.SQLITE
36180 5f 41 50 49 20 73 71 6c 69 74 65 33 20 2a 73 71  _API sqlite3 *sq
36190 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62  lite3_context_db
361a0 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f  _handle(sqlite3_
361b0 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a  context*);../*.*
361c0 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63  * CAPI3REF: Func
361d0 74 69 6f 6e 20 41 75 78 69 6c 69 61 72 79 20 44  tion Auxiliary D
361e0 61 74 61 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ata.**.** These 
361f0 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65  functions may be
36200 20 75 73 65 64 20 62 79 20 28 6e 6f 6e 2d 61 67   used by (non-ag
36210 67 72 65 67 61 74 65 29 20 53 51 4c 20 66 75 6e  gregate) SQL fun
36220 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73  ctions to.** ass
36230 6f 63 69 61 74 65 20 6d 65 74 61 64 61 74 61 20  ociate metadata 
36240 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20 76 61  with argument va
36250 6c 75 65 73 2e 20 49 66 20 74 68 65 20 73 61 6d  lues. If the sam
36260 65 20 76 61 6c 75 65 20 69 73 20 70 61 73 73 65  e value is passe
36270 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65  d to.** multiple
36280 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20   invocations of 
36290 74 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e  the same SQL fun
362a0 63 74 69 6f 6e 20 64 75 72 69 6e 67 20 71 75 65  ction during que
362b0 72 79 20 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e  ry execution, un
362c0 64 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63  der.** some circ
362d0 75 6d 73 74 61 6e 63 65 73 20 74 68 65 20 61 73  umstances the as
362e0 73 6f 63 69 61 74 65 64 20 6d 65 74 61 64 61 74  sociated metadat
362f0 61 20 6d 61 79 20 62 65 20 70 72 65 73 65 72 76  a may be preserv
36300 65 64 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 0a  ed.  An example.
36310 2a 2a 20 6f 66 20 77 68 65 72 65 20 74 68 69 73  ** of where this
36320 20 6d 69 67 68 74 20 62 65 20 75 73 65 66 75 6c   might be useful
36330 20 69 73 20 69 6e 20 61 20 72 65 67 75 6c 61 72   is in a regular
36340 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d 61 74 63  -expression matc
36350 68 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  hing.** function
36360 2e 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 76  . The compiled v
36370 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 72 65  ersion of the re
36380 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e  gular expression
36390 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20 61   can be stored a
363a0 73 0a 2a 2a 20 6d 65 74 61 64 61 74 61 20 61 73  s.** metadata as
363b0 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
363c0 65 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67  e pattern string
363d0 2e 20 20 0a 2a 2a 20 54 68 65 6e 20 61 73 20 6c  .  .** Then as l
363e0 6f 6e 67 20 61 73 20 74 68 65 20 70 61 74 74 65  ong as the patte
363f0 72 6e 20 73 74 72 69 6e 67 20 72 65 6d 61 69 6e  rn string remain
36400 73 20 74 68 65 20 73 61 6d 65 2c 0a 2a 2a 20 74  s the same,.** t
36410 68 65 20 63 6f 6d 70 69 6c 65 64 20 72 65 67 75  he compiled regu
36420 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63  lar expression c
36430 61 6e 20 62 65 20 72 65 75 73 65 64 20 6f 6e 20  an be reused on 
36440 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f  multiple.** invo
36450 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  cations of the s
36460 61 6d 65 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  ame function..**
36470 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
36480 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 69  _get_auxdata() i
36490 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
364a0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
364b0 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61 73  e metadata.** as
364c0 73 6f 63 69 61 74 65 64 20 62 79 20 74 68 65 20  sociated by the 
364d0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
364e0 61 74 61 28 29 20 66 75 6e 63 74 69 6f 6e 20 77  ata() function w
364f0 69 74 68 20 74 68 65 20 4e 74 68 20 61 72 67 75  ith the Nth argu
36500 6d 65 6e 74 0a 2a 2a 20 76 61 6c 75 65 20 74 6f  ment.** value to
36510 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
36520 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
36530 6e 2e 20 5e 49 66 20 74 68 65 72 65 20 69 73 20  n. ^If there is 
36540 6e 6f 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61  no metadata.** a
36550 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
36560 68 65 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75  he function argu
36570 6d 65 6e 74 2c 20 74 68 69 73 20 73 71 6c 69 74  ment, this sqlit
36580 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29  e3_get_auxdata()
36590 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 65   interface.** re
365a0 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69  turns a NULL poi
365b0 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  nter..**.** ^The
365c0 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
365d0 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20 69 6e  data(C,N,P,X) in
365e0 74 65 72 66 61 63 65 20 73 61 76 65 73 20 50 20  terface saves P 
365f0 61 73 20 6d 65 74 61 64 61 74 61 20 66 6f 72 20  as metadata for 
36600 74 68 65 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75  the N-th.** argu
36610 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 70 70 6c  ment of the appl
36620 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
36630 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 53 75 62 73  function.  ^Subs
36640 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20  equent.** calls 
36650 74 6f 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  to sqlite3_get_a
36660 75 78 64 61 74 61 28 43 2c 4e 29 20 72 65 74 75  uxdata(C,N) retu
36670 72 6e 20 50 20 66 72 6f 6d 20 74 68 65 20 6d 6f  rn P from the mo
36680 73 74 20 72 65 63 65 6e 74 0a 2a 2a 20 73 71 6c  st recent.** sql
36690 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
366a0 28 43 2c 4e 2c 50 2c 58 29 20 63 61 6c 6c 20 69  (C,N,P,X) call i
366b0 66 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 69  f the metadata i
366c0 73 20 73 74 69 6c 6c 20 76 61 6c 69 64 20 6f 72  s still valid or
366d0 0a 2a 2a 20 4e 55 4c 4c 20 69 66 20 74 68 65 20  .** NULL if the 
366e0 6d 65 74 61 64 61 74 61 20 68 61 73 20 62 65 65  metadata has bee
366f0 6e 20 64 69 73 63 61 72 64 65 64 2e 0a 2a 2a 20  n discarded..** 
36700 5e 41 66 74 65 72 20 65 61 63 68 20 63 61 6c 6c  ^After each call
36710 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f   to sqlite3_set_
36720 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29  auxdata(C,N,P,X)
36730 20 77 68 65 72 65 20 58 20 69 73 20 6e 6f 74 20   where X is not 
36740 4e 55 4c 4c 2c 0a 2a 2a 20 53 51 4c 69 74 65 20  NULL,.** SQLite 
36750 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20  will invoke the 
36760 64 65 73 74 72 75 63 74 6f 72 20 66 75 6e 63 74  destructor funct
36770 69 6f 6e 20 58 20 77 69 74 68 20 70 61 72 61 6d  ion X with param
36780 65 74 65 72 20 50 20 65 78 61 63 74 6c 79 0a 2a  eter P exactly.*
36790 2a 20 6f 6e 63 65 2c 20 77 68 65 6e 20 74 68 65  * once, when the
367a0 20 6d 65 74 61 64 61 74 61 20 69 73 20 64 69 73   metadata is dis
367b0 63 61 72 64 65 64 2e 0a 2a 2a 20 53 51 4c 69 74  carded..** SQLit
367c0 65 20 69 73 20 66 72 65 65 20 74 6f 20 64 69 73  e is free to dis
367d0 63 61 72 64 20 74 68 65 20 6d 65 74 61 64 61 74  card the metadat
367e0 61 20 61 74 20 61 6e 79 20 74 69 6d 65 2c 20 69  a at any time, i
367f0 6e 63 6c 75 64 69 6e 67 3a 20 3c 75 6c 3e 0a 2a  ncluding: <ul>.*
36800 2a 20 3c 6c 69 3e 20 77 68 65 6e 20 74 68 65 20  * <li> when the 
36810 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 66 75  corresponding fu
36820 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72  nction parameter
36830 20 63 68 61 6e 67 65 73 2c 20 6f 72 0a 2a 2a 20   changes, or.** 
36840 3c 6c 69 3e 20 77 68 65 6e 20 5b 73 71 6c 69 74  <li> when [sqlit
36850 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b  e3_reset()] or [
36860 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
36870 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 66 6f  ()] is called fo
36880 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 53 51  r the.**      SQ
36890 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 6f 72 0a  L statement, or.
368a0 2a 2a 20 3c 6c 69 3e 20 77 68 65 6e 20 73 71 6c  ** <li> when sql
368b0 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
368c0 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 67  () is invoked ag
368d0 61 69 6e 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  ain on the same 
368e0 70 61 72 61 6d 65 74 65 72 2c 20 6f 72 0a 2a 2a  parameter, or.**
368f0 20 3c 6c 69 3e 20 64 75 72 69 6e 67 20 74 68 65   <li> during the
36900 20 6f 72 69 67 69 6e 61 6c 20 73 71 6c 69 74 65   original sqlite
36910 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_set_auxdata() 
36920 63 61 6c 6c 20 77 68 65 6e 20 61 20 6d 65 6d 6f  call when a memo
36930 72 79 20 0a 2a 2a 20 20 20 20 20 20 61 6c 6c 6f  ry .**      allo
36940 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63  cation error occ
36950 75 72 73 2e 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a  urs. </ul>)^.**.
36960 2a 2a 20 4e 6f 74 65 20 74 68 65 20 6c 61 73 74  ** Note the last
36970 20 62 75 6c 6c 65 74 20 69 6e 20 70 61 72 74 69   bullet in parti
36980 63 75 6c 61 72 2e 20 20 54 68 65 20 64 65 73 74  cular.  The dest
36990 72 75 63 74 6f 72 20 58 20 69 6e 20 0a 2a 2a 20  ructor X in .** 
369a0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
369b0 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20 6d 69 67  ata(C,N,P,X) mig
369c0 68 74 20 62 65 20 63 61 6c 6c 65 64 20 69 6d 6d  ht be called imm
369d0 65 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65  ediately, before
369e0 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   the.** sqlite3_
369f0 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e  set_auxdata() in
36a00 74 65 72 66 61 63 65 20 65 76 65 6e 20 72 65 74  terface even ret
36a10 75 72 6e 73 2e 20 20 48 65 6e 63 65 20 73 71 6c  urns.  Hence sql
36a20 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
36a30 28 29 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20  ().** should be 
36a40 63 61 6c 6c 65 64 20 6e 65 61 72 20 74 68 65 20  called near the 
36a50 65 6e 64 20 6f 66 20 74 68 65 20 66 75 6e 63 74  end of the funct
36a60 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ion implementati
36a70 6f 6e 20 61 6e 64 20 74 68 65 0a 2a 2a 20 66 75  on and the.** fu
36a80 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
36a90 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74  ation should not
36aa0 20 6d 61 6b 65 20 61 6e 79 20 75 73 65 20 6f 66   make any use of
36ab0 20 50 20 61 66 74 65 72 0a 2a 2a 20 73 71 6c 69   P after.** sqli
36ac0 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
36ad0 29 20 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 65  ) has been calle
36ae0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 70 72  d..**.** ^(In pr
36af0 61 63 74 69 63 65 2c 20 6d 65 74 61 64 61 74 61  actice, metadata
36b00 20 69 73 20 70 72 65 73 65 72 76 65 64 20 62 65   is preserved be
36b10 74 77 65 65 6e 20 66 75 6e 63 74 69 6f 6e 20 63  tween function c
36b20 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20 66 75 6e 63  alls for.** func
36b30 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 73 20  tion parameters 
36b40 74 68 61 74 20 61 72 65 20 63 6f 6d 70 69 6c 65  that are compile
36b50 2d 74 69 6d 65 20 63 6f 6e 73 74 61 6e 74 73 2c  -time constants,
36b60 20 69 6e 63 6c 75 64 69 6e 67 20 6c 69 74 65 72   including liter
36b70 61 6c 0a 2a 2a 20 76 61 6c 75 65 73 20 61 6e 64  al.** values and
36b80 20 5b 70 61 72 61 6d 65 74 65 72 73 5d 20 61 6e   [parameters] an
36b90 64 20 65 78 70 72 65 73 73 69 6f 6e 73 20 63 6f  d expressions co
36ba0 6d 70 6f 73 65 64 20 66 72 6f 6d 20 74 68 65 20  mposed from the 
36bb0 73 61 6d 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  same.)^.**.** Th
36bc0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73  ese routines mus
36bd0 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  t be called from
36be0 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
36bf0 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65   in which.** the
36c00 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73   SQL function is
36c10 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c   running..*/.SQL
36c20 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71  ITE_API void *sq
36c30 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
36c40 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  a(sqlite3_contex
36c50 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 53 51 4c 49  t*, int N);.SQLI
36c60 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69  TE_API void sqli
36c70 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
36c80 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
36c90 2c 20 69 6e 74 20 4e 2c 20 76 6f 69 64 2a 2c 20  , int N, void*, 
36ca0 76 6f 69 64 20 28 2a 29 28 76 6f 69 64 2a 29 29  void (*)(void*))
36cb0 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  ;.../*.** CAPI3R
36cc0 45 46 3a 20 43 6f 6e 73 74 61 6e 74 73 20 44 65  EF: Constants De
36cd0 66 69 6e 69 6e 67 20 53 70 65 63 69 61 6c 20 44  fining Special D
36ce0 65 73 74 72 75 63 74 6f 72 20 42 65 68 61 76 69  estructor Behavi
36cf0 6f 72 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61  or.**.** These a
36d00 72 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65  re special value
36d10 73 20 66 6f 72 20 74 68 65 20 64 65 73 74 72 75  s for the destru
36d20 63 74 6f 72 20 74 68 61 74 20 69 73 20 70 61 73  ctor that is pas
36d30 73 65 64 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a  sed in as the.**
36d40 20 66 69 6e 61 6c 20 61 72 67 75 6d 65 6e 74 20   final argument 
36d50 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65  to routines like
36d60 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
36d70 5f 62 6c 6f 62 28 29 5d 2e 20 20 5e 49 66 20 74  _blob()].  ^If t
36d80 68 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a  he destructor.**
36d90 20 61 72 67 75 6d 65 6e 74 20 69 73 20 53 51 4c   argument is SQL
36da0 49 54 45 5f 53 54 41 54 49 43 2c 20 69 74 20 6d  ITE_STATIC, it m
36db0 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f  eans that the co
36dc0 6e 74 65 6e 74 20 70 6f 69 6e 74 65 72 20 69 73  ntent pointer is
36dd0 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20 61 6e 64   constant.** and
36de0 20 77 69 6c 6c 20 6e 65 76 65 72 20 63 68 61 6e   will never chan
36df0 67 65 2e 20 20 49 74 20 64 6f 65 73 20 6e 6f 74  ge.  It does not
36e00 20 6e 65 65 64 20 74 6f 20 62 65 20 64 65 73 74   need to be dest
36e10 72 6f 79 65 64 2e 20 20 5e 54 68 65 0a 2a 2a 20  royed.  ^The.** 
36e20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54  SQLITE_TRANSIENT
36e30 20 76 61 6c 75 65 20 6d 65 61 6e 73 20 74 68 61   value means tha
36e40 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 77 69  t the content wi
36e50 6c 6c 20 6c 69 6b 65 6c 79 20 63 68 61 6e 67 65  ll likely change
36e60 20 69 6e 0a 2a 2a 20 74 68 65 20 6e 65 61 72 20   in.** the near 
36e70 66 75 74 75 72 65 20 61 6e 64 20 74 68 61 74 20  future and that 
36e80 53 51 4c 69 74 65 20 73 68 6f 75 6c 64 20 6d 61  SQLite should ma
36e90 6b 65 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61  ke its own priva
36ea0 74 65 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68  te copy of.** th
36eb0 65 20 63 6f 6e 74 65 6e 74 20 62 65 66 6f 72 65  e content before
36ec0 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a   returning..**.*
36ed0 2a 20 54 68 65 20 74 79 70 65 64 65 66 20 69 73  * The typedef is
36ee0 20 6e 65 63 65 73 73 61 72 79 20 74 6f 20 77 6f   necessary to wo
36ef0 72 6b 20 61 72 6f 75 6e 64 20 70 72 6f 62 6c 65  rk around proble
36f00 6d 73 20 69 6e 20 63 65 72 74 61 69 6e 0a 2a 2a  ms in certain.**
36f10 20 43 2b 2b 20 63 6f 6d 70 69 6c 65 72 73 2e 0a   C++ compilers..
36f20 2a 2f 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20  */.typedef void 
36f30 28 2a 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75  (*sqlite3_destru
36f40 63 74 6f 72 5f 74 79 70 65 29 28 76 6f 69 64 2a  ctor_type)(void*
36f50 29 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  );.#define SQLIT
36f60 45 5f 53 54 41 54 49 43 20 20 20 20 20 20 28 28  E_STATIC      ((
36f70 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74  sqlite3_destruct
36f80 6f 72 5f 74 79 70 65 29 30 29 0a 23 64 65 66 69  or_type)0).#defi
36f90 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49  ne SQLITE_TRANSI
36fa0 45 4e 54 20 20 20 28 28 73 71 6c 69 74 65 33 5f  ENT   ((sqlite3_
36fb0 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29  destructor_type)
36fc0 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  -1)../*.** CAPI3
36fd0 52 45 46 3a 20 53 65 74 74 69 6e 67 20 54 68 65  REF: Setting The
36fe0 20 52 65 73 75 6c 74 20 4f 66 20 41 6e 20 53 51   Result Of An SQ
36ff0 4c 20 46 75 6e 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a  L Function.**.**
37000 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
37010 61 72 65 20 75 73 65 64 20 62 79 20 74 68 65 20  are used by the 
37020 78 46 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20  xFunc or xFinal 
37030 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a  callbacks that.*
37040 2a 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20  * implement SQL 
37050 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67  functions and ag
37060 67 72 65 67 61 74 65 73 2e 20 20 53 65 65 0a 2a  gregates.  See.*
37070 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  * [sqlite3_creat
37080 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e  e_function()] an
37090 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  d [sqlite3_creat
370a0 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a  e_function16()].
370b0 2a 2a 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  ** for additiona
370c0 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  l information..*
370d0 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74  *.** These funct
370e0 69 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79 20 6d  ions work very m
370f0 75 63 68 20 6c 69 6b 65 20 74 68 65 20 5b 70 61  uch like the [pa
37100 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 5d  rameter binding]
37110 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66 75   family of.** fu
37120 6e 63 74 69 6f 6e 73 20 75 73 65 64 20 74 6f 20  nctions used to 
37130 62 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 68  bind values to h
37140 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 69  ost parameters i
37150 6e 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  n prepared state
37160 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20  ments..** Refer 
37170 74 6f 20 74 68 65 20 5b 53 51 4c 20 70 61 72 61  to the [SQL para
37180 6d 65 74 65 72 5d 20 64 6f 63 75 6d 65 6e 74 61  meter] documenta
37190 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f  tion for additio
371a0 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  nal information.
371b0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
371c0 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28  te3_result_blob(
371d0 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
371e0 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d   the result from
371f0 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69  .** an applicati
37200 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
37210 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 42 4c  ion to be the BL
37220 4f 42 20 77 68 6f 73 65 20 63 6f 6e 74 65 6e 74  OB whose content
37230 20 69 73 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 74   is pointed.** t
37240 6f 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20  o by the second 
37250 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 77 68  parameter and wh
37260 69 63 68 20 69 73 20 4e 20 62 79 74 65 73 20 6c  ich is N bytes l
37270 6f 6e 67 20 77 68 65 72 65 20 4e 20 69 73 20 74  ong where N is t
37280 68 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61  he.** third para
37290 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  meter..**.** ^Th
372a0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
372b0 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 69 6e 74 65  _zeroblob() inte
372c0 72 66 61 63 65 73 20 73 65 74 20 74 68 65 20 72  rfaces set the r
372d0 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20  esult of.** the 
372e0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
372f0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
37300 62 65 20 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69  be a BLOB contai
37310 6e 69 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a  ning all zero.**
37320 20 62 79 74 65 73 20 61 6e 64 20 4e 20 62 79 74   bytes and N byt
37330 65 73 20 69 6e 20 73 69 7a 65 2c 20 77 68 65 72  es in size, wher
37340 65 20 4e 20 69 73 20 74 68 65 20 76 61 6c 75 65  e N is the value
37350 20 6f 66 20 74 68 65 20 32 6e 64 20 70 61 72 61   of the 2nd para
37360 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  meter..**.** ^Th
37370 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
37380 5f 64 6f 75 62 6c 65 28 29 20 69 6e 74 65 72 66  _double() interf
37390 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73  ace sets the res
373a0 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61  ult from.** an a
373b0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
373c0 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
373d0 65 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  e a floating poi
373e0 6e 74 20 76 61 6c 75 65 20 73 70 65 63 69 66 69  nt value specifi
373f0 65 64 0a 2a 2a 20 62 79 20 69 74 73 20 32 6e 64  ed.** by its 2nd
37400 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
37410 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
37420 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64  sult_error() and
37430 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
37440 65 72 72 6f 72 31 36 28 29 20 66 75 6e 63 74 69  error16() functi
37450 6f 6e 73 0a 2a 2a 20 63 61 75 73 65 20 74 68 65  ons.** cause the
37460 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c   implemented SQL
37470 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72   function to thr
37480 6f 77 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e  ow an exception.
37490 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73  .** ^SQLite uses
374a0 20 74 68 65 20 73 74 72 69 6e 67 20 70 6f 69 6e   the string poin
374b0 74 65 64 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a  ted to by the.**
374c0 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f   2nd parameter o
374d0 66 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  f sqlite3_result
374e0 5f 65 72 72 6f 72 28 29 20 6f 72 20 73 71 6c 69  _error() or sqli
374f0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
37500 31 36 28 29 0a 2a 2a 20 61 73 20 74 68 65 20 74  16().** as the t
37510 65 78 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20  ext of an error 
37520 6d 65 73 73 61 67 65 2e 20 20 5e 53 51 4c 69 74  message.  ^SQLit
37530 65 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65  e interprets the
37540 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67   error.** messag
37550 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71  e string from sq
37560 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
37570 6f 72 28 29 20 61 73 20 55 54 46 2d 38 2e 20 5e  or() as UTF-8. ^
37580 53 51 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70  SQLite.** interp
37590 72 65 74 73 20 74 68 65 20 73 74 72 69 6e 67 20  rets the string 
375a0 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73  from sqlite3_res
375b0 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 61 73  ult_error16() as
375c0 20 55 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76   UTF-16 in nativ
375d0 65 0a 2a 2a 20 62 79 74 65 20 6f 72 64 65 72 2e  e.** byte order.
375e0 20 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20    ^If the third 
375f0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
37600 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
37610 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  r().** or sqlite
37620 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
37630 28 29 20 69 73 20 6e 65 67 61 74 69 76 65 20 74  () is negative t
37640 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73  hen SQLite takes
37650 20 61 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a   as the error.**
37660 20 6d 65 73 73 61 67 65 20 61 6c 6c 20 74 65 78   message all tex
37670 74 20 75 70 20 74 68 72 6f 75 67 68 20 74 68 65  t up through the
37680 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72   first zero char
37690 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68  acter..** ^If th
376a0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
376b0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73  r to sqlite3_res
376c0 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 0a 2a  ult_error() or.*
376d0 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  * sqlite3_result
376e0 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e 6f  _error16() is no
376f0 6e 2d 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20  n-negative then 
37700 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68 61  SQLite takes tha
37710 74 20 6d 61 6e 79 0a 2a 2a 20 62 79 74 65 73 20  t many.** bytes 
37720 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 29  (not characters)
37730 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61   from the 2nd pa
37740 72 61 6d 65 74 65 72 20 61 73 20 74 68 65 20 65  rameter as the e
37750 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a  rror message..**
37760 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
37770 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64  sult_error() and
37780 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
37790 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 72 6f 75  error16().** rou
377a0 74 69 6e 65 73 20 6d 61 6b 65 20 61 20 70 72 69  tines make a pri
377b0 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65  vate copy of the
377c0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74   error message t
377d0 65 78 74 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68  ext before.** th
377e0 65 79 20 72 65 74 75 72 6e 2e 20 20 48 65 6e 63  ey return.  Henc
377f0 65 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66  e, the calling f
37800 75 6e 63 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c  unction can deal
37810 6c 6f 63 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64  locate or.** mod
37820 69 66 79 20 74 68 65 20 74 65 78 74 20 61 66 74  ify the text aft
37830 65 72 20 74 68 65 79 20 72 65 74 75 72 6e 20 77  er they return w
37840 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20  ithout harm..** 
37850 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
37860 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 29  ult_error_code()
37870 20 66 75 6e 63 74 69 6f 6e 20 63 68 61 6e 67 65   function change
37880 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65  s the error code
37890 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20  .** returned by 
378a0 53 51 4c 69 74 65 20 61 73 20 61 20 72 65 73 75  SQLite as a resu
378b0 6c 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 69  lt of an error i
378c0 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e  n a function.  ^
378d0 42 79 20 64 65 66 61 75 6c 74 2c 0a 2a 2a 20 74  By default,.** t
378e0 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73  he error code is
378f0 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20   SQLITE_ERROR.  
37900 5e 41 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  ^A subsequent ca
37910 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  ll to sqlite3_re
37920 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20  sult_error().** 
37930 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  or sqlite3_resul
37940 74 5f 65 72 72 6f 72 31 36 28 29 20 72 65 73 65  t_error16() rese
37950 74 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64  ts the error cod
37960 65 20 74 6f 20 53 51 4c 49 54 45 5f 45 52 52 4f  e to SQLITE_ERRO
37970 52 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  R..**.** ^The sq
37980 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
37990 6f 72 5f 74 6f 6f 62 69 67 28 29 20 69 6e 74 65  or_toobig() inte
379a0 72 66 61 63 65 20 63 61 75 73 65 73 20 53 51 4c  rface causes SQL
379b0 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 0a  ite to throw an.
379c0 2a 2a 20 65 72 72 6f 72 20 69 6e 64 69 63 61 74  ** error indicat
379d0 69 6e 67 20 74 68 61 74 20 61 20 73 74 72 69 6e  ing that a strin
379e0 67 20 6f 72 20 42 4c 4f 42 20 69 73 20 74 6f 6f  g or BLOB is too
379f0 20 6c 6f 6e 67 20 74 6f 20 72 65 70 72 65 73 65   long to represe
37a00 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  nt..**.** ^The s
37a10 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
37a20 72 6f 72 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74 65  ror_nomem() inte
37a30 72 66 61 63 65 20 63 61 75 73 65 73 20 53 51 4c  rface causes SQL
37a40 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 0a  ite to throw an.
37a50 2a 2a 20 65 72 72 6f 72 20 69 6e 64 69 63 61 74  ** error indicat
37a60 69 6e 67 20 74 68 61 74 20 61 20 6d 65 6d 6f 72  ing that a memor
37a70 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69  y allocation fai
37a80 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  led..**.** ^The 
37a90 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69  sqlite3_result_i
37aa0 6e 74 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  nt() interface s
37ab0 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76  ets the return v
37ac0 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61  alue.** of the a
37ad0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
37ae0 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
37af0 65 20 74 68 65 20 33 32 2d 62 69 74 20 73 69 67  e the 32-bit sig
37b00 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76  ned integer.** v
37b10 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68  alue given in th
37b20 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a  e 2nd argument..
37b30 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
37b40 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 29 20 69  result_int64() i
37b50 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
37b60 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a  e return value.*
37b70 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  * of the applica
37b80 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
37b90 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20  ction to be the 
37ba0 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  64-bit signed in
37bb0 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67  teger.** value g
37bc0 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20  iven in the 2nd 
37bd0 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
37be0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
37bf0 75 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e 74 65 72  ult_null() inter
37c00 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65  face sets the re
37c10 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66  turn value.** of
37c20 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
37c30 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
37c40 6e 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a  n to be NULL..**
37c50 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
37c60 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 29 2c 20  _result_text(), 
37c70 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
37c80 65 78 74 31 36 28 29 2c 0a 2a 2a 20 73 71 6c 69  ext16(),.** sqli
37c90 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
37ca0 36 6c 65 28 29 2c 20 61 6e 64 20 73 71 6c 69 74  6le(), and sqlit
37cb0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
37cc0 62 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a  be() interfaces.
37cd0 2a 2a 20 73 65 74 20 74 68 65 20 72 65 74 75 72  ** set the retur
37ce0 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 61  n value of the a
37cf0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
37d00 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
37d10 65 0a 2a 2a 20 61 20 74 65 78 74 20 73 74 72 69  e.** a text stri
37d20 6e 67 20 77 68 69 63 68 20 69 73 20 72 65 70 72  ng which is repr
37d30 65 73 65 6e 74 65 64 20 61 73 20 55 54 46 2d 38  esented as UTF-8
37d40 2c 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20  , UTF-16 native 
37d50 62 79 74 65 20 6f 72 64 65 72 2c 0a 2a 2a 20 55  byte order,.** U
37d60 54 46 2d 31 36 20 6c 69 74 74 6c 65 20 65 6e 64  TF-16 little end
37d70 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 62  ian, or UTF-16 b
37d80 69 67 20 65 6e 64 69 61 6e 2c 20 72 65 73 70 65  ig endian, respe
37d90 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 54 68 65  ctively..** ^The
37da0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
37db0 74 65 78 74 36 34 28 29 20 69 6e 74 65 72 66 61  text64() interfa
37dc0 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75  ce sets the retu
37dd0 72 6e 20 76 61 6c 75 65 20 6f 66 20 61 6e 0a 2a  rn value of an.*
37de0 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  * application-de
37df0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
37e00 6f 20 62 65 20 61 20 74 65 78 74 20 73 74 72 69  o be a text stri
37e10 6e 67 20 69 6e 20 61 6e 20 65 6e 63 6f 64 69 6e  ng in an encodin
37e20 67 0a 2a 2a 20 73 70 65 63 69 66 69 65 64 20 62  g.** specified b
37e30 79 20 74 68 65 20 66 69 66 74 68 20 28 61 6e 64  y the fifth (and
37e40 20 6c 61 73 74 29 20 70 61 72 61 6d 65 74 65 72   last) parameter
37e50 2c 20 77 68 69 63 68 20 6d 75 73 74 20 62 65 20  , which must be 
37e60 6f 6e 65 0a 2a 2a 20 6f 66 20 5b 53 51 4c 49 54  one.** of [SQLIT
37e70 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45  E_UTF8], [SQLITE
37e80 5f 55 54 46 31 36 5d 2c 20 5b 53 51 4c 49 54 45  _UTF16], [SQLITE
37e90 5f 55 54 46 31 36 42 45 5d 2c 20 6f 72 20 5b 53  _UTF16BE], or [S
37ea0 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2e 0a  QLITE_UTF16LE]..
37eb0 2a 2a 20 5e 53 51 4c 69 74 65 20 74 61 6b 65 73  ** ^SQLite takes
37ec0 20 74 68 65 20 74 65 78 74 20 72 65 73 75 6c 74   the text result
37ed0 20 66 72 6f 6d 20 74 68 65 20 61 70 70 6c 69 63   from the applic
37ee0 61 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68  ation from.** th
37ef0 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  e 2nd parameter 
37f00 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72  of the sqlite3_r
37f10 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65  esult_text* inte
37f20 72 66 61 63 65 73 2e 0a 2a 2a 20 5e 49 66 20 74  rfaces..** ^If t
37f30 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  he 3rd parameter
37f40 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
37f50 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74  result_text* int
37f60 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 65  erfaces.** is ne
37f70 67 61 74 69 76 65 2c 20 74 68 65 6e 20 53 51 4c  gative, then SQL
37f80 69 74 65 20 74 61 6b 65 73 20 72 65 73 75 6c 74  ite takes result
37f90 20 74 65 78 74 20 66 72 6f 6d 20 74 68 65 20 32   text from the 2
37fa0 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  nd parameter.** 
37fb0 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 72 73  through the firs
37fc0 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72  t zero character
37fd0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33 72 64  ..** ^If the 3rd
37fe0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
37ff0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
38000 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
38010 73 0a 2a 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67 61  s.** is non-nega
38020 74 69 76 65 2c 20 74 68 65 6e 20 61 73 20 6d 61  tive, then as ma
38030 6e 79 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68  ny bytes (not ch
38040 61 72 61 63 74 65 72 73 29 20 6f 66 20 74 68 65  aracters) of the
38050 20 74 65 78 74 0a 2a 2a 20 70 6f 69 6e 74 65 64   text.** pointed
38060 20 74 6f 20 62 79 20 74 68 65 20 32 6e 64 20 70   to by the 2nd p
38070 61 72 61 6d 65 74 65 72 20 61 72 65 20 74 61 6b  arameter are tak
38080 65 6e 20 61 73 20 74 68 65 20 61 70 70 6c 69 63  en as the applic
38090 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a  ation-defined.**
380a0 20 66 75 6e 63 74 69 6f 6e 20 72 65 73 75 6c 74   function result
380b0 2e 20 20 49 66 20 74 68 65 20 33 72 64 20 70 61  .  If the 3rd pa
380c0 72 61 6d 65 74 65 72 20 69 73 20 6e 6f 6e 2d 6e  rameter is non-n
380d0 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 69 74  egative, then it
380e0 0a 2a 2a 20 6d 75 73 74 20 62 65 20 74 68 65 20  .** must be the 
380f0 62 79 74 65 20 6f 66 66 73 65 74 20 69 6e 74 6f  byte offset into
38100 20 74 68 65 20 73 74 72 69 6e 67 20 77 68 65 72   the string wher
38110 65 20 74 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e  e the NUL termin
38120 61 74 6f 72 20 77 6f 75 6c 64 0a 2a 2a 20 61 70  ator would.** ap
38130 70 65 61 72 20 69 66 20 74 68 65 20 73 74 72 69  pear if the stri
38140 6e 67 20 77 68 65 72 65 20 4e 55 4c 20 74 65 72  ng where NUL ter
38150 6d 69 6e 61 74 65 64 2e 20 20 49 66 20 61 6e 79  minated.  If any
38160 20 4e 55 4c 20 63 68 61 72 61 63 74 65 72 73 20   NUL characters 
38170 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20  occur.** in the 
38180 73 74 72 69 6e 67 20 61 74 20 61 20 62 79 74 65  string at a byte
38190 20 6f 66 66 73 65 74 20 74 68 61 74 20 69 73 20   offset that is 
381a0 6c 65 73 73 20 74 68 61 6e 20 74 68 65 20 76 61  less than the va
381b0 6c 75 65 20 6f 66 20 74 68 65 20 33 72 64 0a 2a  lue of the 3rd.*
381c0 2a 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65  * parameter, the
381d0 6e 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20  n the resulting 
381e0 73 74 72 69 6e 67 20 77 69 6c 6c 20 63 6f 6e 74  string will cont
381f0 61 69 6e 20 65 6d 62 65 64 64 65 64 20 4e 55 4c  ain embedded NUL
38200 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20 72 65 73  s and the.** res
38210 75 6c 74 20 6f 66 20 65 78 70 72 65 73 73 69 6f  ult of expressio
38220 6e 73 20 6f 70 65 72 61 74 69 6e 67 20 6f 6e 20  ns operating on 
38230 73 74 72 69 6e 67 73 20 77 69 74 68 20 65 6d 62  strings with emb
38240 65 64 64 65 64 20 4e 55 4c 73 20 69 73 20 75 6e  edded NULs is un
38250 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20  defined..** ^If 
38260 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65  the 4th paramete
38270 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
38280 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e  _result_text* in
38290 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73  terfaces.** or s
382a0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
382b0 6f 62 20 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c  ob is a non-NULL
382c0 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53   pointer, then S
382d0 51 4c 69 74 65 20 63 61 6c 6c 73 20 74 68 61 74  QLite calls that
382e0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 61 73 20  .** function as 
382f0 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 6f  the destructor o
38300 6e 20 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c  n the text or BL
38310 4f 42 20 72 65 73 75 6c 74 20 77 68 65 6e 20 69  OB result when i
38320 74 20 68 61 73 0a 2a 2a 20 66 69 6e 69 73 68 65  t has.** finishe
38330 64 20 75 73 69 6e 67 20 74 68 61 74 20 72 65 73  d using that res
38340 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ult..** ^If the 
38350 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
38360 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   the sqlite3_res
38370 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66  ult_text* interf
38380 61 63 65 73 20 6f 72 20 74 6f 0a 2a 2a 20 73 71  aces or to.** sq
38390 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
383a0 62 20 69 73 20 74 68 65 20 73 70 65 63 69 61 6c  b is the special
383b0 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45   constant SQLITE
383c0 5f 53 54 41 54 49 43 2c 20 74 68 65 6e 20 53 51  _STATIC, then SQ
383d0 4c 69 74 65 0a 2a 2a 20 61 73 73 75 6d 65 73 20  Lite.** assumes 
383e0 74 68 61 74 20 74 68 65 20 74 65 78 74 20 6f 72  that the text or
383f0 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 69 73 20   BLOB result is 
38400 69 6e 20 63 6f 6e 73 74 61 6e 74 20 73 70 61 63  in constant spac
38410 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 0a 2a  e and does not.*
38420 2a 20 63 6f 70 79 20 74 68 65 20 63 6f 6e 74 65  * copy the conte
38430 6e 74 20 6f 66 20 74 68 65 20 70 61 72 61 6d 65  nt of the parame
38440 74 65 72 20 6e 6f 72 20 63 61 6c 6c 20 61 20 64  ter nor call a d
38450 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65  estructor on the
38460 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 77 68 65 6e   content.** when
38470 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 64   it has finished
38480 20 75 73 69 6e 67 20 74 68 61 74 20 72 65 73 75   using that resu
38490 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34  lt..** ^If the 4
384a0 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
384b0 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
384c0 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
384d0 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  ces.** or sqlite
384e0 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73  3_result_blob is
384f0 20 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e   the special con
38500 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 54 52 41  stant SQLITE_TRA
38510 4e 53 49 45 4e 54 0a 2a 2a 20 74 68 65 6e 20 53  NSIENT.** then S
38520 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f  QLite makes a co
38530 70 79 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  py of the result
38540 20 69 6e 74 6f 20 73 70 61 63 65 20 6f 62 74 61   into space obta
38550 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f  ined from.** fro
38560 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
38570 63 28 29 5d 20 62 65 66 6f 72 65 20 69 74 20 72  c()] before it r
38580 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  eturns..**.** ^T
38590 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
385a0 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66  t_value() interf
385b0 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73  ace sets the res
385c0 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70  ult of.** the ap
385d0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
385e0 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
385f0 20 61 20 63 6f 70 79 20 74 68 65 0a 2a 2a 20 5b   a copy the.** [
38600 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
38610 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
38620 74 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74  t specified by t
38630 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
38640 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74  .  ^The.** sqlit
38650 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
38660 29 20 69 6e 74 65 72 66 61 63 65 20 6d 61 6b 65  ) interface make
38670 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
38680 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a  [sqlite3_value].
38690 2a 2a 20 73 6f 20 74 68 61 74 20 74 68 65 20 5b  ** so that the [
386a0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 73  sqlite3_value] s
386b0 70 65 63 69 66 69 65 64 20 69 6e 20 74 68 65 20  pecified in the 
386c0 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 63 68  parameter may ch
386d0 61 6e 67 65 20 6f 72 0a 2a 2a 20 62 65 20 64 65  ange or.** be de
386e0 61 6c 6c 6f 63 61 74 65 64 20 61 66 74 65 72 20  allocated after 
386f0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
38700 61 6c 75 65 28 29 20 72 65 74 75 72 6e 73 20 77  alue() returns w
38710 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20  ithout harm..** 
38720 5e 41 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71  ^A [protected sq
38730 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
38740 65 63 74 20 6d 61 79 20 61 6c 77 61 79 73 20 62  ect may always b
38750 65 20 75 73 65 64 20 77 68 65 72 65 20 61 6e 0a  e used where an.
38760 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  ** [unprotected 
38770 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
38780 62 6a 65 63 74 20 69 73