System.Data.SQLite
Hex Artifact Content
Not logged in

Artifact 49f1c3ae347e1327b5aaa6c7f76126bdf09c6f42:


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 39 2e 20 20 42  ersion 3.8.9.  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 2f 2a 2a 2a 2a  tic.#endif./****
0550: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 42 65 67 69 6e  ********** Begin
0560: 20 66 69 6c 65 20 73 71 6c 69 74 65 49 6e 74 2e   file sqliteInt.
0570: 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  h **************
0580: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0590: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 0a 2a 2a  *********/./*.**
05a0: 20 32 30 30 31 20 53 65 70 74 65 6d 62 65 72 20   2001 September 
05b0: 31 35 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74  15.**.** The aut
05c0: 68 6f 72 20 64 69 73 63 6c 61 69 6d 73 20 63 6f  hor disclaims co
05d0: 70 79 72 69 67 68 74 20 74 6f 20 74 68 69 73 20  pyright to this 
05e0: 73 6f 75 72 63 65 20 63 6f 64 65 2e 20 20 49 6e  source code.  In
05f0: 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 61 20 6c   place of.** a l
0600: 65 67 61 6c 20 6e 6f 74 69 63 65 2c 20 68 65 72  egal notice, her
0610: 65 20 69 73 20 61 20 62 6c 65 73 73 69 6e 67 3a  e is a blessing:
0620: 0a 2a 2a 0a 2a 2a 20 20 20 20 4d 61 79 20 79 6f  .**.**    May yo
0630: 75 20 64 6f 20 67 6f 6f 64 20 61 6e 64 20 6e 6f  u do good and no
0640: 74 20 65 76 69 6c 2e 0a 2a 2a 20 20 20 20 4d 61  t evil..**    Ma
0650: 79 20 79 6f 75 20 66 69 6e 64 20 66 6f 72 67 69  y you find forgi
0660: 76 65 6e 65 73 73 20 66 6f 72 20 79 6f 75 72 73  veness for yours
0670: 65 6c 66 20 61 6e 64 20 66 6f 72 67 69 76 65 20  elf and forgive 
0680: 6f 74 68 65 72 73 2e 0a 2a 2a 20 20 20 20 4d 61  others..**    Ma
0690: 79 20 79 6f 75 20 73 68 61 72 65 20 66 72 65 65  y you share free
06a0: 6c 79 2c 20 6e 65 76 65 72 20 74 61 6b 69 6e 67  ly, never taking
06b0: 20 6d 6f 72 65 20 74 68 61 6e 20 79 6f 75 20 67   more than you g
06c0: 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a 2a  ive..**.********
06d0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
06e0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
06f0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0700: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0710: 2a 0a 2a 2a 20 49 6e 74 65 72 6e 61 6c 20 69 6e  *.** Internal in
0720: 74 65 72 66 61 63 65 20 64 65 66 69 6e 69 74 69  terface definiti
0730: 6f 6e 73 20 66 6f 72 20 53 51 4c 69 74 65 2e 0a  ons for SQLite..
0740: 2a 2a 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53  **.*/.#ifndef _S
0750: 51 4c 49 54 45 49 4e 54 5f 48 5f 0a 23 64 65 66  QLITEINT_H_.#def
0760: 69 6e 65 20 5f 53 51 4c 49 54 45 49 4e 54 5f 48  ine _SQLITEINT_H
0770: 5f 0a 0a 2f 2a 0a 2a 2a 20 49 6e 63 6c 75 64 65  _../*.** Include
0780: 20 74 68 65 20 68 65 61 64 65 72 20 66 69 6c 65   the header file
0790: 20 75 73 65 64 20 74 6f 20 63 75 73 74 6f 6d 69   used to customi
07a0: 7a 65 20 74 68 65 20 63 6f 6d 70 69 6c 65 72 20  ze the compiler 
07b0: 6f 70 74 69 6f 6e 73 20 66 6f 72 20 4d 53 56 43  options for MSVC
07c0: 2e 0a 2a 2a 20 54 68 69 73 20 73 68 6f 75 6c 64  ..** This should
07d0: 20 62 65 20 64 6f 6e 65 20 66 69 72 73 74 20 73   be done first s
07e0: 6f 20 74 68 61 74 20 69 74 20 63 61 6e 20 73 75  o that it can su
07f0: 63 63 65 73 73 66 75 6c 6c 79 20 70 72 65 76 65  ccessfully preve
0800: 6e 74 20 73 70 75 72 69 6f 75 73 0a 2a 2a 20 63  nt spurious.** c
0810: 6f 6d 70 69 6c 65 72 20 77 61 72 6e 69 6e 67 73  ompiler warnings
0820: 20 64 75 65 20 74 6f 20 73 75 62 73 65 71 75 65   due to subseque
0830: 6e 74 20 63 6f 6e 74 65 6e 74 20 69 6e 20 74 68  nt content in th
0840: 69 73 20 66 69 6c 65 20 61 6e 64 20 6f 74 68 65  is file and othe
0850: 72 20 66 69 6c 65 73 0a 2a 2a 20 74 68 61 74 20  r files.** that 
0860: 61 72 65 20 69 6e 63 6c 75 64 65 64 20 62 79 20  are included by 
0870: 74 68 69 73 20 66 69 6c 65 2e 0a 2a 2f 0a 2f 2a  this file..*/./*
0880: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 49 6e  ************* In
0890: 63 6c 75 64 65 20 6d 73 76 63 2e 68 20 69 6e 20  clude msvc.h in 
08a0: 74 68 65 20 6d 69 64 64 6c 65 20 6f 66 20 73 71  the middle of sq
08b0: 6c 69 74 65 49 6e 74 2e 68 20 2a 2a 2a 2a 2a 2a  liteInt.h ******
08c0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a  ************/./*
08d0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 42 65  ************* Be
08e0: 67 69 6e 20 66 69 6c 65 20 6d 73 76 63 2e 68 20  gin file msvc.h 
08f0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0900: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0910: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a  ************/./*
0920: 0a 2a 2a 20 32 30 31 35 20 4a 61 6e 75 61 72 79  .** 2015 January
0930: 20 31 32 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75   12.**.** The au
0940: 74 68 6f 72 20 64 69 73 63 6c 61 69 6d 73 20 63  thor disclaims c
0950: 6f 70 79 72 69 67 68 74 20 74 6f 20 74 68 69 73  opyright to this
0960: 20 73 6f 75 72 63 65 20 63 6f 64 65 2e 20 20 49   source code.  I
0970: 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 61 20  n place of.** a 
0980: 6c 65 67 61 6c 20 6e 6f 74 69 63 65 2c 20 68 65  legal notice, he
0990: 72 65 20 69 73 20 61 20 62 6c 65 73 73 69 6e 67  re is a blessing
09a0: 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d 61 79 20 79  :.**.**    May y
09b0: 6f 75 20 64 6f 20 67 6f 6f 64 20 61 6e 64 20 6e  ou do good and n
09c0: 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20 20 20 20 4d  ot evil..**    M
09d0: 61 79 20 79 6f 75 20 66 69 6e 64 20 66 6f 72 67  ay you find forg
09e0: 69 76 65 6e 65 73 73 20 66 6f 72 20 79 6f 75 72  iveness for your
09f0: 73 65 6c 66 20 61 6e 64 20 66 6f 72 67 69 76 65  self and forgive
0a00: 20 6f 74 68 65 72 73 2e 0a 2a 2a 20 20 20 20 4d   others..**    M
0a10: 61 79 20 79 6f 75 20 73 68 61 72 65 20 66 72 65  ay you share fre
0a20: 65 6c 79 2c 20 6e 65 76 65 72 20 74 61 6b 69 6e  ely, never takin
0a30: 67 20 6d 6f 72 65 20 74 68 61 6e 20 79 6f 75 20  g more than you 
0a40: 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a  give..**.*******
0a50: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0a60: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0a70: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
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 0a 2a 2a 0a 2a 2a 20 54 68  *******.**.** Th
0aa0: 69 73 20 66 69 6c 65 20 63 6f 6e 74 61 69 6e 73  is file contains
0ab0: 20 63 6f 64 65 20 74 68 61 74 20 69 73 20 73 70   code that is sp
0ac0: 65 63 69 66 69 63 20 74 6f 20 4d 53 56 43 2e 0a  ecific to MSVC..
0ad0: 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 4d 53 56 43  */.#ifndef _MSVC
0ae0: 5f 48 5f 0a 23 64 65 66 69 6e 65 20 5f 4d 53 56  _H_.#define _MSV
0af0: 43 5f 48 5f 0a 0a 23 69 66 20 64 65 66 69 6e 65  C_H_..#if define
0b00: 64 28 5f 4d 53 43 5f 56 45 52 29 0a 23 70 72 61  d(_MSC_VER).#pra
0b10: 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73 61  gma warning(disa
0b20: 62 6c 65 20 3a 20 34 30 35 34 29 0a 23 70 72 61  ble : 4054).#pra
0b30: 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73 61  gma warning(disa
0b40: 62 6c 65 20 3a 20 34 30 35 35 29 0a 23 70 72 61  ble : 4055).#pra
0b50: 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73 61  gma warning(disa
0b60: 62 6c 65 20 3a 20 34 31 30 30 29 0a 23 70 72 61  ble : 4100).#pra
0b70: 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73 61  gma warning(disa
0b80: 62 6c 65 20 3a 20 34 31 32 37 29 0a 23 70 72 61  ble : 4127).#pra
0b90: 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73 61  gma warning(disa
0ba0: 62 6c 65 20 3a 20 34 31 35 32 29 0a 23 70 72 61  ble : 4152).#pra
0bb0: 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73 61  gma warning(disa
0bc0: 62 6c 65 20 3a 20 34 31 38 39 29 0a 23 70 72 61  ble : 4189).#pra
0bd0: 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73 61  gma warning(disa
0be0: 62 6c 65 20 3a 20 34 32 30 36 29 0a 23 70 72 61  ble : 4206).#pra
0bf0: 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73 61  gma warning(disa
0c00: 62 6c 65 20 3a 20 34 32 31 30 29 0a 23 70 72 61  ble : 4210).#pra
0c10: 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73 61  gma warning(disa
0c20: 62 6c 65 20 3a 20 34 32 33 32 29 0a 23 70 72 61  ble : 4232).#pra
0c30: 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73 61  gma warning(disa
0c40: 62 6c 65 20 3a 20 34 32 34 34 29 0a 23 70 72 61  ble : 4244).#pra
0c50: 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73 61  gma warning(disa
0c60: 62 6c 65 20 3a 20 34 33 30 35 29 0a 23 70 72 61  ble : 4305).#pra
0c70: 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73 61  gma warning(disa
0c80: 62 6c 65 20 3a 20 34 33 30 36 29 0a 23 70 72 61  ble : 4306).#pra
0c90: 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73 61  gma warning(disa
0ca0: 62 6c 65 20 3a 20 34 37 30 32 29 0a 23 70 72 61  ble : 4702).#pra
0cb0: 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73 61  gma warning(disa
0cc0: 62 6c 65 20 3a 20 34 37 30 36 29 0a 23 65 6e 64  ble : 4706).#end
0cd0: 69 66 20 2f 2a 20 64 65 66 69 6e 65 64 28 5f 4d  if /* defined(_M
0ce0: 53 43 5f 56 45 52 29 20 2a 2f 0a 0a 23 65 6e 64  SC_VER) */..#end
0cf0: 69 66 20 2f 2a 20 5f 4d 53 56 43 5f 48 5f 20 2a  if /* _MSVC_H_ *
0d00: 2f 0a 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  /../************
0d10: 2a 2a 20 45 6e 64 20 6f 66 20 6d 73 76 63 2e 68  ** End of msvc.h
0d20: 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a   ***************
0d30: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0d40: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0d50: 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  */./************
0d60: 2a 2a 20 43 6f 6e 74 69 6e 75 69 6e 67 20 77 68  ** Continuing wh
0d70: 65 72 65 20 77 65 20 6c 65 66 74 20 6f 66 66 20  ere we left off 
0d80: 69 6e 20 73 71 6c 69 74 65 49 6e 74 2e 68 20 2a  in sqliteInt.h *
0d90: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0da0: 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 61  */../*.** Specia
0db0: 6c 20 73 65 74 75 70 20 66 6f 72 20 56 78 57 6f  l setup for VxWo
0dc0: 72 6b 73 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a  rks.*/./********
0dd0: 2a 2a 2a 2a 2a 2a 20 49 6e 63 6c 75 64 65 20 76  ****** Include v
0de0: 78 77 6f 72 6b 73 2e 68 20 69 6e 20 74 68 65 20  xworks.h in the 
0df0: 6d 69 64 64 6c 65 20 6f 66 20 73 71 6c 69 74 65  middle of sqlite
0e00: 49 6e 74 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  Int.h **********
0e10: 2a 2a 2a 2a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a  *****/./********
0e20: 2a 2a 2a 2a 2a 2a 20 42 65 67 69 6e 20 66 69 6c  ****** Begin fil
0e30: 65 20 76 78 77 6f 72 6b 73 2e 68 20 2a 2a 2a 2a  e vxworks.h ****
0e40: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0e50: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0e60: 2a 2a 2a 2a 2a 2f 0a 2f 2a 0a 2a 2a 20 32 30 31  *****/./*.** 201
0e70: 35 2d 30 33 2d 30 32 0a 2a 2a 0a 2a 2a 20 54 68  5-03-02.**.** Th
0e80: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0e90: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0ea0: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0eb0: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0ec0: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0ed0: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0ee0: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0ef0: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
0f00: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
0f10: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
0f20: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
0f30: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
0f40: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
0f50: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0f60: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0f70: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0f80: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0f90: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0fa0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0fb0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0fc0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0fd0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a 2a 0a 2a  ***********.**.*
0fe0: 2a 20 54 68 69 73 20 66 69 6c 65 20 63 6f 6e 74  * This file cont
0ff0: 61 69 6e 73 20 63 6f 64 65 20 74 68 61 74 20 69  ains code that i
1000: 73 20 73 70 65 63 69 66 69 63 20 74 6f 20 57 69  s specific to Wi
1010: 6e 64 20 52 69 76 65 72 27 73 20 56 78 57 6f 72  nd River's VxWor
1020: 6b 73 0a 2a 2f 0a 23 69 66 20 64 65 66 69 6e 65  ks.*/.#if define
1030: 64 28 5f 5f 52 54 50 5f 5f 29 20 7c 7c 20 64 65  d(__RTP__) || de
1040: 66 69 6e 65 64 28 5f 57 52 53 5f 4b 45 52 4e 45  fined(_WRS_KERNE
1050: 4c 29 0a 2f 2a 20 54 68 69 73 20 69 73 20 56 78  L)./* This is Vx
1060: 57 6f 72 6b 73 2e 20 20 53 65 74 20 75 70 20 74  Works.  Set up t
1070: 68 69 6e 67 73 20 73 70 65 63 69 61 6c 6c 79 20  hings specially 
1080: 66 6f 72 20 74 68 61 74 20 4f 53 0a 2a 2f 0a 23  for that OS.*/.#
1090: 69 6e 63 6c 75 64 65 20 3c 76 78 57 6f 72 6b 73  include <vxWorks
10a0: 2e 68 3e 0a 23 69 6e 63 6c 75 64 65 20 3c 70 74  .h>.#include <pt
10b0: 68 72 65 61 64 2e 68 3e 20 20 2f 2a 20 61 6d 61  hread.h>  /* ama
10c0: 6c 67 61 6d 61 74 6f 72 3a 20 64 6f 6e 74 63 61  lgamator: dontca
10d0: 63 68 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 4f  che */.#define O
10e0: 53 5f 56 58 57 4f 52 4b 53 20 31 0a 23 64 65 66  S_VXWORKS 1.#def
10f0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 53 5f 4f 54  ine SQLITE_OS_OT
1100: 48 45 52 20 30 0a 23 64 65 66 69 6e 65 20 53 51  HER 0.#define SQ
1110: 4c 49 54 45 5f 48 4f 4d 45 47 52 4f 57 4e 5f 52  LITE_HOMEGROWN_R
1120: 45 43 55 52 53 49 56 45 5f 4d 55 54 45 58 20 31  ECURSIVE_MUTEX 1
1130: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1140: 4f 4d 49 54 5f 4c 4f 41 44 5f 45 58 54 45 4e 53  OMIT_LOAD_EXTENS
1150: 49 4f 4e 20 31 0a 23 64 65 66 69 6e 65 20 53 51  ION 1.#define SQ
1160: 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4c 4f 43 4b  LITE_ENABLE_LOCK
1170: 49 4e 47 5f 53 54 59 4c 45 20 30 0a 23 64 65 66  ING_STYLE 0.#def
1180: 69 6e 65 20 48 41 56 45 5f 55 54 49 4d 45 20 31  ine HAVE_UTIME 1
1190: 0a 23 65 6c 73 65 0a 2f 2a 20 54 68 69 73 20 69  .#else./* This i
11a0: 73 20 6e 6f 74 20 56 78 57 6f 72 6b 73 2e 20 2a  s not VxWorks. *
11b0: 2f 0a 23 64 65 66 69 6e 65 20 4f 53 5f 56 58 57  /.#define OS_VXW
11c0: 4f 52 4b 53 20 30 0a 23 65 6e 64 69 66 20 2f 2a  ORKS 0.#endif /*
11d0: 20 64 65 66 69 6e 65 64 28 5f 57 52 53 5f 4b 45   defined(_WRS_KE
11e0: 52 4e 45 4c 29 20 2a 2f 0a 0a 2f 2a 2a 2a 2a 2a  RNEL) */../*****
11f0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 45 6e 64 20 6f 66  ********* End of
1200: 20 76 78 77 6f 72 6b 73 2e 68 20 2a 2a 2a 2a 2a   vxworks.h *****
1210: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1220: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1230: 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 2a 2a 2a 2a  ********/./*****
1240: 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 43 6f 6e 74 69 6e  ********* Contin
1250: 75 69 6e 67 20 77 68 65 72 65 20 77 65 20 6c 65  uing where we le
1260: 66 74 20 6f 66 66 20 69 6e 20 73 71 6c 69 74 65  ft off in sqlite
1270: 49 6e 74 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  Int.h **********
1280: 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 0a 2f 2a 0a 2a 2a  ********/../*.**
1290: 20 54 68 65 73 65 20 23 64 65 66 69 6e 65 73 20   These #defines 
12a0: 73 68 6f 75 6c 64 20 65 6e 61 62 6c 65 20 3e 32  should enable >2
12b0: 47 42 20 66 69 6c 65 20 73 75 70 70 6f 72 74 20  GB file support 
12c0: 6f 6e 20 50 4f 53 49 58 20 69 66 20 74 68 65 0a  on POSIX if the.
12d0: 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70  ** underlying op
12e0: 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 73  erating system s
12f0: 75 70 70 6f 72 74 73 20 69 74 2e 20 20 49 66 20  upports it.  If 
1300: 74 68 65 20 4f 53 20 6c 61 63 6b 73 0a 2a 2a 20  the OS lacks.** 
1310: 6c 61 72 67 65 20 66 69 6c 65 20 73 75 70 70 6f  large file suppo
1320: 72 74 2c 20 6f 72 20 69 66 20 74 68 65 20 4f 53  rt, or if the OS
1330: 20 69 73 20 77 69 6e 64 6f 77 73 2c 20 74 68 65   is windows, the
1340: 73 65 20 73 68 6f 75 6c 64 20 62 65 20 6e 6f 2d  se should be no-
1350: 6f 70 73 2e 0a 2a 2a 0a 2a 2a 20 54 69 63 6b 65  ops..**.** Ticke
1360: 74 20 23 32 37 33 39 3a 20 20 54 68 65 20 5f 4c  t #2739:  The _L
1370: 41 52 47 45 46 49 4c 45 5f 53 4f 55 52 43 45 20  ARGEFILE_SOURCE 
1380: 6d 61 63 72 6f 20 6d 75 73 74 20 61 70 70 65 61  macro must appea
1390: 72 20 62 65 66 6f 72 65 20 61 6e 79 0a 2a 2a 20  r before any.** 
13a0: 73 79 73 74 65 6d 20 23 69 6e 63 6c 75 64 65 73  system #includes
13b0: 2e 20 20 48 65 6e 63 65 2c 20 74 68 69 73 20 62  .  Hence, this b
13c0: 6c 6f 63 6b 20 6f 66 20 63 6f 64 65 20 6d 75 73  lock of code mus
13d0: 74 20 62 65 20 74 68 65 20 76 65 72 79 20 66 69  t be the very fi
13e0: 72 73 74 0a 2a 2a 20 63 6f 64 65 20 69 6e 20 61  rst.** code in a
13f0: 6c 6c 20 73 6f 75 72 63 65 20 66 69 6c 65 73 2e  ll source files.
1400: 0a 2a 2a 0a 2a 2a 20 4c 61 72 67 65 20 66 69 6c  .**.** Large fil
1410: 65 20 73 75 70 70 6f 72 74 20 63 61 6e 20 62 65  e support can be
1420: 20 64 69 73 61 62 6c 65 64 20 75 73 69 6e 67 20   disabled using 
1430: 74 68 65 20 2d 44 53 51 4c 49 54 45 5f 44 49 53  the -DSQLITE_DIS
1440: 41 42 4c 45 5f 4c 46 53 20 73 77 69 74 63 68 0a  ABLE_LFS switch.
1450: 2a 2a 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69 6c  ** on the compil
1460: 65 72 20 63 6f 6d 6d 61 6e 64 20 6c 69 6e 65 2e  er command line.
1470: 20 20 54 68 69 73 20 69 73 20 6e 65 63 65 73 73    This is necess
1480: 61 72 79 20 69 66 20 79 6f 75 20 61 72 65 20 63  ary if you are c
1490: 6f 6d 70 69 6c 69 6e 67 0a 2a 2a 20 6f 6e 20 61  ompiling.** on a
14a0: 20 72 65 63 65 6e 74 20 6d 61 63 68 69 6e 65 20   recent machine 
14b0: 28 65 78 3a 20 52 65 64 20 48 61 74 20 37 2e 32  (ex: Red Hat 7.2
14c0: 29 20 62 75 74 20 79 6f 75 20 77 61 6e 74 20 79  ) but you want y
14d0: 6f 75 72 20 63 6f 64 65 20 74 6f 20 77 6f 72 6b  our code to work
14e0: 0a 2a 2a 20 6f 6e 20 61 6e 20 6f 6c 64 65 72 20  .** on an older 
14f0: 6d 61 63 68 69 6e 65 20 28 65 78 3a 20 52 65 64  machine (ex: Red
1500: 20 48 61 74 20 36 2e 30 29 2e 20 20 49 66 20 79   Hat 6.0).  If y
1510: 6f 75 20 63 6f 6d 70 69 6c 65 20 6f 6e 20 52 65  ou compile on Re
1520: 64 20 48 61 74 20 37 2e 32 0a 2a 2a 20 77 69 74  d Hat 7.2.** wit
1530: 68 6f 75 74 20 74 68 69 73 20 6f 70 74 69 6f 6e  hout this option
1540: 2c 20 4c 46 53 20 69 73 20 65 6e 61 62 6c 65 2e  , LFS is enable.
1550: 20 20 42 75 74 20 4c 46 53 20 64 6f 65 73 20 6e    But LFS does n
1560: 6f 74 20 65 78 69 73 74 20 69 6e 20 74 68 65 20  ot exist in the 
1570: 6b 65 72 6e 65 6c 0a 2a 2a 20 69 6e 20 52 65 64  kernel.** in Red
1580: 20 48 61 74 20 36 2e 30 2c 20 73 6f 20 74 68 65   Hat 6.0, so the
1590: 20 63 6f 64 65 20 77 6f 6e 27 74 20 77 6f 72 6b   code won't work
15a0: 2e 20 20 48 65 6e 63 65 2c 20 66 6f 72 20 6d 61  .  Hence, for ma
15b0: 78 69 6d 75 6d 20 62 69 6e 61 72 79 0a 2a 2a 20  ximum binary.** 
15c0: 70 6f 72 74 61 62 69 6c 69 74 79 20 79 6f 75 20  portability you 
15d0: 73 68 6f 75 6c 64 20 6f 6d 69 74 20 4c 46 53 2e  should omit LFS.
15e0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 76 69  .**.** The previ
15f0: 6f 75 73 20 70 61 72 61 67 72 61 70 68 20 77 61  ous paragraph wa
1600: 73 20 77 72 69 74 74 65 6e 20 69 6e 20 32 30 30  s written in 200
1610: 35 2e 20 20 28 54 68 69 73 20 70 61 72 61 67 72  5.  (This paragr
1620: 61 70 68 20 69 73 20 77 72 69 74 74 65 6e 0a 2a  aph is written.*
1630: 2a 20 6f 6e 20 32 30 30 38 2d 31 31 2d 32 38 2e  * on 2008-11-28.
1640: 29 20 54 68 65 73 65 20 64 61 79 73 2c 20 61 6c  ) These days, al
1650: 6c 20 4c 69 6e 75 78 20 6b 65 72 6e 65 6c 73 20  l Linux kernels 
1660: 73 75 70 70 6f 72 74 20 6c 61 72 67 65 20 66 69  support large fi
1670: 6c 65 73 2c 20 73 6f 0a 2a 2a 20 79 6f 75 20 73  les, so.** you s
1680: 68 6f 75 6c 64 20 70 72 6f 62 61 62 6c 79 20 6c  hould probably l
1690: 65 61 76 65 20 4c 46 53 20 65 6e 61 62 6c 65 64  eave LFS enabled
16a0: 2e 20 20 42 75 74 20 73 6f 6d 65 20 65 6d 62 65  .  But some embe
16b0: 64 64 65 64 20 70 6c 61 74 66 6f 72 6d 73 20 6d  dded platforms m
16c0: 69 67 68 74 0a 2a 2a 20 6c 61 63 6b 20 4c 46 53  ight.** lack LFS
16d0: 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 74   in which case t
16e0: 68 65 20 53 51 4c 49 54 45 5f 44 49 53 41 42 4c  he SQLITE_DISABL
16f0: 45 5f 4c 46 53 20 6d 61 63 72 6f 20 6d 69 67 68  E_LFS macro migh
1700: 74 20 73 74 69 6c 6c 20 62 65 20 75 73 65 66 75  t still be usefu
1710: 6c 2e 0a 2a 2a 0a 2a 2a 20 53 69 6d 69 6c 61 72  l..**.** Similar
1720: 20 69 73 20 74 72 75 65 20 66 6f 72 20 4d 61 63   is true for Mac
1730: 20 4f 53 20 58 2e 20 20 4c 46 53 20 69 73 20 6f   OS X.  LFS is o
1740: 6e 6c 79 20 73 75 70 70 6f 72 74 65 64 20 6f 6e  nly supported on
1750: 20 4d 61 63 20 4f 53 20 58 20 39 20 61 6e 64 20   Mac OS X 9 and 
1760: 6c 61 74 65 72 2e 0a 2a 2f 0a 23 69 66 6e 64 65  later..*/.#ifnde
1770: 66 20 53 51 4c 49 54 45 5f 44 49 53 41 42 4c 45  f SQLITE_DISABLE
1780: 5f 4c 46 53 0a 23 20 64 65 66 69 6e 65 20 5f 4c  _LFS.# define _L
1790: 41 52 47 45 5f 46 49 4c 45 20 20 20 20 20 20 20  ARGE_FILE       
17a0: 31 0a 23 20 69 66 6e 64 65 66 20 5f 46 49 4c 45  1.# ifndef _FILE
17b0: 5f 4f 46 46 53 45 54 5f 42 49 54 53 0a 23 20 20  _OFFSET_BITS.#  
17c0: 20 64 65 66 69 6e 65 20 5f 46 49 4c 45 5f 4f 46   define _FILE_OF
17d0: 46 53 45 54 5f 42 49 54 53 20 36 34 0a 23 20 65  FSET_BITS 64.# e
17e0: 6e 64 69 66 0a 23 20 64 65 66 69 6e 65 20 5f 4c  ndif.# define _L
17f0: 41 52 47 45 46 49 4c 45 5f 53 4f 55 52 43 45 20  ARGEFILE_SOURCE 
1800: 31 0a 23 65 6e 64 69 66 0a 0a 2f 2a 20 4e 65 65  1.#endif../* Nee
1810: 64 65 64 20 66 6f 72 20 76 61 72 69 6f 75 73 20  ded for various 
1820: 64 65 66 69 6e 69 74 69 6f 6e 73 2e 2e 2e 20 2a  definitions... *
1830: 2f 0a 23 69 66 20 64 65 66 69 6e 65 64 28 5f 5f  /.#if defined(__
1840: 47 4e 55 43 5f 5f 29 20 26 26 20 21 64 65 66 69  GNUC__) && !defi
1850: 6e 65 64 28 5f 47 4e 55 5f 53 4f 55 52 43 45 29  ned(_GNU_SOURCE)
1860: 0a 23 20 64 65 66 69 6e 65 20 5f 47 4e 55 5f 53  .# define _GNU_S
1870: 4f 55 52 43 45 0a 23 65 6e 64 69 66 0a 0a 23 69  OURCE.#endif..#i
1880: 66 20 64 65 66 69 6e 65 64 28 5f 5f 4f 70 65 6e  f defined(__Open
1890: 42 53 44 5f 5f 29 20 26 26 20 21 64 65 66 69 6e  BSD__) && !defin
18a0: 65 64 28 5f 42 53 44 5f 53 4f 55 52 43 45 29 0a  ed(_BSD_SOURCE).
18b0: 23 20 64 65 66 69 6e 65 20 5f 42 53 44 5f 53 4f  # define _BSD_SO
18c0: 55 52 43 45 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a  URCE.#endif../*.
18d0: 2a 2a 20 46 6f 72 20 4d 69 6e 47 57 2c 20 63 68  ** For MinGW, ch
18e0: 65 63 6b 20 74 6f 20 73 65 65 20 69 66 20 77 65  eck to see if we
18f0: 20 63 61 6e 20 69 6e 63 6c 75 64 65 20 74 68 65   can include the
1900: 20 68 65 61 64 65 72 20 66 69 6c 65 20 63 6f 6e   header file con
1910: 74 61 69 6e 69 6e 67 20 69 74 73 0a 2a 2a 20 76  taining its.** v
1920: 65 72 73 69 6f 6e 20 69 6e 66 6f 72 6d 61 74 69  ersion informati
1930: 6f 6e 2c 20 61 6d 6f 6e 67 20 6f 74 68 65 72 20  on, among other 
1940: 74 68 69 6e 67 73 2e 20 20 4e 6f 72 6d 61 6c 6c  things.  Normall
1950: 79 2c 20 74 68 69 73 20 69 6e 74 65 72 6e 61 6c  y, this internal
1960: 20 4d 69 6e 47 57 0a 2a 2a 20 68 65 61 64 65 72   MinGW.** header
1970: 20 66 69 6c 65 20 77 6f 75 6c 64 20 5b 6f 6e 6c   file would [onl
1980: 79 5d 20 62 65 20 69 6e 63 6c 75 64 65 64 20 61  y] be included a
1990: 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20  utomatically by 
19a0: 6f 74 68 65 72 20 4d 69 6e 47 57 20 68 65 61 64  other MinGW head
19b0: 65 72 0a 2a 2a 20 66 69 6c 65 73 3b 20 68 6f 77  er.** files; how
19c0: 65 76 65 72 2c 20 74 68 65 20 63 6f 6e 74 61 69  ever, the contai
19d0: 6e 65 64 20 76 65 72 73 69 6f 6e 20 69 6e 66 6f  ned version info
19e0: 72 6d 61 74 69 6f 6e 20 69 73 20 6e 6f 77 20 72  rmation is now r
19f0: 65 71 75 69 72 65 64 20 62 79 20 74 68 69 73 0a  equired by this.
1a00: 2a 2a 20 68 65 61 64 65 72 20 66 69 6c 65 20 74  ** header file t
1a10: 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 62 69  o work around bi
1a20: 6e 61 72 79 20 63 6f 6d 70 61 74 69 62 69 6c 69  nary compatibili
1a30: 74 79 20 69 73 73 75 65 73 20 28 73 65 65 20 62  ty issues (see b
1a40: 65 6c 6f 77 29 20 61 6e 64 0a 2a 2a 20 74 68 69  elow) and.** thi
1a50: 73 20 69 73 20 74 68 65 20 6f 6e 6c 79 20 6b 6e  s is the only kn
1a60: 6f 77 6e 20 77 61 79 20 74 6f 20 72 65 6c 69 61  own way to relia
1a70: 62 6c 79 20 6f 62 74 61 69 6e 20 69 74 2e 20 20  bly obtain it.  
1a80: 54 68 69 73 20 65 6e 74 69 72 65 20 23 69 66 20  This entire #if 
1a90: 62 6c 6f 63 6b 0a 2a 2a 20 77 6f 75 6c 64 20 62  block.** would b
1aa0: 65 20 63 6f 6d 70 6c 65 74 65 6c 79 20 75 6e 6e  e completely unn
1ab0: 65 63 65 73 73 61 72 79 20 69 66 20 74 68 65 72  ecessary if ther
1ac0: 65 20 77 61 73 20 61 6e 79 20 6f 74 68 65 72 20  e was any other 
1ad0: 77 61 79 20 6f 66 20 64 65 74 65 63 74 69 6e 67  way of detecting
1ae0: 0a 2a 2a 20 4d 69 6e 47 57 20 76 69 61 20 74 68  .** MinGW via th
1af0: 65 69 72 20 70 72 65 70 72 6f 63 65 73 73 6f 72  eir preprocessor
1b00: 20 28 65 2e 67 2e 20 69 66 20 74 68 65 79 20 63   (e.g. if they c
1b10: 75 73 74 6f 6d 69 7a 65 64 20 74 68 65 69 72 20  ustomized their 
1b20: 47 43 43 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a  GCC to define.**
1b30: 20 73 6f 6d 65 20 4d 69 6e 47 57 2d 73 70 65 63   some MinGW-spec
1b40: 69 66 69 63 20 6d 61 63 72 6f 73 29 2e 20 20 57  ific macros).  W
1b50: 68 65 6e 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f  hen compiling fo
1b60: 72 20 4d 69 6e 47 57 2c 20 65 69 74 68 65 72 20  r MinGW, either 
1b70: 74 68 65 0a 2a 2a 20 5f 48 41 56 45 5f 4d 49 4e  the.** _HAVE_MIN
1b80: 47 57 5f 48 20 6f 72 20 5f 48 41 56 45 5f 5f 4d  GW_H or _HAVE__M
1b90: 49 4e 47 57 5f 48 20 28 6e 6f 74 65 20 74 68 65  INGW_H (note the
1ba0: 20 65 78 74 72 61 20 75 6e 64 65 72 73 63 6f 72   extra underscor
1bb0: 65 29 20 6d 61 63 72 6f 20 6d 75 73 74 20 62 65  e) macro must be
1bc0: 0a 2a 2a 20 64 65 66 69 6e 65 64 3b 20 6f 74 68  .** defined; oth
1bd0: 65 72 77 69 73 65 2c 20 64 65 74 65 63 74 69 6f  erwise, detectio
1be0: 6e 20 6f 66 20 63 6f 6e 64 69 74 69 6f 6e 73 20  n of conditions 
1bf0: 73 70 65 63 69 66 69 63 20 74 6f 20 4d 69 6e 47  specific to MinG
1c00: 57 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 64 69 73  W will be.** dis
1c10: 61 62 6c 65 64 2e 0a 2a 2f 0a 23 69 66 20 64 65  abled..*/.#if de
1c20: 66 69 6e 65 64 28 5f 48 41 56 45 5f 4d 49 4e 47  fined(_HAVE_MING
1c30: 57 5f 48 29 0a 23 20 69 6e 63 6c 75 64 65 20 22  W_H).# include "
1c40: 6d 69 6e 67 77 2e 68 22 0a 23 65 6c 69 66 20 64  mingw.h".#elif d
1c50: 65 66 69 6e 65 64 28 5f 48 41 56 45 5f 5f 4d 49  efined(_HAVE__MI
1c60: 4e 47 57 5f 48 29 0a 23 20 69 6e 63 6c 75 64 65  NGW_H).# include
1c70: 20 22 5f 6d 69 6e 67 77 2e 68 22 0a 23 65 6e 64   "_mingw.h".#end
1c80: 69 66 0a 0a 2f 2a 0a 2a 2a 20 46 6f 72 20 4d 69  if../*.** For Mi
1c90: 6e 47 57 20 76 65 72 73 69 6f 6e 20 34 2e 78 20  nGW version 4.x 
1ca0: 28 61 6e 64 20 68 69 67 68 65 72 29 2c 20 63 68  (and higher), ch
1cb0: 65 63 6b 20 74 6f 20 73 65 65 20 69 66 20 74 68  eck to see if th
1cc0: 65 20 5f 55 53 45 5f 33 32 42 49 54 5f 54 49 4d  e _USE_32BIT_TIM
1cd0: 45 5f 54 0a 2a 2a 20 64 65 66 69 6e 65 20 69 73  E_T.** define is
1ce0: 20 72 65 71 75 69 72 65 64 20 74 6f 20 6d 61 69   required to mai
1cf0: 6e 74 61 69 6e 20 62 69 6e 61 72 79 20 63 6f 6d  ntain binary com
1d00: 70 61 74 69 62 69 6c 69 74 79 20 77 69 74 68 20  patibility with 
1d10: 74 68 65 20 4d 53 56 43 20 72 75 6e 74 69 6d 65  the MSVC runtime
1d20: 0a 2a 2a 20 6c 69 62 72 61 72 79 20 69 6e 20 75  .** library in u
1d30: 73 65 20 28 65 2e 67 2e 20 66 6f 72 20 57 69 6e  se (e.g. for Win
1d40: 64 6f 77 73 20 58 50 29 2e 0a 2a 2f 0a 23 69 66  dows XP)..*/.#if
1d50: 20 21 64 65 66 69 6e 65 64 28 5f 55 53 45 5f 33   !defined(_USE_3
1d60: 32 42 49 54 5f 54 49 4d 45 5f 54 29 20 26 26 20  2BIT_TIME_T) && 
1d70: 21 64 65 66 69 6e 65 64 28 5f 55 53 45 5f 36 34  !defined(_USE_64
1d80: 42 49 54 5f 54 49 4d 45 5f 54 29 20 26 26 20 5c  BIT_TIME_T) && \
1d90: 0a 20 20 20 20 64 65 66 69 6e 65 64 28 5f 57 49  .    defined(_WI
1da0: 4e 33 32 29 20 26 26 20 21 64 65 66 69 6e 65 64  N32) && !defined
1db0: 28 5f 57 49 4e 36 34 29 20 26 26 20 5c 0a 20 20  (_WIN64) && \.  
1dc0: 20 20 64 65 66 69 6e 65 64 28 5f 5f 4d 49 4e 47    defined(__MING
1dd0: 57 5f 4d 41 4a 4f 52 5f 56 45 52 53 49 4f 4e 29  W_MAJOR_VERSION)
1de0: 20 26 26 20 5f 5f 4d 49 4e 47 57 5f 4d 41 4a 4f   && __MINGW_MAJO
1df0: 52 5f 56 45 52 53 49 4f 4e 20 3e 3d 20 34 20 26  R_VERSION >= 4 &
1e00: 26 20 5c 0a 20 20 20 20 64 65 66 69 6e 65 64 28  & \.    defined(
1e10: 5f 5f 4d 53 56 43 52 54 5f 5f 29 0a 23 20 64 65  __MSVCRT__).# de
1e20: 66 69 6e 65 20 5f 55 53 45 5f 33 32 42 49 54 5f  fine _USE_32BIT_
1e30: 54 49 4d 45 5f 54 0a 23 65 6e 64 69 66 0a 0a 2f  TIME_T.#endif../
1e40: 2a 20 54 68 65 20 70 75 62 6c 69 63 20 53 51 4c  * The public SQL
1e50: 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20  ite interface.  
1e60: 54 68 65 20 5f 46 49 4c 45 5f 4f 46 46 53 45 54  The _FILE_OFFSET
1e70: 5f 42 49 54 53 20 6d 61 63 72 6f 20 6d 75 73 74  _BITS macro must
1e80: 20 61 70 70 65 61 72 0a 2a 2a 20 66 69 72 73 74   appear.** first
1e90: 20 69 6e 20 51 4e 58 2e 20 20 41 6c 73 6f 2c 20   in QNX.  Also, 
1ea0: 74 68 65 20 5f 55 53 45 5f 33 32 42 49 54 5f 54  the _USE_32BIT_T
1eb0: 49 4d 45 5f 54 20 6d 61 63 72 6f 20 6d 75 73 74  IME_T macro must
1ec0: 20 61 70 70 65 61 72 20 66 69 72 73 74 20 66 6f   appear first fo
1ed0: 72 0a 2a 2a 20 4d 69 6e 47 57 2e 0a 2a 2f 0a 2f  r.** MinGW..*/./
1ee0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 49  ************** I
1ef0: 6e 63 6c 75 64 65 20 73 71 6c 69 74 65 33 2e 68  nclude sqlite3.h
1f00: 20 69 6e 20 74 68 65 20 6d 69 64 64 6c 65 20 6f   in the middle o
1f10: 66 20 73 71 6c 69 74 65 49 6e 74 2e 68 20 2a 2a  f sqliteInt.h **
1f20: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f  *************/./
1f30: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 42  ************** B
1f40: 65 67 69 6e 20 66 69 6c 65 20 73 71 6c 69 74 65  egin file sqlite
1f50: 33 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  3.h ************
1f60: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1f70: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f  *************/./
1f80: 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65 6d  *.** 2001 Septem
1f90: 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68 65  ber 15.**.** The
1fa0: 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69 6d   author disclaim
1fb0: 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20 74  s copyright to t
1fc0: 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65 2e  his source code.
1fd0: 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a    In place of.**
1fe0: 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65 2c   a legal notice,
1ff0: 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73 73   here is a bless
2000: 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d 61  ing:.**.**    Ma
2010: 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61 6e  y you do good an
2020: 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20 20  d not evil..**  
2030: 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20 66    May you find f
2040: 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20 79  orgiveness for y
2050: 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72 67  ourself and forg
2060: 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20 20  ive others..**  
2070: 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65 20    May you share 
2080: 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74 61  freely, never ta
2090: 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20 79  king more than y
20a0: 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a 2a  ou give..**.****
20b0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
20c0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
20d0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
20e0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
20f0: 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68 65  *****.** This he
2100: 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e 65  ader file define
2110: 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20  s the interface 
2120: 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65 20  that the SQLite 
2130: 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73 65  library.** prese
2140: 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70 72  nts to client pr
2150: 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43 2d  ograms.  If a C-
2160: 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63 74  function, struct
2170: 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a 2a  ure, datatype,.*
2180: 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64 65  * or constant de
2190: 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e 6f  finition does no
21a0: 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69 73  t appear in this
21b0: 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20 69   file, then it i
21c0: 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c 69  s.** not a publi
21d0: 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c 69  shed API of SQLi
21e0: 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20 74  te, is subject t
21f0: 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75 74  o change without
2200: 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64 20  .** notice, and 
2210: 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72 65  should not be re
2220: 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f 67  ferenced by prog
2230: 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53 51  rams that use SQ
2240: 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65  Lite..**.** Some
2250: 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74 69   of the definiti
2260: 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e 20  ons that are in 
2270: 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d 61  this file are ma
2280: 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70 65  rked as.** "expe
2290: 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70 65  rimental".  Expe
22a0: 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66 61  rimental interfa
22b0: 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c 79  ces are normally
22c0: 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65 73   new.** features
22d0: 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64 20   recently added 
22e0: 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20 64  to SQLite.  We d
22f0: 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74 65  o not anticipate
2300: 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20 65   changes.** to e
2310: 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65  xperimental inte
2320: 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65 72  rfaces but reser
2330: 76 65 20 74 68 65 20 72 69 67 68 74 20 74 6f 20  ve the right to 
2340: 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e 67  make minor chang
2350: 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69 65  es.** if experie
2360: 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69 6e  nce from use "in
2370: 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67 65   the wild" sugge
2380: 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73 20  st such changes 
2390: 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a 0a  are prudent..**.
23a0: 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c 20  ** The official 
23b0: 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20 64  C-language API d
23c0: 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72  ocumentation for
23d0: 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69 76   SQLite is deriv
23e0: 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d 65  ed.** from comme
23f0: 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c 65  nts in this file
2400: 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73 20  .  This file is 
2410: 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69 76  the authoritativ
2420: 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20 68  e source.** on h
2430: 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  ow SQLite interf
2440: 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73 65  aces are suppose
2450: 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a 2a 0a   to operate..**.
2460: 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 74  ** The name of t
2470: 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72 20 63  his file under c
2480: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 6e  onfiguration man
2490: 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71 6c 69  agement is "sqli
24a0: 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54 68 65  te.h.in"..** The
24b0: 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65 73 20   makefile makes 
24c0: 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61 6e 67  some minor chang
24d0: 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c 65 20  es to this file 
24e0: 28 73 75 63 68 20 61 73 20 69 6e 73 65 72 74 69  (such as inserti
24f0: 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73 69 6f  ng.** the versio
2500: 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20 63 68  n number) and ch
2510: 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65 20 74  anges its name t
2520: 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20 61 73  o "sqlite3.h" as
2530: 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68 65 20  .** part of the 
2540: 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e 0a 2a  build process..*
2550: 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c 49 54  /.#ifndef _SQLIT
2560: 45 33 5f 48 5f 0a 23 64 65 66 69 6e 65 20 5f 53  E3_H_.#define _S
2570: 51 4c 49 54 45 33 5f 48 5f 0a 23 69 6e 63 6c 75  QLITE3_H_.#inclu
2580: 64 65 20 3c 73 74 64 61 72 67 2e 68 3e 20 20 20  de <stdarg.h>   
2590: 20 20 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72 20    /* Needed for 
25a0: 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f  the definition o
25b0: 66 20 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f 2a  f va_list */../*
25c0: 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20 77 65  .** Make sure we
25d0: 20 63 61 6e 20 63 61 6c 6c 20 74 68 69 73 20 73   can call this s
25e0: 74 75 66 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a 2a  tuff from C++..*
25f0: 2f 0a 23 69 66 20 30 0a 65 78 74 65 72 6e 20 22  /.#if 0.extern "
2600: 43 22 20 7b 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a  C" {.#endif.../*
2610: 0a 2a 2a 20 50 72 6f 76 69 64 65 20 74 68 65 20  .** Provide the 
2620: 61 62 69 6c 69 74 79 20 74 6f 20 6f 76 65 72 72  ability to overr
2630: 69 64 65 20 6c 69 6e 6b 61 67 65 20 66 65 61 74  ide linkage feat
2640: 75 72 65 73 20 6f 66 20 74 68 65 20 69 6e 74 65  ures of the inte
2650: 72 66 61 63 65 2e 0a 2a 2f 0a 23 69 66 6e 64 65  rface..*/.#ifnde
2660: 66 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a  f SQLITE_EXTERN.
2670: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
2680: 45 58 54 45 52 4e 20 65 78 74 65 72 6e 0a 23 65  EXTERN extern.#e
2690: 6e 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c  ndif.#ifndef SQL
26a0: 49 54 45 5f 41 50 49 0a 23 20 64 65 66 69 6e 65  ITE_API.# define
26b0: 20 53 51 4c 49 54 45 5f 41 50 49 0a 23 65 6e 64   SQLITE_API.#end
26c0: 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54  if.#ifndef SQLIT
26d0: 45 5f 43 44 45 43 4c 0a 23 20 64 65 66 69 6e 65  E_CDECL.# define
26e0: 20 53 51 4c 49 54 45 5f 43 44 45 43 4c 0a 23 65   SQLITE_CDECL.#e
26f0: 6e 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c  ndif.#ifndef SQL
2700: 49 54 45 5f 53 54 44 43 41 4c 4c 0a 23 20 64 65  ITE_STDCALL.# de
2710: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 44 43  fine SQLITE_STDC
2720: 41 4c 4c 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a  ALL.#endif../*.*
2730: 2a 20 54 68 65 73 65 20 6e 6f 2d 6f 70 20 6d 61  * These no-op ma
2740: 63 72 6f 73 20 61 72 65 20 75 73 65 64 20 69 6e  cros are used in
2750: 20 66 72 6f 6e 74 20 6f 66 20 69 6e 74 65 72 66   front of interf
2760: 61 63 65 73 20 74 6f 20 6d 61 72 6b 20 74 68 6f  aces to mark tho
2770: 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  se.** interfaces
2780: 20 61 73 20 65 69 74 68 65 72 20 64 65 70 72 65   as either depre
2790: 63 61 74 65 64 20 6f 72 20 65 78 70 65 72 69 6d  cated or experim
27a0: 65 6e 74 61 6c 2e 20 20 4e 65 77 20 61 70 70 6c  ental.  New appl
27b0: 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75  ications.** shou
27c0: 6c 64 20 6e 6f 74 20 75 73 65 20 64 65 70 72 65  ld not use depre
27d0: 63 61 74 65 64 20 69 6e 74 65 72 66 61 63 65 73  cated interfaces
27e0: 20 2d 20 74 68 65 79 20 61 72 65 20 73 75 70 70   - they are supp
27f0: 6f 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77 61  orted for backwa
2800: 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69  rds.** compatibi
2810: 6c 69 74 79 20 6f 6e 6c 79 2e 20 20 41 70 70 6c  lity only.  Appl
2820: 69 63 61 74 69 6f 6e 20 77 72 69 74 65 72 73 20  ication writers 
2830: 73 68 6f 75 6c 64 20 62 65 20 61 77 61 72 65 20  should be aware 
2840: 74 68 61 74 0a 2a 2a 20 65 78 70 65 72 69 6d 65  that.** experime
2850: 6e 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20  ntal interfaces 
2860: 61 72 65 20 73 75 62 6a 65 63 74 20 74 6f 20 63  are subject to c
2870: 68 61 6e 67 65 20 69 6e 20 70 6f 69 6e 74 20 72  hange in point r
2880: 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  eleases..**.** T
2890: 68 65 73 65 20 6d 61 63 72 6f 73 20 75 73 65 64  hese macros used
28a0: 20 74 6f 20 72 65 73 6f 6c 76 65 20 74 6f 20 76   to resolve to v
28b0: 61 72 69 6f 75 73 20 6b 69 6e 64 73 20 6f 66 20  arious kinds of 
28c0: 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20 74  compiler magic t
28d0: 68 61 74 0a 2a 2a 20 77 6f 75 6c 64 20 67 65 6e  hat.** would gen
28e0: 65 72 61 74 65 20 77 61 72 6e 69 6e 67 20 6d 65  erate warning me
28f0: 73 73 61 67 65 73 20 77 68 65 6e 20 74 68 65 79  ssages when they
2900: 20 77 65 72 65 20 75 73 65 64 2e 20 20 42 75 74   were used.  But
2910: 20 74 68 61 74 0a 2a 2a 20 63 6f 6d 70 69 6c 65   that.** compile
2920: 72 20 6d 61 67 69 63 20 65 6e 64 65 64 20 75 70  r magic ended up
2930: 20 67 65 6e 65 72 61 74 69 6e 67 20 73 75 63 68   generating such
2940: 20 61 20 66 6c 75 72 72 79 20 6f 66 20 62 75 67   a flurry of bug
2950: 20 72 65 70 6f 72 74 73 0a 2a 2a 20 74 68 61 74   reports.** that
2960: 20 77 65 20 68 61 76 65 20 74 61 6b 65 6e 20 69   we have taken i
2970: 74 20 61 6c 6c 20 6f 75 74 20 61 6e 64 20 67 6f  t all out and go
2980: 6e 65 20 62 61 63 6b 20 74 6f 20 75 73 69 6e 67  ne back to using
2990: 20 73 69 6d 70 6c 65 0a 2a 2a 20 6e 6f 6f 70 20   simple.** noop 
29a0: 6d 61 63 72 6f 73 2e 0a 2a 2f 0a 23 64 65 66 69  macros..*/.#defi
29b0: 6e 65 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43  ne SQLITE_DEPREC
29c0: 41 54 45 44 0a 23 64 65 66 69 6e 65 20 53 51 4c  ATED.#define SQL
29d0: 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c  ITE_EXPERIMENTAL
29e0: 0a 0a 2f 2a 0a 2a 2a 20 45 6e 73 75 72 65 20 74  ../*.** Ensure t
29f0: 68 65 73 65 20 73 79 6d 62 6f 6c 73 20 77 65 72  hese symbols wer
2a00: 65 20 6e 6f 74 20 64 65 66 69 6e 65 64 20 62 79  e not defined by
2a10: 20 73 6f 6d 65 20 70 72 65 76 69 6f 75 73 20 68   some previous h
2a20: 65 61 64 65 72 20 66 69 6c 65 2e 0a 2a 2f 0a 23  eader file..*/.#
2a30: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52  ifdef SQLITE_VER
2a40: 53 49 4f 4e 0a 23 20 75 6e 64 65 66 20 53 51 4c  SION.# undef SQL
2a50: 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23 65 6e 64  ITE_VERSION.#end
2a60: 69 66 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45  if.#ifdef SQLITE
2a70: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a  _VERSION_NUMBER.
2a80: 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 56  # undef SQLITE_V
2a90: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23 65  ERSION_NUMBER.#e
2aa0: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
2ab0: 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69  3REF: Compile-Ti
2ac0: 6d 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69  me Library Versi
2ad0: 6f 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 0a 2a 2a  on Numbers.**.**
2ae0: 20 5e 28 54 68 65 20 5b 53 51 4c 49 54 45 5f 56   ^(The [SQLITE_V
2af0: 45 52 53 49 4f 4e 5d 20 43 20 70 72 65 70 72 6f  ERSION] C prepro
2b00: 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 69 6e 20  cessor macro in 
2b10: 74 68 65 20 73 71 6c 69 74 65 33 2e 68 20 68 65  the sqlite3.h he
2b20: 61 64 65 72 0a 2a 2a 20 65 76 61 6c 75 61 74 65  ader.** evaluate
2b30: 73 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69  s to a string li
2b40: 74 65 72 61 6c 20 74 68 61 74 20 69 73 20 74 68  teral that is th
2b50: 65 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  e SQLite version
2b60: 20 69 6e 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 61   in the.** forma
2b70: 74 20 22 58 2e 59 2e 5a 22 20 77 68 65 72 65 20  t "X.Y.Z" where 
2b80: 58 20 69 73 20 74 68 65 20 6d 61 6a 6f 72 20 76  X is the major v
2b90: 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 61  ersion number (a
2ba0: 6c 77 61 79 73 20 33 20 66 6f 72 0a 2a 2a 20 53  lways 3 for.** S
2bb0: 51 4c 69 74 65 33 29 20 61 6e 64 20 59 20 69 73  QLite3) and Y is
2bc0: 20 74 68 65 20 6d 69 6e 6f 72 20 76 65 72 73 69   the minor versi
2bd0: 6f 6e 20 6e 75 6d 62 65 72 20 61 6e 64 20 5a 20  on number and Z 
2be0: 69 73 20 74 68 65 20 72 65 6c 65 61 73 65 20 6e  is the release n
2bf0: 75 6d 62 65 72 2e 29 5e 0a 2a 2a 20 5e 28 54 68  umber.)^.** ^(Th
2c00: 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  e [SQLITE_VERSIO
2c10: 4e 5f 4e 55 4d 42 45 52 5d 20 43 20 70 72 65 70  N_NUMBER] C prep
2c20: 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 72  rocessor macro r
2c30: 65 73 6f 6c 76 65 73 20 74 6f 20 61 6e 20 69 6e  esolves to an in
2c40: 74 65 67 65 72 0a 2a 2a 20 77 69 74 68 20 74 68  teger.** with th
2c50: 65 20 76 61 6c 75 65 20 28 58 2a 31 30 30 30 30  e value (X*10000
2c60: 30 30 20 2b 20 59 2a 31 30 30 30 20 2b 20 5a 29  00 + Y*1000 + Z)
2c70: 20 77 68 65 72 65 20 58 2c 20 59 2c 20 61 6e 64   where X, Y, and
2c80: 20 5a 20 61 72 65 20 74 68 65 20 73 61 6d 65 0a   Z are the same.
2c90: 2a 2a 20 6e 75 6d 62 65 72 73 20 75 73 65 64 20  ** numbers used 
2ca0: 69 6e 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49  in [SQLITE_VERSI
2cb0: 4f 4e 5d 2e 29 5e 0a 2a 2a 20 54 68 65 20 53 51  ON].)^.** The SQ
2cc0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
2cd0: 42 45 52 20 66 6f 72 20 61 6e 79 20 67 69 76 65  BER for any give
2ce0: 6e 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c  n release of SQL
2cf0: 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f 0a 2a 2a  ite will also.**
2d00: 20 62 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20   be larger than 
2d10: 74 68 65 20 72 65 6c 65 61 73 65 20 66 72 6f 6d  the release from
2d20: 20 77 68 69 63 68 20 69 74 20 69 73 20 64 65 72   which it is der
2d30: 69 76 65 64 2e 20 20 45 69 74 68 65 72 20 59 20  ived.  Either Y 
2d40: 77 69 6c 6c 0a 2a 2a 20 62 65 20 68 65 6c 64 20  will.** be held 
2d50: 63 6f 6e 73 74 61 6e 74 20 61 6e 64 20 5a 20 77  constant and Z w
2d60: 69 6c 6c 20 62 65 20 69 6e 63 72 65 6d 65 6e 74  ill be increment
2d70: 65 64 20 6f 72 20 65 6c 73 65 20 59 20 77 69 6c  ed or else Y wil
2d80: 6c 20 62 65 20 69 6e 63 72 65 6d 65 6e 74 65 64  l be incremented
2d90: 0a 2a 2a 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62  .** and Z will b
2da0: 65 20 72 65 73 65 74 20 74 6f 20 7a 65 72 6f 2e  e reset to zero.
2db0: 0a 2a 2a 0a 2a 2a 20 53 69 6e 63 65 20 76 65 72  .**.** Since ver
2dc0: 73 69 6f 6e 20 33 2e 36 2e 31 38 2c 20 53 51 4c  sion 3.6.18, SQL
2dd0: 69 74 65 20 73 6f 75 72 63 65 20 63 6f 64 65 20  ite source code 
2de0: 68 61 73 20 62 65 65 6e 20 73 74 6f 72 65 64 20  has been stored 
2df0: 69 6e 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65  in the.** <a hre
2e00: 66 3d 22 68 74 74 70 3a 2f 2f 77 77 77 2e 66 6f  f="http://www.fo
2e10: 73 73 69 6c 2d 73 63 6d 2e 6f 72 67 2f 22 3e 46  ssil-scm.org/">F
2e20: 6f 73 73 69 6c 20 63 6f 6e 66 69 67 75 72 61 74  ossil configurat
2e30: 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 0a 2a  ion management.*
2e40: 2a 20 73 79 73 74 65 6d 3c 2f 61 3e 2e 20 20 5e  * system</a>.  ^
2e50: 54 68 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43  The SQLITE_SOURC
2e60: 45 5f 49 44 20 6d 61 63 72 6f 20 65 76 61 6c 75  E_ID macro evalu
2e70: 61 74 65 73 20 74 6f 0a 2a 2a 20 61 20 73 74 72  ates to.** a str
2e80: 69 6e 67 20 77 68 69 63 68 20 69 64 65 6e 74 69  ing which identi
2e90: 66 69 65 73 20 61 20 70 61 72 74 69 63 75 6c 61  fies a particula
2ea0: 72 20 63 68 65 63 6b 2d 69 6e 20 6f 66 20 53 51  r check-in of SQ
2eb0: 4c 69 74 65 0a 2a 2a 20 77 69 74 68 69 6e 20 69  Lite.** within i
2ec0: 74 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ts configuration
2ed0: 20 6d 61 6e 61 67 65 6d 65 6e 74 20 73 79 73 74   management syst
2ee0: 65 6d 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45  em.  ^The SQLITE
2ef0: 5f 53 4f 55 52 43 45 5f 49 44 0a 2a 2a 20 73 74  _SOURCE_ID.** st
2f00: 72 69 6e 67 20 63 6f 6e 74 61 69 6e 73 20 74 68  ring contains th
2f10: 65 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20  e date and time 
2f20: 6f 66 20 74 68 65 20 63 68 65 63 6b 2d 69 6e 20  of the check-in 
2f30: 28 55 54 43 29 20 61 6e 64 20 61 6e 20 53 48 41  (UTC) and an SHA
2f40: 31 0a 2a 2a 20 68 61 73 68 20 6f 66 20 74 68 65  1.** hash of the
2f50: 20 65 6e 74 69 72 65 20 73 6f 75 72 63 65 20 74   entire source t
2f60: 72 65 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ree..**.** See a
2f70: 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6c 69  lso: [sqlite3_li
2f80: 62 76 65 72 73 69 6f 6e 28 29 5d 2c 0a 2a 2a 20  bversion()],.** 
2f90: 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73  [sqlite3_libvers
2fa0: 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 5d 2c 20 5b  ion_number()], [
2fb0: 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64  sqlite3_sourceid
2fc0: 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f  ()],.** [sqlite_
2fd0: 76 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b  version()] and [
2fe0: 73 71 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64  sqlite_source_id
2ff0: 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ()]..*/.#define 
3000: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 20  SQLITE_VERSION  
3010: 20 20 20 20 20 20 22 33 2e 38 2e 39 22 0a 23 64        "3.8.9".#d
3020: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45 52  efine SQLITE_VER
3030: 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 33 30 30 38  SION_NUMBER 3008
3040: 30 30 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  009.#define SQLI
3050: 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 20 20 20  TE_SOURCE_ID    
3060: 20 20 22 32 30 31 35 2d 30 34 2d 30 38 20 31 32    "2015-04-08 12
3070: 3a 31 36 3a 33 33 20 38 61 38 66 66 63 38 36 32  :16:33 8a8ffc862
3080: 65 39 36 66 35 37 61 61 36 39 38 66 39 33 64 65  e96f57aa698f93de
3090: 31 30 64 65 65 32 38 65 36 39 66 36 65 30 39 22  10dee28e69f6e09"
30a0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
30b0: 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61  : Run-Time Libra
30c0: 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65  ry Version Numbe
30d0: 72 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  rs.** KEYWORDS: 
30e0: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 2c  sqlite3_version,
30f0: 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69   sqlite3_sourcei
3100: 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e  d.**.** These in
3110: 74 65 72 66 61 63 65 73 20 70 72 6f 76 69 64 65  terfaces provide
3120: 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d   the same inform
3130: 61 74 69 6f 6e 20 61 73 20 74 68 65 20 5b 53 51  ation as the [SQ
3140: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 2c 0a 2a  LITE_VERSION],.*
3150: 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  * [SQLITE_VERSIO
3160: 4e 5f 4e 55 4d 42 45 52 5d 2c 20 61 6e 64 20 5b  N_NUMBER], and [
3170: 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44  SQLITE_SOURCE_ID
3180: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
3190: 20 6d 61 63 72 6f 73 0a 2a 2a 20 62 75 74 20 61   macros.** but a
31a0: 72 65 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  re associated wi
31b0: 74 68 20 74 68 65 20 6c 69 62 72 61 72 79 20 69  th the library i
31c0: 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 68 65  nstead of the he
31d0: 61 64 65 72 20 66 69 6c 65 2e 20 20 5e 28 43 61  ader file.  ^(Ca
31e0: 75 74 69 6f 75 73 0a 2a 2a 20 70 72 6f 67 72 61  utious.** progra
31f0: 6d 6d 65 72 73 20 6d 69 67 68 74 20 69 6e 63 6c  mmers might incl
3200: 75 64 65 20 61 73 73 65 72 74 28 29 20 73 74 61  ude assert() sta
3210: 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 69 72  tements in their
3220: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 0a   application to.
3230: 2a 2a 20 76 65 72 69 66 79 20 74 68 61 74 20 76  ** verify that v
3240: 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62  alues returned b
3250: 79 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63  y these interfac
3260: 65 73 20 6d 61 74 63 68 20 74 68 65 20 6d 61 63  es match the mac
3270: 72 6f 73 20 69 6e 0a 2a 2a 20 74 68 65 20 68 65  ros in.** the he
3280: 61 64 65 72 2c 20 61 6e 64 20 74 68 75 73 20 69  ader, and thus i
3290: 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20 61  nsure that the a
32a0: 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 0a 2a 2a  pplication is.**
32b0: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6d   compiled with m
32c0: 61 74 63 68 69 6e 67 20 6c 69 62 72 61 72 79 20  atching library 
32d0: 61 6e 64 20 68 65 61 64 65 72 20 66 69 6c 65 73  and header files
32e0: 2e 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  ..**.** <blockqu
32f0: 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 61 73 73  ote><pre>.** ass
3300: 65 72 74 28 20 73 71 6c 69 74 65 33 5f 6c 69 62  ert( sqlite3_lib
3310: 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29  version_number()
3320: 3d 3d 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  ==SQLITE_VERSION
3330: 5f 4e 55 4d 42 45 52 20 29 3b 0a 2a 2a 20 61 73  _NUMBER );.** as
3340: 73 65 72 74 28 20 73 74 72 63 6d 70 28 73 71 6c  sert( strcmp(sql
3350: 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29 2c  ite3_sourceid(),
3360: 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44  SQLITE_SOURCE_ID
3370: 29 3d 3d 30 20 29 3b 0a 2a 2a 20 61 73 73 65 72  )==0 );.** asser
3380: 74 28 20 73 74 72 63 6d 70 28 73 71 6c 69 74 65  t( strcmp(sqlite
3390: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 2c 53  3_libversion(),S
33a0: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 29 3d 3d  QLITE_VERSION)==
33b0: 30 20 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  0 );.** </pre></
33c0: 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a  blockquote>)^.**
33d0: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
33e0: 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e  _version[] strin
33f0: 67 20 63 6f 6e 73 74 61 6e 74 20 63 6f 6e 74 61  g constant conta
3400: 69 6e 73 20 74 68 65 20 74 65 78 74 20 6f 66 20  ins the text of 
3410: 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d  [SQLITE_VERSION]
3420: 0a 2a 2a 20 6d 61 63 72 6f 2e 20 20 5e 54 68 65  .** macro.  ^The
3430: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
3440: 69 6f 6e 28 29 20 66 75 6e 63 74 69 6f 6e 20 72  ion() function r
3450: 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
3460: 20 74 6f 20 74 68 65 0a 2a 2a 20 74 6f 20 74 68   to the.** to th
3470: 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f  e sqlite3_versio
3480: 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74  n[] string const
3490: 61 6e 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65  ant.  The sqlite
34a0: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 0a 2a  3_libversion().*
34b0: 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 72  * function is pr
34c0: 6f 76 69 64 65 64 20 66 6f 72 20 75 73 65 20 69  ovided for use i
34d0: 6e 20 44 4c 4c 73 20 73 69 6e 63 65 20 44 4c 4c  n DLLs since DLL
34e0: 20 75 73 65 72 73 20 75 73 75 61 6c 6c 79 20 64   users usually d
34f0: 6f 20 6e 6f 74 20 68 61 76 65 0a 2a 2a 20 64 69  o not have.** di
3500: 72 65 63 74 20 61 63 63 65 73 73 20 74 6f 20 73  rect access to s
3510: 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 20  tring constants 
3520: 77 69 74 68 69 6e 20 74 68 65 20 44 4c 4c 2e 20  within the DLL. 
3530: 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33   ^The.** sqlite3
3540: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62  _libversion_numb
3550: 65 72 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65  er() function re
3560: 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72  turns an integer
3570: 20 65 71 75 61 6c 20 74 6f 0a 2a 2a 20 5b 53 51   equal to.** [SQ
3580: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
3590: 42 45 52 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69  BER].  ^The sqli
35a0: 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29 20 66  te3_sourceid() f
35b0: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
35c0: 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  .** a pointer to
35d0: 20 61 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61   a string consta
35e0: 6e 74 20 77 68 6f 73 65 20 76 61 6c 75 65 20 69  nt whose value i
35f0: 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 74 68  s the same as th
3600: 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 4f  e .** [SQLITE_SO
3610: 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72  URCE_ID] C prepr
3620: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 2e 0a 2a  ocessor macro..*
3630: 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
3640: 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28 29  sqlite_version()
3650: 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73 6f  ] and [sqlite_so
3660: 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a 53  urce_id()]..*/.S
3670: 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
3680: 63 68 61 72 20 73 71 6c 69 74 65 33 5f 76 65 72  char sqlite3_ver
3690: 73 69 6f 6e 5b 5d 20 3d 20 53 51 4c 49 54 45 5f  sion[] = SQLITE_
36a0: 56 45 52 53 49 4f 4e 3b 0a 53 51 4c 49 54 45 5f  VERSION;.SQLITE_
36b0: 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  API const char *
36c0: 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
36d0: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
36e0: 6e 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f  n(void);.SQLITE_
36f0: 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  API const char *
3700: 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
3710: 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28  qlite3_sourceid(
3720: 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50  void);.SQLITE_AP
3730: 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  I int SQLITE_STD
3740: 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6c 69 62  CALL sqlite3_lib
3750: 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 76  version_number(v
3760: 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  oid);../*.** CAP
3770: 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20  I3REF: Run-Time 
3780: 4c 69 62 72 61 72 79 20 43 6f 6d 70 69 6c 61 74  Library Compilat
3790: 69 6f 6e 20 4f 70 74 69 6f 6e 73 20 44 69 61 67  ion Options Diag
37a0: 6e 6f 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 5e 54  nostics.**.** ^T
37b0: 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69  he sqlite3_compi
37c0: 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 20  leoption_used() 
37d0: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
37e0: 20 30 20 6f 72 20 31 20 0a 2a 2a 20 69 6e 64 69   0 or 1 .** indi
37f0: 63 61 74 69 6e 67 20 77 68 65 74 68 65 72 20 74  cating whether t
3800: 68 65 20 73 70 65 63 69 66 69 65 64 20 6f 70 74  he specified opt
3810: 69 6f 6e 20 77 61 73 20 64 65 66 69 6e 65 64 20  ion was defined 
3820: 61 74 20 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74  at .** compile t
3830: 69 6d 65 2e 20 20 5e 54 68 65 20 53 51 4c 49 54  ime.  ^The SQLIT
3840: 45 5f 20 70 72 65 66 69 78 20 6d 61 79 20 62 65  E_ prefix may be
3850: 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68   omitted from th
3860: 65 20 0a 2a 2a 20 6f 70 74 69 6f 6e 20 6e 61 6d  e .** option nam
3870: 65 20 70 61 73 73 65 64 20 74 6f 20 73 71 6c 69  e passed to sqli
3880: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
3890: 6e 5f 75 73 65 64 28 29 2e 20 20 0a 2a 2a 0a 2a  n_used().  .**.*
38a0: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63  * ^The sqlite3_c
38b0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74  ompileoption_get
38c0: 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 6c 6c 6f  () function allo
38d0: 77 73 20 69 74 65 72 61 74 69 6e 67 0a 2a 2a 20  ws iterating.** 
38e0: 6f 76 65 72 20 74 68 65 20 6c 69 73 74 20 6f 66  over the list of
38f0: 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 77 65   options that we
3900: 72 65 20 64 65 66 69 6e 65 64 20 61 74 20 63 6f  re defined at co
3910: 6d 70 69 6c 65 20 74 69 6d 65 20 62 79 0a 2a 2a  mpile time by.**
3920: 20 72 65 74 75 72 6e 69 6e 67 20 74 68 65 20 4e   returning the N
3930: 2d 74 68 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65  -th compile time
3940: 20 6f 70 74 69 6f 6e 20 73 74 72 69 6e 67 2e 20   option string. 
3950: 20 5e 49 66 20 4e 20 69 73 20 6f 75 74 20 6f 66   ^If N is out of
3960: 20 72 61 6e 67 65 2c 0a 2a 2a 20 73 71 6c 69 74   range,.** sqlit
3970: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e  e3_compileoption
3980: 5f 67 65 74 28 29 20 72 65 74 75 72 6e 73 20 61  _get() returns a
3990: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20   NULL pointer.  
39a0: 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 0a 2a 2a  ^The SQLITE_ .**
39b0: 20 70 72 65 66 69 78 20 69 73 20 6f 6d 69 74 74   prefix is omitt
39c0: 65 64 20 66 72 6f 6d 20 61 6e 79 20 73 74 72 69  ed from any stri
39d0: 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ngs returned by 
39e0: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  .** sqlite3_comp
39f0: 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 2e  ileoption_get().
3a00: 0a 2a 2a 0a 2a 2a 20 5e 53 75 70 70 6f 72 74 20  .**.** ^Support 
3a10: 66 6f 72 20 74 68 65 20 64 69 61 67 6e 6f 73 74  for the diagnost
3a20: 69 63 20 66 75 6e 63 74 69 6f 6e 73 20 73 71 6c  ic functions sql
3a30: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
3a40: 6f 6e 5f 75 73 65 64 28 29 0a 2a 2a 20 61 6e 64  on_used().** and
3a50: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
3a60: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 6d 61 79  option_get() may
3a70: 20 62 65 20 6f 6d 69 74 74 65 64 20 62 79 20 73   be omitted by s
3a80: 70 65 63 69 66 79 69 6e 67 20 74 68 65 20 0a 2a  pecifying the .*
3a90: 2a 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43  * [SQLITE_OMIT_C
3aa0: 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41  OMPILEOPTION_DIA
3ab0: 47 53 5d 20 6f 70 74 69 6f 6e 20 61 74 20 63 6f  GS] option at co
3ac0: 6d 70 69 6c 65 20 74 69 6d 65 2e 0a 2a 2a 0a 2a  mpile time..**.*
3ad0: 2a 20 53 65 65 20 61 6c 73 6f 3a 20 53 51 4c 20  * See also: SQL 
3ae0: 66 75 6e 63 74 69 6f 6e 73 20 5b 73 71 6c 69 74  functions [sqlit
3af0: 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  e_compileoption_
3b00: 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b  used()] and.** [
3b10: 73 71 6c 69 74 65 5f 63 6f 6d 70 69 6c 65 6f 70  sqlite_compileop
3b20: 74 69 6f 6e 5f 67 65 74 28 29 5d 20 61 6e 64 20  tion_get()] and 
3b30: 74 68 65 20 5b 63 6f 6d 70 69 6c 65 5f 6f 70 74  the [compile_opt
3b40: 69 6f 6e 73 20 70 72 61 67 6d 61 5d 2e 0a 2a 2f  ions pragma]..*/
3b50: 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f  .#ifndef SQLITE_
3b60: 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45 4f 50 54 49  OMIT_COMPILEOPTI
3b70: 4f 4e 5f 44 49 41 47 53 0a 53 51 4c 49 54 45 5f  ON_DIAGS.SQLITE_
3b80: 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  API int SQLITE_S
3b90: 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63  TDCALL sqlite3_c
3ba0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
3bb0: 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4f  d(const char *zO
3bc0: 70 74 4e 61 6d 65 29 3b 0a 53 51 4c 49 54 45 5f  ptName);.SQLITE_
3bd0: 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  API const char *
3be0: 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
3bf0: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
3c00: 74 69 6f 6e 5f 67 65 74 28 69 6e 74 20 4e 29 3b  tion_get(int N);
3c10: 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43  .#endif../*.** C
3c20: 41 50 49 33 52 45 46 3a 20 54 65 73 74 20 54 6f  API3REF: Test To
3c30: 20 53 65 65 20 49 66 20 54 68 65 20 4c 69 62 72   See If The Libr
3c40: 61 72 79 20 49 73 20 54 68 72 65 61 64 73 61 66  ary Is Threadsaf
3c50: 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  e.**.** ^The sql
3c60: 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28  ite3_threadsafe(
3c70: 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  ) function retur
3c80: 6e 73 20 7a 65 72 6f 20 69 66 20 61 6e 64 20 6f  ns zero if and o
3c90: 6e 6c 79 20 69 66 0a 2a 2a 20 53 51 4c 69 74 65  nly if.** SQLite
3ca0: 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69   was compiled wi
3cb0: 74 68 20 6d 75 74 65 78 69 6e 67 20 63 6f 64 65  th mutexing code
3cc0: 20 6f 6d 69 74 74 65 64 20 64 75 65 20 74 6f 20   omitted due to 
3cd0: 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54  the.** [SQLITE_T
3ce0: 48 52 45 41 44 53 41 46 45 5d 20 63 6f 6d 70 69  HREADSAFE] compi
3cf0: 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 62  le-time option b
3d00: 65 69 6e 67 20 73 65 74 20 74 6f 20 30 2e 0a 2a  eing set to 0..*
3d10: 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 61 6e 20  *.** SQLite can 
3d20: 62 65 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  be compiled with
3d30: 20 6f 72 20 77 69 74 68 6f 75 74 20 6d 75 74 65   or without mute
3d40: 78 65 73 2e 20 20 57 68 65 6e 0a 2a 2a 20 74 68  xes.  When.** th
3d50: 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
3d60: 53 41 46 45 5d 20 43 20 70 72 65 70 72 6f 63 65  SAFE] C preproce
3d70: 73 73 6f 72 20 6d 61 63 72 6f 20 69 73 20 31 20  ssor macro is 1 
3d80: 6f 72 20 32 2c 20 6d 75 74 65 78 65 73 0a 2a 2a  or 2, mutexes.**
3d90: 20 61 72 65 20 65 6e 61 62 6c 65 64 20 61 6e 64   are enabled and
3da0: 20 53 51 4c 69 74 65 20 69 73 20 74 68 72 65 61   SQLite is threa
3db0: 64 73 61 66 65 2e 20 20 57 68 65 6e 20 74 68 65  dsafe.  When the
3dc0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  .** [SQLITE_THRE
3dd0: 41 44 53 41 46 45 5d 20 6d 61 63 72 6f 20 69 73  ADSAFE] macro is
3de0: 20 30 2c 20 0a 2a 2a 20 74 68 65 20 6d 75 74 65   0, .** the mute
3df0: 78 65 73 20 61 72 65 20 6f 6d 69 74 74 65 64 2e  xes are omitted.
3e00: 20 20 57 69 74 68 6f 75 74 20 74 68 65 20 6d 75    Without the mu
3e10: 74 65 78 65 73 2c 20 69 74 20 69 73 20 6e 6f 74  texes, it is not
3e20: 20 73 61 66 65 0a 2a 2a 20 74 6f 20 75 73 65 20   safe.** to use 
3e30: 53 51 4c 69 74 65 20 63 6f 6e 63 75 72 72 65 6e  SQLite concurren
3e40: 74 6c 79 20 66 72 6f 6d 20 6d 6f 72 65 20 74 68  tly from more th
3e50: 61 6e 20 6f 6e 65 20 74 68 72 65 61 64 2e 0a 2a  an one thread..*
3e60: 2a 0a 2a 2a 20 45 6e 61 62 6c 69 6e 67 20 6d 75  *.** Enabling mu
3e70: 74 65 78 65 73 20 69 6e 63 75 72 73 20 61 20 6d  texes incurs a m
3e80: 65 61 73 75 72 61 62 6c 65 20 70 65 72 66 6f 72  easurable perfor
3e90: 6d 61 6e 63 65 20 70 65 6e 61 6c 74 79 2e 0a 2a  mance penalty..*
3ea0: 2a 20 53 6f 20 69 66 20 73 70 65 65 64 20 69 73  * So if speed is
3eb0: 20 6f 66 20 75 74 6d 6f 73 74 20 69 6d 70 6f 72   of utmost impor
3ec0: 74 61 6e 63 65 2c 20 69 74 20 6d 61 6b 65 73 20  tance, it makes 
3ed0: 73 65 6e 73 65 20 74 6f 20 64 69 73 61 62 6c 65  sense to disable
3ee0: 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65 73 2e  .** the mutexes.
3ef0: 20 20 42 75 74 20 66 6f 72 20 6d 61 78 69 6d 75    But for maximu
3f00: 6d 20 73 61 66 65 74 79 2c 20 6d 75 74 65 78 65  m safety, mutexe
3f10: 73 20 73 68 6f 75 6c 64 20 62 65 20 65 6e 61 62  s should be enab
3f20: 6c 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66  led..** ^The def
3f30: 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69 73  ault behavior is
3f40: 20 66 6f 72 20 6d 75 74 65 78 65 73 20 74 6f 20   for mutexes to 
3f50: 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a  be enabled..**.*
3f60: 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65  * This interface
3f70: 20 63 61 6e 20 62 65 20 75 73 65 64 20 62 79 20   can be used by 
3f80: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74  an application t
3f90: 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74  o make sure that
3fa0: 20 74 68 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 20   the.** version 
3fb0: 6f 66 20 53 51 4c 69 74 65 20 74 68 61 74 20 69  of SQLite that i
3fc0: 74 20 69 73 20 6c 69 6e 6b 69 6e 67 20 61 67 61  t is linking aga
3fd0: 69 6e 73 74 20 77 61 73 20 63 6f 6d 70 69 6c 65  inst was compile
3fe0: 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 64 65  d with.** the de
3ff0: 73 69 72 65 64 20 73 65 74 74 69 6e 67 20 6f 66  sired setting of
4000: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
4010: 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f 2e 0a  EADSAFE] macro..
4020: 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72  **.** This inter
4030: 66 61 63 65 20 6f 6e 6c 79 20 72 65 70 6f 72 74  face only report
4040: 73 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65  s on the compile
4050: 2d 74 69 6d 65 20 6d 75 74 65 78 20 73 65 74 74  -time mutex sett
4060: 69 6e 67 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53  ing.** of the [S
4070: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
4080: 5d 20 66 6c 61 67 2e 20 20 49 66 20 53 51 4c 69  ] flag.  If SQLi
4090: 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
40a0: 69 74 68 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 48  ith.** SQLITE_TH
40b0: 52 45 41 44 53 41 46 45 3d 31 20 6f 72 20 3d 32  READSAFE=1 or =2
40c0: 20 74 68 65 6e 20 6d 75 74 65 78 65 73 20 61 72   then mutexes ar
40d0: 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66  e enabled by def
40e0: 61 75 6c 74 20 62 75 74 0a 2a 2a 20 63 61 6e 20  ault but.** can 
40f0: 62 65 20 66 75 6c 6c 79 20 6f 72 20 70 61 72 74  be fully or part
4100: 69 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 20 75  ially disabled u
4110: 73 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 5b  sing a call to [
4120: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
4130: 5d 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 76 65  ].** with the ve
4140: 72 62 73 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  rbs [SQLITE_CONF
4150: 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d  IG_SINGLETHREAD]
4160: 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  , [SQLITE_CONFIG
4170: 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 2c 0a 2a  _MULTITHREAD],.*
4180: 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  * or [SQLITE_CON
4190: 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 5d 2e  FIG_SERIALIZED].
41a0: 20 20 5e 28 54 68 65 20 72 65 74 75 72 6e 20 76    ^(The return v
41b0: 61 6c 75 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73  alue of the.** s
41c0: 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66  qlite3_threadsaf
41d0: 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f  e() function sho
41e0: 77 73 20 6f 6e 6c 79 20 74 68 65 20 63 6f 6d 70  ws only the comp
41f0: 69 6c 65 2d 74 69 6d 65 20 73 65 74 74 69 6e 67  ile-time setting
4200: 20 6f 66 0a 2a 2a 20 74 68 72 65 61 64 20 73 61   of.** thread sa
4210: 66 65 74 79 2c 20 6e 6f 74 20 61 6e 79 20 72 75  fety, not any ru
4220: 6e 2d 74 69 6d 65 20 63 68 61 6e 67 65 73 20 74  n-time changes t
4230: 6f 20 74 68 61 74 20 73 65 74 74 69 6e 67 20 6d  o that setting m
4240: 61 64 65 20 62 79 0a 2a 2a 20 73 71 6c 69 74 65  ade by.** sqlite
4250: 33 5f 63 6f 6e 66 69 67 28 29 2e 20 49 6e 20 6f  3_config(). In o
4260: 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20  ther words, the 
4270: 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f  return value fro
4280: 6d 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64  m sqlite3_thread
4290: 73 61 66 65 28 29 0a 2a 2a 20 69 73 20 75 6e 63  safe().** is unc
42a0: 68 61 6e 67 65 64 20 62 79 20 63 61 6c 6c 73 20  hanged by calls 
42b0: 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  to sqlite3_confi
42c0: 67 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65  g().)^.**.** See
42d0: 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20   the [threading 
42e0: 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 6e 74 61 74  mode] documentat
42f0: 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  ion for addition
4300: 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  al information..
4310: 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
4320: 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
4330: 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73   sqlite3_threads
4340: 61 66 65 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a  afe(void);../*.*
4350: 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61  * CAPI3REF: Data
4360: 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20  base Connection 
4370: 48 61 6e 64 6c 65 0a 2a 2a 20 4b 45 59 57 4f 52  Handle.** KEYWOR
4380: 44 53 3a 20 7b 64 61 74 61 62 61 73 65 20 63 6f  DS: {database co
4390: 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64 61 74 61 62  nnection} {datab
43a0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 7d  ase connections}
43b0: 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f 70 65 6e  .**.** Each open
43c0: 20 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65   SQLite database
43d0: 20 69 73 20 72 65 70 72 65 73 65 6e 74 65 64 20   is represented 
43e0: 62 79 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  by a pointer to 
43f0: 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 0a 2a  an instance of.*
4400: 2a 20 74 68 65 20 6f 70 61 71 75 65 20 73 74 72  * the opaque str
4410: 75 63 74 75 72 65 20 6e 61 6d 65 64 20 22 73 71  ucture named "sq
4420: 6c 69 74 65 33 22 2e 20 20 49 74 20 69 73 20 75  lite3".  It is u
4430: 73 65 66 75 6c 20 74 6f 20 74 68 69 6e 6b 20 6f  seful to think o
4440: 66 20 61 6e 20 73 71 6c 69 74 65 33 0a 2a 2a 20  f an sqlite3.** 
4450: 70 6f 69 6e 74 65 72 20 61 73 20 61 6e 20 6f 62  pointer as an ob
4460: 6a 65 63 74 2e 20 20 54 68 65 20 5b 73 71 6c 69  ject.  The [sqli
4470: 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
4480: 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c  lite3_open16()],
4490: 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
44a0: 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65  _open_v2()] inte
44b0: 72 66 61 63 65 73 20 61 72 65 20 69 74 73 20 63  rfaces are its c
44c0: 6f 6e 73 74 72 75 63 74 6f 72 73 2c 20 61 6e 64  onstructors, and
44d0: 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28   [sqlite3_close(
44e0: 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74  )].** and [sqlit
44f0: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 5d 20 61  e3_close_v2()] a
4500: 72 65 20 69 74 73 20 64 65 73 74 72 75 63 74 6f  re its destructo
4510: 72 73 2e 20 20 54 68 65 72 65 20 61 72 65 20 6d  rs.  There are m
4520: 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 69 6e 74  any other.** int
4530: 65 72 66 61 63 65 73 20 28 73 75 63 68 20 61 73  erfaces (such as
4540: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
4550: 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c  pare_v2()], [sql
4560: 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
4570: 74 69 6f 6e 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  tion()], and.** 
4580: 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69  [sqlite3_busy_ti
4590: 6d 65 6f 75 74 28 29 5d 20 74 6f 20 6e 61 6d 65  meout()] to name
45a0: 20 62 75 74 20 74 68 72 65 65 29 20 74 68 61 74   but three) that
45b0: 20 61 72 65 20 6d 65 74 68 6f 64 73 20 6f 6e 20   are methods on 
45c0: 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 20 6f 62  an.** sqlite3 ob
45d0: 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  ject..*/.typedef
45e0: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 20   struct sqlite3 
45f0: 73 71 6c 69 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a 20  sqlite3;../*.** 
4600: 43 41 50 49 33 52 45 46 3a 20 36 34 2d 42 69 74  CAPI3REF: 64-Bit
4610: 20 49 6e 74 65 67 65 72 20 54 79 70 65 73 0a 2a   Integer Types.*
4620: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69  * KEYWORDS: sqli
4630: 74 65 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f  te_int64 sqlite_
4640: 75 69 6e 74 36 34 0a 2a 2a 0a 2a 2a 20 42 65 63  uint64.**.** Bec
4650: 61 75 73 65 20 74 68 65 72 65 20 69 73 20 6e 6f  ause there is no
4660: 20 63 72 6f 73 73 2d 70 6c 61 74 66 6f 72 6d 20   cross-platform 
4670: 77 61 79 20 74 6f 20 73 70 65 63 69 66 79 20 36  way to specify 6
4680: 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 74 79  4-bit integer ty
4690: 70 65 73 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e  pes.** SQLite in
46a0: 63 6c 75 64 65 73 20 74 79 70 65 64 65 66 73 20  cludes typedefs 
46b0: 66 6f 72 20 36 34 2d 62 69 74 20 73 69 67 6e 65  for 64-bit signe
46c0: 64 20 61 6e 64 20 75 6e 73 69 67 6e 65 64 20 69  d and unsigned i
46d0: 6e 74 65 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54  ntegers..**.** T
46e0: 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  he sqlite3_int64
46f0: 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 75 69 6e   and sqlite3_uin
4700: 74 36 34 20 61 72 65 20 74 68 65 20 70 72 65 66  t64 are the pref
4710: 65 72 72 65 64 20 74 79 70 65 20 64 65 66 69 6e  erred type defin
4720: 69 74 69 6f 6e 73 2e 0a 2a 2a 20 54 68 65 20 73  itions..** The s
4730: 71 6c 69 74 65 5f 69 6e 74 36 34 20 61 6e 64 20  qlite_int64 and 
4740: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 74 79  sqlite_uint64 ty
4750: 70 65 73 20 61 72 65 20 73 75 70 70 6f 72 74 65  pes are supporte
4760: 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 0a  d for backwards.
4770: 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ** compatibility
4780: 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   only..**.** ^Th
4790: 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  e sqlite3_int64 
47a0: 61 6e 64 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  and sqlite_int64
47b0: 20 74 79 70 65 73 20 63 61 6e 20 73 74 6f 72 65   types can store
47c0: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 0a   integer values.
47d0: 2a 2a 20 62 65 74 77 65 65 6e 20 2d 39 32 32 33  ** between -9223
47e0: 33 37 32 30 33 36 38 35 34 37 37 35 38 30 38 20  372036854775808 
47f0: 61 6e 64 20 2b 39 32 32 33 33 37 32 30 33 36 38  and +92233720368
4800: 35 34 37 37 35 38 30 37 20 69 6e 63 6c 75 73 69  54775807 inclusi
4810: 76 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c  ve.  ^The.** sql
4820: 69 74 65 33 5f 75 69 6e 74 36 34 20 61 6e 64 20  ite3_uint64 and 
4830: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 74 79  sqlite_uint64 ty
4840: 70 65 73 20 63 61 6e 20 73 74 6f 72 65 20 69 6e  pes can store in
4850: 74 65 67 65 72 20 76 61 6c 75 65 73 20 0a 2a 2a  teger values .**
4860: 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 2b   between 0 and +
4870: 31 38 34 34 36 37 34 34 30 37 33 37 30 39 35 35  1844674407370955
4880: 31 36 31 35 20 69 6e 63 6c 75 73 69 76 65 2e 0a  1615 inclusive..
4890: 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45  */.#ifdef SQLITE
48a0: 5f 49 4e 54 36 34 5f 54 59 50 45 0a 20 20 74 79  _INT64_TYPE.  ty
48b0: 70 65 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54  pedef SQLITE_INT
48c0: 36 34 5f 54 59 50 45 20 73 71 6c 69 74 65 5f 69  64_TYPE sqlite_i
48d0: 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20  nt64;.  typedef 
48e0: 75 6e 73 69 67 6e 65 64 20 53 51 4c 49 54 45 5f  unsigned SQLITE_
48f0: 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74  INT64_TYPE sqlit
4900: 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 69 66 20  e_uint64;.#elif 
4910: 64 65 66 69 6e 65 64 28 5f 4d 53 43 5f 56 45 52  defined(_MSC_VER
4920: 29 20 7c 7c 20 64 65 66 69 6e 65 64 28 5f 5f 42  ) || defined(__B
4930: 4f 52 4c 41 4e 44 43 5f 5f 29 0a 20 20 74 79 70  ORLANDC__).  typ
4940: 65 64 65 66 20 5f 5f 69 6e 74 36 34 20 73 71 6c  edef __int64 sql
4950: 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70  ite_int64;.  typ
4960: 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 5f 5f  edef unsigned __
4970: 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69 6e  int64 sqlite_uin
4980: 74 36 34 3b 0a 23 65 6c 73 65 0a 20 20 74 79 70  t64;.#else.  typ
4990: 65 64 65 66 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69  edef long long i
49a0: 6e 74 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b  nt sqlite_int64;
49b0: 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67  .  typedef unsig
49c0: 6e 65 64 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e  ned long long in
49d0: 74 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b  t sqlite_uint64;
49e0: 0a 23 65 6e 64 69 66 0a 74 79 70 65 64 65 66 20  .#endif.typedef 
49f0: 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c  sqlite_int64 sql
4a00: 69 74 65 33 5f 69 6e 74 36 34 3b 0a 74 79 70 65  ite3_int64;.type
4a10: 64 65 66 20 73 71 6c 69 74 65 5f 75 69 6e 74 36  def sqlite_uint6
4a20: 34 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  4 sqlite3_uint64
4a30: 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66 20 63 6f 6d 70  ;../*.** If comp
4a40: 69 6c 69 6e 67 20 66 6f 72 20 61 20 70 72 6f 63  iling for a proc
4a50: 65 73 73 6f 72 20 74 68 61 74 20 6c 61 63 6b 73  essor that lacks
4a60: 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
4a70: 73 75 70 70 6f 72 74 2c 0a 2a 2a 20 73 75 62 73  support,.** subs
4a80: 74 69 74 75 74 65 20 69 6e 74 65 67 65 72 20 66  titute integer f
4a90: 6f 72 20 66 6c 6f 61 74 69 6e 67 2d 70 6f 69 6e  or floating-poin
4aa0: 74 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c  t..*/.#ifdef SQL
4ab0: 49 54 45 5f 4f 4d 49 54 5f 46 4c 4f 41 54 49 4e  ITE_OMIT_FLOATIN
4ac0: 47 5f 50 4f 49 4e 54 0a 23 20 64 65 66 69 6e 65  G_POINT.# define
4ad0: 20 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f   double sqlite3_
4ae0: 69 6e 74 36 34 0a 23 65 6e 64 69 66 0a 0a 2f 2a  int64.#endif../*
4af0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6c  .** CAPI3REF: Cl
4b00: 6f 73 69 6e 67 20 41 20 44 61 74 61 62 61 73 65  osing A Database
4b10: 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a   Connection.**.*
4b20: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63  * ^The sqlite3_c
4b30: 6c 6f 73 65 28 29 20 61 6e 64 20 73 71 6c 69 74  lose() and sqlit
4b40: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72 6f  e3_close_v2() ro
4b50: 75 74 69 6e 65 73 20 61 72 65 20 64 65 73 74 72  utines are destr
4b60: 75 63 74 6f 72 73 0a 2a 2a 20 66 6f 72 20 74 68  uctors.** for th
4b70: 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65  e [sqlite3] obje
4b80: 63 74 2e 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f  ct..** ^Calls to
4b90: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29   sqlite3_close()
4ba0: 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f   and sqlite3_clo
4bb0: 73 65 5f 76 32 28 29 20 72 65 74 75 72 6e 20 5b  se_v2() return [
4bc0: 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 0a 2a 2a  SQLITE_OK] if.**
4bd0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f   the [sqlite3] o
4be0: 62 6a 65 63 74 20 69 73 20 73 75 63 63 65 73 73  bject is success
4bf0: 66 75 6c 6c 79 20 64 65 73 74 72 6f 79 65 64 20  fully destroyed 
4c00: 61 6e 64 20 61 6c 6c 20 61 73 73 6f 63 69 61 74  and all associat
4c10: 65 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 73 20  ed.** resources 
4c20: 61 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e  are deallocated.
4c30: 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64  .**.** ^If the d
4c40: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
4c50: 6f 6e 20 69 73 20 61 73 73 6f 63 69 61 74 65 64  on is associated
4c60: 20 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a 65   with unfinalize
4c70: 64 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74  d prepared.** st
4c80: 61 74 65 6d 65 6e 74 73 20 6f 72 20 75 6e 66 69  atements or unfi
4c90: 6e 69 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62  nished sqlite3_b
4ca0: 61 63 6b 75 70 20 6f 62 6a 65 63 74 73 20 74 68  ackup objects th
4cb0: 65 6e 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  en sqlite3_close
4cc0: 28 29 0a 2a 2a 20 77 69 6c 6c 20 6c 65 61 76 65  ().** will leave
4cd0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
4ce0: 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 20 61 6e  nnection open an
4cf0: 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  d return [SQLITE
4d00: 5f 42 55 53 59 5d 2e 0a 2a 2a 20 5e 49 66 20 73  _BUSY]..** ^If s
4d10: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28  qlite3_close_v2(
4d20: 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68  ) is called with
4d30: 20 75 6e 66 69 6e 61 6c 69 7a 65 64 20 70 72 65   unfinalized pre
4d40: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
4d50: 0a 2a 2a 20 61 6e 64 2f 6f 72 20 75 6e 66 69 6e  .** and/or unfin
4d60: 69 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62 61  ished sqlite3_ba
4d70: 63 6b 75 70 73 2c 20 74 68 65 6e 20 74 68 65 20  ckups, then the 
4d80: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
4d90: 69 6f 6e 20 62 65 63 6f 6d 65 73 0a 2a 2a 20 61  ion becomes.** a
4da0: 6e 20 75 6e 75 73 61 62 6c 65 20 22 7a 6f 6d 62  n unusable "zomb
4db0: 69 65 22 20 77 68 69 63 68 20 77 69 6c 6c 20 61  ie" which will a
4dc0: 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 65 20  utomatically be 
4dd0: 64 65 61 6c 6c 6f 63 61 74 65 64 20 77 68 65 6e  deallocated when
4de0: 20 74 68 65 0a 2a 2a 20 6c 61 73 74 20 70 72 65   the.** last pre
4df0: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
4e00: 69 73 20 66 69 6e 61 6c 69 7a 65 64 20 6f 72 20  is finalized or 
4e10: 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33  the last sqlite3
4e20: 5f 62 61 63 6b 75 70 20 69 73 0a 2a 2a 20 66 69  _backup is.** fi
4e30: 6e 69 73 68 65 64 2e 20 20 54 68 65 20 73 71 6c  nished.  The sql
4e40: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20  ite3_close_v2() 
4e50: 69 6e 74 65 72 66 61 63 65 20 69 73 20 69 6e 74  interface is int
4e60: 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 77 69  ended for use wi
4e70: 74 68 0a 2a 2a 20 68 6f 73 74 20 6c 61 6e 67 75  th.** host langu
4e80: 61 67 65 73 20 74 68 61 74 20 61 72 65 20 67 61  ages that are ga
4e90: 72 62 61 67 65 20 63 6f 6c 6c 65 63 74 65 64 2c  rbage collected,
4ea0: 20 61 6e 64 20 77 68 65 72 65 20 74 68 65 20 6f   and where the o
4eb0: 72 64 65 72 20 69 6e 20 77 68 69 63 68 0a 2a 2a  rder in which.**
4ec0: 20 64 65 73 74 72 75 63 74 6f 72 73 20 61 72 65   destructors are
4ed0: 20 63 61 6c 6c 65 64 20 69 73 20 61 72 62 69 74   called is arbit
4ee0: 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c  rary..**.** Appl
4ef0: 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20  ications should 
4f00: 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
4f10: 65 20 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c  e | finalize] al
4f20: 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  l [prepared stat
4f30: 65 6d 65 6e 74 73 5d 2c 0a 2a 2a 20 5b 73 71 6c  ements],.** [sql
4f40: 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20  ite3_blob_close 
4f50: 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c  | close] all [BL
4f60: 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64  OB handles], and
4f70: 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61   .** [sqlite3_ba
4f80: 63 6b 75 70 5f 66 69 6e 69 73 68 20 7c 20 66 69  ckup_finish | fi
4f90: 6e 69 73 68 5d 20 61 6c 6c 20 5b 73 71 6c 69 74  nish] all [sqlit
4fa0: 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63  e3_backup] objec
4fb0: 74 73 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a  ts associated.**
4fc0: 20 77 69 74 68 20 74 68 65 20 5b 73 71 6c 69 74   with the [sqlit
4fd0: 65 33 5d 20 6f 62 6a 65 63 74 20 70 72 69 6f 72  e3] object prior
4fe0: 20 74 6f 20 61 74 74 65 6d 70 74 69 6e 67 20 74   to attempting t
4ff0: 6f 20 63 6c 6f 73 65 20 74 68 65 20 6f 62 6a 65  o close the obje
5000: 63 74 2e 20 20 5e 49 66 0a 2a 2a 20 73 71 6c 69  ct.  ^If.** sqli
5010: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69  te3_close_v2() i
5020: 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 64  s called on a [d
5030: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
5040: 6f 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c 20 68  on] that still h
5050: 61 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64 69 6e  as.** outstandin
5060: 67 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  g [prepared stat
5070: 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68  ements], [BLOB h
5080: 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 2f 6f 72 0a  andles], and/or.
5090: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b  ** [sqlite3_back
50a0: 75 70 5d 20 6f 62 6a 65 63 74 73 20 74 68 65 6e  up] objects then
50b0: 20 69 74 20 72 65 74 75 72 6e 73 20 5b 53 51 4c   it returns [SQL
50c0: 49 54 45 5f 4f 4b 5d 20 61 6e 64 20 74 68 65 20  ITE_OK] and the 
50d0: 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  deallocation.** 
50e0: 6f 66 20 72 65 73 6f 75 72 63 65 73 20 69 73 20  of resources is 
50f0: 64 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61  deferred until a
5100: 6c 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ll [prepared sta
5110: 74 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20  tements], [BLOB 
5120: 68 61 6e 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e 64  handles],.** and
5130: 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70   [sqlite3_backup
5140: 5d 20 6f 62 6a 65 63 74 73 20 61 72 65 20 61 6c  ] objects are al
5150: 73 6f 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a  so destroyed..**
5160: 0a 2a 2a 20 5e 49 66 20 61 6e 20 5b 73 71 6c 69  .** ^If an [sqli
5170: 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 64  te3] object is d
5180: 65 73 74 72 6f 79 65 64 20 77 68 69 6c 65 20 61  estroyed while a
5190: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20   transaction is 
51a0: 6f 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61  open,.** the tra
51b0: 6e 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f  nsaction is auto
51c0: 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64  matically rolled
51d0: 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   back..**.** The
51e0: 20 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20   C parameter to 
51f0: 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43  [sqlite3_close(C
5200: 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
5210: 63 6c 6f 73 65 5f 76 32 28 43 29 5d 0a 2a 2a 20  close_v2(C)].** 
5220: 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61  must be either a
5230: 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72   NULL.** pointer
5240: 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d   or an [sqlite3]
5250: 20 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20   object pointer 
5260: 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d  obtained.** from
5270: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
5280: 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
5290: 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71  16()], or.** [sq
52a0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
52b0: 2c 20 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f  , and not previo
52c0: 75 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20  usly closed..** 
52d0: 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33  ^Calling sqlite3
52e0: 5f 63 6c 6f 73 65 28 29 20 6f 72 20 73 71 6c 69  _close() or sqli
52f0: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 77  te3_close_v2() w
5300: 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ith a NULL point
5310: 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69  er.** argument i
5320: 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d  s a harmless no-
5330: 6f 70 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  op..*/.SQLITE_AP
5340: 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  I int SQLITE_STD
5350: 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6c 6f  CALL sqlite3_clo
5360: 73 65 28 73 71 6c 69 74 65 33 2a 29 3b 0a 53 51  se(sqlite3*);.SQ
5370: 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c  LITE_API int SQL
5380: 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
5390: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 73 71 6c  te3_close_v2(sql
53a0: 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54  ite3*);../*.** T
53b0: 68 65 20 74 79 70 65 20 66 6f 72 20 61 20 63 61  he type for a ca
53c0: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 2e  llback function.
53d0: 0a 2a 2a 20 54 68 69 73 20 69 73 20 6c 65 67 61  .** This is lega
53e0: 63 79 20 61 6e 64 20 64 65 70 72 65 63 61 74 65  cy and deprecate
53f0: 64 2e 20 20 49 74 20 69 73 20 69 6e 63 6c 75 64  d.  It is includ
5400: 65 64 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61  ed for historica
5410: 6c 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69  l.** compatibili
5420: 74 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 64 6f  ty and is not do
5430: 63 75 6d 65 6e 74 65 64 2e 0a 2a 2f 0a 74 79 70  cumented..*/.typ
5440: 65 64 65 66 20 69 6e 74 20 28 2a 73 71 6c 69 74  edef int (*sqlit
5450: 65 33 5f 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69  e3_callback)(voi
5460: 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 20 63  d*,int,char**, c
5470: 68 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  har**);../*.** C
5480: 41 50 49 33 52 45 46 3a 20 4f 6e 65 2d 53 74 65  API3REF: One-Ste
5490: 70 20 51 75 65 72 79 20 45 78 65 63 75 74 69 6f  p Query Executio
54a0: 6e 20 49 6e 74 65 72 66 61 63 65 0a 2a 2a 0a 2a  n Interface.**.*
54b0: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78  * The sqlite3_ex
54c0: 65 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  ec() interface i
54d0: 73 20 61 20 63 6f 6e 76 65 6e 69 65 6e 63 65 20  s a convenience 
54e0: 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a  wrapper around.*
54f0: 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
5500: 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74  re_v2()], [sqlit
5510: 65 33 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64 20  e3_step()], and 
5520: 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
5530: 65 28 29 5d 2c 0a 2a 2a 20 74 68 61 74 20 61 6c  e()],.** that al
5540: 6c 6f 77 73 20 61 6e 20 61 70 70 6c 69 63 61 74  lows an applicat
5550: 69 6f 6e 20 74 6f 20 72 75 6e 20 6d 75 6c 74 69  ion to run multi
5560: 70 6c 65 20 73 74 61 74 65 6d 65 6e 74 73 20 6f  ple statements o
5570: 66 20 53 51 4c 0a 2a 2a 20 77 69 74 68 6f 75 74  f SQL.** without
5580: 20 68 61 76 69 6e 67 20 74 6f 20 75 73 65 20 61   having to use a
5590: 20 6c 6f 74 20 6f 66 20 43 20 63 6f 64 65 2e 20   lot of C code. 
55a0: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
55b0: 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72  te3_exec() inter
55c0: 66 61 63 65 20 72 75 6e 73 20 7a 65 72 6f 20 6f  face runs zero o
55d0: 72 20 6d 6f 72 65 20 55 54 46 2d 38 20 65 6e 63  r more UTF-8 enc
55e0: 6f 64 65 64 2c 0a 2a 2a 20 73 65 6d 69 63 6f 6c  oded,.** semicol
55f0: 6f 6e 2d 73 65 70 61 72 61 74 65 20 53 51 4c 20  on-separate SQL 
5600: 73 74 61 74 65 6d 65 6e 74 73 20 70 61 73 73 65  statements passe
5610: 64 20 69 6e 74 6f 20 69 74 73 20 32 6e 64 20 61  d into its 2nd a
5620: 72 67 75 6d 65 6e 74 2c 0a 2a 2a 20 69 6e 20 74  rgument,.** in t
5630: 68 65 20 63 6f 6e 74 65 78 74 20 6f 66 20 74 68  he context of th
5640: 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
5650: 65 63 74 69 6f 6e 5d 20 70 61 73 73 65 64 20 69  ection] passed i
5660: 6e 20 61 73 20 69 74 73 20 31 73 74 0a 2a 2a 20  n as its 1st.** 
5670: 61 72 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20 74  argument.  ^If t
5680: 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  he callback func
5690: 74 69 6f 6e 20 6f 66 20 74 68 65 20 33 72 64 20  tion of the 3rd 
56a0: 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73  argument to.** s
56b0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73  qlite3_exec() is
56c0: 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20   not NULL, then 
56d0: 69 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 66 6f  it is invoked fo
56e0: 72 20 65 61 63 68 20 72 65 73 75 6c 74 20 72 6f  r each result ro
56f0: 77 0a 2a 2a 20 63 6f 6d 69 6e 67 20 6f 75 74 20  w.** coming out 
5700: 6f 66 20 74 68 65 20 65 76 61 6c 75 61 74 65 64  of the evaluated
5710: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e   SQL statements.
5720: 20 20 5e 54 68 65 20 34 74 68 20 61 72 67 75 6d    ^The 4th argum
5730: 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  ent to.** sqlite
5740: 33 5f 65 78 65 63 28 29 20 69 73 20 72 65 6c 61  3_exec() is rela
5750: 79 65 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74  yed through to t
5760: 68 65 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20  he 1st argument 
5770: 6f 66 20 65 61 63 68 0a 2a 2a 20 63 61 6c 6c 62  of each.** callb
5780: 61 63 6b 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 20  ack invocation. 
5790: 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63   ^If the callbac
57a0: 6b 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c  k pointer to sql
57b0: 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69  ite3_exec().** i
57c0: 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f 20  s NULL, then no 
57d0: 63 61 6c 6c 62 61 63 6b 20 69 73 20 65 76 65 72  callback is ever
57e0: 20 69 6e 76 6f 6b 65 64 20 61 6e 64 20 72 65 73   invoked and res
57f0: 75 6c 74 20 72 6f 77 73 20 61 72 65 0a 2a 2a 20  ult rows are.** 
5800: 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  ignored..**.** ^
5810: 49 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75  If an error occu
5820: 72 73 20 77 68 69 6c 65 20 65 76 61 6c 75 61 74  rs while evaluat
5830: 69 6e 67 20 74 68 65 20 53 51 4c 20 73 74 61 74  ing the SQL stat
5840: 65 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e  ements passed in
5850: 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78  to.** sqlite3_ex
5860: 65 63 28 29 2c 20 74 68 65 6e 20 65 78 65 63 75  ec(), then execu
5870: 74 69 6f 6e 20 6f 66 20 74 68 65 20 63 75 72 72  tion of the curr
5880: 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 20 73 74  ent statement st
5890: 6f 70 73 20 61 6e 64 0a 2a 2a 20 73 75 62 73 65  ops and.** subse
58a0: 71 75 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 73  quent statements
58b0: 20 61 72 65 20 73 6b 69 70 70 65 64 2e 20 20 5e   are skipped.  ^
58c0: 49 66 20 74 68 65 20 35 74 68 20 70 61 72 61 6d  If the 5th param
58d0: 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
58e0: 65 78 65 63 28 29 0a 2a 2a 20 69 73 20 6e 6f 74  exec().** is not
58f0: 20 4e 55 4c 4c 20 74 68 65 6e 20 61 6e 79 20 65   NULL then any e
5900: 72 72 6f 72 20 6d 65 73 73 61 67 65 20 69 73 20  rror message is 
5910: 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d  written into mem
5920: 6f 72 79 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20  ory obtained.** 
5930: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
5940: 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 70 61 73 73  lloc()] and pass
5950: 65 64 20 62 61 63 6b 20 74 68 72 6f 75 67 68 20  ed back through 
5960: 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  the 5th paramete
5970: 72 2e 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20 6d  r..** To avoid m
5980: 65 6d 6f 72 79 20 6c 65 61 6b 73 2c 20 74 68 65  emory leaks, the
5990: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f   application sho
59a0: 75 6c 64 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69  uld invoke [sqli
59b0: 74 65 33 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 6f  te3_free()].** o
59c0: 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  n error message 
59d0: 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64  strings returned
59e0: 20 74 68 72 6f 75 67 68 20 74 68 65 20 35 74 68   through the 5th
59f0: 20 70 61 72 61 6d 65 74 65 72 20 6f 66 0a 2a 2a   parameter of.**
5a00: 20 6f 66 20 73 71 6c 69 74 65 33 5f 65 78 65 63   of sqlite3_exec
5a10: 28 29 20 61 66 74 65 72 20 74 68 65 20 65 72 72  () after the err
5a20: 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e  or message strin
5a30: 67 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e  g is no longer n
5a40: 65 65 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68  eeded..** ^If th
5a50: 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 5th parameter 
5a60: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
5a70: 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e  ) is not NULL an
5a80: 64 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f  d no errors.** o
5a90: 63 63 75 72 2c 20 74 68 65 6e 20 73 71 6c 69 74  ccur, then sqlit
5aa0: 65 33 5f 65 78 65 63 28 29 20 73 65 74 73 20 74  e3_exec() sets t
5ab0: 68 65 20 70 6f 69 6e 74 65 72 20 69 6e 20 69 74  he pointer in it
5ac0: 73 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20  s 5th parameter 
5ad0: 74 6f 0a 2a 2a 20 4e 55 4c 4c 20 62 65 66 6f 72  to.** NULL befor
5ae0: 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a  e returning..**.
5af0: 2a 2a 20 5e 49 66 20 61 6e 20 73 71 6c 69 74 65  ** ^If an sqlite
5b00: 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63  3_exec() callbac
5b10: 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65  k returns non-ze
5b20: 72 6f 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ro, the sqlite3_
5b30: 65 78 65 63 28 29 0a 2a 2a 20 72 6f 75 74 69 6e  exec().** routin
5b40: 65 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45  e returns SQLITE
5b50: 5f 41 42 4f 52 54 20 77 69 74 68 6f 75 74 20 69  _ABORT without i
5b60: 6e 76 6f 6b 69 6e 67 20 74 68 65 20 63 61 6c 6c  nvoking the call
5b70: 62 61 63 6b 20 61 67 61 69 6e 20 61 6e 64 0a 2a  back again and.*
5b80: 2a 20 77 69 74 68 6f 75 74 20 72 75 6e 6e 69 6e  * without runnin
5b90: 67 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e 74  g any subsequent
5ba0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e   SQL statements.
5bb0: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 32 6e 64 20  .**.** ^The 2nd 
5bc0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
5bd0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63  sqlite3_exec() c
5be0: 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
5bf0: 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65   is the.** numbe
5c00: 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
5c10: 74 68 65 20 72 65 73 75 6c 74 2e 20 20 5e 54 68  the result.  ^Th
5c20: 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74  e 3rd argument t
5c30: 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78  o the sqlite3_ex
5c40: 65 63 28 29 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  ec().** callback
5c50: 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20   is an array of 
5c60: 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69  pointers to stri
5c70: 6e 67 73 20 6f 62 74 61 69 6e 65 64 20 61 73 20  ngs obtained as 
5c80: 69 66 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69  if from.** [sqli
5c90: 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
5ca0: 29 5d 2c 20 6f 6e 65 20 66 6f 72 20 65 61 63 68  )], one for each
5cb0: 20 63 6f 6c 75 6d 6e 2e 20 20 5e 49 66 20 61 6e   column.  ^If an
5cc0: 20 65 6c 65 6d 65 6e 74 20 6f 66 20 61 0a 2a 2a   element of a.**
5cd0: 20 72 65 73 75 6c 74 20 72 6f 77 20 69 73 20 4e   result row is N
5ce0: 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 63 6f 72  ULL then the cor
5cf0: 72 65 73 70 6f 6e 64 69 6e 67 20 73 74 72 69 6e  responding strin
5d00: 67 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68  g pointer for th
5d10: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65  e.** sqlite3_exe
5d20: 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  c() callback is 
5d30: 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20  a NULL pointer. 
5d40: 20 5e 54 68 65 20 34 74 68 20 61 72 67 75 6d 65   ^The 4th argume
5d50: 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 73 71 6c  nt to the.** sql
5d60: 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c  ite3_exec() call
5d70: 62 61 63 6b 20 69 73 20 61 6e 20 61 72 72 61 79  back is an array
5d80: 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20   of pointers to 
5d90: 73 74 72 69 6e 67 73 20 77 68 65 72 65 20 65 61  strings where ea
5da0: 63 68 0a 2a 2a 20 65 6e 74 72 79 20 72 65 70 72  ch.** entry repr
5db0: 65 73 65 6e 74 73 20 74 68 65 20 6e 61 6d 65 20  esents the name 
5dc0: 6f 66 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  of corresponding
5dd0: 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 61   result column a
5de0: 73 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72  s obtained.** fr
5df0: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  om [sqlite3_colu
5e00: 6d 6e 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a  mn_name()]..**.*
5e10: 2a 20 5e 49 66 20 74 68 65 20 32 6e 64 20 70 61  * ^If the 2nd pa
5e20: 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
5e30: 65 33 5f 65 78 65 63 28 29 20 69 73 20 61 20 4e  e3_exec() is a N
5e40: 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 61 20 70  ULL pointer, a p
5e50: 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 61 6e 20  ointer.** to an 
5e60: 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 6f 72  empty string, or
5e70: 20 61 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20   a pointer that 
5e80: 63 6f 6e 74 61 69 6e 73 20 6f 6e 6c 79 20 77 68  contains only wh
5e90: 69 74 65 73 70 61 63 65 20 61 6e 64 2f 6f 72 20  itespace and/or 
5ea0: 0a 2a 2a 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 73  .** SQL comments
5eb0: 2c 20 74 68 65 6e 20 6e 6f 20 53 51 4c 20 73 74  , then no SQL st
5ec0: 61 74 65 6d 65 6e 74 73 20 61 72 65 20 65 76 61  atements are eva
5ed0: 6c 75 61 74 65 64 20 61 6e 64 20 74 68 65 20 64  luated and the d
5ee0: 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 6e 6f  atabase.** is no
5ef0: 74 20 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a  t changed..**.**
5f00: 20 52 65 73 74 72 69 63 74 69 6f 6e 73 3a 0a 2a   Restrictions:.*
5f10: 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
5f20: 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  > The applicatio
5f30: 6e 20 6d 75 73 74 20 69 6e 73 75 72 65 20 74 68  n must insure th
5f40: 61 74 20 74 68 65 20 31 73 74 20 70 61 72 61 6d  at the 1st param
5f50: 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
5f60: 65 78 65 63 28 29 0a 2a 2a 20 20 20 20 20 20 69  exec().**      i
5f70: 73 20 61 20 76 61 6c 69 64 20 61 6e 64 20 6f 70  s a valid and op
5f80: 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  en [database con
5f90: 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69  nection]..** <li
5fa0: 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  > The applicatio
5fb0: 6e 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65  n must not close
5fc0: 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
5fd0: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69  onnection] speci
5fe0: 66 69 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20  fied by.**      
5ff0: 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 65  the 1st paramete
6000: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65  r to sqlite3_exe
6010: 63 28 29 20 77 68 69 6c 65 20 73 71 6c 69 74 65  c() while sqlite
6020: 33 5f 65 78 65 63 28 29 20 69 73 20 72 75 6e 6e  3_exec() is runn
6030: 69 6e 67 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  ing..** <li> The
6040: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
6050: 74 20 6e 6f 74 20 6d 6f 64 69 66 79 20 74 68 65  t not modify the
6060: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
6070: 65 78 74 20 70 61 73 73 65 64 20 69 6e 74 6f 0a  ext passed into.
6080: 2a 2a 20 20 20 20 20 20 74 68 65 20 32 6e 64 20  **      the 2nd 
6090: 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73 71 6c  parameter of sql
60a0: 69 74 65 33 5f 65 78 65 63 28 29 20 77 68 69 6c  ite3_exec() whil
60b0: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
60c0: 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20   is running..** 
60d0: 3c 2f 75 6c 3e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  </ul>.*/.SQLITE_
60e0: 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  API int SQLITE_S
60f0: 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 65  TDCALL sqlite3_e
6100: 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  xec(.  sqlite3*,
6110: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6120: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6130: 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74    /* An open dat
6140: 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  abase */.  const
6150: 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20 20   char *sql,     
6160: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6170: 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20        /* SQL to 
6180: 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a  be evaluated */.
6190: 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63 6b    int (*callback
61a0: 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72  )(void*,int,char
61b0: 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a 20  **,char**),  /* 
61c0: 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  Callback functio
61d0: 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 20  n */.  void *,  
61e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
61f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6200: 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d 65 6e    /* 1st argumen
6210: 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a 2f  t to callback */
6220: 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73 67  .  char **errmsg
6230: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6240: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
6250: 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74   Error msg writt
6260: 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f  en here */.);../
6270: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
6280: 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b  esult Codes.** K
6290: 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74  EYWORDS: {result
62a0: 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69 6f 6e   code definition
62b0: 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51  s}.**.** Many SQ
62c0: 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20 72  Lite functions r
62d0: 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65 72  eturn an integer
62e0: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72 6f   result code fro
62f0: 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e 0a  m the set shown.
6300: 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65 72  ** here in order
6310: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 73 75 63   to indicate suc
6320: 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65 2e  cess or failure.
6330: 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f 72  .**.** New error
6340: 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20 61 64   codes may be ad
6350: 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 76 65  ded in future ve
6360: 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
6370: 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
6380: 3a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  : [extended resu
6390: 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69  lt code definiti
63a0: 6f 6e 73 5d 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ons].*/.#define 
63b0: 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20 20  SQLITE_OK       
63c0: 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63 63 65      0   /* Succe
63d0: 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a  ssful result */.
63e0: 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d  /* beginning-of-
63f0: 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23  error-codes */.#
6400: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 52  define SQLITE_ER
6410: 52 4f 52 20 20 20 20 20 20 20 20 31 20 20 20 2f  ROR        1   /
6420: 2a 20 53 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d  * SQL error or m
6430: 69 73 73 69 6e 67 20 64 61 74 61 62 61 73 65 20  issing database 
6440: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6450: 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 20 32  E_INTERNAL     2
6460: 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c     /* Internal l
6470: 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 53 51  ogic error in SQ
6480: 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  Lite */.#define 
6490: 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20 20  SQLITE_PERM     
64a0: 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63 65 73      3   /* Acces
64b0: 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e  s permission den
64c0: 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ied */.#define S
64d0: 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 20 20  QLITE_ABORT     
64e0: 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61     4   /* Callba
64f0: 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 75 65  ck routine reque
6500: 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f  sted an abort */
6510: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6520: 42 55 53 59 20 20 20 20 20 20 20 20 20 35 20 20  BUSY         5  
6530: 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65   /* The database
6540: 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20   file is locked 
6550: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6560: 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 36  E_LOCKED       6
6570: 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e     /* A table in
6580: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
6590: 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69   locked */.#defi
65a0: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20  ne SQLITE_NOMEM 
65b0: 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 41 20         7   /* A 
65c0: 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64 20  malloc() failed 
65d0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
65e0: 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 38  E_READONLY     8
65f0: 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f     /* Attempt to
6600: 20 77 72 69 74 65 20 61 20 72 65 61 64 6f 6e 6c   write a readonl
6610: 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64  y database */.#d
6620: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54  efine SQLITE_INT
6630: 45 52 52 55 50 54 20 20 20 20 39 20 20 20 2f 2a  ERRUPT    9   /*
6640: 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 6d 69   Operation termi
6650: 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33  nated by sqlite3
6660: 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a 23  _interrupt()*/.#
6670: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6680: 45 52 52 20 20 20 20 20 20 20 31 30 20 20 20 2f  ERR       10   /
6690: 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64  * Some kind of d
66a0: 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63  isk I/O error oc
66b0: 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e  curred */.#defin
66c0: 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54  e SQLITE_CORRUPT
66d0: 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 68 65       11   /* The
66e0: 20 64 61 74 61 62 61 73 65 20 64 69 73 6b 20 69   database disk i
66f0: 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65  mage is malforme
6700: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
6710: 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20  ITE_NOTFOUND    
6720: 31 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e 20  12   /* Unknown 
6730: 6f 70 63 6f 64 65 20 69 6e 20 73 71 6c 69 74 65  opcode in sqlite
6740: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
6750: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6760: 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 31  TE_FULL        1
6770: 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e  3   /* Insertion
6780: 20 66 61 69 6c 65 64 20 62 65 63 61 75 73 65 20   failed because 
6790: 64 61 74 61 62 61 73 65 20 69 73 20 66 75 6c 6c  database is full
67a0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
67b0: 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20 31  TE_CANTOPEN    1
67c0: 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f  4   /* Unable to
67d0: 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61   open the databa
67e0: 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69  se file */.#defi
67f0: 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43  ne SQLITE_PROTOC
6800: 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 44 61  OL    15   /* Da
6810: 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74  tabase lock prot
6820: 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64  ocol error */.#d
6830: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50  efine SQLITE_EMP
6840: 54 59 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a  TY       16   /*
6850: 20 44 61 74 61 62 61 73 65 20 69 73 20 65 6d 70   Database is emp
6860: 74 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ty */.#define SQ
6870: 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20 20  LITE_SCHEMA     
6880: 20 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61 74   17   /* The dat
6890: 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61  abase schema cha
68a0: 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nged */.#define 
68b0: 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20 20  SQLITE_TOOBIG   
68c0: 20 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69 6e     18   /* Strin
68d0: 67 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65 64  g or BLOB exceed
68e0: 73 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a  s size limit */.
68f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
6900: 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20 20  ONSTRAINT  19   
6910: 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f 20  /* Abort due to 
6920: 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61  constraint viola
6930: 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  tion */.#define 
6940: 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48 20  SQLITE_MISMATCH 
6950: 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61 20     20   /* Data 
6960: 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f  type mismatch */
6970: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6980: 4d 49 53 55 53 45 20 20 20 20 20 20 32 31 20 20  MISUSE      21  
6990: 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65 64   /* Library used
69a0: 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a   incorrectly */.
69b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
69c0: 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20 20 20  OLFS       22   
69d0: 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74 75  /* Uses OS featu
69e0: 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 65  res not supporte
69f0: 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65  d on host */.#de
6a00: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48  fine SQLITE_AUTH
6a10: 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20          23   /* 
6a20: 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65  Authorization de
6a30: 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nied */.#define 
6a40: 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20 20  SQLITE_FORMAT   
6a50: 20 20 20 32 34 20 20 20 2f 2a 20 41 75 78 69 6c     24   /* Auxil
6a60: 69 61 72 79 20 64 61 74 61 62 61 73 65 20 66 6f  iary database fo
6a70: 72 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64  rmat error */.#d
6a80: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e  efine SQLITE_RAN
6a90: 47 45 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a  GE       25   /*
6aa0: 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74   2nd parameter t
6ab0: 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f  o sqlite3_bind o
6ac0: 75 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23  ut of range */.#
6ad0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
6ae0: 54 41 44 42 20 20 20 20 20 20 32 36 20 20 20 2f  TADB      26   /
6af0: 2a 20 46 69 6c 65 20 6f 70 65 6e 65 64 20 74 68  * File opened th
6b00: 61 74 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61  at is not a data
6b10: 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65  base file */.#de
6b20: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49  fine SQLITE_NOTI
6b30: 43 45 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20  CE      27   /* 
6b40: 4e 6f 74 69 66 69 63 61 74 69 6f 6e 73 20 66 72  Notifications fr
6b50: 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29  om sqlite3_log()
6b60: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6b70: 54 45 5f 57 41 52 4e 49 4e 47 20 20 20 20 20 32  TE_WARNING     2
6b80: 38 20 20 20 2f 2a 20 57 61 72 6e 69 6e 67 73 20  8   /* Warnings 
6b90: 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67  from sqlite3_log
6ba0: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
6bb0: 4c 49 54 45 5f 52 4f 57 20 20 20 20 20 20 20 20  LITE_ROW        
6bc0: 20 31 30 30 20 20 2f 2a 20 73 71 6c 69 74 65 33   100  /* sqlite3
6bd0: 5f 73 74 65 70 28 29 20 68 61 73 20 61 6e 6f 74  _step() has anot
6be0: 68 65 72 20 72 6f 77 20 72 65 61 64 79 20 2a 2f  her row ready */
6bf0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6c00: 44 4f 4e 45 20 20 20 20 20 20 20 20 31 30 31 20  DONE        101 
6c10: 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70   /* sqlite3_step
6c20: 28 29 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  () has finished 
6c30: 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20  executing */./* 
6c40: 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64  end-of-error-cod
6c50: 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  es */../*.** CAP
6c60: 49 33 52 45 46 3a 20 45 78 74 65 6e 64 65 64 20  I3REF: Extended 
6c70: 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20  Result Codes.** 
6c80: 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e  KEYWORDS: {exten
6c90: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 20  ded result code 
6ca0: 64 65 66 69 6e 69 74 69 6f 6e 73 7d 0a 2a 2a 0a  definitions}.**.
6cb0: 2a 2a 20 49 6e 20 69 74 73 20 64 65 66 61 75 6c  ** In its defaul
6cc0: 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c  t configuration,
6cd0: 20 53 51 4c 69 74 65 20 41 50 49 20 72 6f 75 74   SQLite API rout
6ce0: 69 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e 65 20  ines return one 
6cf0: 6f 66 20 33 30 20 69 6e 74 65 67 65 72 0a 2a 2a  of 30 integer.**
6d00: 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 2e   [result codes].
6d10: 20 20 48 6f 77 65 76 65 72 2c 20 65 78 70 65 72    However, exper
6d20: 69 65 6e 63 65 20 68 61 73 20 73 68 6f 77 6e 20  ience has shown 
6d30: 74 68 61 74 20 6d 61 6e 79 20 6f 66 0a 2a 2a 20  that many of.** 
6d40: 74 68 65 73 65 20 72 65 73 75 6c 74 20 63 6f 64  these result cod
6d50: 65 73 20 61 72 65 20 74 6f 6f 20 63 6f 61 72 73  es are too coars
6d60: 65 2d 67 72 61 69 6e 65 64 2e 20 20 54 68 65 79  e-grained.  They
6d70: 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69 64 65 20   do not provide 
6d80: 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e 66 6f 72  as.** much infor
6d90: 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 70 72 6f  mation about pro
6da0: 62 6c 65 6d 73 20 61 73 20 70 72 6f 67 72 61 6d  blems as program
6db0: 6d 65 72 73 20 6d 69 67 68 74 20 6c 69 6b 65 2e  mers might like.
6dc0: 20 20 49 6e 20 61 6e 20 65 66 66 6f 72 74 20 74    In an effort t
6dd0: 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20 74 68 69  o.** address thi
6de0: 73 2c 20 6e 65 77 65 72 20 76 65 72 73 69 6f 6e  s, newer version
6df0: 73 20 6f 66 20 53 51 4c 69 74 65 20 28 76 65 72  s of SQLite (ver
6e00: 73 69 6f 6e 20 33 2e 33 2e 38 20 61 6e 64 20 6c  sion 3.3.8 and l
6e10: 61 74 65 72 29 20 69 6e 63 6c 75 64 65 0a 2a 2a  ater) include.**
6e20: 20 73 75 70 70 6f 72 74 20 66 6f 72 20 61 64 64   support for add
6e30: 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c 74 20 63  itional result c
6e40: 6f 64 65 73 20 74 68 61 74 20 70 72 6f 76 69 64  odes that provid
6e50: 65 20 6d 6f 72 65 20 64 65 74 61 69 6c 65 64 20  e more detailed 
6e60: 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61  information.** a
6e70: 62 6f 75 74 20 65 72 72 6f 72 73 2e 20 54 68 65  bout errors. The
6e80: 73 65 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  se [extended res
6e90: 75 6c 74 20 63 6f 64 65 73 5d 20 61 72 65 20 65  ult codes] are e
6ea0: 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c  nabled or disabl
6eb0: 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 65 72 20 64  ed.** on a per d
6ec0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
6ed0: 6f 6e 20 62 61 73 69 73 20 75 73 69 6e 67 20 74  on basis using t
6ee0: 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  he.** [sqlite3_e
6ef0: 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63  xtended_result_c
6f00: 6f 64 65 73 28 29 5d 20 41 50 49 2e 20 20 4f 72  odes()] API.  Or
6f10: 2c 20 74 68 65 20 65 78 74 65 6e 64 65 64 20 63  , the extended c
6f20: 6f 64 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 6d  ode for.** the m
6f30: 6f 73 74 20 72 65 63 65 6e 74 20 65 72 72 6f 72  ost recent error
6f40: 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64   can be obtained
6f50: 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
6f60: 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63  e3_extended_errc
6f70: 6f 64 65 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69  ode()]..*/.#defi
6f80: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
6f90: 52 45 41 44 20 20 20 20 20 20 20 20 20 20 20 20  READ            
6fa0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
6fb0: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
6fc0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53  e SQLITE_IOERR_S
6fd0: 48 4f 52 54 5f 52 45 41 44 20 20 20 20 20 20 20  HORT_READ       
6fe0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
6ff0: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (2<<8)).#define
7000: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 57 52   SQLITE_IOERR_WR
7010: 49 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ITE             
7020: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
7030: 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (3<<8)).#define 
7040: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 59  SQLITE_IOERR_FSY
7050: 4e 43 20 20 20 20 20 20 20 20 20 20 20 20 20 28  NC             (
7060: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
7070: 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  4<<8)).#define S
7080: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f  QLITE_IOERR_DIR_
7090: 46 53 59 4e 43 20 20 20 20 20 20 20 20 20 28 53  FSYNC         (S
70a0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 35  QLITE_IOERR | (5
70b0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
70c0: 4c 49 54 45 5f 49 4f 45 52 52 5f 54 52 55 4e 43  LITE_IOERR_TRUNC
70d0: 41 54 45 20 20 20 20 20 20 20 20 20 20 28 53 51  ATE          (SQ
70e0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 36 3c  LITE_IOERR | (6<
70f0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
7100: 49 54 45 5f 49 4f 45 52 52 5f 46 53 54 41 54 20  ITE_IOERR_FSTAT 
7110: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
7120: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 37 3c 3c  ITE_IOERR | (7<<
7130: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
7140: 54 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20  TE_IOERR_UNLOCK 
7150: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
7160: 54 45 5f 49 4f 45 52 52 20 7c 20 28 38 3c 3c 38  TE_IOERR | (8<<8
7170: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
7180: 45 5f 49 4f 45 52 52 5f 52 44 4c 4f 43 4b 20 20  E_IOERR_RDLOCK  
7190: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
71a0: 45 5f 49 4f 45 52 52 20 7c 20 28 39 3c 3c 38 29  E_IOERR | (9<<8)
71b0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
71c0: 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 20 20 20  _IOERR_DELETE   
71d0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
71e0: 5f 49 4f 45 52 52 20 7c 20 28 31 30 3c 3c 38 29  _IOERR | (10<<8)
71f0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
7200: 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 20 20  _IOERR_BLOCKED  
7210: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
7220: 5f 49 4f 45 52 52 20 7c 20 28 31 31 3c 3c 38 29  _IOERR | (11<<8)
7230: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
7240: 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20 20 20  _IOERR_NOMEM    
7250: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
7260: 5f 49 4f 45 52 52 20 7c 20 28 31 32 3c 3c 38 29  _IOERR | (12<<8)
7270: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
7280: 5f 49 4f 45 52 52 5f 41 43 43 45 53 53 20 20 20  _IOERR_ACCESS   
7290: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
72a0: 5f 49 4f 45 52 52 20 7c 20 28 31 33 3c 3c 38 29  _IOERR | (13<<8)
72b0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
72c0: 5f 49 4f 45 52 52 5f 43 48 45 43 4b 52 45 53 45  _IOERR_CHECKRESE
72d0: 52 56 45 44 4c 4f 43 4b 20 28 53 51 4c 49 54 45  RVEDLOCK (SQLITE
72e0: 5f 49 4f 45 52 52 20 7c 20 28 31 34 3c 3c 38 29  _IOERR | (14<<8)
72f0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
7300: 5f 49 4f 45 52 52 5f 4c 4f 43 4b 20 20 20 20 20  _IOERR_LOCK     
7310: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
7320: 5f 49 4f 45 52 52 20 7c 20 28 31 35 3c 3c 38 29  _IOERR | (15<<8)
7330: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
7340: 5f 49 4f 45 52 52 5f 43 4c 4f 53 45 20 20 20 20  _IOERR_CLOSE    
7350: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
7360: 5f 49 4f 45 52 52 20 7c 20 28 31 36 3c 3c 38 29  _IOERR | (16<<8)
7370: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
7380: 5f 49 4f 45 52 52 5f 44 49 52 5f 43 4c 4f 53 45  _IOERR_DIR_CLOSE
7390: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
73a0: 5f 49 4f 45 52 52 20 7c 20 28 31 37 3c 3c 38 29  _IOERR | (17<<8)
73b0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
73c0: 5f 49 4f 45 52 52 5f 53 48 4d 4f 50 45 4e 20 20  _IOERR_SHMOPEN  
73d0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
73e0: 5f 49 4f 45 52 52 20 7c 20 28 31 38 3c 3c 38 29  _IOERR | (18<<8)
73f0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
7400: 5f 49 4f 45 52 52 5f 53 48 4d 53 49 5a 45 20 20  _IOERR_SHMSIZE  
7410: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
7420: 5f 49 4f 45 52 52 20 7c 20 28 31 39 3c 3c 38 29  _IOERR | (19<<8)
7430: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
7440: 5f 49 4f 45 52 52 5f 53 48 4d 4c 4f 43 4b 20 20  _IOERR_SHMLOCK  
7450: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
7460: 5f 49 4f 45 52 52 20 7c 20 28 32 30 3c 3c 38 29  _IOERR | (20<<8)
7470: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
7480: 5f 49 4f 45 52 52 5f 53 48 4d 4d 41 50 20 20 20  _IOERR_SHMMAP   
7490: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
74a0: 5f 49 4f 45 52 52 20 7c 20 28 32 31 3c 3c 38 29  _IOERR | (21<<8)
74b0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
74c0: 5f 49 4f 45 52 52 5f 53 45 45 4b 20 20 20 20 20  _IOERR_SEEK     
74d0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
74e0: 5f 49 4f 45 52 52 20 7c 20 28 32 32 3c 3c 38 29  _IOERR | (22<<8)
74f0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
7500: 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 5f 4e 4f  _IOERR_DELETE_NO
7510: 45 4e 54 20 20 20 20 20 20 28 53 51 4c 49 54 45  ENT      (SQLITE
7520: 5f 49 4f 45 52 52 20 7c 20 28 32 33 3c 3c 38 29  _IOERR | (23<<8)
7530: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
7540: 5f 49 4f 45 52 52 5f 4d 4d 41 50 20 20 20 20 20  _IOERR_MMAP     
7550: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
7560: 5f 49 4f 45 52 52 20 7c 20 28 32 34 3c 3c 38 29  _IOERR | (24<<8)
7570: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
7580: 5f 49 4f 45 52 52 5f 47 45 54 54 45 4d 50 50 41  _IOERR_GETTEMPPA
7590: 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  TH       (SQLITE
75a0: 5f 49 4f 45 52 52 20 7c 20 28 32 35 3c 3c 38 29  _IOERR | (25<<8)
75b0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
75c0: 5f 49 4f 45 52 52 5f 43 4f 4e 56 50 41 54 48 20  _IOERR_CONVPATH 
75d0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
75e0: 5f 49 4f 45 52 52 20 7c 20 28 32 36 3c 3c 38 29  _IOERR | (26<<8)
75f0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
7600: 5f 4c 4f 43 4b 45 44 5f 53 48 41 52 45 44 43 41  _LOCKED_SHAREDCA
7610: 43 48 45 20 20 20 20 20 20 28 53 51 4c 49 54 45  CHE      (SQLITE
7620: 5f 4c 4f 43 4b 45 44 20 7c 20 20 28 31 3c 3c 38  _LOCKED |  (1<<8
7630: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
7640: 45 5f 42 55 53 59 5f 52 45 43 4f 56 45 52 59 20  E_BUSY_RECOVERY 
7650: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
7660: 45 5f 42 55 53 59 20 20 20 7c 20 20 28 31 3c 3c  E_BUSY   |  (1<<
7670: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
7680: 54 45 5f 42 55 53 59 5f 53 4e 41 50 53 48 4f 54  TE_BUSY_SNAPSHOT
7690: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
76a0: 54 45 5f 42 55 53 59 20 20 20 7c 20 20 28 32 3c  TE_BUSY   |  (2<
76b0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
76c0: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 4e 4f 54  ITE_CANTOPEN_NOT
76d0: 45 4d 50 44 49 52 20 20 20 20 20 20 28 53 51 4c  EMPDIR      (SQL
76e0: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28  ITE_CANTOPEN | (
76f0: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
7700: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 49  QLITE_CANTOPEN_I
7710: 53 44 49 52 20 20 20 20 20 20 20 20 20 20 28 53  SDIR          (S
7720: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c  QLITE_CANTOPEN |
7730: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (2<<8)).#define
7740: 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e   SQLITE_CANTOPEN
7750: 5f 46 55 4c 4c 50 41 54 48 20 20 20 20 20 20 20  _FULLPATH       
7760: 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e  (SQLITE_CANTOPEN
7770: 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69   | (3<<8)).#defi
7780: 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  ne SQLITE_CANTOP
7790: 45 4e 5f 43 4f 4e 56 50 41 54 48 20 20 20 20 20  EN_CONVPATH     
77a0: 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50    (SQLITE_CANTOP
77b0: 45 4e 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65  EN | (4<<8)).#de
77c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52  fine SQLITE_CORR
77d0: 55 50 54 5f 56 54 41 42 20 20 20 20 20 20 20 20  UPT_VTAB        
77e0: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 52 52      (SQLITE_CORR
77f0: 55 50 54 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64  UPT | (1<<8)).#d
7800: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41  efine SQLITE_REA
7810: 44 4f 4e 4c 59 5f 52 45 43 4f 56 45 52 59 20 20  DONLY_RECOVERY  
7820: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41       (SQLITE_REA
7830: 44 4f 4e 4c 59 20 7c 20 28 31 3c 3c 38 29 29 0a  DONLY | (1<<8)).
7840: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
7850: 45 41 44 4f 4e 4c 59 5f 43 41 4e 54 4c 4f 43 4b  EADONLY_CANTLOCK
7860: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52         (SQLITE_R
7870: 45 41 44 4f 4e 4c 59 20 7c 20 28 32 3c 3c 38 29  EADONLY | (2<<8)
7880: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
7890: 5f 52 45 41 44 4f 4e 4c 59 5f 52 4f 4c 4c 42 41  _READONLY_ROLLBA
78a0: 43 4b 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  CK       (SQLITE
78b0: 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 33 3c 3c  _READONLY | (3<<
78c0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
78d0: 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 44 42 4d 4f  TE_READONLY_DBMO
78e0: 56 45 44 20 20 20 20 20 20 20 20 28 53 51 4c 49  VED        (SQLI
78f0: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 34  TE_READONLY | (4
7900: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
7910: 4c 49 54 45 5f 41 42 4f 52 54 5f 52 4f 4c 4c 42  LITE_ABORT_ROLLB
7920: 41 43 4b 20 20 20 20 20 20 20 20 20 20 28 53 51  ACK          (SQ
7930: 4c 49 54 45 5f 41 42 4f 52 54 20 7c 20 28 32 3c  LITE_ABORT | (2<
7940: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
7950: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43  ITE_CONSTRAINT_C
7960: 48 45 43 4b 20 20 20 20 20 20 20 20 28 53 51 4c  HECK        (SQL
7970: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
7980: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
7990: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
79a0: 4e 54 5f 43 4f 4d 4d 49 54 48 4f 4f 4b 20 20 20  NT_COMMITHOOK   
79b0: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
79c0: 4e 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65  NT | (2<<8)).#de
79d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
79e0: 54 52 41 49 4e 54 5f 46 4f 52 45 49 47 4e 4b 45  TRAINT_FOREIGNKE
79f0: 59 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53  Y   (SQLITE_CONS
7a00: 54 52 41 49 4e 54 20 7c 20 28 33 3c 3c 38 29 29  TRAINT | (3<<8))
7a10: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
7a20: 43 4f 4e 53 54 52 41 49 4e 54 5f 46 55 4e 43 54  CONSTRAINT_FUNCT
7a30: 49 4f 4e 20 20 20 20 20 28 53 51 4c 49 54 45 5f  ION     (SQLITE_
7a40: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 34 3c  CONSTRAINT | (4<
7a50: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
7a60: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4e  ITE_CONSTRAINT_N
7a70: 4f 54 4e 55 4c 4c 20 20 20 20 20 20 28 53 51 4c  OTNULL      (SQL
7a80: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
7a90: 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (5<<8)).#define
7aa0: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
7ab0: 4e 54 5f 50 52 49 4d 41 52 59 4b 45 59 20 20 20  NT_PRIMARYKEY   
7ac0: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
7ad0: 4e 54 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65  NT | (6<<8)).#de
7ae0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
7af0: 54 52 41 49 4e 54 5f 54 52 49 47 47 45 52 20 20  TRAINT_TRIGGER  
7b00: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53      (SQLITE_CONS
7b10: 54 52 41 49 4e 54 20 7c 20 28 37 3c 3c 38 29 29  TRAINT | (7<<8))
7b20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
7b30: 43 4f 4e 53 54 52 41 49 4e 54 5f 55 4e 49 51 55  CONSTRAINT_UNIQU
7b40: 45 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  E       (SQLITE_
7b50: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 38 3c  CONSTRAINT | (8<
7b60: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
7b70: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 56  ITE_CONSTRAINT_V
7b80: 54 41 42 20 20 20 20 20 20 20 20 20 28 53 51 4c  TAB         (SQL
7b90: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
7ba0: 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (9<<8)).#define
7bb0: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
7bc0: 4e 54 5f 52 4f 57 49 44 20 20 20 20 20 20 20 20  NT_ROWID        
7bd0: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
7be0: 4e 54 20 7c 28 31 30 3c 3c 38 29 29 0a 23 64 65  NT |(10<<8)).#de
7bf0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49  fine SQLITE_NOTI
7c00: 43 45 5f 52 45 43 4f 56 45 52 5f 57 41 4c 20 20  CE_RECOVER_WAL  
7c10: 20 20 20 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49      (SQLITE_NOTI
7c20: 43 45 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  CE | (1<<8)).#de
7c30: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49  fine SQLITE_NOTI
7c40: 43 45 5f 52 45 43 4f 56 45 52 5f 52 4f 4c 4c 42  CE_RECOVER_ROLLB
7c50: 41 43 4b 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49  ACK (SQLITE_NOTI
7c60: 43 45 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65  CE | (2<<8)).#de
7c70: 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52 4e  fine SQLITE_WARN
7c80: 49 4e 47 5f 41 55 54 4f 49 4e 44 45 58 20 20 20  ING_AUTOINDEX   
7c90: 20 20 20 20 28 53 51 4c 49 54 45 5f 57 41 52 4e      (SQLITE_WARN
7ca0: 49 4e 47 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64  ING | (1<<8)).#d
7cb0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54  efine SQLITE_AUT
7cc0: 48 5f 55 53 45 52 20 20 20 20 20 20 20 20 20 20  H_USER          
7cd0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 41 55 54       (SQLITE_AUT
7ce0: 48 20 7c 20 28 31 3c 3c 38 29 29 0a 0a 2f 2a 0a  H | (1<<8))../*.
7cf0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61  ** CAPI3REF: Fla
7d00: 67 73 20 46 6f 72 20 46 69 6c 65 20 4f 70 65 6e  gs For File Open
7d10: 20 4f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a   Operations.**.*
7d20: 2a 20 54 68 65 73 65 20 62 69 74 20 76 61 6c 75  * These bit valu
7d30: 65 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20  es are intended 
7d40: 66 6f 72 20 75 73 65 20 69 6e 20 74 68 65 0a 2a  for use in the.*
7d50: 2a 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  * 3rd parameter 
7d60: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
7d70: 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72  open_v2()] inter
7d80: 66 61 63 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74  face and.** in t
7d90: 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  he 4th parameter
7da0: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
7db0: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68  _vfs.xOpen] meth
7dc0: 6f 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  od..*/.#define S
7dd0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
7de0: 4e 4c 59 20 20 20 20 20 20 20 20 20 30 78 30 30  NLY         0x00
7df0: 30 30 30 30 30 31 20 20 2f 2a 20 4f 6b 20 66 6f  000001  /* Ok fo
7e00: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
7e10: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
7e20: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
7e30: 52 49 54 45 20 20 20 20 20 20 20 20 30 78 30 30  RITE        0x00
7e40: 30 30 30 30 30 32 20 20 2f 2a 20 4f 6b 20 66 6f  000002  /* Ok fo
7e50: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
7e60: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
7e70: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
7e80: 45 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30  E           0x00
7e90: 30 30 30 30 30 34 20 20 2f 2a 20 4f 6b 20 66 6f  000004  /* Ok fo
7ea0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
7eb0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
7ec0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
7ed0: 45 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78 30 30  EONCLOSE    0x00
7ee0: 30 30 30 30 30 38 20 20 2f 2a 20 56 46 53 20 6f  000008  /* VFS o
7ef0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
7f00: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55  QLITE_OPEN_EXCLU
7f10: 53 49 56 45 20 20 20 20 20 20 20 20 30 78 30 30  SIVE        0x00
7f20: 30 30 30 30 31 30 20 20 2f 2a 20 56 46 53 20 6f  000010  /* VFS o
7f30: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
7f40: 51 4c 49 54 45 5f 4f 50 45 4e 5f 41 55 54 4f 50  QLITE_OPEN_AUTOP
7f50: 52 4f 58 59 20 20 20 20 20 20 20 20 30 78 30 30  ROXY        0x00
7f60: 30 30 30 30 32 30 20 20 2f 2a 20 56 46 53 20 6f  000020  /* VFS o
7f70: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
7f80: 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 20  QLITE_OPEN_URI  
7f90: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
7fa0: 30 30 30 30 34 30 20 20 2f 2a 20 4f 6b 20 66 6f  000040  /* Ok fo
7fb0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
7fc0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
7fd0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 45 4d 4f 52  QLITE_OPEN_MEMOR
7fe0: 59 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30  Y           0x00
7ff0: 30 30 30 30 38 30 20 20 2f 2a 20 4f 6b 20 66 6f  000080  /* Ok fo
8000: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
8010: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
8020: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
8030: 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30  DB          0x00
8040: 30 30 30 31 30 30 20 20 2f 2a 20 56 46 53 20 6f  000100  /* VFS o
8050: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
8060: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
8070: 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30  DB          0x00
8080: 30 30 30 32 30 30 20 20 2f 2a 20 56 46 53 20 6f  000200  /* VFS o
8090: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
80a0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53  QLITE_OPEN_TRANS
80b0: 49 45 4e 54 5f 44 42 20 20 20 20 20 30 78 30 30  IENT_DB     0x00
80c0: 30 30 30 34 30 30 20 20 2f 2a 20 56 46 53 20 6f  000400  /* VFS o
80d0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
80e0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
80f0: 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30  JOURNAL     0x00
8100: 30 30 30 38 30 30 20 20 2f 2a 20 56 46 53 20 6f  000800  /* VFS o
8110: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
8120: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
8130: 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30  JOURNAL     0x00
8140: 30 30 31 30 30 30 20 20 2f 2a 20 56 46 53 20 6f  001000  /* VFS o
8150: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
8160: 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f  QLITE_OPEN_SUBJO
8170: 55 52 4e 41 4c 20 20 20 20 20 20 20 30 78 30 30  URNAL       0x00
8180: 30 30 32 30 30 30 20 20 2f 2a 20 56 46 53 20 6f  002000  /* VFS o
8190: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
81a0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45  QLITE_OPEN_MASTE
81b0: 52 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30 30  R_JOURNAL   0x00
81c0: 30 30 34 30 30 30 20 20 2f 2a 20 56 46 53 20 6f  004000  /* VFS o
81d0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
81e0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54  QLITE_OPEN_NOMUT
81f0: 45 58 20 20 20 20 20 20 20 20 20 20 30 78 30 30  EX          0x00
8200: 30 30 38 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f  008000  /* Ok fo
8210: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
8220: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
8230: 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d  QLITE_OPEN_FULLM
8240: 55 54 45 58 20 20 20 20 20 20 20 20 30 78 30 30  UTEX        0x00
8250: 30 31 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f  010000  /* Ok fo
8260: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
8270: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
8280: 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45  QLITE_OPEN_SHARE
8290: 44 43 41 43 48 45 20 20 20 20 20 20 30 78 30 30  DCACHE      0x00
82a0: 30 32 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f  020000  /* Ok fo
82b0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
82c0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
82d0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41  QLITE_OPEN_PRIVA
82e0: 54 45 43 41 43 48 45 20 20 20 20 20 30 78 30 30  TECACHE     0x00
82f0: 30 34 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f  040000  /* Ok fo
8300: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
8310: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
8320: 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 20 20  QLITE_OPEN_WAL  
8330: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
8340: 30 38 30 30 30 30 20 20 2f 2a 20 56 46 53 20 6f  080000  /* VFS o
8350: 6e 6c 79 20 2a 2f 0a 0a 2f 2a 20 52 65 73 65 72  nly */../* Reser
8360: 76 65 64 3a 20 20 20 20 20 20 20 20 20 20 20 20  ved:            
8370: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
8380: 30 46 30 30 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a  0F00000 */../*.*
8390: 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 76 69  * CAPI3REF: Devi
83a0: 63 65 20 43 68 61 72 61 63 74 65 72 69 73 74 69  ce Characteristi
83b0: 63 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65  cs.**.** The xDe
83c0: 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74  viceCharacterist
83d0: 69 63 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68  ics method of th
83e0: 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  e [sqlite3_io_me
83f0: 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74  thods].** object
8400: 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65   returns an inte
8410: 67 65 72 20 77 68 69 63 68 20 69 73 20 61 20 76  ger which is a v
8420: 65 63 74 6f 72 20 6f 66 20 74 68 65 73 65 0a 2a  ector of these.*
8430: 2a 20 62 69 74 20 76 61 6c 75 65 73 20 65 78 70  * bit values exp
8440: 72 65 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 72  ressing I/O char
8450: 61 63 74 65 72 69 73 74 69 63 73 20 6f 66 20 74  acteristics of t
8460: 68 65 20 6d 61 73 73 20 73 74 6f 72 61 67 65 0a  he mass storage.
8470: 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 68  ** device that h
8480: 6f 6c 64 73 20 74 68 65 20 66 69 6c 65 20 74 68  olds the file th
8490: 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  at the [sqlite3_
84a0: 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72  io_methods].** r
84b0: 65 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20  efers to..**.** 
84c0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
84d0: 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79  _ATOMIC property
84e0: 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20   means that all 
84f0: 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79  writes of.** any
8500: 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63   size are atomic
8510: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
8520: 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61  CAP_ATOMICnnn va
8530: 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61  lues.** mean tha
8540: 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63  t writes of bloc
8550: 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20  ks that are nnn 
8560: 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e  bytes in size an
8570: 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64  d.** are aligned
8580: 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77   to an address w
8590: 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67  hich is an integ
85a0: 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a  er multiple of.*
85b0: 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63  * nnn are atomic
85c0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
85d0: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20  CAP_SAFE_APPEND 
85e0: 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74  value means.** t
85f0: 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73  hat when data is
8600: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66   appended to a f
8610: 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73  ile, the data is
8620: 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72   appended.** fir
8630: 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65  st then the size
8640: 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20   of the file is 
8650: 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20  extended, never 
8660: 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79  the other.** way
8670: 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51   around.  The SQ
8680: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
8690: 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d  NTIAL property m
86a0: 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66  eans that.** inf
86b0: 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74  ormation is writ
86c0: 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74  ten to disk in t
86d0: 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73  he same order as
86e0: 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72   calls.** to xWr
86f0: 69 74 65 28 29 2e 20 20 54 68 65 20 53 51 4c 49  ite().  The SQLI
8700: 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41  TE_IOCAP_POWERSA
8710: 46 45 5f 4f 56 45 52 57 52 49 54 45 20 70 72 6f  FE_OVERWRITE pro
8720: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
8730: 0a 2a 2a 20 61 66 74 65 72 20 72 65 62 6f 6f 74  .** after reboot
8740: 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 72 61   following a cra
8750: 73 68 20 6f 72 20 70 6f 77 65 72 20 6c 6f 73 73  sh or power loss
8760: 2c 20 74 68 65 20 6f 6e 6c 79 20 62 79 74 65 73  , the only bytes
8770: 20 69 6e 20 61 0a 2a 2a 20 66 69 6c 65 20 74 68   in a.** file th
8780: 61 74 20 77 65 72 65 20 77 72 69 74 74 65 6e 20  at were written 
8790: 61 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  at the applicati
87a0: 6f 6e 20 6c 65 76 65 6c 20 6d 69 67 68 74 20 68  on level might h
87b0: 61 76 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 61  ave changed.** a
87c0: 6e 64 20 74 68 61 74 20 61 64 6a 61 63 65 6e 74  nd that adjacent
87d0: 20 62 79 74 65 73 2c 20 65 76 65 6e 20 62 79 74   bytes, even byt
87e0: 65 73 20 77 69 74 68 69 6e 20 74 68 65 20 73 61  es within the sa
87f0: 6d 65 20 73 65 63 74 6f 72 20 61 72 65 0a 2a 2a  me sector are.**
8800: 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62   guaranteed to b
8810: 65 20 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68  e unchanged.  Th
8820: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55  e SQLITE_IOCAP_U
8830: 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f  NDELETABLE_WHEN_
8840: 4f 50 45 4e 0a 2a 2a 20 66 6c 61 67 20 69 6e 64  OPEN.** flag ind
8850: 69 63 61 74 65 20 74 68 61 74 20 61 20 66 69 6c  icate that a fil
8860: 65 20 63 61 6e 6e 6f 74 20 62 65 20 64 65 6c 65  e cannot be dele
8870: 74 65 64 20 77 68 65 6e 20 6f 70 65 6e 2e 20 20  ted when open.  
8880: 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f  The.** SQLITE_IO
8890: 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 20 66 6c  CAP_IMMUTABLE fl
88a0: 61 67 20 69 6e 64 69 63 61 74 65 73 20 74 68 61  ag indicates tha
88b0: 74 20 74 68 65 20 66 69 6c 65 20 69 73 20 6f 6e  t the file is on
88c0: 0a 2a 2a 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65  .** read-only me
88d0: 64 69 61 20 61 6e 64 20 63 61 6e 6e 6f 74 20 62  dia and cannot b
88e0: 65 20 63 68 61 6e 67 65 64 20 65 76 65 6e 20 62  e changed even b
88f0: 79 20 70 72 6f 63 65 73 73 65 73 20 77 69 74 68  y processes with
8900: 0a 2a 2a 20 65 6c 65 76 61 74 65 64 20 70 72 69  .** elevated pri
8910: 76 69 6c 65 67 65 73 2e 0a 2a 2f 0a 23 64 65 66  vileges..*/.#def
8920: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
8930: 5f 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20 20  _ATOMIC         
8940: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
8950: 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  01.#define SQLIT
8960: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31  E_IOCAP_ATOMIC51
8970: 32 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30  2              0
8980: 78 30 30 30 30 30 30 30 32 0a 23 64 65 66 69 6e  x00000002.#defin
8990: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
89a0: 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 20 20  TOMIC1K         
89b0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34        0x00000004
89c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
89d0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20 20  IOCAP_ATOMIC2K  
89e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
89f0: 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20  0000008.#define 
8a00: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
8a10: 4d 49 43 34 4b 20 20 20 20 20 20 20 20 20 20 20  MIC4K           
8a20: 20 20 20 20 30 78 30 30 30 30 30 30 31 30 0a 23      0x00000010.#
8a30: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
8a40: 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20 20  CAP_ATOMIC8K    
8a50: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
8a60: 30 30 30 32 30 0a 23 64 65 66 69 6e 65 20 53 51  00020.#define SQ
8a70: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8a80: 43 31 36 4b 20 20 20 20 20 20 20 20 20 20 20 20  C16K            
8a90: 20 20 30 78 30 30 30 30 30 30 34 30 0a 23 64 65    0x00000040.#de
8aa0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
8ab0: 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20 20 20  P_ATOMIC32K     
8ac0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
8ad0: 30 38 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  080.#define SQLI
8ae0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36  TE_IOCAP_ATOMIC6
8af0: 34 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  4K              
8b00: 30 78 30 30 30 30 30 31 30 30 0a 23 64 65 66 69  0x00000100.#defi
8b10: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
8b20: 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20 20 20  SAFE_APPEND     
8b30: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30         0x0000020
8b40: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
8b50: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41  _IOCAP_SEQUENTIA
8b60: 4c 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78  L             0x
8b70: 30 30 30 30 30 34 30 30 0a 23 64 65 66 69 6e 65  00000400.#define
8b80: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e   SQLITE_IOCAP_UN
8b90: 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f  DELETABLE_WHEN_O
8ba0: 50 45 4e 20 20 30 78 30 30 30 30 30 38 30 30 0a  PEN  0x00000800.
8bb0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
8bc0: 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f  OCAP_POWERSAFE_O
8bd0: 56 45 52 57 52 49 54 45 20 20 20 20 30 78 30 30  VERWRITE    0x00
8be0: 30 30 31 30 30 30 0a 23 64 65 66 69 6e 65 20 53  001000.#define S
8bf0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55  QLITE_IOCAP_IMMU
8c00: 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 20  TABLE           
8c10: 20 20 20 30 78 30 30 30 30 32 30 30 30 0a 0a 2f     0x00002000../
8c20: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
8c30: 69 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65  ile Locking Leve
8c40: 6c 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  ls.**.** SQLite 
8c50: 75 73 65 73 20 6f 6e 65 20 6f 66 20 74 68 65 73  uses one of thes
8c60: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
8c70: 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a   as the second.*
8c80: 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61  * argument to ca
8c90: 6c 6c 73 20 69 74 20 6d 61 6b 65 73 20 74 6f 20  lls it makes to 
8ca0: 74 68 65 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20  the xLock() and 
8cb0: 78 55 6e 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64  xUnlock() method
8cc0: 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69  s.** of an [sqli
8cd0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
8ce0: 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69  object..*/.#defi
8cf0: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e  ne SQLITE_LOCK_N
8d00: 4f 4e 45 20 20 20 20 20 20 20 20 20 20 30 0a 23  ONE          0.#
8d10: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
8d20: 43 4b 5f 53 48 41 52 45 44 20 20 20 20 20 20 20  CK_SHARED       
8d30: 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
8d40: 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 20  E_LOCK_RESERVED 
8d50: 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
8d60: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49  QLITE_LOCK_PENDI
8d70: 4e 47 20 20 20 20 20 20 20 33 0a 23 64 65 66 69  NG       3.#defi
8d80: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45  ne SQLITE_LOCK_E
8d90: 58 43 4c 55 53 49 56 45 20 20 20 20 20 34 0a 0a  XCLUSIVE     4..
8da0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
8db0: 53 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20  Synchronization 
8dc0: 54 79 70 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a  Type Flags.**.**
8dd0: 20 57 68 65 6e 20 53 51 4c 69 74 65 20 69 6e 76   When SQLite inv
8de0: 6f 6b 65 73 20 74 68 65 20 78 53 79 6e 63 28 29  okes the xSync()
8df0: 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a   method of an.**
8e00: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
8e10: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 69 74 20  hods] object it 
8e20: 75 73 65 73 20 61 20 63 6f 6d 62 69 6e 61 74 69  uses a combinati
8e30: 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69  on of.** these i
8e40: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73  nteger values as
8e50: 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
8e60: 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  ment..**.** When
8e70: 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43   the SQLITE_SYNC
8e80: 5f 44 41 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69  _DATAONLY flag i
8e90: 73 20 75 73 65 64 2c 20 69 74 20 6d 65 61 6e 73  s used, it means
8ea0: 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e   that the.** syn
8eb0: 63 20 6f 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79  c operation only
8ec0: 20 6e 65 65 64 73 20 74 6f 20 66 6c 75 73 68 20   needs to flush 
8ed0: 64 61 74 61 20 74 6f 20 6d 61 73 73 20 73 74 6f  data to mass sto
8ee0: 72 61 67 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20  rage.  Inode.** 
8ef0: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64  information need
8f00: 20 6e 6f 74 20 62 65 20 66 6c 75 73 68 65 64 2e   not be flushed.
8f10: 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f   If the lower fo
8f20: 75 72 20 62 69 74 73 20 6f 66 20 74 68 65 20 66  ur bits of the f
8f30: 6c 61 67 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c  lag.** equal SQL
8f40: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c  ITE_SYNC_NORMAL,
8f50: 20 74 68 61 74 20 6d 65 61 6e 73 20 74 6f 20 75   that means to u
8f60: 73 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28  se normal fsync(
8f70: 29 20 73 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20  ) semantics..** 
8f80: 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75  If the lower fou
8f90: 72 20 62 69 74 73 20 65 71 75 61 6c 20 53 51 4c  r bits equal SQL
8fa0: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74  ITE_SYNC_FULL, t
8fb0: 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20  hat means.** to 
8fc0: 75 73 65 20 4d 61 63 20 4f 53 20 58 20 73 74 79  use Mac OS X sty
8fd0: 6c 65 20 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74  le fullsync inst
8fe0: 65 61 64 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a  ead of fsync()..
8ff0: 2a 2a 0a 2a 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e  **.** Do not con
9000: 66 75 73 65 20 74 68 65 20 53 51 4c 49 54 45 5f  fuse the SQLITE_
9010: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20  SYNC_NORMAL and 
9020: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
9030: 20 66 6c 61 67 73 0a 2a 2a 20 77 69 74 68 20 74   flags.** with t
9040: 68 65 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68  he [PRAGMA synch
9050: 72 6f 6e 6f 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61  ronous]=NORMAL a
9060: 6e 64 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68  nd [PRAGMA synch
9070: 72 6f 6e 6f 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20  ronous]=FULL.** 
9080: 73 65 74 74 69 6e 67 73 2e 20 20 54 68 65 20 5b  settings.  The [
9090: 73 79 6e 63 68 72 6f 6e 6f 75 73 20 70 72 61 67  synchronous prag
90a0: 6d 61 5d 20 64 65 74 65 72 6d 69 6e 65 73 20 77  ma] determines w
90b0: 68 65 6e 20 63 61 6c 6c 73 20 74 6f 20 74 68 65  hen calls to the
90c0: 0a 2a 2a 20 78 53 79 6e 63 20 56 46 53 20 6d 65  .** xSync VFS me
90d0: 74 68 6f 64 20 6f 63 63 75 72 20 61 6e 64 20 61  thod occur and a
90e0: 70 70 6c 69 65 73 20 75 6e 69 66 6f 72 6d 6c 79  pplies uniformly
90f0: 20 61 63 72 6f 73 73 20 61 6c 6c 20 70 6c 61 74   across all plat
9100: 66 6f 72 6d 73 2e 0a 2a 2a 20 54 68 65 20 53 51  forms..** The SQ
9110: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
9120: 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43   and SQLITE_SYNC
9130: 5f 46 55 4c 4c 20 66 6c 61 67 73 20 64 65 74 65  _FULL flags dete
9140: 72 6d 69 6e 65 20 68 6f 77 0a 2a 2a 20 65 6e 65  rmine how.** ene
9150: 72 67 65 74 69 63 20 6f 72 20 72 69 67 6f 72 6f  rgetic or rigoro
9160: 75 73 20 6f 72 20 66 6f 72 63 65 66 75 6c 20 74  us or forceful t
9170: 68 65 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f  he sync operatio
9180: 6e 73 20 61 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e  ns are and.** on
9190: 6c 79 20 6d 61 6b 65 20 61 20 64 69 66 66 65 72  ly make a differ
91a0: 65 6e 63 65 20 6f 6e 20 4d 61 63 20 4f 53 58 20  ence on Mac OSX 
91b0: 66 6f 72 20 74 68 65 20 64 65 66 61 75 6c 74 20  for the default 
91c0: 53 51 4c 69 74 65 20 63 6f 64 65 2e 0a 2a 2a 20  SQLite code..** 
91d0: 28 54 68 69 72 64 2d 70 61 72 74 79 20 56 46 53  (Third-party VFS
91e0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
91f0: 20 6d 69 67 68 74 20 61 6c 73 6f 20 6d 61 6b 65   might also make
9200: 20 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e   the distinction
9210: 0a 2a 2a 20 62 65 74 77 65 65 6e 20 53 51 4c 49  .** between SQLI
9220: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61  TE_SYNC_NORMAL a
9230: 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  nd SQLITE_SYNC_F
9240: 55 4c 4c 2c 20 62 75 74 20 61 6d 6f 6e 67 20 74  ULL, but among t
9250: 68 65 0a 2a 2a 20 6f 70 65 72 61 74 69 6e 67 20  he.** operating 
9260: 73 79 73 74 65 6d 73 20 6e 61 74 69 76 65 6c 79  systems natively
9270: 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 51   supported by SQ
9280: 4c 69 74 65 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f  Lite, only Mac O
9290: 53 58 0a 2a 2a 20 63 61 72 65 73 20 61 62 6f 75  SX.** cares abou
92a0: 74 20 74 68 65 20 64 69 66 66 65 72 65 6e 63 65  t the difference
92b0: 2e 29 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  .).*/.#define SQ
92c0: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
92d0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 32 0a          0x00002.
92e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
92f0: 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20 20 20  YNC_FULL        
9300: 20 20 30 78 30 30 30 30 33 0a 23 64 65 66 69 6e    0x00003.#defin
9310: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41  e SQLITE_SYNC_DA
9320: 54 41 4f 4e 4c 59 20 20 20 20 20 20 30 78 30 30  TAONLY      0x00
9330: 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  010../*.** CAPI3
9340: 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63  REF: OS Interfac
9350: 65 20 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e 64  e Open File Hand
9360: 6c 65 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c  le.**.** An [sql
9370: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
9380: 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20  t represents an 
9390: 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20 74 68 65  open file in the
93a0: 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66   .** [sqlite3_vf
93b0: 73 20 7c 20 4f 53 20 69 6e 74 65 72 66 61 63 65  s | OS interface
93c0: 20 6c 61 79 65 72 5d 2e 20 20 49 6e 64 69 76 69   layer].  Indivi
93d0: 64 75 61 6c 20 4f 53 20 69 6e 74 65 72 66 61 63  dual OS interfac
93e0: 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e.** implementat
93f0: 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e  ions will.** wan
9400: 74 20 74 6f 20 73 75 62 63 6c 61 73 73 20 74 68  t to subclass th
9410: 69 73 20 6f 62 6a 65 63 74 20 62 79 20 61 70 70  is object by app
9420: 65 6e 64 69 6e 67 20 61 64 64 69 74 69 6f 6e 61  ending additiona
9430: 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20  l fields.** for 
9440: 74 68 65 69 72 20 6f 77 6e 20 75 73 65 2e 20 20  their own use.  
9450: 54 68 65 20 70 4d 65 74 68 6f 64 73 20 65 6e 74  The pMethods ent
9460: 72 79 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ry is a pointer 
9470: 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65  to an.** [sqlite
9480: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
9490: 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65  ject that define
94a0: 73 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 70 65  s methods for pe
94b0: 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20  rforming.** I/O 
94c0: 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68  operations on th
94d0: 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a  e open file..*/.
94e0: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
94f0: 71 6c 69 74 65 33 5f 66 69 6c 65 20 73 71 6c 69  qlite3_file sqli
9500: 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74  te3_file;.struct
9510: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a   sqlite3_file {.
9520: 20 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73    const struct s
9530: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
9540: 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a  s *pMethods;  /*
9550: 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 61 6e 20   Methods for an 
9560: 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a  open file */.};.
9570: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
9580: 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 46 69   OS Interface Fi
9590: 6c 65 20 56 69 72 74 75 61 6c 20 4d 65 74 68 6f  le Virtual Metho
95a0: 64 73 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20  ds Object.**.** 
95b0: 45 76 65 72 79 20 66 69 6c 65 20 6f 70 65 6e 65  Every file opene
95c0: 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65  d by the [sqlite
95d0: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74  3_vfs.xOpen] met
95e0: 68 6f 64 20 70 6f 70 75 6c 61 74 65 73 20 61 6e  hod populates an
95f0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
9600: 65 5d 20 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d  e] object (or, m
9610: 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20  ore commonly, a 
9620: 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65 0a  subclass of the.
9630: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
9640: 5d 20 6f 62 6a 65 63 74 29 20 77 69 74 68 20 61  ] object) with a
9650: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
9660: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
9670: 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20  object..** This 
9680: 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74  object defines t
9690: 68 65 20 6d 65 74 68 6f 64 73 20 75 73 65 64 20  he methods used 
96a0: 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f  to perform vario
96b0: 75 73 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a  us operations.**
96c0: 20 61 67 61 69 6e 73 74 20 74 68 65 20 6f 70 65   against the ope
96d0: 6e 20 66 69 6c 65 20 72 65 70 72 65 73 65 6e 74  n file represent
96e0: 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74  ed by the [sqlit
96f0: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e  e3_file] object.
9700: 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b 73  .**.** If the [s
9710: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
9720: 5d 20 6d 65 74 68 6f 64 20 73 65 74 73 20 74 68  ] method sets th
9730: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70  e sqlite3_file.p
9740: 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20  Methods element 
9750: 0a 2a 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c  .** to a non-NUL
9760: 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20  L pointer, then 
9770: 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  the sqlite3_io_m
9780: 65 74 68 6f 64 73 2e 78 43 6c 6f 73 65 20 6d 65  ethods.xClose me
9790: 74 68 6f 64 0a 2a 2a 20 6d 61 79 20 62 65 20 69  thod.** may be i
97a0: 6e 76 6f 6b 65 64 20 65 76 65 6e 20 69 66 20 74  nvoked even if t
97b0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  he [sqlite3_vfs.
97c0: 78 4f 70 65 6e 5d 20 72 65 70 6f 72 74 65 64 20  xOpen] reported 
97d0: 74 68 61 74 20 69 74 20 66 61 69 6c 65 64 2e 20  that it failed. 
97e0: 20 54 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79   The.** only way
97f0: 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 63 61   to prevent a ca
9800: 6c 6c 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f 6c  ll to xClose fol
9810: 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 65 64 20  lowing a failed 
9820: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70  [sqlite3_vfs.xOp
9830: 65 6e 5d 0a 2a 2a 20 69 73 20 66 6f 72 20 74 68  en].** is for th
9840: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  e [sqlite3_vfs.x
9850: 4f 70 65 6e 5d 20 74 6f 20 73 65 74 20 74 68 65  Open] to set the
9860: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d   sqlite3_file.pM
9870: 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 0a 2a  ethods element.*
9880: 2a 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  * to NULL..**.**
9890: 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d   The flags argum
98a0: 65 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d 61 79  ent to xSync may
98b0: 20 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49   be one of [SQLI
98c0: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20  TE_SYNC_NORMAL] 
98d0: 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59  or.** [SQLITE_SY
98e0: 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66  NC_FULL].  The f
98f0: 69 72 73 74 20 63 68 6f 69 63 65 20 69 73 20 74  irst choice is t
9900: 68 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28  he normal fsync(
9910: 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  )..** The second
9920: 20 63 68 6f 69 63 65 20 69 73 20 61 20 4d 61 63   choice is a Mac
9930: 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c   OS X style full
9940: 73 79 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c 49  sync.  The [SQLI
9950: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59  TE_SYNC_DATAONLY
9960: 5d 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62 65  ].** flag may be
9970: 20 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e 64 69   ORed in to indi
9980: 63 61 74 65 20 74 68 61 74 20 6f 6e 6c 79 20 74  cate that only t
9990: 68 65 20 64 61 74 61 20 6f 66 20 74 68 65 20 66  he data of the f
99a0: 69 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69  ile.** and not i
99b0: 74 73 20 69 6e 6f 64 65 20 6e 65 65 64 73 20 74  ts inode needs t
99c0: 6f 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a  o be synced..**.
99d0: 2a 2a 20 54 68 65 20 69 6e 74 65 67 65 72 20 76  ** The integer v
99e0: 61 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29  alues to xLock()
99f0: 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61   and xUnlock() a
9a00: 72 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c  re one of.** <ul
9a10: 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  >.** <li> [SQLIT
9a20: 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a  E_LOCK_NONE],.**
9a30: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
9a40: 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c  CK_SHARED],.** <
9a50: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
9a60: 5f 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c  _RESERVED],.** <
9a70: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
9a80: 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a  _PENDING], or.**
9a90: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
9aa0: 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a  CK_EXCLUSIVE]..*
9ab0: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b  * </ul>.** xLock
9ac0: 28 29 20 69 6e 63 72 65 61 73 65 73 20 74 68 65  () increases the
9ad0: 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29   lock. xUnlock()
9ae0: 20 64 65 63 72 65 61 73 65 73 20 74 68 65 20 6c   decreases the l
9af0: 6f 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65  ock..** The xChe
9b00: 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 28 29  ckReservedLock()
9b10: 20 6d 65 74 68 6f 64 20 63 68 65 63 6b 73 20 77   method checks w
9b20: 68 65 74 68 65 72 20 61 6e 79 20 64 61 74 61 62  hether any datab
9b30: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a  ase connection,.
9b40: 2a 2a 20 65 69 74 68 65 72 20 69 6e 20 74 68 69  ** either in thi
9b50: 73 20 70 72 6f 63 65 73 73 20 6f 72 20 69 6e 20  s process or in 
9b60: 73 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f 63 65  some other proce
9b70: 73 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20 61  ss, is holding a
9b80: 20 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45   RESERVED,.** PE
9b90: 4e 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53  NDING, or EXCLUS
9ba0: 49 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20  IVE lock on the 
9bb0: 66 69 6c 65 2e 20 20 49 74 20 72 65 74 75 72 6e  file.  It return
9bc0: 73 20 74 72 75 65 0a 2a 2a 20 69 66 20 73 75 63  s true.** if suc
9bd0: 68 20 61 20 6c 6f 63 6b 20 65 78 69 73 74 73 20  h a lock exists 
9be0: 61 6e 64 20 66 61 6c 73 65 20 6f 74 68 65 72 77  and false otherw
9bf0: 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ise..**.** The x
9c00: 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65  FileControl() me
9c10: 74 68 6f 64 20 69 73 20 61 20 67 65 6e 65 72 69  thod is a generi
9c20: 63 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  c interface that
9c30: 20 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a   allows custom.*
9c40: 2a 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  * VFS implementa
9c50: 74 69 6f 6e 73 20 74 6f 20 64 69 72 65 63 74 6c  tions to directl
9c60: 79 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65  y control an ope
9c70: 6e 20 66 69 6c 65 20 75 73 69 6e 67 20 74 68 65  n file using the
9c80: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
9c90: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74  e_control()] int
9ca0: 65 72 66 61 63 65 2e 20 20 54 68 65 20 73 65 63  erface.  The sec
9cb0: 6f 6e 64 20 22 6f 70 22 20 61 72 67 75 6d 65 6e  ond "op" argumen
9cc0: 74 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67  t is an.** integ
9cd0: 65 72 20 6f 70 63 6f 64 65 2e 20 20 54 68 65 20  er opcode.  The 
9ce0: 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69  third argument i
9cf0: 73 20 61 20 67 65 6e 65 72 69 63 20 70 6f 69 6e  s a generic poin
9d00: 74 65 72 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a  ter intended to.
9d10: 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74  ** point to a st
9d20: 72 75 63 74 75 72 65 20 74 68 61 74 20 6d 61 79  ructure that may
9d30: 20 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e   contain argumen
9d40: 74 73 20 6f 72 20 73 70 61 63 65 20 69 6e 20 77  ts or space in w
9d50: 68 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65  hich to.** write
9d60: 20 72 65 74 75 72 6e 20 76 61 6c 75 65 73 2e 20   return values. 
9d70: 20 50 6f 74 65 6e 74 69 61 6c 20 75 73 65 73 20   Potential uses 
9d80: 66 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  for xFileControl
9d90: 28 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66  () might be.** f
9da0: 75 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62  unctions to enab
9db0: 6c 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b  le blocking lock
9dc0: 73 20 77 69 74 68 20 74 69 6d 65 6f 75 74 73 2c  s with timeouts,
9dd0: 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 0a 2a   to change the.*
9de0: 2a 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74 65  * locking strate
9df0: 67 79 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20  gy (for example 
9e00: 74 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c 65 20  to use dot-file 
9e10: 6c 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69  locks), to inqui
9e20: 72 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20  re.** about the 
9e30: 73 74 61 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b  status of a lock
9e40: 2c 20 6f 72 20 74 6f 20 62 72 65 61 6b 20 73 74  , or to break st
9e50: 61 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20  ale locks.  The 
9e60: 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72  SQLite.** core r
9e70: 65 73 65 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f  eserves all opco
9e80: 64 65 73 20 6c 65 73 73 20 74 68 61 6e 20 31 30  des less than 10
9e90: 30 20 66 6f 72 20 69 74 73 20 6f 77 6e 20 75 73  0 for its own us
9ea0: 65 2e 0a 2a 2a 20 41 20 5b 66 69 6c 65 20 63 6f  e..** A [file co
9eb0: 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 7c 20  ntrol opcodes | 
9ec0: 6c 69 73 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d  list of opcodes]
9ed0: 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 69   less than 100 i
9ee0: 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20  s available..** 
9ef0: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  Applications tha
9f00: 74 20 64 65 66 69 6e 65 20 61 20 63 75 73 74 6f  t define a custo
9f10: 6d 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d  m xFileControl m
9f20: 65 74 68 6f 64 20 73 68 6f 75 6c 64 20 75 73 65  ethod should use
9f30: 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61   opcodes.** grea
9f40: 74 65 72 20 74 68 61 6e 20 31 30 30 20 74 6f 20  ter than 100 to 
9f50: 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e  avoid conflicts.
9f60: 20 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61    VFS implementa
9f70: 74 69 6f 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a 20  tions should.** 
9f80: 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e  return [SQLITE_N
9f90: 4f 54 46 4f 55 4e 44 5d 20 66 6f 72 20 66 69 6c  OTFOUND] for fil
9fa0: 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65  e control opcode
9fb0: 73 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e  s that they do n
9fc0: 6f 74 0a 2a 2a 20 72 65 63 6f 67 6e 69 7a 65 2e  ot.** recognize.
9fd0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63 74  .**.** The xSect
9fe0: 6f 72 53 69 7a 65 28 29 20 6d 65 74 68 6f 64 20  orSize() method 
9ff0: 72 65 74 75 72 6e 73 20 74 68 65 20 73 65 63 74  returns the sect
a000: 6f 72 20 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a  or size of the.*
a010: 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 75 6e  * device that un
a020: 64 65 72 6c 69 65 73 20 74 68 65 20 66 69 6c 65  derlies the file
a030: 2e 20 20 54 68 65 20 73 65 63 74 6f 72 20 73 69  .  The sector si
a040: 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e  ze is the.** min
a050: 69 6d 75 6d 20 77 72 69 74 65 20 74 68 61 74 20  imum write that 
a060: 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64  can be performed
a070: 20 77 69 74 68 6f 75 74 20 64 69 73 74 75 72 62   without disturb
a080: 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74  ing.** other byt
a090: 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 2e 20  es in the file. 
a0a0: 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61 72   The xDeviceChar
a0b0: 61 63 74 65 72 69 73 74 69 63 73 28 29 0a 2a 2a  acteristics().**
a0c0: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
a0d0: 61 20 62 69 74 20 76 65 63 74 6f 72 20 64 65 73  a bit vector des
a0e0: 63 72 69 62 69 6e 67 20 62 65 68 61 76 69 6f 72  cribing behavior
a0f0: 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65  s of the.** unde
a100: 72 6c 79 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a  rlying device:.*
a110: 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
a120: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
a130: 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20  ATOMIC].** <li> 
a140: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
a150: 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e  OMIC512].** <li>
a160: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
a170: 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC1K].** <li>
a180: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
a190: 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC2K].** <li>
a1a0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
a1b0: 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC4K].** <li>
a1c0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
a1d0: 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC8K].** <li>
a1e0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
a1f0: 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69  TOMIC16K].** <li
a200: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
a210: 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c  ATOMIC32K].** <l
a220: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
a230: 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c  _ATOMIC64K].** <
a240: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
a250: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a  P_SAFE_APPEND].*
a260: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
a270: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d  OCAP_SEQUENTIAL]
a280: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
a290: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
a2a0: 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79  _ATOMIC property
a2b0: 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20   means that all 
a2c0: 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79  writes of.** any
a2d0: 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63   size are atomic
a2e0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
a2f0: 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61  CAP_ATOMICnnn va
a300: 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61  lues.** mean tha
a310: 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63  t writes of bloc
a320: 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20  ks that are nnn 
a330: 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e  bytes in size an
a340: 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64  d.** are aligned
a350: 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77   to an address w
a360: 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67  hich is an integ
a370: 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a  er multiple of.*
a380: 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63  * nnn are atomic
a390: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
a3a0: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20  CAP_SAFE_APPEND 
a3b0: 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74  value means.** t
a3c0: 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73  hat when data is
a3d0: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66   appended to a f
a3e0: 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73  ile, the data is
a3f0: 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72   appended.** fir
a400: 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65  st then the size
a410: 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20   of the file is 
a420: 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20  extended, never 
a430: 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79  the other.** way
a440: 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51   around.  The SQ
a450: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
a460: 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d  NTIAL property m
a470: 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66  eans that.** inf
a480: 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74  ormation is writ
a490: 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74  ten to disk in t
a4a0: 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73  he same order as
a4b0: 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72   calls.** to xWr
a4c0: 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  ite()..**.** If 
a4d0: 78 52 65 61 64 28 29 20 72 65 74 75 72 6e 73 20  xRead() returns 
a4e0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f  SQLITE_IOERR_SHO
a4f0: 52 54 5f 52 45 41 44 20 69 74 20 6d 75 73 74 20  RT_READ it must 
a500: 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20  also fill.** in 
a510: 74 68 65 20 75 6e 72 65 61 64 20 70 6f 72 74 69  the unread porti
a520: 6f 6e 73 20 6f 66 20 74 68 65 20 62 75 66 66 65  ons of the buffe
a530: 72 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 20 41  r with zeros.  A
a540: 20 56 46 53 20 74 68 61 74 0a 2a 2a 20 66 61 69   VFS that.** fai
a550: 6c 73 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20  ls to zero-fill 
a560: 73 68 6f 72 74 20 72 65 61 64 73 20 6d 69 67 68  short reads migh
a570: 74 20 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e 20  t seem to work. 
a580: 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61 69   However,.** fai
a590: 6c 75 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69 6c  lure to zero-fil
a5a0: 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 77 69  l short reads wi
a5b0: 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c 65  ll eventually le
a5c0: 61 64 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61 73  ad to.** databas
a5d0: 65 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f  e corruption..*/
a5e0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
a5f0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
a600: 64 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  ds sqlite3_io_me
a610: 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71  thods;.struct sq
a620: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
a630: 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f   {.  int iVersio
a640: 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73  n;.  int (*xClos
a650: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
a660: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61 64  );.  int (*xRead
a670: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
a680: 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74   void*, int iAmt
a690: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
a6a0: 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a  iOfst);.  int (*
a6b0: 78 57 72 69 74 65 29 28 73 71 6c 69 74 65 33 5f  xWrite)(sqlite3_
a6c0: 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  file*, const voi
a6d0: 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71  d*, int iAmt, sq
a6e0: 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73  lite3_int64 iOfs
a6f0: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72 75  t);.  int (*xTru
a700: 6e 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f 66  ncate)(sqlite3_f
a710: 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ile*, sqlite3_in
a720: 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74  t64 size);.  int
a730: 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65   (*xSync)(sqlite
a740: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61  3_file*, int fla
a750: 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69  gs);.  int (*xFi
a760: 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f  leSize)(sqlite3_
a770: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
a780: 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20  nt64 *pSize);.  
a790: 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c  int (*xLock)(sql
a7a0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29  ite3_file*, int)
a7b0: 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63  ;.  int (*xUnloc
a7c0: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  k)(sqlite3_file*
a7d0: 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a  , int);.  int (*
a7e0: 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f  xCheckReservedLo
a7f0: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
a800: 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29  *, int *pResOut)
a810: 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 43  ;.  int (*xFileC
a820: 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f  ontrol)(sqlite3_
a830: 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76  file*, int op, v
a840: 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e  oid *pArg);.  in
a850: 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a 65 29  t (*xSectorSize)
a860: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b  (sqlite3_file*);
a870: 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69 63 65  .  int (*xDevice
a880: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 29  Characteristics)
a890: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b  (sqlite3_file*);
a8a0: 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62  .  /* Methods ab
a8b0: 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f  ove are valid fo
a8c0: 72 20 76 65 72 73 69 6f 6e 20 31 20 2a 2f 0a 20  r version 1 */. 
a8d0: 20 69 6e 74 20 28 2a 78 53 68 6d 4d 61 70 29 28   int (*xShmMap)(
a8e0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
a8f0: 6e 74 20 69 50 67 2c 20 69 6e 74 20 70 67 73 7a  nt iPg, int pgsz
a900: 2c 20 69 6e 74 2c 20 76 6f 69 64 20 76 6f 6c 61  , int, void vola
a910: 74 69 6c 65 2a 2a 29 3b 0a 20 20 69 6e 74 20 28  tile**);.  int (
a920: 2a 78 53 68 6d 4c 6f 63 6b 29 28 73 71 6c 69 74  *xShmLock)(sqlit
a930: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 66  e3_file*, int of
a940: 66 73 65 74 2c 20 69 6e 74 20 6e 2c 20 69 6e 74  fset, int n, int
a950: 20 66 6c 61 67 73 29 3b 0a 20 20 76 6f 69 64 20   flags);.  void 
a960: 28 2a 78 53 68 6d 42 61 72 72 69 65 72 29 28 73  (*xShmBarrier)(s
a970: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20  qlite3_file*);. 
a980: 20 69 6e 74 20 28 2a 78 53 68 6d 55 6e 6d 61 70   int (*xShmUnmap
a990: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
a9a0: 20 69 6e 74 20 64 65 6c 65 74 65 46 6c 61 67 29   int deleteFlag)
a9b0: 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61  ;.  /* Methods a
a9c0: 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66  bove are valid f
a9d0: 6f 72 20 76 65 72 73 69 6f 6e 20 32 20 2a 2f 0a  or version 2 */.
a9e0: 20 20 69 6e 74 20 28 2a 78 46 65 74 63 68 29 28    int (*xFetch)(
a9f0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73  sqlite3_file*, s
aa00: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66  qlite3_int64 iOf
aa10: 73 74 2c 20 69 6e 74 20 69 41 6d 74 2c 20 76 6f  st, int iAmt, vo
aa20: 69 64 20 2a 2a 70 70 29 3b 0a 20 20 69 6e 74 20  id **pp);.  int 
aa30: 28 2a 78 55 6e 66 65 74 63 68 29 28 73 71 6c 69  (*xUnfetch)(sqli
aa40: 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74  te3_file*, sqlit
aa50: 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c 20  e3_int64 iOfst, 
aa60: 76 6f 69 64 20 2a 70 29 3b 0a 20 20 2f 2a 20 4d  void *p);.  /* M
aa70: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
aa80: 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69   valid for versi
aa90: 6f 6e 20 33 20 2a 2f 0a 20 20 2f 2a 20 41 64 64  on 3 */.  /* Add
aaa0: 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20  itional methods 
aab0: 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
aac0: 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
aad0: 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
aae0: 49 33 52 45 46 3a 20 53 74 61 6e 64 61 72 64 20  I3REF: Standard 
aaf0: 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63  File Control Opc
ab00: 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  odes.** KEYWORDS
ab10: 3a 20 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  : {file control 
ab20: 6f 70 63 6f 64 65 73 7d 20 7b 66 69 6c 65 20 63  opcodes} {file c
ab30: 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 7d 0a 2a  ontrol opcode}.*
ab40: 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67  *.** These integ
ab50: 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65  er constants are
ab60: 20 6f 70 63 6f 64 65 73 20 66 6f 72 20 74 68 65   opcodes for the
ab70: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65   xFileControl me
ab80: 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  thod.** of the [
ab90: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
aba0: 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20 66  ds] object and f
abb0: 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  or the [sqlite3_
abc0: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a  file_control()].
abd0: 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  ** interface..**
abe0: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
abf0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c  [[SQLITE_FCNTL_L
ac00: 4f 43 4b 53 54 41 54 45 5d 5d 0a 2a 2a 20 54 68  OCKSTATE]].** Th
ac10: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
ac20: 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64  LOCKSTATE] opcod
ac30: 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65  e is used for de
ac40: 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a  bugging.  This.*
ac50: 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20  * opcode causes 
ac60: 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  the xFileControl
ac70: 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74 65   method to write
ac80: 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61   the current sta
ac90: 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63  te of.** the loc
aca0: 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  k (one of [SQLIT
acb0: 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53  E_LOCK_NONE], [S
acc0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45  QLITE_LOCK_SHARE
acd0: 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c  D],.** [SQLITE_L
ace0: 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b  OCK_RESERVED], [
acf0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44  SQLITE_LOCK_PEND
ad00: 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  ING], or [SQLITE
ad10: 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d  _LOCK_EXCLUSIVE]
ad20: 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74  ).** into an int
ad30: 65 67 65 72 20 74 68 61 74 20 74 68 65 20 70 41  eger that the pA
ad40: 72 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e  rg argument poin
ad50: 74 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70 61  ts to. This capa
ad60: 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73 65  bility.** is use
ad70: 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67  d during testing
ad80: 20 61 6e 64 20 69 73 20 6f 6e 6c 79 20 61 76 61   and is only ava
ad90: 69 6c 61 62 6c 65 20 77 68 65 6e 20 74 68 65 20  ilable when the 
ada0: 53 51 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20 63  SQLITE_TEST.** c
adb0: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
adc0: 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a  on is used..**.*
add0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
ade0: 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 5d  CNTL_SIZE_HINT]]
adf0: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
ae00: 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d  FCNTL_SIZE_HINT]
ae10: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
ae20: 62 79 20 53 51 4c 69 74 65 20 74 6f 20 67 69 76  by SQLite to giv
ae30: 65 20 74 68 65 20 56 46 53 0a 2a 2a 20 6c 61 79  e the VFS.** lay
ae40: 65 72 20 61 20 68 69 6e 74 20 6f 66 20 68 6f 77  er a hint of how
ae50: 20 6c 61 72 67 65 20 74 68 65 20 64 61 74 61 62   large the datab
ae60: 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 67 72  ase file will gr
ae70: 6f 77 20 74 6f 20 62 65 20 64 75 72 69 6e 67 20  ow to be during 
ae80: 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 74  the.** current t
ae90: 72 61 6e 73 61 63 74 69 6f 6e 2e 20 20 54 68 69  ransaction.  Thi
aea0: 73 20 68 69 6e 74 20 69 73 20 6e 6f 74 20 67 75  s hint is not gu
aeb0: 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20 61  aranteed to be a
aec0: 63 63 75 72 61 74 65 20 62 75 74 20 69 74 0a 2a  ccurate but it.*
aed0: 2a 20 69 73 20 6f 66 74 65 6e 20 63 6c 6f 73 65  * is often close
aee0: 2e 20 20 54 68 65 20 75 6e 64 65 72 6c 79 69 6e  .  The underlyin
aef0: 67 20 56 46 53 20 6d 69 67 68 74 20 63 68 6f 6f  g VFS might choo
af00: 73 65 20 74 6f 20 70 72 65 61 6c 6c 6f 63 61 74  se to preallocat
af10: 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69  e database.** fi
af20: 6c 65 20 73 70 61 63 65 20 62 61 73 65 64 20 6f  le space based o
af30: 6e 20 74 68 69 73 20 68 69 6e 74 20 69 6e 20 6f  n this hint in o
af40: 72 64 65 72 20 74 6f 20 68 65 6c 70 20 77 72 69  rder to help wri
af50: 74 65 73 20 74 6f 20 74 68 65 20 64 61 74 61 62  tes to the datab
af60: 61 73 65 0a 2a 2a 20 66 69 6c 65 20 72 75 6e 20  ase.** file run 
af70: 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  faster..**.** <l
af80: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
af90: 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 5d 0a 2a 2a  _CHUNK_SIZE]].**
afa0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
afb0: 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f  TL_CHUNK_SIZE] o
afc0: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f  pcode is used to
afd0: 20 72 65 71 75 65 73 74 20 74 68 61 74 20 74 68   request that th
afe0: 65 20 56 46 53 0a 2a 2a 20 65 78 74 65 6e 64 73  e VFS.** extends
aff0: 20 61 6e 64 20 74 72 75 6e 63 61 74 65 73 20 74   and truncates t
b000: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
b010: 20 69 6e 20 63 68 75 6e 6b 73 20 6f 66 20 61 20   in chunks of a 
b020: 73 69 7a 65 20 73 70 65 63 69 66 69 65 64 0a 2a  size specified.*
b030: 2a 20 62 79 20 74 68 65 20 75 73 65 72 2e 20 54  * by the user. T
b040: 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  he fourth argume
b050: 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  nt to [sqlite3_f
b060: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 73  ile_control()] s
b070: 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69 6e 74 20  hould .** point 
b080: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 28 74  to an integer (t
b090: 79 70 65 20 69 6e 74 29 20 63 6f 6e 74 61 69 6e  ype int) contain
b0a0: 69 6e 67 20 74 68 65 20 6e 65 77 20 63 68 75 6e  ing the new chun
b0b0: 6b 2d 73 69 7a 65 20 74 6f 20 75 73 65 0a 2a 2a  k-size to use.**
b0c0: 20 66 6f 72 20 74 68 65 20 6e 6f 6d 69 6e 61 74   for the nominat
b0d0: 65 64 20 64 61 74 61 62 61 73 65 2e 20 41 6c 6c  ed database. All
b0e0: 6f 63 61 74 69 6e 67 20 64 61 74 61 62 61 73 65  ocating database
b0f0: 20 66 69 6c 65 20 73 70 61 63 65 20 69 6e 20 6c   file space in l
b100: 61 72 67 65 0a 2a 2a 20 63 68 75 6e 6b 73 20 28  arge.** chunks (
b110: 73 61 79 20 31 4d 42 20 61 74 20 61 20 74 69 6d  say 1MB at a tim
b120: 65 29 2c 20 6d 61 79 20 72 65 64 75 63 65 20 66  e), may reduce f
b130: 69 6c 65 2d 73 79 73 74 65 6d 20 66 72 61 67 6d  ile-system fragm
b140: 65 6e 74 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20  entation and.** 
b150: 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61  improve performa
b160: 6e 63 65 20 6f 6e 20 73 6f 6d 65 20 73 79 73 74  nce on some syst
b170: 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ems..**.** <li>[
b180: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49  [SQLITE_FCNTL_FI
b190: 4c 45 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20  LE_POINTER]].** 
b1a0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
b1b0: 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 20  L_FILE_POINTER] 
b1c0: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74  opcode is used t
b1d0: 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f 69 6e 74  o obtain a point
b1e0: 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71  er.** to the [sq
b1f0: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
b200: 63 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ct associated wi
b210: 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  th a particular 
b220: 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
b230: 65 63 74 69 6f 6e 2e 20 20 53 65 65 20 74 68 65  ection.  See the
b240: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
b250: 6f 6e 74 72 6f 6c 28 29 5d 20 64 6f 63 75 6d 65  ontrol()] docume
b260: 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 61  ntation for.** a
b270: 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
b280: 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  ation..**.** <li
b290: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
b2a0: 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 5d 0a 2a  SYNC_OMITTED]].*
b2b0: 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 69 6e 20 75  * No longer in u
b2c0: 73 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  se..**.** <li>[[
b2d0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e  SQLITE_FCNTL_SYN
b2e0: 43 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  C]].** The [SQLI
b2f0: 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d 20 6f  TE_FCNTL_SYNC] o
b300: 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61 74  pcode is generat
b310: 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79  ed internally by
b320: 20 53 51 4c 69 74 65 20 61 6e 64 0a 2a 2a 20 73   SQLite and.** s
b330: 65 6e 74 20 74 6f 20 74 68 65 20 56 46 53 20 69  ent to the VFS i
b340: 6d 6d 65 64 69 61 74 65 6c 79 20 62 65 66 6f 72  mmediately befor
b350: 65 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68  e the xSync meth
b360: 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e  od is invoked on
b370: 20 61 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 66   a.** database f
b380: 69 6c 65 20 64 65 73 63 72 69 70 74 6f 72 2e 20  ile descriptor. 
b390: 4f 72 2c 20 69 66 20 74 68 65 20 78 53 79 6e 63  Or, if the xSync
b3a0: 20 6d 65 74 68 6f 64 20 69 73 20 6e 6f 74 20 69   method is not i
b3b0: 6e 76 6f 6b 65 64 20 0a 2a 2a 20 62 65 63 61 75  nvoked .** becau
b3c0: 73 65 20 74 68 65 20 75 73 65 72 20 68 61 73 20  se the user has 
b3d0: 63 6f 6e 66 69 67 75 72 65 64 20 53 51 4c 69 74  configured SQLit
b3e0: 65 20 77 69 74 68 20 0a 2a 2a 20 5b 50 52 41 47  e with .** [PRAG
b3f0: 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 20 7c  MA synchronous |
b400: 20 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e   PRAGMA synchron
b410: 6f 75 73 3d 4f 46 46 5d 20 69 74 20 69 73 20 69  ous=OFF] it is i
b420: 6e 76 6f 6b 65 64 20 69 6e 20 70 6c 61 63 65 20  nvoked in place 
b430: 0a 2a 2a 20 6f 66 20 74 68 65 20 78 53 79 6e 63  .** of the xSync
b440: 20 6d 65 74 68 6f 64 2e 20 49 6e 20 6d 6f 73 74   method. In most
b450: 20 63 61 73 65 73 2c 20 74 68 65 20 70 6f 69 6e   cases, the poin
b460: 74 65 72 20 61 72 67 75 6d 65 6e 74 20 70 61 73  ter argument pas
b470: 73 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 69 73  sed with.** this
b480: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73   file-control is
b490: 20 4e 55 4c 4c 2e 20 48 6f 77 65 76 65 72 2c 20   NULL. However, 
b4a0: 69 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  if the database 
b4b0: 66 69 6c 65 20 69 73 20 62 65 69 6e 67 20 73 79  file is being sy
b4c0: 6e 63 65 64 0a 2a 2a 20 61 73 20 70 61 72 74 20  nced.** as part 
b4d0: 6f 66 20 61 20 6d 75 6c 74 69 2d 64 61 74 61 62  of a multi-datab
b4e0: 61 73 65 20 63 6f 6d 6d 69 74 2c 20 74 68 65 20  ase commit, the 
b4f0: 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20  argument points 
b500: 74 6f 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61  to a nul-termina
b510: 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f  ted.** string co
b520: 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 74 72 61  ntaining the tra
b530: 6e 73 61 63 74 69 6f 6e 73 20 6d 61 73 74 65 72  nsactions master
b540: 2d 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 6e 61  -journal file na
b550: 6d 65 2e 20 56 46 53 65 73 20 74 68 61 74 20 0a  me. VFSes that .
b560: 2a 2a 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74  ** do not need t
b570: 68 69 73 20 73 69 67 6e 61 6c 20 73 68 6f 75 6c  his signal shoul
b580: 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72  d silently ignor
b590: 65 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20 41  e this opcode. A
b5a0: 70 70 6c 69 63 61 74 69 6f 6e 73 20 0a 2a 2a 20  pplications .** 
b5b0: 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 20  should not call 
b5c0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
b5d0: 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74 68  ntrol()] with th
b5e0: 69 73 20 6f 70 63 6f 64 65 20 61 73 20 64 6f 69  is opcode as doi
b5f0: 6e 67 20 73 6f 20 6d 61 79 20 0a 2a 2a 20 64 69  ng so may .** di
b600: 73 72 75 70 74 20 74 68 65 20 6f 70 65 72 61 74  srupt the operat
b610: 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63 69  ion of the speci
b620: 61 6c 69 7a 65 64 20 56 46 53 65 73 20 74 68 61  alized VFSes tha
b630: 74 20 64 6f 20 72 65 71 75 69 72 65 20 69 74 2e  t do require it.
b640: 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53    .**.** <li>[[S
b650: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d  QLITE_FCNTL_COMM
b660: 49 54 5f 50 48 41 53 45 54 57 4f 5d 5d 0a 2a 2a  IT_PHASETWO]].**
b670: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
b680: 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54  TL_COMMIT_PHASET
b690: 57 4f 5d 20 6f 70 63 6f 64 65 20 69 73 20 67 65  WO] opcode is ge
b6a0: 6e 65 72 61 74 65 64 20 69 6e 74 65 72 6e 61 6c  nerated internal
b6b0: 6c 79 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20  ly by SQLite.** 
b6c0: 61 6e 64 20 73 65 6e 74 20 74 6f 20 74 68 65 20  and sent to the 
b6d0: 56 46 53 20 61 66 74 65 72 20 61 20 74 72 61 6e  VFS after a tran
b6e0: 73 61 63 74 69 6f 6e 20 68 61 73 20 62 65 65 6e  saction has been
b6f0: 20 63 6f 6d 6d 69 74 74 65 64 20 69 6d 6d 65 64   committed immed
b700: 69 61 74 65 6c 79 0a 2a 2a 20 62 75 74 20 62 65  iately.** but be
b710: 66 6f 72 65 20 74 68 65 20 64 61 74 61 62 61 73  fore the databas
b720: 65 20 69 73 20 75 6e 6c 6f 63 6b 65 64 2e 20 56  e is unlocked. V
b730: 46 53 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74  FSes that do not
b740: 20 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e 61   need this signa
b750: 6c 0a 2a 2a 20 73 68 6f 75 6c 64 20 73 69 6c 65  l.** should sile
b760: 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 73  ntly ignore this
b770: 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69 63 61   opcode. Applica
b780: 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74  tions should not
b790: 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65   call.** [sqlite
b7a0: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
b7b0: 5d 20 77 69 74 68 20 74 68 69 73 20 6f 70 63 6f  ] with this opco
b7c0: 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d  de as doing so m
b7d0: 61 79 20 64 69 73 72 75 70 74 20 74 68 65 20 0a  ay disrupt the .
b7e0: 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20  ** operation of 
b7f0: 74 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20  the specialized 
b800: 56 46 53 65 73 20 74 68 61 74 20 64 6f 20 72 65  VFSes that do re
b810: 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a  quire it.  .**.*
b820: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
b830: 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45  CNTL_WIN32_AV_RE
b840: 54 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  TRY]].** ^The [S
b850: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33  QLITE_FCNTL_WIN3
b860: 32 5f 41 56 5f 52 45 54 52 59 5d 20 6f 70 63 6f  2_AV_RETRY] opco
b870: 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f  de is used to co
b880: 6e 66 69 67 75 72 65 20 61 75 74 6f 6d 61 74 69  nfigure automati
b890: 63 0a 2a 2a 20 72 65 74 72 79 20 63 6f 75 6e 74  c.** retry count
b8a0: 73 20 61 6e 64 20 69 6e 74 65 72 76 61 6c 73 20  s and intervals 
b8b0: 66 6f 72 20 63 65 72 74 61 69 6e 20 64 69 73 6b  for certain disk
b8c0: 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20   I/O operations 
b8d0: 66 6f 72 20 74 68 65 0a 2a 2a 20 77 69 6e 64 6f  for the.** windo
b8e0: 77 73 20 5b 56 46 53 5d 20 69 6e 20 6f 72 64 65  ws [VFS] in orde
b8f0: 72 20 74 6f 20 70 72 6f 76 69 64 65 20 72 6f 62  r to provide rob
b900: 75 73 74 6e 65 73 73 20 69 6e 20 74 68 65 20 70  ustness in the p
b910: 72 65 73 65 6e 63 65 20 6f 66 0a 2a 2a 20 61 6e  resence of.** an
b920: 74 69 2d 76 69 72 75 73 20 70 72 6f 67 72 61 6d  ti-virus program
b930: 73 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c 20  s.  By default, 
b940: 74 68 65 20 77 69 6e 64 6f 77 73 20 56 46 53 20  the windows VFS 
b950: 77 69 6c 6c 20 72 65 74 72 79 20 66 69 6c 65 20  will retry file 
b960: 72 65 61 64 2c 0a 2a 2a 20 66 69 6c 65 20 77 72  read,.** file wr
b970: 69 74 65 2c 20 61 6e 64 20 66 69 6c 65 20 64 65  ite, and file de
b980: 6c 65 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20  lete operations 
b990: 75 70 20 74 6f 20 31 30 20 74 69 6d 65 73 2c 20  up to 10 times, 
b9a0: 77 69 74 68 20 61 20 64 65 6c 61 79 0a 2a 2a 20  with a delay.** 
b9b0: 6f 66 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e  of 25 millisecon
b9c0: 64 73 20 62 65 66 6f 72 65 20 74 68 65 20 66 69  ds before the fi
b9d0: 72 73 74 20 72 65 74 72 79 20 61 6e 64 20 77 69  rst retry and wi
b9e0: 74 68 20 74 68 65 20 64 65 6c 61 79 20 69 6e 63  th the delay inc
b9f0: 72 65 61 73 69 6e 67 0a 2a 2a 20 62 79 20 61 6e  reasing.** by an
ba00: 20 61 64 64 69 74 69 6f 6e 61 6c 20 32 35 20 6d   additional 25 m
ba10: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 77 69 74 68  illiseconds with
ba20: 20 65 61 63 68 20 73 75 62 73 65 71 75 65 6e 74   each subsequent
ba30: 20 72 65 74 72 79 2e 20 20 54 68 69 73 0a 2a 2a   retry.  This.**
ba40: 20 6f 70 63 6f 64 65 20 61 6c 6c 6f 77 73 20 74   opcode allows t
ba50: 68 65 73 65 20 74 77 6f 20 76 61 6c 75 65 73 20  hese two values 
ba60: 28 31 30 20 72 65 74 72 69 65 73 20 61 6e 64 20  (10 retries and 
ba70: 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  25 milliseconds 
ba80: 6f 66 20 64 65 6c 61 79 29 0a 2a 2a 20 74 6f 20  of delay).** to 
ba90: 62 65 20 61 64 6a 75 73 74 65 64 2e 20 20 54 68  be adjusted.  Th
baa0: 65 20 76 61 6c 75 65 73 20 61 72 65 20 63 68 61  e values are cha
bab0: 6e 67 65 64 20 66 6f 72 20 61 6c 6c 20 64 61 74  nged for all dat
bac0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
bad0: 73 0a 2a 2a 20 77 69 74 68 69 6e 20 74 68 65 20  s.** within the 
bae0: 73 61 6d 65 20 70 72 6f 63 65 73 73 2e 20 20 54  same process.  T
baf0: 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  he argument is a
bb00: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 61   pointer to an a
bb10: 72 72 61 79 20 6f 66 20 74 77 6f 0a 2a 2a 20 69  rray of two.** i
bb20: 6e 74 65 67 65 72 73 20 77 68 65 72 65 20 74 68  ntegers where th
bb30: 65 20 66 69 72 73 74 20 69 6e 74 65 67 65 72 20  e first integer 
bb40: 69 20 74 68 65 20 6e 65 77 20 72 65 74 72 79 20  i the new retry 
bb50: 63 6f 75 6e 74 20 61 6e 64 20 74 68 65 20 73 65  count and the se
bb60: 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20  cond.** integer 
bb70: 69 73 20 74 68 65 20 64 65 6c 61 79 2e 20 20 49  is the delay.  I
bb80: 66 20 65 69 74 68 65 72 20 69 6e 74 65 67 65 72  f either integer
bb90: 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
bba0: 65 6e 20 74 68 65 20 73 65 74 74 69 6e 67 0a 2a  en the setting.*
bbb0: 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64  * is not changed
bbc0: 20 62 75 74 20 69 6e 73 74 65 61 64 20 74 68 65   but instead the
bbd0: 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20   prior value of 
bbe0: 74 68 61 74 20 73 65 74 74 69 6e 67 20 69 73 20  that setting is 
bbf0: 77 72 69 74 74 65 6e 0a 2a 2a 20 69 6e 74 6f 20  written.** into 
bc00: 74 68 65 20 61 72 72 61 79 20 65 6e 74 72 79 2c  the array entry,
bc10: 20 61 6c 6c 6f 77 69 6e 67 20 74 68 65 20 63 75   allowing the cu
bc20: 72 72 65 6e 74 20 72 65 74 72 79 20 73 65 74 74  rrent retry sett
bc30: 69 6e 67 73 20 74 6f 20 62 65 0a 2a 2a 20 69 6e  ings to be.** in
bc40: 74 65 72 72 6f 67 61 74 65 64 2e 20 20 54 68 65  terrogated.  The
bc50: 20 7a 44 62 4e 61 6d 65 20 70 61 72 61 6d 65 74   zDbName paramet
bc60: 65 72 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a  er is ignored..*
bc70: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
bc80: 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f  E_FCNTL_PERSIST_
bc90: 57 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  WAL]].** ^The [S
bca0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53  QLITE_FCNTL_PERS
bcb0: 49 53 54 5f 57 41 4c 5d 20 6f 70 63 6f 64 65 20  IST_WAL] opcode 
bcc0: 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f  is used to set o
bcd0: 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 70  r query the.** p
bce0: 65 72 73 69 73 74 65 6e 74 20 5b 57 41 4c 20 7c  ersistent [WAL |
bcf0: 20 57 72 69 74 65 20 41 68 65 61 64 20 4c 6f 67   Write Ahead Log
bd00: 5d 20 73 65 74 74 69 6e 67 2e 20 20 42 79 20 64  ] setting.  By d
bd10: 65 66 61 75 6c 74 2c 20 74 68 65 20 61 75 78 69  efault, the auxi
bd20: 6c 69 61 72 79 0a 2a 2a 20 77 72 69 74 65 20 61  liary.** write a
bd30: 68 65 61 64 20 6c 6f 67 20 61 6e 64 20 73 68 61  head log and sha
bd40: 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73  red memory files
bd50: 20 75 73 65 64 20 66 6f 72 20 74 72 61 6e 73 61   used for transa
bd60: 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 0a 2a 2a  ction control.**
bd70: 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c   are automatical
bd80: 6c 79 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20  ly deleted when 
bd90: 74 68 65 20 6c 61 74 65 73 74 20 63 6f 6e 6e 65  the latest conne
bda0: 63 74 69 6f 6e 20 74 6f 20 74 68 65 20 64 61 74  ction to the dat
bdb0: 61 62 61 73 65 0a 2a 2a 20 63 6c 6f 73 65 73 2e  abase.** closes.
bdc0: 20 20 53 65 74 74 69 6e 67 20 70 65 72 73 69 73    Setting persis
bdd0: 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 63 61  tent WAL mode ca
bde0: 75 73 65 73 20 74 68 6f 73 65 20 66 69 6c 65 73  uses those files
bdf0: 20 74 6f 20 70 65 72 73 69 73 74 20 61 66 74 65   to persist afte
be00: 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20 50 65 72  r.** close.  Per
be10: 73 69 73 74 69 6e 67 20 74 68 65 20 66 69 6c 65  sisting the file
be20: 73 20 69 73 20 75 73 65 66 75 6c 20 77 68 65 6e  s is useful when
be30: 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 65 73   other processes
be40: 20 74 68 61 74 20 64 6f 20 6e 6f 74 0a 2a 2a 20   that do not.** 
be50: 68 61 76 65 20 77 72 69 74 65 20 70 65 72 6d 69  have write permi
be60: 73 73 69 6f 6e 20 6f 6e 20 74 68 65 20 64 69 72  ssion on the dir
be70: 65 63 74 6f 72 79 20 63 6f 6e 74 61 69 6e 69 6e  ectory containin
be80: 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  g the database f
be90: 69 6c 65 20 77 61 6e 74 0a 2a 2a 20 74 6f 20 72  ile want.** to r
bea0: 65 61 64 20 74 68 65 20 64 61 74 61 62 61 73 65  ead the database
beb0: 20 66 69 6c 65 2c 20 61 73 20 74 68 65 20 57 41   file, as the WA
bec0: 4c 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d  L and shared mem
bed0: 6f 72 79 20 66 69 6c 65 73 20 6d 75 73 74 20 65  ory files must e
bee0: 78 69 73 74 0a 2a 2a 20 69 6e 20 6f 72 64 65 72  xist.** in order
bef0: 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 73   for the databas
bf00: 65 20 74 6f 20 62 65 20 72 65 61 64 61 62 6c 65  e to be readable
bf10: 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20 70 61  .  The fourth pa
bf20: 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73  rameter to.** [s
bf30: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
bf40: 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20  rol()] for this 
bf50: 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65  opcode should be
bf60: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
bf70: 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61   integer..** Tha
bf80: 74 20 69 6e 74 65 67 65 72 20 69 73 20 30 20 74  t integer is 0 t
bf90: 6f 20 64 69 73 61 62 6c 65 20 70 65 72 73 69 73  o disable persis
bfa0: 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 6f 72  tent WAL mode or
bfb0: 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 70 65 72   1 to enable per
bfc0: 73 69 73 74 65 6e 74 0a 2a 2a 20 57 41 4c 20 6d  sistent.** WAL m
bfd0: 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74  ode.  If the int
bfe0: 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e  eger is -1, then
bff0: 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 74   it is overwritt
c000: 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 72  en with the curr
c010: 65 6e 74 0a 2a 2a 20 57 41 4c 20 70 65 72 73 69  ent.** WAL persi
c020: 73 74 65 6e 63 65 20 73 65 74 74 69 6e 67 2e 0a  stence setting..
c030: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
c040: 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41  TE_FCNTL_POWERSA
c050: 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a  FE_OVERWRITE]].*
c060: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
c070: 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f  CNTL_POWERSAFE_O
c080: 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65  VERWRITE] opcode
c090: 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20   is used to set 
c0a0: 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20  or query the.** 
c0b0: 70 65 72 73 69 73 74 65 6e 74 20 22 70 6f 77 65  persistent "powe
c0c0: 72 73 61 66 65 2d 6f 76 65 72 77 72 69 74 65 22  rsafe-overwrite"
c0d0: 20 6f 72 20 22 50 53 4f 57 22 20 73 65 74 74 69   or "PSOW" setti
c0e0: 6e 67 2e 20 20 54 68 65 20 50 53 4f 57 20 73 65  ng.  The PSOW se
c0f0: 74 74 69 6e 67 0a 2a 2a 20 64 65 74 65 72 6d 69  tting.** determi
c100: 6e 65 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  nes the [SQLITE_
c110: 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f  IOCAP_POWERSAFE_
c120: 4f 56 45 52 57 52 49 54 45 5d 20 62 69 74 20 6f  OVERWRITE] bit o
c130: 66 20 74 68 65 0a 2a 2a 20 78 44 65 76 69 63 65  f the.** xDevice
c140: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20  Characteristics 
c150: 6d 65 74 68 6f 64 73 2e 20 54 68 65 20 66 6f 75  methods. The fou
c160: 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
c170: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
c180: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72  e_control()] for
c190: 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68 6f   this opcode sho
c1a0: 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65 72  uld be a pointer
c1b0: 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a   to an integer..
c1c0: 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72 20  ** That integer 
c1d0: 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20  is 0 to disable 
c1e0: 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65  zero-damage mode
c1f0: 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20   or 1 to enable 
c200: 7a 65 72 6f 2d 64 61 6d 61 67 65 0a 2a 2a 20 6d  zero-damage.** m
c210: 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74  ode.  If the int
c220: 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e  eger is -1, then
c230: 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 74   it is overwritt
c240: 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 72  en with the curr
c250: 65 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64 61 6d 61  ent.** zero-dama
c260: 67 65 20 6d 6f 64 65 20 73 65 74 74 69 6e 67 2e  ge mode setting.
c270: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
c280: 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52  ITE_FCNTL_OVERWR
c290: 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  ITE]].** ^The [S
c2a0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52  QLITE_FCNTL_OVER
c2b0: 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73  WRITE] opcode is
c2c0: 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c 69   invoked by SQLi
c2d0: 74 65 20 61 66 74 65 72 20 6f 70 65 6e 69 6e 67  te after opening
c2e0: 0a 2a 2a 20 61 20 77 72 69 74 65 20 74 72 61 6e  .** a write tran
c2f0: 73 61 63 74 69 6f 6e 20 74 6f 20 69 6e 64 69 63  saction to indic
c300: 61 74 65 20 74 68 61 74 2c 20 75 6e 6c 65 73 73  ate that, unless
c310: 20 69 74 20 69 73 20 72 6f 6c 6c 65 64 20 62 61   it is rolled ba
c320: 63 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a 2a 20 72  ck for some.** r
c330: 65 61 73 6f 6e 2c 20 74 68 65 20 65 6e 74 69 72  eason, the entir
c340: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
c350: 77 69 6c 6c 20 62 65 20 6f 76 65 72 77 72 69 74  will be overwrit
c360: 74 65 6e 20 62 79 20 74 68 65 20 63 75 72 72 65  ten by the curre
c370: 6e 74 20 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69  nt .** transacti
c380: 6f 6e 2e 20 54 68 69 73 20 69 73 20 75 73 65 64  on. This is used
c390: 20 62 79 20 56 41 43 55 55 4d 20 6f 70 65 72 61   by VACUUM opera
c3a0: 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  tions..**.** <li
c3b0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
c3c0: 56 46 53 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 54 68  VFSNAME]].** ^Th
c3d0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
c3e0: 56 46 53 4e 41 4d 45 5d 20 6f 70 63 6f 64 65 20  VFSNAME] opcode 
c3f0: 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
c400: 62 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20  btain the names 
c410: 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46 53 65 73  of.** all [VFSes
c420: 5d 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 61  ] in the VFS sta
c430: 63 6b 2e 20 20 54 68 65 20 6e 61 6d 65 73 20 61  ck.  The names a
c440: 72 65 20 6f 66 20 61 6c 6c 20 56 46 53 20 73 68  re of all VFS sh
c450: 69 6d 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20 66  ims and the.** f
c460: 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c 65 76 65  inal bottom-leve
c470: 6c 20 56 46 53 20 61 72 65 20 77 72 69 74 74 65  l VFS are writte
c480: 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  n into memory ob
c490: 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20  tained from .** 
c4a0: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
c4b0: 29 5d 20 61 6e 64 20 74 68 65 20 72 65 73 75 6c  )] and the resul
c4c0: 74 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 74  t is stored in t
c4d0: 68 65 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c  he char* variabl
c4e0: 65 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 66 6f  e.** that the fo
c4f0: 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f  urth parameter o
c500: 66 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  f [sqlite3_file_
c510: 63 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f 69 6e 74  control()] point
c520: 73 20 74 6f 2e 0a 2a 2a 20 54 68 65 20 63 61 6c  s to..** The cal
c530: 6c 65 72 20 69 73 20 72 65 73 70 6f 6e 73 69 62  ler is responsib
c540: 6c 65 20 66 6f 72 20 66 72 65 65 69 6e 67 20 74  le for freeing t
c550: 68 65 20 6d 65 6d 6f 72 79 20 77 68 65 6e 20 64  he memory when d
c560: 6f 6e 65 2e 20 20 41 73 20 77 69 74 68 0a 2a 2a  one.  As with.**
c570: 20 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e 74 72 6f   all file-contro
c580: 6c 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 72 65  l actions, there
c590: 20 69 73 20 6e 6f 20 67 75 61 72 61 6e 74 65 65   is no guarantee
c5a0: 20 74 68 61 74 20 74 68 69 73 20 77 69 6c 6c 20   that this will 
c5b0: 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 64 6f 20 61  actually.** do a
c5c0: 6e 79 74 68 69 6e 67 2e 20 20 43 61 6c 6c 65 72  nything.  Caller
c5d0: 73 20 73 68 6f 75 6c 64 20 69 6e 69 74 69 61 6c  s should initial
c5e0: 69 7a 65 20 74 68 65 20 63 68 61 72 2a 20 76 61  ize the char* va
c5f0: 72 69 61 62 6c 65 20 74 6f 20 61 20 4e 55 4c 4c  riable to a NULL
c600: 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 20 63  .** pointer in c
c610: 61 73 65 20 74 68 69 73 20 66 69 6c 65 2d 63 6f  ase this file-co
c620: 6e 74 72 6f 6c 20 69 73 20 6e 6f 74 20 69 6d 70  ntrol is not imp
c630: 6c 65 6d 65 6e 74 65 64 2e 20 20 54 68 69 73 20  lemented.  This 
c640: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20  file-control.** 
c650: 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  is intended for 
c660: 64 69 61 67 6e 6f 73 74 69 63 20 75 73 65 20 6f  diagnostic use o
c670: 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  nly..**.** <li>[
c680: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
c690: 41 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68 65 6e 65  AGMA]].** ^Whene
c6a0: 76 65 72 20 61 20 5b 50 52 41 47 4d 41 5d 20 73  ver a [PRAGMA] s
c6b0: 74 61 74 65 6d 65 6e 74 20 69 73 20 70 61 72 73  tatement is pars
c6c0: 65 64 2c 20 61 6e 20 5b 53 51 4c 49 54 45 5f 46  ed, an [SQLITE_F
c6d0: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 0a 2a 2a  CNTL_PRAGMA] .**
c6e0: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73   file control is
c6f0: 20 73 65 6e 74 20 74 6f 20 74 68 65 20 6f 70 65   sent to the ope
c700: 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  n [sqlite3_file]
c710: 20 6f 62 6a 65 63 74 20 63 6f 72 72 65 73 70 6f   object correspo
c720: 6e 64 69 6e 67 0a 2a 2a 20 74 6f 20 74 68 65 20  nding.** to the 
c730: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 6f  database file to
c740: 20 77 68 69 63 68 20 74 68 65 20 70 72 61 67 6d   which the pragm
c750: 61 20 73 74 61 74 65 6d 65 6e 74 20 72 65 66 65  a statement refe
c760: 72 73 2e 20 5e 54 68 65 20 61 72 67 75 6d 65 6e  rs. ^The argumen
c770: 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 53 51 4c  t.** to the [SQL
c780: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
c790: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69  ] file control i
c7a0: 73 20 61 6e 20 61 72 72 61 79 20 6f 66 0a 2a 2a  s an array of.**
c7b0: 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72   pointers to str
c7c0: 69 6e 67 73 20 28 63 68 61 72 2a 2a 29 20 69 6e  ings (char**) in
c7d0: 20 77 68 69 63 68 20 74 68 65 20 73 65 63 6f 6e   which the secon
c7e0: 64 20 65 6c 65 6d 65 6e 74 20 6f 66 20 74 68 65  d element of the
c7f0: 20 61 72 72 61 79 0a 2a 2a 20 69 73 20 74 68 65   array.** is the
c800: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 70 72 61   name of the pra
c810: 67 6d 61 20 61 6e 64 20 74 68 65 20 74 68 69 72  gma and the thir
c820: 64 20 65 6c 65 6d 65 6e 74 20 69 73 20 74 68 65  d element is the
c830: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
c840: 0a 2a 2a 20 70 72 61 67 6d 61 20 6f 72 20 4e 55  .** pragma or NU
c850: 4c 4c 20 69 66 20 74 68 65 20 70 72 61 67 6d 61  LL if the pragma
c860: 20 68 61 73 20 6e 6f 20 61 72 67 75 6d 65 6e 74   has no argument
c870: 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 20  .  ^The handler 
c880: 66 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54  for an.** [SQLIT
c890: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20  E_FCNTL_PRAGMA] 
c8a0: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 63 61 6e  file control can
c8b0: 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d 61 6b 65   optionally make
c8c0: 20 74 68 65 20 66 69 72 73 74 20 65 6c 65 6d 65   the first eleme
c8d0: 6e 74 0a 2a 2a 20 6f 66 20 74 68 65 20 63 68 61  nt.** of the cha
c8e0: 72 2a 2a 20 61 72 67 75 6d 65 6e 74 20 70 6f 69  r** argument poi
c8f0: 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6f  nt to a string o
c900: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
c910: 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d  lite3_mprintf()]
c920: 0a 2a 2a 20 6f 72 20 74 68 65 20 65 71 75 69 76  .** or the equiv
c930: 61 6c 65 6e 74 20 61 6e 64 20 74 68 61 74 20 73  alent and that s
c940: 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 63 6f 6d  tring will becom
c950: 65 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20  e the result of 
c960: 74 68 65 20 70 72 61 67 6d 61 20 6f 72 0a 2a 2a  the pragma or.**
c970: 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
c980: 67 65 20 69 66 20 74 68 65 20 70 72 61 67 6d 61  ge if the pragma
c990: 20 66 61 69 6c 73 2e 20 5e 49 66 20 74 68 65 0a   fails. ^If the.
c9a0: 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ** [SQLITE_FCNTL
c9b0: 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f  _PRAGMA] file co
c9c0: 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53  ntrol returns [S
c9d0: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c  QLITE_NOTFOUND],
c9e0: 20 74 68 65 6e 20 6e 6f 72 6d 61 6c 20 0a 2a 2a   then normal .**
c9f0: 20 5b 50 52 41 47 4d 41 5d 20 70 72 6f 63 65 73   [PRAGMA] proces
ca00: 73 69 6e 67 20 63 6f 6e 74 69 6e 75 65 73 2e 20  sing continues. 
ca10: 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45   ^If the [SQLITE
ca20: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a  _FCNTL_PRAGMA].*
ca30: 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72  * file control r
ca40: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
ca50: 4b 5d 2c 20 74 68 65 6e 20 74 68 65 20 70 61 72  K], then the par
ca60: 73 65 72 20 61 73 73 75 6d 65 73 20 74 68 61 74  ser assumes that
ca70: 20 74 68 65 0a 2a 2a 20 56 46 53 20 68 61 73 20   the.** VFS has 
ca80: 68 61 6e 64 6c 65 64 20 74 68 65 20 50 52 41 47  handled the PRAG
ca90: 4d 41 20 69 74 73 65 6c 66 20 61 6e 64 20 74 68  MA itself and th
caa0: 65 20 70 61 72 73 65 72 20 67 65 6e 65 72 61 74  e parser generat
cab0: 65 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a 20 70 72  es a no-op.** pr
cac0: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
cad0: 20 69 66 20 72 65 73 75 6c 74 20 73 74 72 69 6e   if result strin
cae0: 67 20 69 73 20 4e 55 4c 4c 2c 20 6f 72 20 74 68  g is NULL, or th
caf0: 61 74 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70  at returns a cop
cb00: 79 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75  y.** of the resu
cb10: 6c 74 20 73 74 72 69 6e 67 20 69 66 20 74 68 65  lt string if the
cb20: 20 73 74 72 69 6e 67 20 69 73 20 6e 6f 6e 2d 4e   string is non-N
cb30: 55 4c 4c 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ULL..** ^If the 
cb40: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
cb50: 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72  AGMA] file contr
cb60: 6f 6c 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e  ol returns.** an
cb70: 79 20 72 65 73 75 6c 74 20 63 6f 64 65 20 6f 74  y result code ot
cb80: 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
cb90: 5f 4f 4b 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  _OK] or [SQLITE_
cba0: 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 61 74 20  NOTFOUND], that 
cbb0: 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 74 68  means.** that th
cbc0: 65 20 56 46 53 20 65 6e 63 6f 75 6e 74 65 72 65  e VFS encountere
cbd0: 64 20 61 6e 20 65 72 72 6f 72 20 77 68 69 6c 65  d an error while
cbe0: 20 68 61 6e 64 6c 69 6e 67 20 74 68 65 20 5b 50   handling the [P
cbf0: 52 41 47 4d 41 5d 20 61 6e 64 20 74 68 65 0a 2a  RAGMA] and the.*
cc00: 2a 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 6f 66  * compilation of
cc10: 20 74 68 65 20 50 52 41 47 4d 41 20 66 61 69 6c   the PRAGMA fail
cc20: 73 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e  s with an error.
cc30: 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46    ^The [SQLITE_F
cc40: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20  CNTL_PRAGMA].** 
cc50: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 63 63  file control occ
cc60: 75 72 73 20 61 74 20 74 68 65 20 62 65 67 69 6e  urs at the begin
cc70: 6e 69 6e 67 20 6f 66 20 70 72 61 67 6d 61 20 73  ning of pragma s
cc80: 74 61 74 65 6d 65 6e 74 20 61 6e 61 6c 79 73 69  tatement analysi
cc90: 73 20 61 6e 64 20 73 6f 0a 2a 2a 20 69 74 20 69  s and so.** it i
cca0: 73 20 61 62 6c 65 20 74 6f 20 6f 76 65 72 72 69  s able to overri
ccb0: 64 65 20 62 75 69 6c 74 2d 69 6e 20 5b 50 52 41  de built-in [PRA
ccc0: 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e  GMA] statements.
ccd0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
cce0: 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41  ITE_FCNTL_BUSYHA
ccf0: 4e 44 4c 45 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20  NDLER]].** ^The 
cd00: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55  [SQLITE_FCNTL_BU
cd10: 53 59 48 41 4e 44 4c 45 52 5d 0a 2a 2a 20 66 69  SYHANDLER].** fi
cd20: 6c 65 2d 63 6f 6e 74 72 6f 6c 20 6d 61 79 20 62  le-control may b
cd30: 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c  e invoked by SQL
cd40: 69 74 65 20 6f 6e 20 74 68 65 20 64 61 74 61 62  ite on the datab
cd50: 61 73 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 0a  ase file handle.
cd60: 2a 2a 20 73 68 6f 72 74 6c 79 20 61 66 74 65 72  ** shortly after
cd70: 20 69 74 20 69 73 20 6f 70 65 6e 65 64 20 69 6e   it is opened in
cd80: 20 6f 72 64 65 72 20 74 6f 20 70 72 6f 76 69 64   order to provid
cd90: 65 20 61 20 63 75 73 74 6f 6d 20 56 46 53 20 77  e a custom VFS w
cda0: 69 74 68 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f  ith access.** to
cdb0: 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73   the connections
cdc0: 20 62 75 73 79 2d 68 61 6e 64 6c 65 72 20 63 61   busy-handler ca
cdd0: 6c 6c 62 61 63 6b 2e 20 54 68 65 20 61 72 67 75  llback. The argu
cde0: 6d 65 6e 74 20 69 73 20 6f 66 20 74 79 70 65 20  ment is of type 
cdf0: 28 76 6f 69 64 20 2a 2a 29 0a 2a 2a 20 2d 20 61  (void **).** - a
ce00: 6e 20 61 72 72 61 79 20 6f 66 20 74 77 6f 20 28  n array of two (
ce10: 76 6f 69 64 20 2a 29 20 76 61 6c 75 65 73 2e 20  void *) values. 
ce20: 54 68 65 20 66 69 72 73 74 20 28 76 6f 69 64 20  The first (void 
ce30: 2a 29 20 61 63 74 75 61 6c 6c 79 20 70 6f 69 6e  *) actually poin
ce40: 74 73 0a 2a 2a 20 74 6f 20 61 20 66 75 6e 63 74  ts.** to a funct
ce50: 69 6f 6e 20 6f 66 20 74 79 70 65 20 28 69 6e 74  ion of type (int
ce60: 20 28 2a 29 28 76 6f 69 64 20 2a 29 29 2e 20 49   (*)(void *)). I
ce70: 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 76 6f 6b  n order to invok
ce80: 65 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  e the connection
ce90: 73 0a 2a 2a 20 62 75 73 79 2d 68 61 6e 64 6c 65  s.** busy-handle
cea0: 72 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  r, this function
ceb0: 20 73 68 6f 75 6c 64 20 62 65 20 69 6e 76 6f 6b   should be invok
cec0: 65 64 20 77 69 74 68 20 74 68 65 20 73 65 63 6f  ed with the seco
ced0: 6e 64 20 28 76 6f 69 64 20 2a 29 20 69 6e 0a 2a  nd (void *) in.*
cee0: 2a 20 74 68 65 20 61 72 72 61 79 20 61 73 20 74  * the array as t
cef0: 68 65 20 6f 6e 6c 79 20 61 72 67 75 6d 65 6e 74  he only argument
cf00: 2e 20 49 66 20 69 74 20 72 65 74 75 72 6e 73 20  . If it returns 
cf10: 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74  non-zero, then t
cf20: 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20  he operation.** 
cf30: 73 68 6f 75 6c 64 20 62 65 20 72 65 74 72 69 65  should be retrie
cf40: 64 2e 20 49 66 20 69 74 20 72 65 74 75 72 6e 73  d. If it returns
cf50: 20 7a 65 72 6f 2c 20 74 68 65 20 63 75 73 74 6f   zero, the custo
cf60: 6d 20 56 46 53 20 73 68 6f 75 6c 64 20 61 62 61  m VFS should aba
cf70: 6e 64 6f 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72  ndon the.** curr
cf80: 65 6e 74 20 6f 70 65 72 61 74 69 6f 6e 2e 0a 2a  ent operation..*
cf90: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
cfa0: 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45  E_FCNTL_TEMPFILE
cfb0: 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 41 70 70 6c 69  NAME]].** ^Appli
cfc0: 63 61 74 69 6f 6e 20 63 61 6e 20 69 6e 76 6f 6b  cation can invok
cfd0: 65 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  e the [SQLITE_FC
cfe0: 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45  NTL_TEMPFILENAME
cff0: 5d 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a  ] file-control.*
d000: 2a 20 74 6f 20 68 61 76 65 20 53 51 4c 69 74 65  * to have SQLite
d010: 20 67 65 6e 65 72 61 74 65 20 61 0a 2a 2a 20 74   generate a.** t
d020: 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d  emporary filenam
d030: 65 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65  e using the same
d040: 20 61 6c 67 6f 72 69 74 68 6d 20 74 68 61 74 20   algorithm that 
d050: 69 73 20 66 6f 6c 6c 6f 77 65 64 20 74 6f 20 67  is followed to g
d060: 65 6e 65 72 61 74 65 0a 2a 2a 20 74 65 6d 70 6f  enerate.** tempo
d070: 72 61 72 79 20 66 69 6c 65 6e 61 6d 65 73 20 66  rary filenames f
d080: 6f 72 20 54 45 4d 50 20 74 61 62 6c 65 73 20 61  or TEMP tables a
d090: 6e 64 20 6f 74 68 65 72 20 69 6e 74 65 72 6e 61  nd other interna
d0a0: 6c 20 75 73 65 73 2e 20 20 54 68 65 0a 2a 2a 20  l uses.  The.** 
d0b0: 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20  argument should 
d0c0: 62 65 20 61 20 63 68 61 72 2a 2a 20 77 68 69 63  be a char** whic
d0d0: 68 20 77 69 6c 6c 20 62 65 20 66 69 6c 6c 65 64  h will be filled
d0e0: 20 77 69 74 68 20 74 68 65 20 66 69 6c 65 6e 61   with the filena
d0f0: 6d 65 0a 2a 2a 20 77 72 69 74 74 65 6e 20 69 6e  me.** written in
d100: 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
d110: 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
d120: 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 68 65  _malloc()].  The
d130: 20 63 61 6c 6c 65 72 20 73 68 6f 75 6c 64 0a 2a   caller should.*
d140: 2a 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65  * invoke [sqlite
d150: 33 5f 66 72 65 65 28 29 5d 20 6f 6e 20 74 68 65  3_free()] on the
d160: 20 72 65 73 75 6c 74 20 74 6f 20 61 76 6f 69 64   result to avoid
d170: 20 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 2e 0a   a memory leak..
d180: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
d190: 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49  TE_FCNTL_MMAP_SI
d1a0: 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ZE]].** The [SQL
d1b0: 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53  ITE_FCNTL_MMAP_S
d1c0: 49 5a 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f  IZE] file contro
d1d0: 6c 20 69 73 20 75 73 65 64 20 74 6f 20 71 75 65  l is used to que
d1e0: 72 79 20 6f 72 20 73 65 74 20 74 68 65 0a 2a 2a  ry or set the.**
d1f0: 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
d200: 6f 66 20 62 79 74 65 73 20 74 68 61 74 20 77 69  of bytes that wi
d210: 6c 6c 20 62 65 20 75 73 65 64 20 66 6f 72 20 6d  ll be used for m
d220: 65 6d 6f 72 79 2d 6d 61 70 70 65 64 20 49 2f 4f  emory-mapped I/O
d230: 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e  ..** The argumen
d240: 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  t is a pointer t
d250: 6f 20 61 20 76 61 6c 75 65 20 6f 66 20 74 79 70  o a value of typ
d260: 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  e sqlite3_int64 
d270: 74 68 61 74 0a 2a 2a 20 69 73 20 61 6e 20 61 64  that.** is an ad
d280: 76 69 73 6f 72 79 20 6d 61 78 69 6d 75 6d 20 6e  visory maximum n
d290: 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
d2a0: 6e 20 74 68 65 20 66 69 6c 65 20 74 6f 20 6d 65  n the file to me
d2b0: 6d 6f 72 79 20 6d 61 70 2e 20 20 54 68 65 0a 2a  mory map.  The.*
d2c0: 2a 20 70 6f 69 6e 74 65 72 20 69 73 20 6f 76 65  * pointer is ove
d2d0: 72 77 72 69 74 74 65 6e 20 77 69 74 68 20 74 68  rwritten with th
d2e0: 65 20 6f 6c 64 20 76 61 6c 75 65 2e 20 20 54 68  e old value.  Th
d2f0: 65 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 63  e limit is not c
d300: 68 61 6e 67 65 64 20 69 66 0a 2a 2a 20 74 68 65  hanged if.** the
d310: 20 76 61 6c 75 65 20 6f 72 69 67 69 6e 61 6c 6c   value originall
d320: 79 20 70 6f 69 6e 74 65 64 20 74 6f 20 69 73 20  y pointed to is 
d330: 6e 65 67 61 74 69 76 65 2c 20 61 6e 64 20 73 6f  negative, and so
d340: 20 74 68 65 20 63 75 72 72 65 6e 74 20 6c 69 6d   the current lim
d350: 69 74 20 0a 2a 2a 20 63 61 6e 20 62 65 20 71 75  it .** can be qu
d360: 65 72 69 65 64 20 62 79 20 70 61 73 73 69 6e 67  eried by passing
d370: 20 69 6e 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   in a pointer to
d380: 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62   a negative numb
d390: 65 72 2e 20 20 54 68 69 73 0a 2a 2a 20 66 69 6c  er.  This.** fil
d3a0: 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65  e-control is use
d3b0: 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20  d internally to 
d3c0: 69 6d 70 6c 65 6d 65 6e 74 20 5b 50 52 41 47 4d  implement [PRAGM
d3d0: 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 2e 0a 2a 2a  A mmap_size]..**
d3e0: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
d3f0: 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 5d 0a 2a  _FCNTL_TRACE]].*
d400: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
d410: 4e 54 4c 5f 54 52 41 43 45 5d 20 66 69 6c 65 20  NTL_TRACE] file 
d420: 63 6f 6e 74 72 6f 6c 20 70 72 6f 76 69 64 65 73  control provides
d430: 20 61 64 76 69 73 6f 72 79 20 69 6e 66 6f 72 6d   advisory inform
d440: 61 74 69 6f 6e 0a 2a 2a 20 74 6f 20 74 68 65 20  ation.** to the 
d450: 56 46 53 20 61 62 6f 75 74 20 77 68 61 74 20 74  VFS about what t
d460: 68 65 20 68 69 67 68 65 72 20 6c 61 79 65 72 73  he higher layers
d470: 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 73   of the SQLite s
d480: 74 61 63 6b 20 61 72 65 20 64 6f 69 6e 67 2e 0a  tack are doing..
d490: 2a 2a 20 54 68 69 73 20 66 69 6c 65 20 63 6f 6e  ** This file con
d4a0: 74 72 6f 6c 20 69 73 20 75 73 65 64 20 62 79 20  trol is used by 
d4b0: 73 6f 6d 65 20 56 46 53 20 61 63 74 69 76 69 74  some VFS activit
d4c0: 79 20 74 72 61 63 69 6e 67 20 5b 73 68 69 6d 73  y tracing [shims
d4d0: 5d 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65  ]..** The argume
d4e0: 6e 74 20 69 73 20 61 20 7a 65 72 6f 2d 74 65 72  nt is a zero-ter
d4f0: 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 2e 20  minated string. 
d500: 20 48 69 67 68 65 72 20 6c 61 79 65 72 73 20 69   Higher layers i
d510: 6e 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20  n the.** SQLite 
d520: 73 74 61 63 6b 20 6d 61 79 20 67 65 6e 65 72 61  stack may genera
d530: 74 65 20 69 6e 73 74 61 6e 63 65 73 20 6f 66 20  te instances of 
d540: 74 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f  this file contro
d550: 6c 20 69 66 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  l if.** the [SQL
d560: 49 54 45 5f 55 53 45 5f 46 43 4e 54 4c 5f 54 52  ITE_USE_FCNTL_TR
d570: 41 43 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  ACE] compile-tim
d580: 65 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 62  e option is enab
d590: 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  led..**.** <li>[
d5a0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41  [SQLITE_FCNTL_HA
d5b0: 53 5f 4d 4f 56 45 44 5d 5d 0a 2a 2a 20 54 68 65  S_MOVED]].** The
d5c0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48   [SQLITE_FCNTL_H
d5d0: 41 53 5f 4d 4f 56 45 44 5d 20 66 69 6c 65 20 63  AS_MOVED] file c
d5e0: 6f 6e 74 72 6f 6c 20 69 6e 74 65 72 70 72 65 74  ontrol interpret
d5f0: 73 20 69 74 73 20 61 72 67 75 6d 65 6e 74 20 61  s its argument a
d600: 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74  s a.** pointer t
d610: 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 61 6e 64  o an integer and
d620: 20 69 74 20 77 72 69 74 65 73 20 61 20 62 6f 6f   it writes a boo
d630: 6c 65 61 6e 20 69 6e 74 6f 20 74 68 61 74 20 69  lean into that i
d640: 6e 74 65 67 65 72 20 64 65 70 65 6e 64 69 6e 67  nteger depending
d650: 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 6f  .** on whether o
d660: 72 20 6e 6f 74 20 74 68 65 20 66 69 6c 65 20 68  r not the file h
d670: 61 73 20 62 65 65 6e 20 72 65 6e 61 6d 65 64 2c  as been renamed,
d680: 20 6d 6f 76 65 64 2c 20 6f 72 20 64 65 6c 65 74   moved, or delet
d690: 65 64 20 73 69 6e 63 65 20 69 74 0a 2a 2a 20 77  ed since it.** w
d6a0: 61 73 20 66 69 72 73 74 20 6f 70 65 6e 65 64 2e  as first opened.
d6b0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
d6c0: 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f  ITE_FCNTL_WIN32_
d6d0: 53 45 54 5f 48 41 4e 44 4c 45 5d 5d 0a 2a 2a 20  SET_HANDLE]].** 
d6e0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
d6f0: 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44  L_WIN32_SET_HAND
d700: 4c 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  LE] opcode is us
d710: 65 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67  ed for debugging
d720: 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64  .  This.** opcod
d730: 65 20 63 61 75 73 65 73 20 74 68 65 20 78 46 69  e causes the xFi
d740: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
d750: 20 74 6f 20 73 77 61 70 20 74 68 65 20 66 69 6c   to swap the fil
d760: 65 20 68 61 6e 64 6c 65 20 77 69 74 68 20 74 68  e handle with th
d770: 65 20 6f 6e 65 0a 2a 2a 20 70 6f 69 6e 74 65 64  e one.** pointed
d780: 20 74 6f 20 62 79 20 74 68 65 20 70 41 72 67 20   to by the pArg 
d790: 61 72 67 75 6d 65 6e 74 2e 20 20 54 68 69 73 20  argument.  This 
d7a0: 63 61 70 61 62 69 6c 69 74 79 20 69 73 20 75 73  capability is us
d7b0: 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e  ed during testin
d7c0: 67 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 6e 65  g.** and only ne
d7d0: 65 64 73 20 74 6f 20 62 65 20 73 75 70 70 6f 72  eds to be suppor
d7e0: 74 65 64 20 77 68 65 6e 20 53 51 4c 49 54 45 5f  ted when SQLITE_
d7f0: 54 45 53 54 20 69 73 20 64 65 66 69 6e 65 64 2e  TEST is defined.
d800: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
d810: 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c  ITE_FCNTL_WAL_BL
d820: 4f 43 4b 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  OCK]].** The [SQ
d830: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42  LITE_FCNTL_WAL_B
d840: 4c 4f 43 4b 5d 20 69 73 20 61 20 73 69 67 6e 61  LOCK] is a signa
d850: 6c 20 74 6f 20 74 68 65 20 56 46 53 20 6c 61 79  l to the VFS lay
d860: 65 72 20 74 68 61 74 20 69 74 20 6d 69 67 68 74  er that it might
d870: 0a 2a 2a 20 62 65 20 61 64 76 61 6e 74 61 67 65  .** be advantage
d880: 6f 75 73 20 74 6f 20 62 6c 6f 63 6b 20 6f 6e 20  ous to block on 
d890: 74 68 65 20 6e 65 78 74 20 57 41 4c 20 6c 6f 63  the next WAL loc
d8a0: 6b 20 69 66 20 74 68 65 20 6c 6f 63 6b 20 69 73  k if the lock is
d8b0: 20 6e 6f 74 20 69 6d 6d 65 64 69 61 74 65 6c 79   not immediately
d8c0: 0a 2a 2a 20 61 76 61 69 6c 61 62 6c 65 2e 20 20  .** available.  
d8d0: 54 68 65 20 57 41 4c 20 73 75 62 73 79 73 74 65  The WAL subsyste
d8e0: 6d 20 69 73 73 75 65 73 20 74 68 69 73 20 73 69  m issues this si
d8f0: 67 6e 61 6c 20 64 75 72 69 6e 67 20 72 61 72 65  gnal during rare
d900: 0a 2a 2a 20 63 69 72 63 75 6d 73 74 61 6e 63 65  .** circumstance
d910: 73 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69  s in order to fi
d920: 78 20 61 20 70 72 6f 62 6c 65 6d 20 77 69 74 68  x a problem with
d930: 20 70 72 69 6f 72 69 74 79 20 69 6e 76 65 72 73   priority invers
d940: 69 6f 6e 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74  ion..** Applicat
d950: 69 6f 6e 73 20 73 68 6f 75 6c 64 20 3c 65 6d 3e  ions should <em>
d960: 6e 6f 74 3c 2f 65 6d 3e 20 75 73 65 20 74 68 69  not</em> use thi
d970: 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 2e 0a  s file-control..
d980: 2a 2a 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 23  **.** </ul>.*/.#
d990: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
d9a0: 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20  NTL_LOCKSTATE   
d9b0: 20 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64              1.#d
d9c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
d9d0: 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59  TL_GET_LOCKPROXY
d9e0: 46 49 4c 45 20 20 20 20 20 20 20 32 0a 23 64 65  FILE       2.#de
d9f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
da00: 4c 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46  L_SET_LOCKPROXYF
da10: 49 4c 45 20 20 20 20 20 20 20 33 0a 23 64 65 66  ILE       3.#def
da20: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
da30: 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20  _LAST_ERRNO     
da40: 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69           4.#defi
da50: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
da60: 53 49 5a 45 5f 48 49 4e 54 20 20 20 20 20 20 20  SIZE_HINT       
da70: 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e          5.#defin
da80: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43  e SQLITE_FCNTL_C
da90: 48 55 4e 4b 5f 53 49 5a 45 20 20 20 20 20 20 20  HUNK_SIZE       
daa0: 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65         6.#define
dab0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49   SQLITE_FCNTL_FI
dac0: 4c 45 5f 50 4f 49 4e 54 45 52 20 20 20 20 20 20  LE_POINTER      
dad0: 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20        7.#define 
dae0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e  SQLITE_FCNTL_SYN
daf0: 43 5f 4f 4d 49 54 54 45 44 20 20 20 20 20 20 20  C_OMITTED       
db00: 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53       8.#define S
db10: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33  QLITE_FCNTL_WIN3
db20: 32 5f 41 56 5f 52 45 54 52 59 20 20 20 20 20 20  2_AV_RETRY      
db30: 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51      9.#define SQ
db40: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49  LITE_FCNTL_PERSI
db50: 53 54 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20  ST_WAL          
db60: 20 20 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c    10.#define SQL
db70: 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52  ITE_FCNTL_OVERWR
db80: 49 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ITE             
db90: 20 31 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   11.#define SQLI
dba0: 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45  TE_FCNTL_VFSNAME
dbb0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
dbc0: 31 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  12.#define SQLIT
dbd0: 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46  E_FCNTL_POWERSAF
dbe0: 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 31  E_OVERWRITE    1
dbf0: 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
dc00: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 20 20 20  _FCNTL_PRAGMA   
dc10: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 34                14
dc20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
dc30: 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45  FCNTL_BUSYHANDLE
dc40: 52 20 20 20 20 20 20 20 20 20 20 20 20 31 35 0a  R            15.
dc50: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
dc60: 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d  CNTL_TEMPFILENAM
dc70: 45 20 20 20 20 20 20 20 20 20 20 20 31 36 0a 23  E           16.#
dc80: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
dc90: 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 20 20 20  NTL_MMAP_SIZE   
dca0: 20 20 20 20 20 20 20 20 20 20 20 31 38 0a 23 64             18.#d
dcb0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
dcc0: 54 4c 5f 54 52 41 43 45 20 20 20 20 20 20 20 20  TL_TRACE        
dcd0: 20 20 20 20 20 20 20 20 20 20 31 39 0a 23 64 65            19.#de
dce0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
dcf0: 4c 5f 48 41 53 5f 4d 4f 56 45 44 20 20 20 20 20  L_HAS_MOVED     
dd00: 20 20 20 20 20 20 20 20 20 32 30 0a 23 64 65 66           20.#def
dd10: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
dd20: 5f 53 59 4e 43 20 20 20 20 20 20 20 20 20 20 20  _SYNC           
dd30: 20 20 20 20 20 20 20 20 32 31 0a 23 64 65 66 69          21.#defi
dd40: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
dd50: 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f 20  COMMIT_PHASETWO 
dd60: 20 20 20 20 20 20 20 32 32 0a 23 64 65 66 69 6e         22.#defin
dd70: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57  e SQLITE_FCNTL_W
dd80: 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 20  IN32_SET_HANDLE 
dd90: 20 20 20 20 20 20 32 33 0a 23 64 65 66 69 6e 65        23.#define
dda0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41   SQLITE_FCNTL_WA
ddb0: 4c 5f 42 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  L_BLOCK         
ddc0: 20 20 20 20 20 32 34 0a 0a 2f 2a 20 64 65 70 72       24../* depr
ddd0: 65 63 61 74 65 64 20 6e 61 6d 65 73 20 2a 2f 0a  ecated names */.
dde0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 47  #define SQLITE_G
ddf0: 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45  ET_LOCKPROXYFILE
de00: 20 20 20 20 20 20 53 51 4c 49 54 45 5f 46 43 4e        SQLITE_FCN
de10: 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59  TL_GET_LOCKPROXY
de20: 46 49 4c 45 0a 23 64 65 66 69 6e 65 20 53 51 4c  FILE.#define SQL
de30: 49 54 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58  ITE_SET_LOCKPROX
de40: 59 46 49 4c 45 20 20 20 20 20 20 53 51 4c 49 54  YFILE      SQLIT
de50: 45 5f 46 43 4e 54 4c 5f 53 45 54 5f 4c 4f 43 4b  E_FCNTL_SET_LOCK
de60: 50 52 4f 58 59 46 49 4c 45 0a 23 64 65 66 69 6e  PROXYFILE.#defin
de70: 65 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f 45 52  e SQLITE_LAST_ER
de80: 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20 20  RNO             
de90: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 41 53  SQLITE_FCNTL_LAS
dea0: 54 5f 45 52 52 4e 4f 0a 0a 0a 2f 2a 0a 2a 2a 20  T_ERRNO.../*.** 
deb0: 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20  CAPI3REF: Mutex 
dec0: 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65  Handle.**.** The
ded0: 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 69   mutex module wi
dee0: 74 68 69 6e 20 53 51 4c 69 74 65 20 64 65 66 69  thin SQLite defi
def0: 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  nes [sqlite3_mut
df00: 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20  ex] to be an.** 
df10: 61 62 73 74 72 61 63 74 20 74 79 70 65 20 66 6f  abstract type fo
df20: 72 20 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 74  r a mutex object
df30: 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f  .  The SQLite co
df40: 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a  re never looks.*
df50: 2a 20 61 74 20 74 68 65 20 69 6e 74 65 72 6e 61  * at the interna
df60: 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e  l representation
df70: 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   of an [sqlite3_
df80: 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79  mutex].  It only
df90: 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74 68 20 70  .** deals with p
dfa0: 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20 5b  ointers to the [
dfb0: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f  sqlite3_mutex] o
dfc0: 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74  bject..**.** Mut
dfd0: 65 78 65 73 20 61 72 65 20 63 72 65 61 74 65 64  exes are created
dfe0: 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
dff0: 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a  mutex_alloc()]..
e000: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
e010: 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20  t sqlite3_mutex 
e020: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a  sqlite3_mutex;..
e030: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
e040: 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 62 6a  OS Interface Obj
e050: 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  ect.**.** An ins
e060: 74 61 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c  tance of the sql
e070: 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20  ite3_vfs object 
e080: 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65  defines the inte
e090: 72 66 61 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a  rface between.**
e0a0: 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   the SQLite core
e0b0: 20 61 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79   and the underly
e0c0: 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79  ing operating sy
e0d0: 73 74 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22  stem.  The "vfs"
e0e0: 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20  .** in the name 
e0f0: 6f 66 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74  of the object st
e100: 61 6e 64 73 20 66 6f 72 20 22 76 69 72 74 75 61  ands for "virtua
e110: 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 20  l file system". 
e120: 20 53 65 65 0a 2a 2a 20 74 68 65 20 5b 56 46 53   See.** the [VFS
e130: 20 7c 20 56 46 53 20 64 6f 63 75 6d 65 6e 74 61   | VFS documenta
e140: 74 69 6f 6e 5d 20 66 6f 72 20 66 75 72 74 68 65  tion] for furthe
e150: 72 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  r information..*
e160: 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 6f  *.** The value o
e170: 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66  f the iVersion f
e180: 69 65 6c 64 20 69 73 20 69 6e 69 74 69 61 6c 6c  ield is initiall
e190: 79 20 31 20 62 75 74 20 6d 61 79 20 62 65 20 6c  y 1 but may be l
e1a0: 61 72 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74 75  arger in.** futu
e1b0: 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
e1c0: 51 4c 69 74 65 2e 20 20 41 64 64 69 74 69 6f 6e  QLite.  Addition
e1d0: 61 6c 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65  al fields may be
e1e0: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 74 68 69   appended to thi
e1f0: 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e  s.** object when
e200: 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 76 61   the iVersion va
e210: 6c 75 65 20 69 73 20 69 6e 63 72 65 61 73 65 64  lue is increased
e220: 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65  .  Note that the
e230: 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66   structure.** of
e240: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73   the sqlite3_vfs
e250: 20 6f 62 6a 65 63 74 20 63 68 61 6e 67 65 73 20   object changes 
e260: 69 6e 20 74 68 65 20 74 72 61 6e 73 61 63 74 69  in the transacti
e270: 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53 51  on between.** SQ
e280: 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35  Lite version 3.5
e290: 2e 39 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e 64  .9 and 3.6.0 and
e2a0: 20 79 65 74 20 74 68 65 20 69 56 65 72 73 69 6f   yet the iVersio
e2b0: 6e 20 66 69 65 6c 64 20 77 61 73 20 6e 6f 74 0a  n field was not.
e2c0: 2a 2a 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a  ** modified..**.
e2d0: 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65 20  ** The szOsFile 
e2e0: 66 69 65 6c 64 20 69 73 20 74 68 65 20 73 69 7a  field is the siz
e2f0: 65 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61 73  e of the subclas
e300: 73 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  sed [sqlite3_fil
e310: 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20  e].** structure 
e320: 75 73 65 64 20 62 79 20 74 68 69 73 20 56 46 53  used by this VFS
e330: 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69 73  .  mxPathname is
e340: 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e   the maximum len
e350: 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68  gth of.** a path
e360: 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46 53  name in this VFS
e370: 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72  ..**.** Register
e380: 65 64 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f  ed sqlite3_vfs o
e390: 62 6a 65 63 74 73 20 61 72 65 20 6b 65 70 74 20  bjects are kept 
e3a0: 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74  on a linked list
e3b0: 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68   formed by.** th
e3c0: 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e  e pNext pointer.
e3d0: 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76    The [sqlite3_v
e3e0: 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a 2a  fs_register()].*
e3f0: 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76  * and [sqlite3_v
e400: 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29 5d  fs_unregister()]
e410: 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e 61   interfaces mana
e420: 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20  ge this list.** 
e430: 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66 65  in a thread-safe
e440: 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c 69   way.  The [sqli
e450: 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20  te3_vfs_find()] 
e460: 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 61  interface.** sea
e470: 72 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e 20  rches the list. 
e480: 20 4e 65 69 74 68 65 72 20 74 68 65 20 61 70 70   Neither the app
e490: 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f  lication code no
e4a0: 72 20 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70  r the VFS.** imp
e4b0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75  lementation shou
e4c0: 6c 64 20 75 73 65 20 74 68 65 20 70 4e 65 78 74  ld use the pNext
e4d0: 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
e4e0: 54 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64 20  The pNext field 
e4f0: 69 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c  is the only fiel
e500: 64 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33  d in the sqlite3
e510: 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63 74 75 72  _vfs.** structur
e520: 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69  e that SQLite wi
e530: 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e 20  ll ever modify. 
e540: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c   SQLite will onl
e550: 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d  y access.** or m
e560: 6f 64 69 66 79 20 74 68 69 73 20 66 69 65 6c 64  odify this field
e570: 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61   while holding a
e580: 20 70 61 72 74 69 63 75 6c 61 72 20 73 74 61 74   particular stat
e590: 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65  ic mutex..** The
e5a0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f   application sho
e5b0: 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 79  uld never modify
e5c0: 20 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69 6e   anything within
e5d0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73   the sqlite3_vfs
e5e0: 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20  .** object once 
e5f0: 74 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20 62  the object has b
e600: 65 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e 0a  een registered..
e610: 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20  **.** The zName 
e620: 66 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 20  field holds the 
e630: 6e 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53 20  name of the VFS 
e640: 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d  module.  The nam
e650: 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69  e must.** be uni
e660: 71 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 56  que across all V
e670: 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a  FS modules..**.*
e680: 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  * [[sqlite3_vfs.
e690: 78 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c 69  xOpen]].** ^SQLi
e6a0: 74 65 20 67 75 61 72 61 6e 74 65 65 73 20 74 68  te guarantees th
e6b0: 61 74 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65  at the zFilename
e6c0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f   parameter to xO
e6d0: 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65 72  pen.** is either
e6e0: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
e6f0: 6f 72 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e  or string obtain
e700: 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c 6c  ed.** from xFull
e710: 50 61 74 68 6e 61 6d 65 28 29 20 77 69 74 68 20  Pathname() with 
e720: 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 73 75 66 66  an optional suff
e730: 69 78 20 61 64 64 65 64 2e 0a 2a 2a 20 5e 49 66  ix added..** ^If
e740: 20 61 20 73 75 66 66 69 78 20 69 73 20 61 64 64   a suffix is add
e750: 65 64 20 74 6f 20 74 68 65 20 7a 46 69 6c 65 6e  ed to the zFilen
e760: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 2c 20 69  ame parameter, i
e770: 74 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69 73  t will.** consis
e780: 74 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 22 2d  t of a single "-
e790: 22 20 63 68 61 72 61 63 74 65 72 20 66 6f 6c 6c  " character foll
e7a0: 6f 77 65 64 20 62 79 20 6e 6f 20 6d 6f 72 65 20  owed by no more 
e7b0: 74 68 61 6e 0a 2a 2a 20 31 31 20 61 6c 70 68 61  than.** 11 alpha
e7c0: 6e 75 6d 65 72 69 63 20 61 6e 64 2f 6f 72 20 22  numeric and/or "
e7d0: 2d 22 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a  -" characters..*
e7e0: 2a 20 5e 53 51 4c 69 74 65 20 66 75 72 74 68 65  * ^SQLite furthe
e7f0: 72 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61  r guarantees tha
e800: 74 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20  t.** the string 
e810: 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 6e  will be valid an
e820: 64 20 75 6e 63 68 61 6e 67 65 64 20 75 6e 74 69  d unchanged unti
e830: 6c 20 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a  l xClose() is.**
e840: 20 63 61 6c 6c 65 64 2e 20 42 65 63 61 75 73 65   called. Because
e850: 20 6f 66 20 74 68 65 20 70 72 65 76 69 6f 75 73   of the previous
e860: 20 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74 68   sentence,.** th
e870: 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  e [sqlite3_file]
e880: 20 63 61 6e 20 73 61 66 65 6c 79 20 73 74 6f 72   can safely stor
e890: 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  e a pointer to t
e8a0: 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69  he.** filename i
e8b0: 66 20 69 74 20 6e 65 65 64 73 20 74 6f 20 72 65  f it needs to re
e8c0: 6d 65 6d 62 65 72 20 74 68 65 20 66 69 6c 65 6e  member the filen
e8d0: 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72 65 61  ame for some rea
e8e0: 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 20 7a  son..** If the z
e8f0: 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74  Filename paramet
e900: 65 72 20 74 6f 20 78 4f 70 65 6e 20 69 73 20 61  er to xOpen is a
e910: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68   NULL pointer th
e920: 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74  en xOpen.** must
e930: 20 69 6e 76 65 6e 74 20 69 74 73 20 6f 77 6e 20   invent its own 
e940: 74 65 6d 70 6f 72 61 72 79 20 6e 61 6d 65 20 66  temporary name f
e950: 6f 72 20 74 68 65 20 66 69 6c 65 2e 20 20 5e 57  or the file.  ^W
e960: 68 65 6e 65 76 65 72 20 74 68 65 20 0a 2a 2a 20  henever the .** 
e970: 78 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65  xFilename parame
e980: 74 65 72 20 69 73 20 4e 55 4c 4c 20 69 74 20 77  ter is NULL it w
e990: 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74 68 65 20  ill also be the 
e9a0: 63 61 73 65 20 74 68 61 74 20 74 68 65 0a 2a 2a  case that the.**
e9b0: 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72   flags parameter
e9c0: 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65 20 5b 53   will include [S
e9d0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
e9e0: 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a  EONCLOSE]..**.**
e9f0: 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d   The flags argum
ea00: 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29 20 69  ent to xOpen() i
ea10: 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62 69 74 73  ncludes all bits
ea20: 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66   set in.** the f
ea30: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f  lags argument to
ea40: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
ea50: 32 28 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71  2()].  Or if [sq
ea60: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a  lite3_open()].**
ea70: 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   or [sqlite3_ope
ea80: 6e 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20  n16()] is used, 
ea90: 74 68 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75  then flags inclu
eaa0: 64 65 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20  des at least.** 
eab0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
eac0: 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54  DWRITE] | [SQLIT
ead0: 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20  E_OPEN_CREATE]. 
eae0: 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29 20 6f  .** If xOpen() o
eaf0: 70 65 6e 73 20 61 20 66 69 6c 65 20 72 65 61 64  pens a file read
eb00: 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20 73 65  -only then it se
eb10: 74 73 20 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f  ts *pOutFlags to
eb20: 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c  .** include [SQL
eb30: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
eb40: 59 5d 2e 20 20 4f 74 68 65 72 20 62 69 74 73 20  Y].  Other bits 
eb50: 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61  in *pOutFlags ma
eb60: 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20  y be set..**.** 
eb70: 5e 28 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c  ^(SQLite will al
eb80: 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68  so add one of th
eb90: 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67  e following flag
eba0: 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29  s to the xOpen()
ebb0: 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64  .** call, depend
ebc0: 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63  ing on the objec
ebd0: 74 20 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a  t being opened:.
ebe0: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
ebf0: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
ec00: 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69  _MAIN_DB].** <li
ec10: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
ec20: 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a  MAIN_JOURNAL].**
ec30: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
ec40: 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20  PEN_TEMP_DB].** 
ec50: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
ec60: 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d  EN_TEMP_JOURNAL]
ec70: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
ec80: 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54  E_OPEN_TRANSIENT
ec90: 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  _DB].** <li>  [S
eca0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f  QLITE_OPEN_SUBJO
ecb0: 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  URNAL].** <li>  
ecc0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53  [SQLITE_OPEN_MAS
ecd0: 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20  TER_JOURNAL].** 
ece0: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
ecf0: 45 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e  EN_WAL].** </ul>
ed00: 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c  )^.**.** The fil
ed10: 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61  e I/O implementa
ed20: 74 69 6f 6e 20 63 61 6e 20 75 73 65 20 74 68 65  tion can use the
ed30: 20 6f 62 6a 65 63 74 20 74 79 70 65 20 66 6c 61   object type fla
ed40: 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 20  gs to.** change 
ed50: 74 68 65 20 77 61 79 20 69 74 20 64 65 61 6c 73  the way it deals
ed60: 20 77 69 74 68 20 66 69 6c 65 73 2e 20 20 46 6f   with files.  Fo
ed70: 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70  r example, an ap
ed80: 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61  plication.** tha
ed90: 74 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20  t does not care 
eda0: 61 62 6f 75 74 20 63 72 61 73 68 20 72 65 63 6f  about crash reco
edb0: 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b  very or rollback
edc0: 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74   might make.** t
edd0: 68 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75  he open of a jou
ede0: 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f  rnal file a no-o
edf0: 70 2e 20 20 57 72 69 74 65 73 20 74 6f 20 74 68  p.  Writes to th
ee00: 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64  is journal would
ee10: 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f  .** also be no-o
ee20: 70 73 2c 20 61 6e 64 20 61 6e 79 20 61 74 74 65  ps, and any atte
ee30: 6d 70 74 20 74 6f 20 72 65 61 64 20 74 68 65 20  mpt to read the 
ee40: 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65  journal would re
ee50: 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 49  turn.** SQLITE_I
ee60: 4f 45 52 52 2e 20 20 4f 72 20 74 68 65 20 69 6d  OERR.  Or the im
ee70: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67  plementation mig
ee80: 68 74 20 72 65 63 6f 67 6e 69 7a 65 20 74 68 61  ht recognize tha
ee90: 74 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  t a database.** 
eea0: 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f 69  file will be doi
eeb0: 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e 65 64 20  ng page-aligned 
eec0: 73 65 63 74 6f 72 20 72 65 61 64 73 20 61 6e 64  sector reads and
eed0: 20 77 72 69 74 65 73 20 69 6e 20 61 20 72 61 6e   writes in a ran
eee0: 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e 64  dom.** order and
eef0: 20 73 65 74 20 75 70 20 69 74 73 20 49 2f 4f 20   set up its I/O 
ef00: 73 75 62 73 79 73 74 65 6d 20 61 63 63 6f 72 64  subsystem accord
ef10: 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  ingly..**.** SQL
ef20: 69 74 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 61  ite might also a
ef30: 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f  dd one of the fo
ef40: 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f  llowing flags to
ef50: 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f   the xOpen metho
ef60: 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  d:.**.** <ul>.**
ef70: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50   <li> [SQLITE_OP
ef80: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
ef90: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
efa0: 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45  E_OPEN_EXCLUSIVE
efb0: 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  ].** </ul>.**.**
efc0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   The [SQLITE_OPE
efd0: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d  N_DELETEONCLOSE]
efe0: 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20   flag means the 
eff0: 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a  file should be.*
f000: 2a 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 69  * deleted when i
f010: 74 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 5e 54  t is closed.  ^T
f020: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
f030: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a  DELETEONCLOSE].*
f040: 2a 20 77 69 6c 6c 20 62 65 20 73 65 74 20 66 6f  * will be set fo
f050: 72 20 54 45 4d 50 20 64 61 74 61 62 61 73 65 73  r TEMP databases
f060: 20 61 6e 64 20 74 68 65 69 72 20 6a 6f 75 72 6e   and their journ
f070: 61 6c 73 2c 20 74 72 61 6e 73 69 65 6e 74 0a 2a  als, transient.*
f080: 2a 20 64 61 74 61 62 61 73 65 73 2c 20 61 6e 64  * databases, and
f090: 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a   subjournals..**
f0a0: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
f0b0: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d  _OPEN_EXCLUSIVE]
f0c0: 20 66 6c 61 67 20 69 73 20 61 6c 77 61 79 73 20   flag is always 
f0d0: 75 73 65 64 20 69 6e 20 63 6f 6e 6a 75 6e 63 74  used in conjunct
f0e0: 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ion.** with the 
f0f0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45  [SQLITE_OPEN_CRE
f100: 41 54 45 5d 20 66 6c 61 67 2c 20 77 68 69 63 68  ATE] flag, which
f110: 20 61 72 65 20 62 6f 74 68 20 64 69 72 65 63 74   are both direct
f120: 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73 20  ly.** analogous 
f130: 74 6f 20 74 68 65 20 4f 5f 45 58 43 4c 20 61 6e  to the O_EXCL an
f140: 64 20 4f 5f 43 52 45 41 54 20 66 6c 61 67 73 20  d O_CREAT flags 
f150: 6f 66 20 74 68 65 20 50 4f 53 49 58 20 6f 70 65  of the POSIX ope
f160: 6e 28 29 0a 2a 2a 20 41 50 49 2e 20 20 54 68 65  n().** API.  The
f170: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43   SQLITE_OPEN_EXC
f180: 4c 55 53 49 56 45 20 66 6c 61 67 2c 20 77 68 65  LUSIVE flag, whe
f190: 6e 20 70 61 69 72 65 64 20 77 69 74 68 20 74 68  n paired with th
f1a0: 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 50 45  e .** SQLITE_OPE
f1b0: 4e 5f 43 52 45 41 54 45 2c 20 69 73 20 75 73 65  N_CREATE, is use
f1c0: 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68  d to indicate th
f1d0: 61 74 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 61  at file should a
f1e0: 6c 77 61 79 73 0a 2a 2a 20 62 65 20 63 72 65 61  lways.** be crea
f1f0: 74 65 64 2c 20 61 6e 64 20 74 68 61 74 20 69 74  ted, and that it
f200: 20 69 73 20 61 6e 20 65 72 72 6f 72 20 69 66 20   is an error if 
f210: 69 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74  it already exist
f220: 73 2e 0a 2a 2a 20 49 74 20 69 73 20 3c 69 3e 6e  s..** It is <i>n
f230: 6f 74 3c 2f 69 3e 20 75 73 65 64 20 74 6f 20 69  ot</i> used to i
f240: 6e 64 69 63 61 74 65 20 74 68 65 20 66 69 6c 65  ndicate the file
f250: 20 73 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65   should be opene
f260: 64 20 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73  d .** for exclus
f270: 69 76 65 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a  ive access..**.*
f280: 2a 20 5e 41 74 20 6c 65 61 73 74 20 73 7a 4f 73  * ^At least szOs
f290: 46 69 6c 65 20 62 79 74 65 73 20 6f 66 20 6d 65  File bytes of me
f2a0: 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f 63 61 74  mory are allocat
f2b0: 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20  ed by SQLite.** 
f2c0: 74 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b 73 71  to hold the  [sq
f2d0: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73 74 72 75  lite3_file] stru
f2e0: 63 74 75 72 65 20 70 61 73 73 65 64 20 61 73 20  cture passed as 
f2f0: 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 67  the third.** arg
f300: 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20  ument to xOpen. 
f310: 20 54 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f   The xOpen metho
f320: 64 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20  d does not have 
f330: 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74  to.** allocate t
f340: 68 65 20 73 74 72 75 63 74 75 72 65 3b 20 69 74  he structure; it
f350: 20 73 68 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c   should just fil
f360: 6c 20 69 74 20 69 6e 2e 20 20 4e 6f 74 65 20 74  l it in.  Note t
f370: 68 61 74 0a 2a 2a 20 74 68 65 20 78 4f 70 65 6e  hat.** the xOpen
f380: 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 73 65 74   method must set
f390: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c   the sqlite3_fil
f3a0: 65 2e 70 4d 65 74 68 6f 64 73 20 74 6f 20 65 69  e.pMethods to ei
f3b0: 74 68 65 72 0a 2a 2a 20 61 20 76 61 6c 69 64 20  ther.** a valid 
f3c0: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
f3d0: 6f 64 73 5d 20 6f 62 6a 65 63 74 20 6f 72 20 74  ods] object or t
f3e0: 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d  o NULL.  xOpen m
f3f0: 75 73 74 20 64 6f 0a 2a 2a 20 74 68 69 73 20 65  ust do.** this e
f400: 76 65 6e 20 69 66 20 74 68 65 20 6f 70 65 6e 20  ven if the open 
f410: 66 61 69 6c 73 2e 20 20 53 51 4c 69 74 65 20 65  fails.  SQLite e
f420: 78 70 65 63 74 73 20 74 68 61 74 20 74 68 65 20  xpects that the 
f430: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65  sqlite3_file.pMe
f440: 74 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74  thods.** element
f450: 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61   will be valid a
f460: 66 74 65 72 20 78 4f 70 65 6e 20 72 65 74 75 72  fter xOpen retur
f470: 6e 73 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66  ns regardless of
f480: 20 74 68 65 20 73 75 63 63 65 73 73 0a 2a 2a 20   the success.** 
f490: 6f 72 20 66 61 69 6c 75 72 65 20 6f 66 20 74 68  or failure of th
f4a0: 65 20 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a  e xOpen call..**
f4b0: 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66  .** [[sqlite3_vf
f4c0: 73 2e 78 41 63 63 65 73 73 5d 5d 0a 2a 2a 20 5e  s.xAccess]].** ^
f4d0: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  The flags argume
f4e0: 6e 74 20 74 6f 20 78 41 63 63 65 73 73 28 29 20  nt to xAccess() 
f4f0: 6d 61 79 20 62 65 20 5b 53 51 4c 49 54 45 5f 41  may be [SQLITE_A
f500: 43 43 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a  CCESS_EXISTS].**
f510: 20 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68 65   to test for the
f520: 20 65 78 69 73 74 65 6e 63 65 20 6f 66 20 61 20   existence of a 
f530: 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45  file, or [SQLITE
f540: 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
f550: 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68  E] to.** test wh
f560: 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20  ether a file is 
f570: 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69  readable and wri
f580: 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54  table, or [SQLIT
f590: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a  E_ACCESS_READ].*
f5a0: 2a 20 74 6f 20 74 65 73 74 20 77 68 65 74 68 65  * to test whethe
f5b0: 72 20 61 20 66 69 6c 65 20 69 73 20 61 74 20 6c  r a file is at l
f5c0: 65 61 73 74 20 72 65 61 64 61 62 6c 65 2e 20 20  east readable.  
f5d0: 20 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62 65   The file can be
f5e0: 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e   a.** directory.
f5f0: 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77  .**.** ^SQLite w
f600: 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63  ill always alloc
f610: 61 74 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50  ate at least mxP
f620: 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 20  athname+1 bytes 
f630: 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75  for the.** outpu
f640: 74 20 62 75 66 66 65 72 20 78 46 75 6c 6c 50 61  t buffer xFullPa
f650: 74 68 6e 61 6d 65 2e 20 20 54 68 65 20 65 78 61  thname.  The exa
f660: 63 74 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6f  ct size of the o
f670: 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20  utput buffer.** 
f680: 69 73 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61  is also passed a
f690: 73 20 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f  s a parameter to
f6a0: 20 62 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e 20   both  methods. 
f6b0: 49 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75  If the output bu
f6c0: 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c  ffer.** is not l
f6d0: 61 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51  arge enough, [SQ
f6e0: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73  LITE_CANTOPEN] s
f6f0: 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65  hould be returne
f700: 64 2e 20 53 69 6e 63 65 20 74 68 69 73 20 69 73  d. Since this is
f710: 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 61  .** handled as a
f720: 20 66 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20   fatal error by 
f730: 53 51 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 6c  SQLite, vfs impl
f740: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75  ementations shou
f750: 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74  ld endeavor.** t
f760: 6f 20 70 72 65 76 65 6e 74 20 74 68 69 73 20 62  o prevent this b
f770: 79 20 73 65 74 74 69 6e 67 20 6d 78 50 61 74 68  y setting mxPath
f780: 6e 61 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63  name to a suffic
f790: 69 65 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c  iently large val
f7a0: 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52  ue..**.** The xR
f7b0: 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c  andomness(), xSl
f7c0: 65 65 70 28 29 2c 20 78 43 75 72 72 65 6e 74 54  eep(), xCurrentT
f7d0: 69 6d 65 28 29 2c 20 61 6e 64 20 78 43 75 72 72  ime(), and xCurr
f7e0: 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 0a 2a  entTimeInt64().*
f7f0: 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  * interfaces are
f800: 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 61 20   not strictly a 
f810: 70 61 72 74 20 6f 66 20 74 68 65 20 66 69 6c 65  part of the file
f820: 73 79 73 74 65 6d 2c 20 62 75 74 20 74 68 65 79  system, but they
f830: 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64   are.** included
f840: 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 72 75   in the VFS stru
f850: 63 74 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65  cture for comple
f860: 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78  teness..** The x
f870: 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e  Randomness() fun
f880: 63 74 69 6f 6e 20 61 74 74 65 6d 70 74 73 20 74  ction attempts t
f890: 6f 20 72 65 74 75 72 6e 20 6e 42 79 74 65 73 20  o return nBytes 
f8a0: 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64  bytes.** of good
f8b0: 2d 71 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e  -quality randomn
f8c0: 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20  ess into zOut.  
f8d0: 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  The return value
f8e0: 20 69 73 0a 2a 2a 20 74 68 65 20 61 63 74 75 61   is.** the actua
f8f0: 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  l number of byte
f900: 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20  s of randomness 
f910: 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65  obtained..** The
f920: 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64   xSleep() method
f930: 20 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c   causes the call
f940: 69 6e 67 20 74 68 72 65 61 64 20 74 6f 20 73 6c  ing thread to sl
f950: 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65  eep for at.** le
f960: 61 73 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ast the number o
f970: 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20 67  f microseconds g
f980: 69 76 65 6e 2e 20 20 5e 54 68 65 20 78 43 75 72  iven.  ^The xCur
f990: 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65  rentTime().** me
f9a0: 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 4a  thod returns a J
f9b0: 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62 65 72  ulian Day Number
f9c0: 20 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74   for the current
f9d0: 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 61   date and time a
f9e0: 73 0a 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67 20  s.** a floating 
f9f0: 70 6f 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 20  point value..** 
fa00: 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d  ^The xCurrentTim
fa10: 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20  eInt64() method 
fa20: 72 65 74 75 72 6e 73 2c 20 61 73 20 61 6e 20 69  returns, as an i
fa30: 6e 74 65 67 65 72 2c 20 74 68 65 20 4a 75 6c 69  nteger, the Juli
fa40: 61 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65 72  an.** Day Number
fa50: 20 6d 75 6c 74 69 70 6c 69 65 64 20 62 79 20 38   multiplied by 8
fa60: 36 34 30 30 30 30 30 20 28 74 68 65 20 6e 75 6d  6400000 (the num
fa70: 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f  ber of milliseco
fa80: 6e 64 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d  nds in .** a 24-
fa90: 68 6f 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20  hour day).  .** 
faa0: 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65  ^SQLite will use
fab0: 20 74 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d   the xCurrentTim
fac0: 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20  eInt64() method 
fad0: 74 6f 20 67 65 74 20 74 68 65 20 63 75 72 72 65  to get the curre
fae0: 6e 74 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20 74  nt.** date and t
faf0: 69 6d 65 20 69 66 20 74 68 61 74 20 6d 65 74 68  ime if that meth
fb00: 6f 64 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20  od is available 
fb10: 28 69 66 20 69 56 65 72 73 69 6f 6e 20 69 73 20  (if iVersion is 
fb20: 32 20 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65 72  2 or .** greater
fb30: 20 61 6e 64 20 74 68 65 20 66 75 6e 63 74 69 6f   and the functio
fb40: 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74  n pointer is not
fb50: 20 4e 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20   NULL) and will 
fb60: 66 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20  fall back.** to 
fb70: 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 20 69  xCurrentTime() i
fb80: 66 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e  f xCurrentTimeIn
fb90: 74 36 34 28 29 20 69 73 20 75 6e 61 76 61 69 6c  t64() is unavail
fba0: 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  able..**.** ^The
fbb0: 20 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 28   xSetSystemCall(
fbc0: 29 2c 20 78 47 65 74 53 79 73 74 65 6d 43 61 6c  ), xGetSystemCal
fbd0: 6c 28 29 2c 20 61 6e 64 20 78 4e 65 73 74 53 79  l(), and xNestSy
fbe0: 73 74 65 6d 43 61 6c 6c 28 29 20 69 6e 74 65 72  stemCall() inter
fbf0: 66 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74  faces.** are not
fc00: 20 75 73 65 64 20 62 79 20 74 68 65 20 53 51 4c   used by the SQL
fc10: 69 74 65 20 63 6f 72 65 2e 20 20 54 68 65 73 65  ite core.  These
fc20: 20 6f 70 74 69 6f 6e 61 6c 20 69 6e 74 65 72 66   optional interf
fc30: 61 63 65 73 20 61 72 65 20 70 72 6f 76 69 64 65  aces are provide
fc40: 64 0a 2a 2a 20 62 79 20 73 6f 6d 65 20 56 46 53  d.** by some VFS
fc50: 65 73 20 74 6f 20 66 61 63 69 6c 69 74 61 74 65  es to facilitate
fc60: 20 74 65 73 74 69 6e 67 20 6f 66 20 74 68 65 20   testing of the 
fc70: 56 46 53 20 63 6f 64 65 2e 20 42 79 20 6f 76 65  VFS code. By ove
fc80: 72 72 69 64 69 6e 67 20 0a 2a 2a 20 73 79 73 74  rriding .** syst
fc90: 65 6d 20 63 61 6c 6c 73 20 77 69 74 68 20 66 75  em calls with fu
fca0: 6e 63 74 69 6f 6e 73 20 75 6e 64 65 72 20 69 74  nctions under it
fcb0: 73 20 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 65 73  s control, a tes
fcc0: 74 20 70 72 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a  t program can.**
fcd0: 20 73 69 6d 75 6c 61 74 65 20 66 61 75 6c 74 73   simulate faults
fce0: 20 61 6e 64 20 65 72 72 6f 72 20 63 6f 6e 64 69   and error condi
fcf0: 74 69 6f 6e 73 20 74 68 61 74 20 77 6f 75 6c 64  tions that would
fd00: 20 6f 74 68 65 72 77 69 73 65 20 62 65 20 64 69   otherwise be di
fd10: 66 66 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d  fficult.** or im
fd20: 70 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e 64 75  possible to indu
fd30: 63 65 2e 20 20 54 68 65 20 73 65 74 20 6f 66 20  ce.  The set of 
fd40: 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 74 68 61  system calls tha
fd50: 74 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64  t can be overrid
fd60: 64 65 6e 0a 2a 2a 20 76 61 72 69 65 73 20 66 72  den.** varies fr
fd70: 6f 6d 20 6f 6e 65 20 56 46 53 20 74 6f 20 61 6e  om one VFS to an
fd80: 6f 74 68 65 72 2c 20 61 6e 64 20 66 72 6f 6d 20  other, and from 
fd90: 6f 6e 65 20 76 65 72 73 69 6f 6e 20 6f 66 20 74  one version of t
fda0: 68 65 20 73 61 6d 65 20 56 46 53 20 74 6f 20 74  he same VFS to t
fdb0: 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70  he.** next.  App
fdc0: 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 75  lications that u
fdd0: 73 65 20 74 68 65 73 65 20 69 6e 74 65 72 66 61  se these interfa
fde0: 63 65 73 20 6d 75 73 74 20 62 65 20 70 72 65 70  ces must be prep
fdf0: 61 72 65 64 20 66 6f 72 20 61 6e 79 0a 2a 2a 20  ared for any.** 
fe00: 6f 72 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20  or all of these 
fe10: 69 6e 74 65 72 66 61 63 65 73 20 74 6f 20 62 65  interfaces to be
fe20: 20 4e 55 4c 4c 20 6f 72 20 66 6f 72 20 74 68 65   NULL or for the
fe30: 69 72 20 62 65 68 61 76 69 6f 72 20 74 6f 20 63  ir behavior to c
fe40: 68 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e  hange.** from on
fe50: 65 20 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65  e release to the
fe60: 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74   next.  Applicat
fe70: 69 6f 6e 73 20 6d 75 73 74 20 6e 6f 74 20 61 74  ions must not at
fe80: 74 65 6d 70 74 20 74 6f 20 61 63 63 65 73 73 0a  tempt to access.
fe90: 2a 2a 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20  ** any of these 
fea0: 6d 65 74 68 6f 64 73 20 69 66 20 74 68 65 20 69  methods if the i
feb0: 56 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 56  Version of the V
fec0: 46 53 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20  FS is less than 
fed0: 33 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  3..*/.typedef st
fee0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73  ruct sqlite3_vfs
fef0: 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a 74 79   sqlite3_vfs;.ty
ff00: 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c  pedef void (*sql
ff10: 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72  ite3_syscall_ptr
ff20: 29 28 76 6f 69 64 29 3b 0a 73 74 72 75 63 74 20  )(void);.struct 
ff30: 73 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20  sqlite3_vfs {.  
ff40: 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20  int iVersion;   
ff50: 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75           /* Stru
ff60: 63 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75  cture version nu
ff70: 6d 62 65 72 20 28 63 75 72 72 65 6e 74 6c 79 20  mber (currently 
ff80: 33 29 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73  3) */.  int szOs
ff90: 46 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20  File;           
ffa0: 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63   /* Size of subc
ffb0: 6c 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66  lassed sqlite3_f
ffc0: 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50  ile */.  int mxP
ffd0: 61 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20  athname;        
ffe0: 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c    /* Maximum fil
fff0: 65 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74  e pathname lengt
10000 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76  h */.  sqlite3_v
10010 66 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20  fs *pNext;      
10020 2f 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65 72  /* Next register
10030 65 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73  ed VFS */.  cons
10040 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20  t char *zName;  
10050 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20       /* Name of 
10060 74 68 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c  this virtual fil
10070 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f  e system */.  vo
10080 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20  id *pAppData;   
10090 20 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65         /* Pointe
100a0 72 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e  r to application
100b0 2d 73 70 65 63 69 66 69 63 20 64 61 74 61 20 2a  -specific data *
100c0 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29  /.  int (*xOpen)
100d0 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
100e0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
100f0 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  , sqlite3_file*,
10100 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
10110 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a  int flags, int *
10120 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e  pOutFlags);.  in
10130 74 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c  t (*xDelete)(sql
10140 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
10150 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e   char *zName, in
10160 74 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e  t syncDir);.  in
10170 74 20 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c  t (*xAccess)(sql
10180 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
10190 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e   char *zName, in
101a0 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52  t flags, int *pR
101b0 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a  esOut);.  int (*
101c0 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73  xFullPathname)(s
101d0 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
101e0 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
101f0 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a  int nOut, char *
10200 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28  zOut);.  void *(
10210 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65  *xDlOpen)(sqlite
10220 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
10230 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a  ar *zFilename);.
10240 20 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f    void (*xDlErro
10250 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  r)(sqlite3_vfs*,
10260 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72   int nByte, char
10270 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f   *zErrMsg);.  vo
10280 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73  id (*(*xDlSym)(s
10290 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64  qlite3_vfs*,void
102a0 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
102b0 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a  Symbol))(void);.
102c0 20 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73    void (*xDlClos
102d0 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  e)(sqlite3_vfs*,
102e0 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28   void*);.  int (
102f0 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71  *xRandomness)(sq
10300 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20  lite3_vfs*, int 
10310 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75  nByte, char *zOu
10320 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65  t);.  int (*xSle
10330 65 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ep)(sqlite3_vfs*
10340 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e  , int microsecon
10350 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75  ds);.  int (*xCu
10360 72 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74  rrentTime)(sqlit
10370 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a  e3_vfs*, double*
10380 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c  );.  int (*xGetL
10390 61 73 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65  astError)(sqlite
103a0 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61  3_vfs*, int, cha
103b0 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20  r *);.  /*.  ** 
103c0 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76  The methods abov
103d0 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e  e are in version
103e0 20 31 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65   1 of the sqlite
103f0 5f 76 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a  _vfs object.  **
10400 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68   definition.  Th
10410 6f 73 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20  ose that follow 
10420 61 72 65 20 61 64 64 65 64 20 69 6e 20 76 65 72  are added in ver
10430 73 69 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a  sion 2 or later.
10440 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75    */.  int (*xCu
10450 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 29 28  rrentTimeInt64)(
10460 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73 71  sqlite3_vfs*, sq
10470 6c 69 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20  lite3_int64*);. 
10480 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74   /*.  ** The met
10490 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69  hods above are i
104a0 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 61 6e 64  n versions 1 and
104b0 20 32 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65   2 of the sqlite
104c0 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a  _vfs object..  *
104d0 2a 20 54 68 6f 73 65 20 62 65 6c 6f 77 20 61 72  * Those below ar
104e0 65 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20  e for version 3 
104f0 61 6e 64 20 67 72 65 61 74 65 72 2e 0a 20 20 2a  and greater..  *
10500 2f 0a 20 20 69 6e 74 20 28 2a 78 53 65 74 53 79  /.  int (*xSetSy
10510 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65  stemCall)(sqlite
10520 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
10530 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74  ar *zName, sqlit
10540 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 3b  e3_syscall_ptr);
10550 0a 20 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61  .  sqlite3_sysca
10560 6c 6c 5f 70 74 72 20 28 2a 78 47 65 74 53 79 73  ll_ptr (*xGetSys
10570 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33  temCall)(sqlite3
10580 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
10590 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e  r *zName);.  con
105a0 73 74 20 63 68 61 72 20 2a 28 2a 78 4e 65 78 74  st char *(*xNext
105b0 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69  SystemCall)(sqli
105c0 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
105d0 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20  char *zName);.  
105e0 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68  /*.  ** The meth
105f0 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e  ods above are in
10600 20 76 65 72 73 69 6f 6e 73 20 31 20 74 68 72 6f   versions 1 thro
10610 75 67 68 20 33 20 6f 66 20 74 68 65 20 73 71 6c  ugh 3 of the sql
10620 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a  ite_vfs object..
10630 20 20 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73 20    ** New fields 
10640 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20  may be appended 
10650 69 6e 20 66 69 67 75 72 65 20 76 65 72 73 69 6f  in figure versio
10660 6e 73 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f  ns.  The iVersio
10670 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c  n.  ** value wil
10680 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e  l increment when
10690 65 76 65 72 20 74 68 69 73 20 68 61 70 70 65 6e  ever this happen
106a0 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a  s. .  */.};../*.
106b0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61  ** CAPI3REF: Fla
106c0 67 73 20 66 6f 72 20 74 68 65 20 78 41 63 63 65  gs for the xAcce
106d0 73 73 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a  ss VFS method.**
106e0 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65  .** These intege
106f0 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20  r constants can 
10700 62 65 20 75 73 65 64 20 61 73 20 74 68 65 20 74  be used as the t
10710 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
10720 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73  o.** the xAccess
10730 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73   method of an [s
10740 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
10750 63 74 2e 20 20 54 68 65 79 20 64 65 74 65 72 6d  ct.  They determ
10760 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64  ine.** what kind
10770 20 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 20   of permissions 
10780 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
10790 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f  od is looking fo
107a0 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54  r..** With SQLIT
107b0 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c  E_ACCESS_EXISTS,
107c0 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
107d0 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68  hod.** simply ch
107e0 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65  ecks whether the
107f0 20 66 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a   file exists..**
10800 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43   With SQLITE_ACC
10810 45 53 53 5f 52 45 41 44 57 52 49 54 45 2c 20 74  ESS_READWRITE, t
10820 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
10830 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74  d.** checks whet
10840 68 65 72 20 74 68 65 20 6e 61 6d 65 64 20 64 69  her the named di
10850 72 65 63 74 6f 72 79 20 69 73 20 62 6f 74 68 20  rectory is both 
10860 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69  readable and wri
10870 74 61 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68  table.** (in oth
10880 65 72 20 77 6f 72 64 73 2c 20 69 66 20 66 69 6c  er words, if fil
10890 65 73 20 63 61 6e 20 62 65 20 61 64 64 65 64 2c  es can be added,
108a0 20 72 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65   removed, and re
108b0 6e 61 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20  named within.** 
108c0 74 68 65 20 64 69 72 65 63 74 6f 72 79 29 2e 0a  the directory)..
108d0 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43  ** The SQLITE_AC
108e0 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 63  CESS_READWRITE c
108f0 6f 6e 73 74 61 6e 74 20 69 73 20 63 75 72 72 65  onstant is curre
10900 6e 74 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20 62  ntly used only b
10910 79 20 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73  y the.** [temp_s
10920 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70  tore_directory p
10930 72 61 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74  ragma], though t
10940 68 69 73 20 63 6f 75 6c 64 20 63 68 61 6e 67 65  his could change
10950 20 69 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20   in a future.** 
10960 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74  release of SQLit
10970 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54  e..** With SQLIT
10980 45 5f 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74  E_ACCESS_READ, t
10990 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
109a0 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74  d.** checks whet
109b0 68 65 72 20 74 68 65 20 66 69 6c 65 20 69 73 20  her the file is 
109c0 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20 53  readable.  The S
109d0 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
109e0 44 20 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a  D constant is.**
109f0 20 63 75 72 72 65 6e 74 6c 79 20 75 6e 75 73 65   currently unuse
10a00 64 2c 20 74 68 6f 75 67 68 20 69 74 20 6d 69 67  d, though it mig
10a10 68 74 20 62 65 20 75 73 65 64 20 69 6e 20 61 20  ht be used in a 
10a20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f  future release o
10a30 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  f.** SQLite..*/.
10a40 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
10a50 43 43 45 53 53 5f 45 58 49 53 54 53 20 20 20 20  CCESS_EXISTS    
10a60 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
10a70 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
10a80 45 20 31 20 20 20 2f 2a 20 55 73 65 64 20 62 79  E 1   /* Used by
10a90 20 50 52 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f   PRAGMA temp_sto
10aa0 72 65 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a  re_directory */.
10ab0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
10ac0 43 43 45 53 53 5f 52 45 41 44 20 20 20 20 20 20  CCESS_READ      
10ad0 32 20 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f  2   /* Unused */
10ae0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
10af0 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20  : Flags for the 
10b00 78 53 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74  xShmLock VFS met
10b10 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  hod.**.** These 
10b20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74  integer constant
10b30 73 20 64 65 66 69 6e 65 20 74 68 65 20 76 61 72  s define the var
10b40 69 6f 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65  ious locking ope
10b50 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77  rations.** allow
10b60 65 64 20 62 79 20 74 68 65 20 78 53 68 6d 4c 6f  ed by the xShmLo
10b70 63 6b 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71  ck method of [sq
10b80 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
10b90 5d 2e 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f  ].  The.** follo
10ba0 77 69 6e 67 20 61 72 65 20 74 68 65 20 6f 6e 6c  wing are the onl
10bb0 79 20 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74  y legal combinat
10bc0 69 6f 6e 73 20 6f 66 20 66 6c 61 67 73 20 74 6f  ions of flags to
10bd0 20 74 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b   the.** xShmLock
10be0 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c   method:.**.** <
10bf0 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  ul>.** <li>  SQL
10c00 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53  ITE_SHM_LOCK | S
10c10 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44  QLITE_SHM_SHARED
10c20 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
10c30 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49  _SHM_LOCK | SQLI
10c40 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45  TE_SHM_EXCLUSIVE
10c50 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
10c60 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51  _SHM_UNLOCK | SQ
10c70 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a  LITE_SHM_SHARED.
10c80 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f  ** <li>  SQLITE_
10c90 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c  SHM_UNLOCK | SQL
10ca0 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56  ITE_SHM_EXCLUSIV
10cb0 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  E.** </ul>.**.**
10cc0 20 57 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c   When unlocking,
10cd0 20 74 68 65 20 73 61 6d 65 20 53 48 41 52 45 44   the same SHARED
10ce0 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 66 6c   or EXCLUSIVE fl
10cf0 61 67 20 6d 75 73 74 20 62 65 20 73 75 70 70 6c  ag must be suppl
10d00 69 65 64 20 61 73 0a 2a 2a 20 77 61 73 20 67 69  ied as.** was gi
10d10 76 65 6e 20 6f 6e 20 74 68 65 20 63 6f 72 72 65  ven on the corre
10d20 73 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20  sponding lock.  
10d30 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c  .**.** The xShmL
10d40 6f 63 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20 74  ock method can t
10d50 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65  ransition betwee
10d60 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53  n unlocked and S
10d70 48 41 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77  HARED or.** betw
10d80 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64  een unlocked and
10d90 20 45 58 43 4c 55 53 49 56 45 2e 20 20 49 74 20   EXCLUSIVE.  It 
10da0 63 61 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f  cannot transitio
10db0 6e 20 62 65 74 77 65 65 6e 20 53 48 41 52 45 44  n between SHARED
10dc0 0a 2a 2a 20 61 6e 64 20 45 58 43 4c 55 53 49 56  .** and EXCLUSIV
10dd0 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  E..*/.#define SQ
10de0 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20  LITE_SHM_UNLOCK 
10df0 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
10e00 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20  SQLITE_SHM_LOCK 
10e10 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e          2.#defin
10e20 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41  e SQLITE_SHM_SHA
10e30 52 45 44 20 20 20 20 20 20 20 34 0a 23 64 65 66  RED       4.#def
10e40 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45  ine SQLITE_SHM_E
10e50 58 43 4c 55 53 49 56 45 20 20 20 20 38 0a 0a 2f  XCLUSIVE    8../
10e60 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
10e70 61 78 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20  aximum xShmLock 
10e80 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20  index.**.** The 
10e90 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20  xShmLock method 
10ea0 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  on [sqlite3_io_m
10eb0 65 74 68 6f 64 73 5d 20 6d 61 79 20 75 73 65 20  ethods] may use 
10ec0 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65  values.** betwee
10ed0 6e 20 30 20 61 6e 64 20 74 68 69 73 20 75 70 70  n 0 and this upp
10ee0 65 72 20 62 6f 75 6e 64 20 61 73 20 69 74 73 20  er bound as its 
10ef0 22 6f 66 66 73 65 74 22 20 61 72 67 75 6d 65 6e  "offset" argumen
10f00 74 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65  t..** The SQLite
10f10 20 63 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65 72   core will never
10f20 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63 71 75   attempt to acqu
10f30 69 72 65 20 6f 72 20 72 65 6c 65 61 73 65 20 61  ire or release a
10f40 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65  .** lock outside
10f50 20 6f 66 20 74 68 69 73 20 72 61 6e 67 65 0a 2a   of this range.*
10f60 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
10f70 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20  _SHM_NLOCK      
10f80 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49    8.../*.** CAPI
10f90 33 52 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65  3REF: Initialize
10fa0 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72   The SQLite Libr
10fb0 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ary.**.** ^The s
10fc0 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
10fd0 65 28 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74  e() routine init
10fe0 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53  ializes the.** S
10ff0 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20  QLite library.  
11000 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75  ^The sqlite3_shu
11010 74 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a  tdown() routine.
11020 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61  ** deallocates a
11030 6e 79 20 72 65 73 6f 75 72 63 65 73 20 74 68 61  ny resources tha
11040 74 20 77 65 72 65 20 61 6c 6c 6f 63 61 74 65 64  t were allocated
11050 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   by sqlite3_init
11060 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65  ialize()..** The
11070 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
11080 64 65 73 69 67 6e 65 64 20 74 6f 20 61 69 64 20  designed to aid 
11090 69 6e 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69  in process initi
110a0 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a  alization and.**
110b0 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62   shutdown on emb
110c0 65 64 64 65 64 20 73 79 73 74 65 6d 73 2e 20 20  edded systems.  
110d0 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c  Workstation appl
110e0 69 63 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a  ications using.*
110f0 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c  * SQLite normall
11100 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f  y do not need to
11110 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 6f   invoke either o
11120 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
11130 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74  ..**.** A call t
11140 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  o sqlite3_initia
11150 6c 69 7a 65 28 29 20 69 73 20 61 6e 20 22 65 66  lize() is an "ef
11160 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66  fective" call if
11170 20 69 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 69   it is.** the fi
11180 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33  rst time sqlite3
11190 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
111a0 20 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 20   invoked during 
111b0 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a  the lifetime of.
111c0 2a 2a 20 74 68 65 20 70 72 6f 63 65 73 73 2c 20  ** the process, 
111d0 6f 72 20 69 66 20 69 74 20 69 73 20 74 68 65 20  or if it is the 
111e0 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74  first time sqlit
111f0 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
11200 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f  is invoked.** fo
11210 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74  llowing a call t
11220 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
11230 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e  wn().  ^(Only an
11240 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 0a   effective call.
11250 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e  ** of sqlite3_in
11260 69 74 69 61 6c 69 7a 65 28 29 20 64 6f 65 73 20  itialize() does 
11270 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  any initializati
11280 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 63  on.  All other c
11290 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d  alls.** are harm
112a0 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a  less no-ops.)^.*
112b0 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73  *.** A call to s
112c0 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
112d0 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 74 69  ) is an "effecti
112e0 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69  ve" call if it i
112f0 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 63  s the first.** c
11300 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
11310 68 75 74 64 6f 77 6e 28 29 20 73 69 6e 63 65 20  hutdown() since 
11320 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33  the last sqlite3
11330 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20 20  _initialize().  
11340 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66  ^(Only.** an eff
11350 65 63 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 73  ective call to s
11360 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
11370 29 20 64 6f 65 73 20 61 6e 79 20 64 65 69 6e 69  ) does any deini
11380 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20  tialization..** 
11390 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 69 64 20  All other valid 
113a0 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
113b0 5f 73 68 75 74 64 6f 77 6e 28 29 20 61 72 65 20  _shutdown() are 
113c0 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e  harmless no-ops.
113d0 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  )^.**.** The sql
113e0 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
113f0 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74  ) interface is t
11400 68 72 65 61 64 73 61 66 65 2c 20 62 75 74 20 73  hreadsafe, but s
11410 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
11420 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68  ).** is not.  Th
11430 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  e sqlite3_shutdo
11440 77 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d  wn() interface m
11450 75 73 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c  ust only be call
11460 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e  ed from a.** sin
11470 67 6c 65 20 74 68 72 65 61 64 2e 20 20 41 6c 6c  gle thread.  All
11480 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20   open [database 
11490 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73  connections] mus
114a0 74 20 62 65 20 63 6c 6f 73 65 64 20 61 6e 64 20  t be closed and 
114b0 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c  all.** other SQL
114c0 69 74 65 20 72 65 73 6f 75 72 63 65 73 20 6d 75  ite resources mu
114d0 73 74 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65  st be deallocate
114e0 64 20 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b  d prior to invok
114f0 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  ing.** sqlite3_s
11500 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a  hutdown()..**.**
11510 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69   Among other thi
11520 6e 67 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e  ngs, ^sqlite3_in
11530 69 74 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20  itialize() will 
11540 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65  invoke.** sqlite
11550 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69  3_os_init().  Si
11560 6d 69 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65  milarly, ^sqlite
11570 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20  3_shutdown().** 
11580 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69  will invoke sqli
11590 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a  te3_os_end()..**
115a0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
115b0 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f  _initialize() ro
115c0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53  utine returns [S
115d0 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63  QLITE_OK] on suc
115e0 63 65 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72  cess..** ^If for
115f0 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71   some reason, sq
11600 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
11610 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  () is unable to 
11620 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68  initialize.** th
11630 65 20 6c 69 62 72 61 72 79 20 28 70 65 72 68 61  e library (perha
11640 70 73 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20  ps it is unable 
11650 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65  to allocate a ne
11660 65 64 65 64 20 72 65 73 6f 75 72 63 65 20 73 75  eded resource su
11670 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 78  ch.** as a mutex
11680 29 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20  ) it returns an 
11690 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68  [error code] oth
116a0 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
116b0 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  OK]..**.** ^The 
116c0 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
116d0 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20  ze() routine is 
116e0 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c  called internall
116f0 79 20 62 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a  y by many other.
11700 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  ** SQLite interf
11710 61 63 65 73 20 73 6f 20 74 68 61 74 20 61 6e 20  aces so that an 
11720 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 75 61  application usua
11730 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  lly does not nee
11740 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73  d to.** invoke s
11750 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
11760 65 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 46  e() directly.  F
11770 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c  or example, [sql
11780 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20  ite3_open()].** 
11790 63 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e  calls sqlite3_in
117a0 69 74 69 61 6c 69 7a 65 28 29 20 73 6f 20 74 68  itialize() so th
117b0 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  e SQLite library
117c0 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74   will be automat
117d0 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61  ically.** initia
117e0 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c 69  lized when [sqli
117f0 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63  te3_open()] is c
11800 61 6c 6c 65 64 20 69 66 20 69 74 20 68 61 73 20  alled if it has 
11810 6e 6f 74 20 62 65 20 69 6e 69 74 69 61 6c 69 7a  not be initializ
11820 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20  ed.** already.  
11830 5e 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c  ^However, if SQL
11840 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
11850 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45  with the [SQLITE
11860 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a  _OMIT_AUTOINIT].
11870 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  ** compile-time 
11880 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65  option, then the
11890 20 61 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73   automatic calls
118a0 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   to sqlite3_init
118b0 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20  ialize().** are 
118c0 6f 6d 69 74 74 65 64 20 61 6e 64 20 74 68 65 20  omitted and the 
118d0 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
118e0 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e   call sqlite3_in
118f0 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63  itialize() direc
11900 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20  tly.** prior to 
11910 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20  using any other 
11920 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
11930 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70  .  For maximum p
11940 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69  ortability,.** i
11950 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  t is recommended
11960 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f   that applicatio
11970 6e 73 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65  ns always invoke
11980 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
11990 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c  ize().** directl
119a0 79 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67  y prior to using
119b0 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74   any other SQLit
119c0 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 75  e interface.  Fu
119d0 74 75 72 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a  ture releases.**
119e0 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 72   of SQLite may r
119f0 65 71 75 69 72 65 20 74 68 69 73 2e 20 20 49 6e  equire this.  In
11a00 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
11a10 65 20 62 65 68 61 76 69 6f 72 20 65 78 68 69 62  e behavior exhib
11a20 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c  ited.** when SQL
11a30 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
11a40 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49  with [SQLITE_OMI
11a50 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68  T_AUTOINIT] migh
11a60 74 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20  t become the.** 
11a70 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72  default behavior
11a80 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20   in some future 
11a90 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74  release of SQLit
11aa0 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  e..**.** The sql
11ab0 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72  ite3_os_init() r
11ac0 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72  outine does oper
11ad0 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65  ating-system spe
11ae0 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c  cific.** initial
11af0 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53  ization of the S
11b00 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20  QLite library.  
11b10 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  The sqlite3_os_e
11b20 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  nd().** routine 
11b30 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65 63  undoes the effec
11b40 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f  t of sqlite3_os_
11b50 69 6e 69 74 28 29 2e 20 20 54 79 70 69 63 61 6c  init().  Typical
11b60 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72   tasks.** perfor
11b70 6d 65 64 20 62 79 20 74 68 65 73 65 20 72 6f 75  med by these rou
11b80 74 69 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 6c  tines include al
11b90 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c  location or deal
11ba0 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73  location.** of s
11bb0 74 61 74 69 63 20 72 65 73 6f 75 72 63 65 73 2c  tatic resources,
11bc0 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
11bd0 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62  of global variab
11be0 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20  les,.** setting 
11bf0 75 70 20 61 20 64 65 66 61 75 6c 74 20 5b 73 71  up a default [sq
11c00 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c  lite3_vfs] modul
11c10 65 2c 20 6f 72 20 73 65 74 74 69 6e 67 20 75 70  e, or setting up
11c20 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74 20 63 6f  .** a default co
11c30 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 73 69 6e  nfiguration usin
11c40 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  g [sqlite3_confi
11c50 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  g()]..**.** The 
11c60 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
11c70 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20  ld never invoke 
11c80 65 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f  either sqlite3_o
11c90 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73  s_init().** or s
11ca0 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20  qlite3_os_end() 
11cb0 64 69 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61  directly.  The a
11cc0 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
11cd0 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a  d only invoke.**
11ce0 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
11cf0 69 7a 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ize() and sqlite
11d00 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54  3_shutdown().  T
11d10 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  he sqlite3_os_in
11d20 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  it().** interfac
11d30 65 20 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f  e is called auto
11d40 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c  matically by sql
11d50 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
11d60 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ) and.** sqlite3
11d70 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20 63 61 6c  _os_end() is cal
11d80 6c 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73  led by sqlite3_s
11d90 68 75 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 72  hutdown().  Appr
11da0 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65  opriate.** imple
11db0 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 73  mentations for s
11dc0 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
11dd0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f   and sqlite3_os_
11de0 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 69  end().** are bui
11df0 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 77  lt into SQLite w
11e00 68 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c  hen it is compil
11e10 65 64 20 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e  ed for Unix, Win
11e20 64 6f 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a  dows, or OS/2..*
11e30 2a 20 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62  * When [custom b
11e40 75 69 6c 64 73 20 7c 20 62 75 69 6c 74 20 66 6f  uilds | built fo
11e50 72 20 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d  r other platform
11e60 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68 65  s].** (using the
11e70 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45   [SQLITE_OS_OTHE
11e80 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  R=1] compile-tim
11e90 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65  e.** option) the
11ea0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
11eb0 74 20 73 75 70 70 6c 79 20 61 20 73 75 69 74 61  t supply a suita
11ec0 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ble implementati
11ed0 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  on for.** sqlite
11ee0 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20  3_os_init() and 
11ef0 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
11f00 2e 20 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f  .  An applicatio
11f10 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d  n-supplied.** im
11f20 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
11f30 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
11f40 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f  ) or sqlite3_os_
11f50 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65  end().** must re
11f60 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
11f70 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20   on success and 
11f80 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72 72 6f  some other [erro
11f90 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20  r code] upon.** 
11fa0 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 53 51 4c 49  failure..*/.SQLI
11fb0 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54  TE_API int SQLIT
11fc0 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
11fd0 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69  3_initialize(voi
11fe0 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  d);.SQLITE_API i
11ff0 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  nt SQLITE_STDCAL
12000 4c 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  L sqlite3_shutdo
12010 77 6e 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45  wn(void);.SQLITE
12020 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f  _API int SQLITE_
12030 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
12040 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a 53  os_init(void);.S
12050 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51  QLITE_API int SQ
12060 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
12070 69 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64  ite3_os_end(void
12080 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
12090 45 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67 20  EF: Configuring 
120a0 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61  The SQLite Libra
120b0 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  ry.**.** The sql
120c0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e  ite3_config() in
120d0 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20  terface is used 
120e0 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 63  to make global c
120f0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20  onfiguration.** 
12100 63 68 61 6e 67 65 73 20 74 6f 20 53 51 4c 69 74  changes to SQLit
12110 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 74 75  e in order to tu
12120 6e 65 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65  ne SQLite to the
12130 20 73 70 65 63 69 66 69 63 20 6e 65 65 64 73 20   specific needs 
12140 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  of.** the applic
12150 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 66 61  ation.  The defa
12160 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ult configuratio
12170 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  n is recommended
12180 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 70   for most.** app
12190 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64 20 73 6f  lications and so
121a0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73   this routine is
121b0 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 63   usually not nec
121c0 65 73 73 61 72 79 2e 20 20 49 74 20 69 73 0a 2a  essary.  It is.*
121d0 2a 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 75  * provided to su
121e0 70 70 6f 72 74 20 72 61 72 65 20 61 70 70 6c 69  pport rare appli
121f0 63 61 74 69 6f 6e 73 20 77 69 74 68 20 75 6e 75  cations with unu
12200 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a  sual needs..**.*
12210 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  * The sqlite3_co
12220 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65  nfig() interface
12230 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73 61   is not threadsa
12240 66 65 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61  fe.  The applica
12250 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 73  tion.** must ins
12260 75 72 65 20 74 68 61 74 20 6e 6f 20 6f 74 68 65  ure that no othe
12270 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  r SQLite interfa
12280 63 65 73 20 61 72 65 20 69 6e 76 6f 6b 65 64 20  ces are invoked 
12290 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68 72 65  by other.** thre
122a0 61 64 73 20 77 68 69 6c 65 20 73 71 6c 69 74 65  ads while sqlite
122b0 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 72 75  3_config() is ru
122c0 6e 6e 69 6e 67 2e 20 20 46 75 72 74 68 65 72 6d  nning.  Furtherm
122d0 6f 72 65 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e  ore, sqlite3_con
122e0 66 69 67 28 29 0a 2a 2a 20 6d 61 79 20 6f 6e 6c  fig().** may onl
122f0 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 72 69  y be invoked pri
12300 6f 72 20 74 6f 20 6c 69 62 72 61 72 79 20 69 6e  or to library in
12310 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75 73 69  itialization usi
12320 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69  ng.** [sqlite3_i
12330 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f 72 20  nitialize()] or 
12340 61 66 74 65 72 20 73 68 75 74 64 6f 77 6e 20 62  after shutdown b
12350 79 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64  y [sqlite3_shutd
12360 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20 73  own()]..** ^If s
12370 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
12380 69 73 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20  is called after 
12390 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c  [sqlite3_initial
123a0 69 7a 65 28 29 5d 20 61 6e 64 20 62 65 66 6f 72  ize()] and befor
123b0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68  e.** [sqlite3_sh
123c0 75 74 64 6f 77 6e 28 29 5d 20 74 68 65 6e 20 69  utdown()] then i
123d0 74 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 53 51  t will return SQ
123e0 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a 20  LITE_MISUSE..** 
123f0 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c 20 74  Note, however, t
12400 68 61 74 20 5e 73 71 6c 69 74 65 33 5f 63 6f 6e  hat ^sqlite3_con
12410 66 69 67 28 29 20 63 61 6e 20 62 65 20 63 61 6c  fig() can be cal
12420 6c 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74  led as part of t
12430 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  he.** implementa
12440 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c 69  tion of an appli
12450 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 5b  cation-defined [
12460 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
12470 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  )]..**.** The fi
12480 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
12490 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
124a0 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a   is an integer.*
124b0 2a 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  * [configuration
124c0 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20 64 65   option] that de
124d0 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74  termines.** what
124e0 20 70 72 6f 70 65 72 74 79 20 6f 66 20 53 51 4c   property of SQL
124f0 69 74 65 20 69 73 20 74 6f 20 62 65 20 63 6f 6e  ite is to be con
12500 66 69 67 75 72 65 64 2e 20 20 53 75 62 73 65 71  figured.  Subseq
12510 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a  uent arguments.*
12520 2a 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67  * vary depending
12530 20 6f 6e 20 74 68 65 20 5b 63 6f 6e 66 69 67 75   on the [configu
12540 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a  ration option].*
12550 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61  * in the first a
12560 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e  rgument..**.** ^
12570 57 68 65 6e 20 61 20 63 6f 6e 66 69 67 75 72 61  When a configura
12580 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 73  tion option is s
12590 65 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  et, sqlite3_conf
125a0 69 67 28 29 20 72 65 74 75 72 6e 73 20 5b 53 51  ig() returns [SQ
125b0 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66  LITE_OK]..** ^If
125c0 20 74 68 65 20 6f 70 74 69 6f 6e 20 69 73 20 75   the option is u
125d0 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74 65  nknown or SQLite
125e0 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 73 65   is unable to se
125f0 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20  t the option.** 
12600 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e  then this routin
12610 65 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d  e returns a non-
12620 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65  zero [error code
12630 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  ]..*/.SQLITE_API
12640 20 69 6e 74 20 53 51 4c 49 54 45 5f 43 44 45 43   int SQLITE_CDEC
12650 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  L sqlite3_config
12660 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a  (int, ...);../*.
12670 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
12680 66 69 67 75 72 65 20 64 61 74 61 62 61 73 65 20  figure database 
12690 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 0a 2a  connections.**.*
126a0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62  * The sqlite3_db
126b0 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66  _config() interf
126c0 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d  ace is used to m
126d0 61 6b 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ake configuratio
126e0 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20  n.** changes to 
126f0 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
12700 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e  ection].  The in
12710 74 65 72 66 61 63 65 20 69 73 20 73 69 6d 69 6c  terface is simil
12720 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ar to.** [sqlite
12730 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65 78 63 65  3_config()] exce
12740 70 74 20 74 68 61 74 20 74 68 65 20 63 68 61 6e  pt that the chan
12750 67 65 73 20 61 70 70 6c 79 20 74 6f 20 61 20 73  ges apply to a s
12760 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61  ingle.** [databa
12770 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28  se connection] (
12780 73 70 65 63 69 66 69 65 64 20 69 6e 20 74 68 65  specified in the
12790 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 29   first argument)
127a0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f  ..**.** The seco
127b0 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  nd argument to s
127c0 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
127d0 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68  (D,V,...)  is th
127e0 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 42 43  e.** [SQLITE_DBC
127f0 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20  ONFIG_LOOKASIDE 
12800 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  | configuration 
12810 76 65 72 62 5d 20 2d 20 61 6e 20 69 6e 74 65 67  verb] - an integ
12820 65 72 20 63 6f 64 65 20 0a 2a 2a 20 74 68 61 74  er code .** that
12830 20 69 6e 64 69 63 61 74 65 73 20 77 68 61 74 20   indicates what 
12840 61 73 70 65 63 74 20 6f 66 20 74 68 65 20 5b 64  aspect of the [d
12850 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
12860 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 63 6f 6e  on] is being con
12870 66 69 67 75 72 65 64 2e 0a 2a 2a 20 53 75 62 73  figured..** Subs
12880 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73  equent arguments
12890 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20   vary depending 
128a0 6f 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61  on the configura
128b0 74 69 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a  tion verb..**.**
128c0 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74   ^Calls to sqlit
128d0 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 72  e3_db_config() r
128e0 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20  eturn SQLITE_OK 
128f0 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a  if and only if.*
12900 2a 20 74 68 65 20 63 61 6c 6c 20 69 73 20 63 6f  * the call is co
12910 6e 73 69 64 65 72 65 64 20 73 75 63 63 65 73 73  nsidered success
12920 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ful..*/.SQLITE_A
12930 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 43 44  PI int SQLITE_CD
12940 45 43 4c 20 73 71 6c 69 74 65 33 5f 64 62 5f 63  ECL sqlite3_db_c
12950 6f 6e 66 69 67 28 73 71 6c 69 74 65 33 2a 2c 20  onfig(sqlite3*, 
12960 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f  int op, ...);../
12970 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
12980 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e  emory Allocation
12990 20 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20   Routines.**.** 
129a0 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  An instance of t
129b0 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e  his object defin
129c0 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
129d0 20 62 65 74 77 65 65 6e 20 53 51 4c 69 74 65 0a   between SQLite.
129e0 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c  ** and low-level
129f0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
12a00 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a  on routines..**.
12a10 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69  ** This object i
12a20 73 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f  s used in only o
12a30 6e 65 20 70 6c 61 63 65 20 69 6e 20 74 68 65 20  ne place in the 
12a40 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
12a50 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74  ..** A pointer t
12a60 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  o an instance of
12a70 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20   this object is 
12a80 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  the argument to.
12a90 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
12aa0 69 67 28 29 5d 20 77 68 65 6e 20 74 68 65 20 63  ig()] when the c
12ab0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
12ac0 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54  ion is.** [SQLIT
12ad0 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d  E_CONFIG_MALLOC]
12ae0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   or [SQLITE_CONF
12af0 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20  IG_GETMALLOC].  
12b00 0a 2a 2a 20 42 79 20 63 72 65 61 74 69 6e 67 20  .** By creating 
12b10 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
12b20 68 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e  his object.** an
12b30 64 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20  d passing it to 
12b40 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d  [sqlite3_config]
12b50 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  ([SQLITE_CONFIG_
12b60 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 69  MALLOC]).** duri
12b70 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ng configuration
12b80 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  , an application
12b90 20 63 61 6e 20 73 70 65 63 69 66 79 20 61 6e 20   can specify an 
12ba0 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d  alternative.** m
12bb0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
12bc0 20 73 75 62 73 79 73 74 65 6d 20 66 6f 72 20 53   subsystem for S
12bd0 51 4c 69 74 65 20 74 6f 20 75 73 65 20 66 6f 72  QLite to use for
12be0 20 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 64   all of its.** d
12bf0 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65  ynamic memory ne
12c00 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  eds..**.** Note 
12c10 74 68 61 74 20 53 51 4c 69 74 65 20 63 6f 6d 65  that SQLite come
12c20 73 20 77 69 74 68 20 73 65 76 65 72 61 6c 20 5b  s with several [
12c30 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20  built-in memory 
12c40 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 74  allocators].** t
12c50 68 61 74 20 61 72 65 20 70 65 72 66 65 63 74 6c  hat are perfectl
12c60 79 20 61 64 65 71 75 61 74 65 20 66 6f 72 20 74  y adequate for t
12c70 68 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20  he overwhelming 
12c80 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70 6c  majority of appl
12c90 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20  ications.** and 
12ca0 74 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63 74  that this object
12cb0 20 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20   is only useful 
12cc0 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69  to a tiny minori
12cd0 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f  ty of applicatio
12ce0 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63 69  ns.** with speci
12cf0 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c  alized memory al
12d00 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72 65  location require
12d10 6d 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62 6a  ments.  This obj
12d20 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75  ect is.** also u
12d30 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69  sed during testi
12d40 6e 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e 20  ng of SQLite in 
12d50 6f 72 64 65 72 20 74 6f 20 73 70 65 63 69 66 79  order to specify
12d60 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a   an alternative.
12d70 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ** memory alloca
12d80 74 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74  tor that simulat
12d90 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66  es memory out-of
12da0 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f  -memory conditio
12db0 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74  ns in.** order t
12dc0 6f 20 76 65 72 69 66 79 20 74 68 61 74 20 53 51  o verify that SQ
12dd0 4c 69 74 65 20 72 65 63 6f 76 65 72 73 20 67 72  Lite recovers gr
12de0 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75  acefully from su
12df0 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73  ch.** conditions
12e00 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c  ..**.** The xMal
12e10 6c 6f 63 2c 20 78 52 65 61 6c 6c 6f 63 2c 20 61  loc, xRealloc, a
12e20 6e 64 20 78 46 72 65 65 20 6d 65 74 68 6f 64 73  nd xFree methods
12e30 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20   must work like 
12e40 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 2c  the.** malloc(),
12e50 20 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66   realloc() and f
12e60 72 65 65 28 29 20 66 75 6e 63 74 69 6f 6e 73 20  ree() functions 
12e70 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72  from the standar
12e80 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20  d C library..** 
12e90 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65  ^SQLite guarante
12ea0 65 73 20 74 68 61 74 20 74 68 65 20 73 65 63 6f  es that the seco
12eb0 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  nd argument to.*
12ec0 2a 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 61 6c  * xRealloc is al
12ed0 77 61 79 73 20 61 20 76 61 6c 75 65 20 72 65 74  ways a value ret
12ee0 75 72 6e 65 64 20 62 79 20 61 20 70 72 69 6f 72  urned by a prior
12ef0 20 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 75   call to xRoundu
12f00 70 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 73  p..**.** xSize s
12f10 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65  hould return the
12f20 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20   allocated size 
12f30 6f 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  of a memory allo
12f40 63 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f  cation.** previo
12f50 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72  usly obtained fr
12f60 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 52  om xMalloc or xR
12f70 65 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61 6c 6c  ealloc.  The all
12f80 6f 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a 20 69  ocated size.** i
12f90 73 20 61 6c 77 61 79 73 20 61 74 20 6c 65 61 73  s always at leas
12fa0 74 20 61 73 20 62 69 67 20 61 73 20 74 68 65 20  t as big as the 
12fb0 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 20 62  requested size b
12fc0 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72  ut may be larger
12fd0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 6f 75  ..**.** The xRou
12fe0 6e 64 75 70 20 6d 65 74 68 6f 64 20 72 65 74 75  ndup method retu
12ff0 72 6e 73 20 77 68 61 74 20 77 6f 75 6c 64 20 62  rns what would b
13000 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20  e the allocated 
13010 73 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d  size of.** a mem
13020 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 67  ory allocation g
13030 69 76 65 6e 20 61 20 70 61 72 74 69 63 75 6c 61  iven a particula
13040 72 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65  r requested size
13050 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a  .  Most memory.*
13060 2a 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75  * allocators rou
13070 6e 64 20 75 70 20 6d 65 6d 6f 72 79 20 61 6c 6c  nd up memory all
13080 6f 63 61 74 69 6f 6e 73 20 61 74 20 6c 65 61 73  ocations at leas
13090 74 20 74 6f 20 74 68 65 20 6e 65 78 74 20 6d 75  t to the next mu
130a0 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20  ltiple.** of 8. 
130b0 20 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 73   Some allocators
130c0 20 72 6f 75 6e 64 20 75 70 20 74 6f 20 61 20 6c   round up to a l
130d0 61 72 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f  arger multiple o
130e0 72 20 74 6f 20 61 20 70 6f 77 65 72 20 6f 66 20  r to a power of 
130f0 32 2e 0a 2a 2a 20 45 76 65 72 79 20 6d 65 6d 6f  2..** Every memo
13100 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65  ry allocation re
13110 71 75 65 73 74 20 63 6f 6d 69 6e 67 20 69 6e 20  quest coming in 
13120 74 68 72 6f 75 67 68 20 5b 73 71 6c 69 74 65 33  through [sqlite3
13130 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72  _malloc()].** or
13140 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
13150 63 28 29 5d 20 66 69 72 73 74 20 63 61 6c 6c 73  c()] first calls
13160 20 78 52 6f 75 6e 64 75 70 2e 20 20 49 66 20 78   xRoundup.  If x
13170 52 6f 75 6e 64 75 70 20 72 65 74 75 72 6e 73 20  Roundup returns 
13180 30 2c 20 0a 2a 2a 20 74 68 61 74 20 63 61 75 73  0, .** that caus
13190 65 73 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  es the correspon
131a0 64 69 6e 67 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ding memory allo
131b0 63 61 74 69 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a  cation to fail..
131c0 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74 20  **.** The xInit 
131d0 6d 65 74 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a  method initializ
131e0 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c  es the memory al
131f0 6c 6f 63 61 74 6f 72 2e 20 20 46 6f 72 20 65 78  locator.  For ex
13200 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67  ample,.** it mig
13210 68 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20  ht allocate any 
13220 72 65 71 75 69 72 65 20 6d 75 74 65 78 65 73 20  require mutexes 
13230 6f 72 20 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e  or initialize in
13240 74 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73  ternal data.** s
13250 74 72 75 63 74 75 72 65 73 2e 20 20 54 68 65 20  tructures.  The 
13260 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64  xShutdown method
13270 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64   is invoked (ind
13280 69 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b  irectly) by.** [
13290 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
132a0 28 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20 64  ()] and should d
132b0 65 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65  eallocate any re
132c0 73 6f 75 72 63 65 73 20 61 63 71 75 69 72 65 64  sources acquired
132d0 0a 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20 20 54  .** by xInit.  T
132e0 68 65 20 70 41 70 70 44 61 74 61 20 70 6f 69 6e  he pAppData poin
132f0 74 65 72 20 69 73 20 75 73 65 64 20 61 73 20 74  ter is used as t
13300 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65  he only paramete
13310 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e  r to.** xInit an
13320 64 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a  d xShutdown..**.
13330 2a 2a 20 53 51 4c 69 74 65 20 68 6f 6c 64 73 20  ** SQLite holds 
13340 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45  the [SQLITE_MUTE
13350 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 45 52 5d  X_STATIC_MASTER]
13360 20 6d 75 74 65 78 20 77 68 65 6e 20 69 74 20 69   mutex when it i
13370 6e 76 6f 6b 65 73 0a 2a 2a 20 74 68 65 20 78 49  nvokes.** the xI
13380 6e 69 74 20 6d 65 74 68 6f 64 2c 20 73 6f 20 74  nit method, so t
13390 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20  he xInit method 
133a0 6e 65 65 64 20 6e 6f 74 20 62 65 20 74 68 72 65  need not be thre
133b0 61 64 73 61 66 65 2e 20 20 54 68 65 0a 2a 2a 20  adsafe.  The.** 
133c0 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64  xShutdown method
133d0 20 69 73 20 6f 6e 6c 79 20 63 61 6c 6c 65 64 20   is only called 
133e0 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73 68  from [sqlite3_sh
133f0 75 74 64 6f 77 6e 28 29 5d 20 73 6f 20 69 74 20  utdown()] so it 
13400 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64  does.** not need
13410 20 74 6f 20 62 65 20 74 68 72 65 61 64 73 61 66   to be threadsaf
13420 65 20 65 69 74 68 65 72 2e 20 20 46 6f 72 20 61  e either.  For a
13430 6c 6c 20 6f 74 68 65 72 20 6d 65 74 68 6f 64 73  ll other methods
13440 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64  , SQLite.** hold
13450 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55  s the [SQLITE_MU
13460 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 5d 20  TEX_STATIC_MEM] 
13470 6d 75 74 65 78 20 61 73 20 6c 6f 6e 67 20 61 73  mutex as long as
13480 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
13490 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
134a0 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  ] configuration 
134b0 6f 70 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64  option is turned
134c0 20 6f 6e 20 28 77 68 69 63 68 0a 2a 2a 20 69 74   on (which.** it
134d0 20 69 73 20 62 79 20 64 65 66 61 75 6c 74 29 20   is by default) 
134e0 61 6e 64 20 73 6f 20 74 68 65 20 6d 65 74 68 6f  and so the metho
134f0 64 73 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63  ds are automatic
13500 61 6c 6c 79 20 73 65 72 69 61 6c 69 7a 65 64 2e  ally serialized.
13510 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 69 66 20  .** However, if 
13520 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
13530 45 4d 53 54 41 54 55 53 5d 20 69 73 20 64 69 73  EMSTATUS] is dis
13540 61 62 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20  abled, then the 
13550 6f 74 68 65 72 0a 2a 2a 20 6d 65 74 68 6f 64 73  other.** methods
13560 20 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 73   must be threads
13570 61 66 65 20 6f 72 20 65 6c 73 65 20 6d 61 6b 65  afe or else make
13580 20 74 68 65 69 72 20 6f 77 6e 20 61 72 72 61 6e   their own arran
13590 67 65 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a 20 73  gements for.** s
135a0 65 72 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a  erialization..**
135b0 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  .** SQLite will 
135c0 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 78 49 6e  never invoke xIn
135d0 69 74 28 29 20 6d 6f 72 65 20 74 68 61 6e 20 6f  it() more than o
135e0 6e 63 65 20 77 69 74 68 6f 75 74 20 61 6e 20 69  nce without an i
135f0 6e 74 65 72 76 65 6e 69 6e 67 0a 2a 2a 20 63 61  ntervening.** ca
13600 6c 6c 20 74 6f 20 78 53 68 75 74 64 6f 77 6e 28  ll to xShutdown(
13610 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  )..*/.typedef st
13620 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d  ruct sqlite3_mem
13630 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33  _methods sqlite3
13640 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74  _mem_methods;.st
13650 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d  ruct sqlite3_mem
13660 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69  _methods {.  voi
13670 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e  d *(*xMalloc)(in
13680 74 29 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 4d  t);         /* M
13690 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
136a0 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76   function */.  v
136b0 6f 69 64 20 28 2a 78 46 72 65 65 29 28 76 6f 69  oid (*xFree)(voi
136c0 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a  d*);          /*
136d0 20 46 72 65 65 20 61 20 70 72 69 6f 72 20 61 6c   Free a prior al
136e0 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f  location */.  vo
136f0 69 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28  id *(*xRealloc)(
13700 76 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20  void*,int);  /* 
13710 52 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61  Resize an alloca
13720 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  tion */.  int (*
13730 78 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20  xSize)(void*);  
13740 20 20 20 20 20 20 20 20 20 2f 2a 20 52 65 74 75           /* Retu
13750 72 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61  rn the size of a
13760 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a  n allocation */.
13770 20 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70    int (*xRoundup
13780 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20  )(int);         
13790 20 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72 65 71   /* Round up req
137a0 75 65 73 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c  uest size to all
137b0 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a  ocation size */.
137c0 20 20 69 6e 74 20 28 2a 78 49 6e 69 74 29 28 76    int (*xInit)(v
137d0 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20  oid*);          
137e0 20 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65 20 74   /* Initialize t
137f0 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
13800 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a  tor */.  void (*
13810 78 53 68 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a  xShutdown)(void*
13820 29 3b 20 20 20 20 20 20 2f 2a 20 44 65 69 6e 69  );      /* Deini
13830 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f  tialize the memo
13840 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a  ry allocator */.
13850 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61    void *pAppData
13860 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ;               
13870 20 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74 6f 20   /* Argument to 
13880 78 49 6e 69 74 28 29 20 61 6e 64 20 78 53 68 75  xInit() and xShu
13890 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f  tdown() */.};../
138a0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
138b0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74  onfiguration Opt
138c0 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ions.** KEYWORDS
138d0 3a 20 7b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  : {configuration
138e0 20 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54   option}.**.** T
138f0 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61  hese constants a
13900 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65  re the available
13910 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75   integer configu
13920 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74  ration options t
13930 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61  hat.** can be pa
13940 73 73 65 64 20 61 73 20 74 68 65 20 66 69 72 73  ssed as the firs
13950 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
13960 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  e [sqlite3_confi
13970 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a  g()] interface..
13980 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67  **.** New config
13990 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
139a0 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
139b0 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
139c0 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78  of SQLite..** Ex
139d0 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61  isting configura
139e0 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67  tion options mig
139f0 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75  ht be discontinu
13a00 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  ed.  Application
13a10 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63  s.** should chec
13a20 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64  k the return cod
13a30 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  e from [sqlite3_
13a40 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b  config()] to mak
13a50 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74  e sure that.** t
13a60 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20  he call worked. 
13a70 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
13a80 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63  nfig()] interfac
13a90 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a  e will return a.
13aa0 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72  ** non-zero [err
13ab0 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69  or code] if a di
13ac0 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e  scontinued or un
13ad0 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67  supported config
13ae0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a  uration option.*
13af0 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a  * is invoked..**
13b00 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51  .** <dl>.** [[SQ
13b10 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
13b20 4c 45 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53  LETHREAD]] <dt>S
13b30 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
13b40 47 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a  GLETHREAD</dt>.*
13b50 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20  * <dd>There are 
13b60 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  no arguments to 
13b70 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54  this option.  ^T
13b80 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20  his option sets 
13b90 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e  the.** [threadin
13ba0 67 20 6d 6f 64 65 5d 20 74 6f 20 53 69 6e 67 6c  g mode] to Singl
13bb0 65 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74  e-thread.  In ot
13bc0 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69  her words, it di
13bd0 73 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75  sables.** all mu
13be0 74 65 78 69 6e 67 20 61 6e 64 20 70 75 74 73 20  texing and puts 
13bf0 53 51 4c 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f  SQLite into a mo
13c00 64 65 20 77 68 65 72 65 20 69 74 20 63 61 6e 20  de where it can 
13c10 6f 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a 2a 20  only be used.** 
13c20 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65  by a single thre
13c30 61 64 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65  ad.   ^If SQLite
13c40 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
13c50 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  h.** the [SQLITE
13c60 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51  _THREADSAFE | SQ
13c70 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
13c80 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  0] compile-time 
13c90 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69  option then.** i
13ca0 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c  t is not possibl
13cb0 65 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20  e to change the 
13cc0 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
13cd0 20 66 72 6f 6d 20 69 74 73 20 64 65 66 61 75 6c   from its defaul
13ce0 74 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 53 69  t.** value of Si
13cf0 6e 67 6c 65 2d 74 68 72 65 61 64 20 61 6e 64 20  ngle-thread and 
13d00 73 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  so [sqlite3_conf
13d10 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  ig()] will retur
13d20 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52  n .** [SQLITE_ER
13d30 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77  ROR] if called w
13d40 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43  ith the SQLITE_C
13d50 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
13d60 41 44 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74  AD.** configurat
13d70 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e  ion option.</dd>
13d80 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
13d90 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
13da0 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  AD]] <dt>SQLITE_
13db0 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
13dc0 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  AD</dt>.** <dd>T
13dd0 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75  here are no argu
13de0 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70  ments to this op
13df0 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74  tion.  ^This opt
13e00 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20  ion sets the.** 
13e10 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
13e20 20 74 6f 20 4d 75 6c 74 69 2d 74 68 72 65 61 64   to Multi-thread
13e30 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  .  In other word
13e40 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a  s, it disables.*
13e50 2a 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64  * mutexing on [d
13e60 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
13e70 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65  on] and [prepare
13e80 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a  d statement] obj
13e90 65 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70  ects..** The app
13ea0 6c 69 63 61 74 69 6f 6e 20 69 73 20 72 65 73 70  lication is resp
13eb0 6f 6e 73 69 62 6c 65 20 66 6f 72 20 73 65 72 69  onsible for seri
13ec0 61 6c 69 7a 69 6e 67 20 61 63 63 65 73 73 20 74  alizing access t
13ed0 6f 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  o.** [database c
13ee0 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20  onnections] and 
13ef0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
13f00 65 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74 68 65  ents].  But othe
13f10 72 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65  r mutexes.** are
13f20 20 65 6e 61 62 6c 65 64 20 73 6f 20 74 68 61 74   enabled so that
13f30 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20   SQLite will be 
13f40 73 61 66 65 20 74 6f 20 75 73 65 20 69 6e 20 61  safe to use in a
13f50 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 0a   multi-threaded.
13f60 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 61  ** environment a
13f70 73 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f  s long as no two
13f80 20 74 68 72 65 61 64 73 20 61 74 74 65 6d 70 74   threads attempt
13f90 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65   to use the same
13fa0 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
13fb0 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 74 68 65  nnection] at the
13fc0 20 73 61 6d 65 20 74 69 6d 65 2e 20 20 5e 49 66   same time.  ^If
13fd0 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
13fe0 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
13ff0 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
14000 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45  FE | SQLITE_THRE
14010 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c  ADSAFE=0] compil
14020 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68  e-time option th
14030 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20  en.** it is not 
14040 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20  possible to set 
14050 74 68 65 20 4d 75 6c 74 69 2d 74 68 72 65 61 64  the Multi-thread
14060 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
14070 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
14080 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c  3_config()] will
14090 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
140a0 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64  ERROR] if called
140b0 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c   with the.** SQL
140c0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49  ITE_CONFIG_MULTI
140d0 54 48 52 45 41 44 20 63 6f 6e 66 69 67 75 72 61  THREAD configura
140e0 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64  tion option.</dd
140f0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
14100 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a  _CONFIG_SERIALIZ
14110 45 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  ED]] <dt>SQLITE_
14120 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
14130 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
14140 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d  ere are no argum
14150 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74  ents to this opt
14160 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69  ion.  ^This opti
14170 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b  on sets the.** [
14180 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
14190 74 6f 20 53 65 72 69 61 6c 69 7a 65 64 2e 20 49  to Serialized. I
141a0 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74  n other words, t
141b0 68 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c  his option enabl
141c0 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65  es.** all mutexe
141d0 73 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 65 20  s including the 
141e0 72 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74  recursive.** mut
141f0 65 78 65 73 20 6f 6e 20 5b 64 61 74 61 62 61 73  exes on [databas
14200 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e  e connection] an
14210 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
14220 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a  ement] objects..
14230 2a 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64 65 20  ** In this mode 
14240 28 77 68 69 63 68 20 69 73 20 74 68 65 20 64 65  (which is the de
14250 66 61 75 6c 74 20 77 68 65 6e 20 53 51 4c 69 74  fault when SQLit
14260 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
14270 74 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48  th.** [SQLITE_TH
14280 52 45 41 44 53 41 46 45 3d 31 5d 29 20 74 68 65  READSAFE=1]) the
14290 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20   SQLite library 
142a0 77 69 6c 6c 20 69 74 73 65 6c 66 20 73 65 72 69  will itself seri
142b0 61 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20  alize access.** 
142c0 74 6f 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  to [database con
142d0 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70  nections] and [p
142e0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
142f0 74 73 5d 20 73 6f 20 74 68 61 74 20 74 68 65 0a  ts] so that the.
14300 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69  ** application i
14310 73 20 66 72 65 65 20 74 6f 20 75 73 65 20 74 68  s free to use th
14320 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65  e same [database
14330 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20   connection] or 
14340 74 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65  the.** same [pre
14350 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
14360 20 69 6e 20 64 69 66 66 65 72 65 6e 74 20 74 68   in different th
14370 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d  reads at the sam
14380 65 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53  e time..** ^If S
14390 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
143a0 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53  d with.** the [S
143b0 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
143c0 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44   | SQLITE_THREAD
143d0 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d  SAFE=0] compile-
143e0 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e  time option then
143f0 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f  .** it is not po
14400 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68  ssible to set th
14410 65 20 53 65 72 69 61 6c 69 7a 65 64 20 5b 74 68  e Serialized [th
14420 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e  reading mode] an
14430 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d.** [sqlite3_co
14440 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74  nfig()] will ret
14450 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  urn [SQLITE_ERRO
14460 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74  R] if called wit
14470 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f  h the.** SQLITE_
14480 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
14490 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  D configuration 
144a0 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a  option.</dd>.**.
144b0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
144c0 49 47 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e  IG_MALLOC]] <dt>
144d0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
144e0 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  LLOC</dt>.** <dd
144f0 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43  > ^(The SQLITE_C
14500 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 6f 70 74  ONFIG_MALLOC opt
14510 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
14520 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
14530 68 20 69 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74  h is .** a point
14540 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
14550 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  e of the [sqlite
14560 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73  3_mem_methods] s
14570 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65  tructure..** The
14580 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66   argument specif
14590 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69  ies.** alternati
145a0 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d  ve low-level mem
145b0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
145c0 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73  outines to be us
145d0 65 64 20 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  ed in place of.*
145e0 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  * the memory all
145f0 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
14600 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69   built into SQLi
14610 74 65 2e 29 5e 20 5e 53 51 4c 69 74 65 20 6d 61  te.)^ ^SQLite ma
14620 6b 65 73 0a 2a 2a 20 69 74 73 20 6f 77 6e 20 70  kes.** its own p
14630 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74  rivate copy of t
14640 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
14650 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  e [sqlite3_mem_m
14660 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
14670 65 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 65 20  e.** before the 
14680 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
14690 29 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e  )] call returns.
146a0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
146b0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
146c0 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49  ALLOC]] <dt>SQLI
146d0 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c  TE_CONFIG_GETMAL
146e0 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  LOC</dt>.** <dd>
146f0 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f   ^(The SQLITE_CO
14700 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 6f  NFIG_GETMALLOC o
14710 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
14720 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
14730 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e  ich.** is a poin
14740 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e  ter to an instan
14750 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ce of the [sqlit
14760 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20  e3_mem_methods] 
14770 73 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68  structure..** Th
14780 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  e [sqlite3_mem_m
14790 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63  ethods].** struc
147a0 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77  ture is filled w
147b0 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c  ith the currentl
147c0 79 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f 72 79  y defined memory
147d0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
147e0 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20  ines.)^.** This 
147f0 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73  option can be us
14800 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74  ed to overload t
14810 68 65 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72  he default memor
14820 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  y allocation.** 
14830 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20  routines with a 
14840 77 72 61 70 70 65 72 20 74 68 61 74 20 73 69 6d  wrapper that sim
14850 75 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 20  ulations memory 
14860 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75  allocation failu
14870 72 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 20  re or.** tracks 
14880 6d 65 6d 6f 72 79 20 75 73 61 67 65 2c 20 66 6f  memory usage, fo
14890 72 20 65 78 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e  r example. </dd>
148a0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
148b0 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
148c0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
148d0 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c 2f  NFIG_MEMSTATUS</
148e0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65  dt>.** <dd> ^The
148f0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
14900 45 4d 53 54 41 54 55 53 20 6f 70 74 69 6f 6e 20  EMSTATUS option 
14910 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 61 72 67  takes single arg
14920 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e  ument of type in
14930 74 2c 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 65  t,.** interprete
14940 64 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e 2c 20  d as a boolean, 
14950 77 68 69 63 68 20 65 6e 61 62 6c 65 73 20 6f 72  which enables or
14960 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 63 6f   disables the co
14970 6c 6c 65 63 74 69 6f 6e 20 6f 66 0a 2a 2a 20 6d  llection of.** m
14980 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
14990 20 73 74 61 74 69 73 74 69 63 73 2e 20 5e 28 57   statistics. ^(W
149a0 68 65 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  hen memory alloc
149b0 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73  ation statistics
149c0 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64   are.** disabled
149d0 2c 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  , the following 
149e0 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
149f0 73 20 62 65 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65  s become non-ope
14a00 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c  rational:.**   <
14a10 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73  ul>.**   <li> [s
14a20 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
14a30 65 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20  ed()].**   <li> 
14a40 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
14a50 68 69 67 68 77 61 74 65 72 28 29 5d 0a 2a 2a 20  highwater()].** 
14a60 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f    <li> [sqlite3_
14a70 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36  soft_heap_limit6
14a80 34 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b  4()].**   <li> [
14a90 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73 36 34  sqlite3_status64
14aa0 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e  ()].**   </ul>)^
14ab0 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f  .** ^Memory allo
14ac0 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63  cation statistic
14ad0 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79  s are enabled by
14ae0 20 64 65 66 61 75 6c 74 20 75 6e 6c 65 73 73 20   default unless 
14af0 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d  SQLite is.** com
14b00 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49  piled with [SQLI
14b10 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54  TE_DEFAULT_MEMST
14b20 41 54 55 53 5d 3d 30 20 69 6e 20 77 68 69 63 68  ATUS]=0 in which
14b30 20 63 61 73 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20   case memory.** 
14b40 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69  allocation stati
14b50 73 74 69 63 73 20 61 72 65 20 64 69 73 61 62 6c  stics are disabl
14b60 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a  ed by default..*
14b70 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  * </dd>.**.** [[
14b80 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
14b90 52 41 54 43 48 5d 5d 20 3c 64 74 3e 53 51 4c 49  RATCH]] <dt>SQLI
14ba0 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43  TE_CONFIG_SCRATC
14bb0 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  H</dt>.** <dd> ^
14bc0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
14bd0 47 5f 53 43 52 41 54 43 48 20 6f 70 74 69 6f 6e  G_SCRATCH option
14be0 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61   specifies a sta
14bf0 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  tic memory buffe
14c00 72 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65  r.** that SQLite
14c10 20 63 61 6e 20 75 73 65 20 66 6f 72 20 73 63 72   can use for scr
14c20 61 74 63 68 20 6d 65 6d 6f 72 79 2e 20 20 5e 28  atch memory.  ^(
14c30 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20  There are three 
14c40 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 74 6f 20  arguments.** to 
14c50 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
14c60 52 41 54 43 48 3a 20 20 41 20 70 6f 69 6e 74 65  RATCH:  A pointe
14c70 72 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61  r an 8-byte.** a
14c80 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20 62 75  ligned memory bu
14c90 66 66 65 72 20 66 72 6f 6d 20 77 68 69 63 68 20  ffer from which 
14ca0 74 68 65 20 73 63 72 61 74 63 68 20 61 6c 6c 6f  the scratch allo
14cb0 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65 0a  cations will be.
14cc0 2a 2a 20 64 72 61 77 6e 2c 20 74 68 65 20 73 69  ** drawn, the si
14cd0 7a 65 20 6f 66 20 65 61 63 68 20 73 63 72 61 74  ze of each scrat
14ce0 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 28 73  ch allocation (s
14cf0 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6d  z),.** and the m
14d00 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
14d10 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74   scratch allocat
14d20 69 6f 6e 73 20 28 4e 29 2e 29 5e 0a 2a 2a 20 54  ions (N).)^.** T
14d30 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
14d40 74 20 6d 75 73 74 20 62 65 20 61 20 70 6f 69 6e  t must be a poin
14d50 74 65 72 20 74 6f 20 61 6e 20 38 2d 62 79 74 65  ter to an 8-byte
14d60 20 61 6c 69 67 6e 65 64 20 62 75 66 66 65 72 0a   aligned buffer.
14d70 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73  ** of at least s
14d80 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d  z*N bytes of mem
14d90 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ory..** ^SQLite 
14da0 77 69 6c 6c 20 6e 6f 74 20 75 73 65 20 6d 6f 72  will not use mor
14db0 65 20 74 68 61 6e 20 6f 6e 65 20 73 63 72 61 74  e than one scrat
14dc0 63 68 20 62 75 66 66 65 72 73 20 70 65 72 20 74  ch buffers per t
14dd0 68 72 65 61 64 2e 0a 2a 2a 20 5e 53 51 4c 69 74  hread..** ^SQLit
14de0 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 72 65 71  e will never req
14df0 75 65 73 74 20 61 20 73 63 72 61 74 63 68 20 62  uest a scratch b
14e00 75 66 66 65 72 20 74 68 61 74 20 69 73 20 6d 6f  uffer that is mo
14e10 72 65 20 74 68 61 6e 20 36 0a 2a 2a 20 74 69 6d  re than 6.** tim
14e20 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  es the database 
14e30 70 61 67 65 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49  page size..** ^I
14e40 66 20 53 51 4c 69 74 65 20 6e 65 65 64 73 20 6e  f SQLite needs n
14e50 65 65 64 73 20 61 64 64 69 74 69 6f 6e 61 6c 0a  eeds additional.
14e60 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72  ** scratch memor
14e70 79 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73  y beyond what is
14e80 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 69   provided by thi
14e90 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  s configuration 
14ea0 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a  option, then .**
14eb0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
14ec0 28 29 5d 20 77 69 6c 6c 20 62 65 20 75 73 65 64  ()] will be used
14ed0 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6d   to obtain the m
14ee0 65 6d 6f 72 79 20 6e 65 65 64 65 64 2e 3c 70 3e  emory needed.<p>
14ef0 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 61 70  .** ^When the ap
14f00 70 6c 69 63 61 74 69 6f 6e 20 70 72 6f 76 69 64  plication provid
14f10 65 73 20 61 6e 79 20 61 6d 6f 75 6e 74 20 6f 66  es any amount of
14f20 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20   scratch memory 
14f30 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 49 54 45 5f  using.** SQLITE_
14f40 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 2c 20  CONFIG_SCRATCH, 
14f50 53 51 4c 69 74 65 20 61 76 6f 69 64 73 20 75 6e  SQLite avoids un
14f60 6e 65 63 65 73 73 61 72 79 20 6c 61 72 67 65 0a  necessary large.
14f70 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ** [sqlite3_mall
14f80 6f 63 7c 68 65 61 70 20 61 6c 6c 6f 63 61 74 69  oc|heap allocati
14f90 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 69 73 20 63 61  ons]..** This ca
14fa0 6e 20 68 65 6c 70 20 5b 52 6f 62 73 6f 6e 20 70  n help [Robson p
14fb0 72 6f 6f 66 7c 70 72 65 76 65 6e 74 20 6d 65 6d  roof|prevent mem
14fc0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
14fd0 61 69 6c 75 72 65 73 5d 20 64 75 65 20 74 6f 20  ailures] due to 
14fe0 68 65 61 70 0a 2a 2a 20 66 72 61 67 6d 65 6e 74  heap.** fragment
14ff0 61 74 69 6f 6e 20 69 6e 20 6c 6f 77 2d 6d 65 6d  ation in low-mem
15000 6f 72 79 20 65 6d 62 65 64 64 65 64 20 73 79 73  ory embedded sys
15010 74 65 6d 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a  tems..** </dd>.*
15020 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
15030 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 5d  NFIG_PAGECACHE]]
15040 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
15050 49 47 5f 50 41 47 45 43 41 43 48 45 3c 2f 64 74  IG_PAGECACHE</dt
15060 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53  >.** <dd> ^The S
15070 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
15080 45 43 41 43 48 45 20 6f 70 74 69 6f 6e 20 73 70  ECACHE option sp
15090 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63  ecifies a static
150a0 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 0a 2a   memory buffer.*
150b0 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61  * that SQLite ca
150c0 6e 20 75 73 65 20 66 6f 72 20 74 68 65 20 64 61  n use for the da
150d0 74 61 62 61 73 65 20 70 61 67 65 20 63 61 63 68  tabase page cach
150e0 65 20 77 69 74 68 20 74 68 65 20 64 65 66 61 75  e with the defau
150f0 6c 74 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65  lt page.** cache
15100 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e   implementation.
15110 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69    .** This confi
15120 67 75 72 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  guration should 
15130 6e 6f 74 20 62 65 20 75 73 65 64 20 69 66 20 61  not be used if a
15140 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
15150 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63 61 63  fine page.** cac
15160 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
15170 6e 20 69 73 20 6c 6f 61 64 65 64 20 75 73 69 6e  n is loaded usin
15180 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f  g the [SQLITE_CO
15190 4e 46 49 47 5f 50 43 41 43 48 45 32 5d 0a 2a 2a  NFIG_PCACHE2].**
151a0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
151b0 70 74 69 6f 6e 2e 0a 2a 2a 20 5e 54 68 65 72 65  ption..** ^There
151c0 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d   are three argum
151d0 65 6e 74 73 20 74 6f 20 53 51 4c 49 54 45 5f 43  ents to SQLITE_C
151e0 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 3a  ONFIG_PAGECACHE:
151f0 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a   A pointer to.**
15200 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 0a   8-byte aligned.
15210 2a 2a 20 6d 65 6d 6f 72 79 2c 20 74 68 65 20 73  ** memory, the s
15220 69 7a 65 20 6f 66 20 65 61 63 68 20 70 61 67 65  ize of each page
15230 20 62 75 66 66 65 72 20 28 73 7a 29 2c 20 61 6e   buffer (sz), an
15240 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  d the number of 
15250 70 61 67 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68  pages (N)..** Th
15260 65 20 73 7a 20 61 72 67 75 6d 65 6e 74 20 73 68  e sz argument sh
15270 6f 75 6c 64 20 62 65 20 74 68 65 20 73 69 7a 65  ould be the size
15280 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20   of the largest 
15290 64 61 74 61 62 61 73 65 20 70 61 67 65 0a 2a 2a  database page.**
152a0 20 28 61 20 70 6f 77 65 72 20 6f 66 20 74 77 6f   (a power of two
152b0 20 62 65 74 77 65 65 6e 20 35 31 32 20 61 6e 64   between 512 and
152c0 20 36 35 35 33 36 29 20 70 6c 75 73 20 73 6f 6d   65536) plus som
152d0 65 20 65 78 74 72 61 20 62 79 74 65 73 20 66 6f  e extra bytes fo
152e0 72 20 65 61 63 68 0a 2a 2a 20 70 61 67 65 20 68  r each.** page h
152f0 65 61 64 65 72 2e 20 20 5e 54 68 65 20 6e 75 6d  eader.  ^The num
15300 62 65 72 20 6f 66 20 65 78 74 72 61 20 62 79 74  ber of extra byt
15310 65 73 20 6e 65 65 64 65 64 20 62 79 20 74 68 65  es needed by the
15320 20 70 61 67 65 20 68 65 61 64 65 72 0a 2a 2a 20   page header.** 
15330 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65  can be determine
15340 64 20 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c  d using the [SQL
15350 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
15360 45 5f 48 44 52 53 5a 5d 20 6f 70 74 69 6f 6e 20  E_HDRSZ] option 
15370 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  .** to [sqlite3_
15380 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 20 5e 49  config()]..** ^I
15390 74 20 69 73 20 68 61 72 6d 6c 65 73 73 2c 20 61  t is harmless, a
153a0 70 61 72 74 20 66 72 6f 6d 20 74 68 65 20 77 61  part from the wa
153b0 73 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20  sted memory,.** 
153c0 66 6f 72 20 74 68 65 20 73 7a 20 70 61 72 61 6d  for the sz param
153d0 65 74 65 72 20 74 6f 20 62 65 20 6c 61 72 67 65  eter to be large
153e0 72 20 74 68 61 6e 20 6e 65 63 65 73 73 61 72 79  r than necessary
153f0 2e 20 20 54 68 65 20 66 69 72 73 74 0a 2a 2a 20  .  The first.** 
15400 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20  argument should 
15410 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d  pointer to an 8-
15420 62 79 74 65 20 61 6c 69 67 6e 65 64 20 62 6c 6f  byte aligned blo
15430 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 74 68 61  ck of memory tha
15440 74 0a 2a 2a 20 69 73 20 61 74 20 6c 65 61 73 74  t.** is at least
15450 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d   sz*N bytes of m
15460 65 6d 6f 72 79 2c 20 6f 74 68 65 72 77 69 73 65  emory, otherwise
15470 20 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61   subsequent beha
15480 76 69 6f 72 20 69 73 0a 2a 2a 20 75 6e 64 65 66  vior is.** undef
15490 69 6e 65 64 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  ined..** ^SQLite
154a0 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20 6d 65   will use the me
154b0 6d 6f 72 79 20 70 72 6f 76 69 64 65 64 20 62 79  mory provided by
154c0 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
154d0 65 6e 74 20 74 6f 20 73 61 74 69 73 66 79 20 69  ent to satisfy i
154e0 74 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e 65 65  ts.** memory nee
154f0 64 73 20 66 6f 72 20 74 68 65 20 66 69 72 73 74  ds for the first
15500 20 4e 20 70 61 67 65 73 20 74 68 61 74 20 69 74   N pages that it
15510 20 61 64 64 73 20 74 6f 20 63 61 63 68 65 2e 20   adds to cache. 
15520 20 5e 49 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a   ^If additional.
15530 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20 6d 65  ** page cache me
15540 6d 6f 72 79 20 69 73 20 6e 65 65 64 65 64 20 62  mory is needed b
15550 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72  eyond what is pr
15560 6f 76 69 64 65 64 20 62 79 20 74 68 69 73 20 6f  ovided by this o
15570 70 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20 53  ption, then.** S
15580 51 4c 69 74 65 20 67 6f 65 73 20 74 6f 20 5b 73  QLite goes to [s
15590 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
155a0 20 66 6f 72 20 74 68 65 20 61 64 64 69 74 69 6f   for the additio
155b0 6e 61 6c 20 73 74 6f 72 61 67 65 20 73 70 61 63  nal storage spac
155c0 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  e.</dd>.**.** [[
155d0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45  SQLITE_CONFIG_HE
155e0 41 50 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  AP]] <dt>SQLITE_
155f0 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f 64 74 3e  CONFIG_HEAP</dt>
15600 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51  .** <dd> ^The SQ
15610 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50  LITE_CONFIG_HEAP
15620 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65   option specifie
15630 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72  s a static memor
15640 79 20 62 75 66 66 65 72 20 0a 2a 2a 20 74 68 61  y buffer .** tha
15650 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73  t SQLite will us
15660 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73  e for all of its
15670 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20   dynamic memory 
15680 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73  allocation needs
15690 0a 2a 2a 20 62 65 79 6f 6e 64 20 74 68 6f 73 65  .** beyond those
156a0 20 70 72 6f 76 69 64 65 64 20 66 6f 72 20 62 79   provided for by
156b0 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
156c0 53 43 52 41 54 43 48 5d 20 61 6e 64 0a 2a 2a 20  SCRATCH] and.** 
156d0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  [SQLITE_CONFIG_P
156e0 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 5e 54  AGECACHE]..** ^T
156f0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
15700 5f 48 45 41 50 20 6f 70 74 69 6f 6e 20 69 73 20  _HEAP option is 
15710 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69  only available i
15720 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
15730 69 6c 65 64 0a 2a 2a 20 77 69 74 68 20 65 69 74  iled.** with eit
15740 68 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42  her [SQLITE_ENAB
15750 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 20 5b  LE_MEMSYS3] or [
15760 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45  SQLITE_ENABLE_ME
15770 4d 53 59 53 35 5d 20 61 6e 64 20 72 65 74 75 72  MSYS5] and retur
15780 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52  ns.** [SQLITE_ER
15790 52 4f 52 5d 20 69 66 20 69 6e 76 6f 6b 65 64 20  ROR] if invoked 
157a0 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 20 5e 54  otherwise..** ^T
157b0 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61  here are three a
157c0 72 67 75 6d 65 6e 74 73 20 74 6f 20 53 51 4c 49  rguments to SQLI
157d0 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3a 0a  TE_CONFIG_HEAP:.
157e0 2a 2a 20 41 6e 20 38 2d 62 79 74 65 20 61 6c 69  ** An 8-byte ali
157f0 67 6e 65 64 20 70 6f 69 6e 74 65 72 20 74 6f 20  gned pointer to 
15800 74 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74  the memory,.** t
15810 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
15820 65 73 20 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79  es in the memory
15830 20 62 75 66 66 65 72 2c 20 61 6e 64 20 74 68 65   buffer, and the
15840 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74   minimum allocat
15850 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66  ion size..** ^If
15860 20 74 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74   the first point
15870 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70  er (the memory p
15880 6f 69 6e 74 65 72 29 20 69 73 20 4e 55 4c 4c 2c  ointer) is NULL,
15890 20 74 68 65 6e 20 53 51 4c 69 74 65 20 72 65 76   then SQLite rev
158a0 65 72 74 73 0a 2a 2a 20 74 6f 20 75 73 69 6e 67  erts.** to using
158b0 20 69 74 73 20 64 65 66 61 75 6c 74 20 6d 65 6d   its default mem
158c0 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 28 74  ory allocator (t
158d0 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63  he system malloc
158e0 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  () implementatio
158f0 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20 61  n),.** undoing a
15900 6e 79 20 70 72 69 6f 72 20 69 6e 76 6f 63 61 74  ny prior invocat
15910 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f 43  ion of [SQLITE_C
15920 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20  ONFIG_MALLOC].  
15930 5e 49 66 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72  ^If the.** memor
15940 79 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74  y pointer is not
15950 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 61   NULL then the a
15960 6c 74 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72  lternative memor
15970 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 20 69  y.** allocator i
15980 73 20 65 6e 67 61 67 65 64 20 74 6f 20 68 61 6e  s engaged to han
15990 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c 69 74  dle all of SQLit
159a0 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  es memory alloca
159b0 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20 54  tion needs..** T
159c0 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72  he first pointer
159d0 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69   (the memory poi
159e0 6e 74 65 72 29 20 6d 75 73 74 20 62 65 20 61 6c  nter) must be al
159f0 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79  igned to an 8-by
15a00 74 65 0a 2a 2a 20 62 6f 75 6e 64 61 72 79 20 6f  te.** boundary o
15a10 72 20 73 75 62 73 65 71 75 65 6e 74 20 62 65 68  r subsequent beh
15a20 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 20  avior of SQLite 
15a30 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e 65  will be undefine
15a40 64 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e 69 6d 75  d..** The minimu
15a50 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a  m allocation siz
15a60 65 20 69 73 20 63 61 70 70 65 64 20 61 74 20 32  e is capped at 2
15a70 2a 2a 31 32 2e 20 52 65 61 73 6f 6e 61 62 6c 65  **12. Reasonable
15a80 20 76 61 6c 75 65 73 0a 2a 2a 20 66 6f 72 20 74   values.** for t
15a90 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63  he minimum alloc
15aa0 61 74 69 6f 6e 20 73 69 7a 65 20 61 72 65 20 32  ation size are 2
15ab0 2a 2a 35 20 74 68 72 6f 75 67 68 20 32 2a 2a 38  **5 through 2**8
15ac0 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
15ad0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54  QLITE_CONFIG_MUT
15ae0 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  EX]] <dt>SQLITE_
15af0 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74  CONFIG_MUTEX</dt
15b00 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20  >.** <dd> ^(The 
15b10 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
15b20 54 45 58 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  TEX option takes
15b30 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
15b40 6e 74 20 77 68 69 63 68 20 69 73 20 61 0a 2a 2a  nt which is a.**
15b50 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
15b60 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b  nstance of the [
15b70 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
15b80 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
15b90 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e  ..** The argumen
15ba0 74 20 73 70 65 63 69 66 69 65 73 20 61 6c 74 65  t specifies alte
15bb0 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65  rnative low-leve
15bc0 6c 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73  l mutex routines
15bd0 20 74 6f 20 62 65 20 75 73 65 64 0a 2a 2a 20 69   to be used.** i
15be0 6e 20 70 6c 61 63 65 20 74 68 65 20 6d 75 74 65  n place the mute
15bf0 78 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74  x routines built
15c00 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20   into SQLite.)^ 
15c10 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61   ^SQLite makes a
15c20 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20   copy of.** the 
15c30 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b  content of the [
15c40 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
15c50 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
15c60 20 62 65 66 6f 72 65 20 74 68 65 20 63 61 6c 6c   before the call
15c70 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
15c80 63 6f 6e 66 69 67 28 29 5d 20 72 65 74 75 72 6e  config()] return
15c90 73 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73  s. ^If SQLite is
15ca0 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
15cb0 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  * the [SQLITE_TH
15cc0 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54  READSAFE | SQLIT
15cd0 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
15ce0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
15cf0 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20  ion then.** the 
15d00 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20  entire mutexing 
15d10 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69  subsystem is omi
15d20 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75  tted from the bu
15d30 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61  ild and hence ca
15d40 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  lls to.** [sqlit
15d50 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74  e3_config()] wit
15d60 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  h the SQLITE_CON
15d70 46 49 47 5f 4d 55 54 45 58 20 63 6f 6e 66 69 67  FIG_MUTEX config
15d80 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77  uration option w
15d90 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53  ill.** return [S
15da0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64  QLITE_ERROR].</d
15db0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
15dc0 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45  E_CONFIG_GETMUTE
15dd0 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  X]] <dt>SQLITE_C
15de0 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 3c 2f  ONFIG_GETMUTEX</
15df0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
15e00 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
15e10 47 45 54 4d 55 54 45 58 20 6f 70 74 69 6f 6e 20  GETMUTEX option 
15e20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
15e30 72 67 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a  rgument which.**
15e40 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
15e50 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
15e60 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  the [sqlite3_mut
15e70 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  ex_methods] stru
15e80 63 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b  cture.  The.** [
15e90 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
15ea0 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74  thods].** struct
15eb0 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69  ure is filled wi
15ec0 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79  th the currently
15ed0 20 64 65 66 69 6e 65 64 20 6d 75 74 65 78 20 72   defined mutex r
15ee0 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68  outines.)^.** Th
15ef0 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65  is option can be
15f00 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61   used to overloa
15f10 64 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 75  d the default mu
15f20 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  tex allocation.*
15f30 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20  * routines with 
15f40 61 20 77 72 61 70 70 65 72 20 75 73 65 64 20 74  a wrapper used t
15f50 6f 20 74 72 61 63 6b 20 6d 75 74 65 78 20 75 73  o track mutex us
15f60 61 67 65 20 66 6f 72 20 70 65 72 66 6f 72 6d 61  age for performa
15f70 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e 67  nce.** profiling
15f80 20 6f 72 20 74 65 73 74 69 6e 67 2c 20 66 6f 72   or testing, for
15f90 20 65 78 61 6d 70 6c 65 2e 20 20 20 5e 49 66 20   example.   ^If 
15fa0 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
15fb0 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
15fc0 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
15fd0 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41  E | SQLITE_THREA
15fe0 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65  DSAFE=0] compile
15ff0 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65  -time option the
16000 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20  n.** the entire 
16010 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79 73 74  mutexing subsyst
16020 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  em is omitted fr
16030 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64  om the build and
16040 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a   hence calls to.
16050 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
16060 69 67 28 29 5d 20 77 69 74 68 20 74 68 65 20 53  ig()] with the S
16070 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
16080 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74  MUTEX configurat
16090 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a  ion option will.
160a0 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ** return [SQLIT
160b0 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a  E_ERROR].</dd>.*
160c0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
160d0 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 5d  NFIG_LOOKASIDE]]
160e0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
160f0 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74  IG_LOOKASIDE</dt
16100 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20  >.** <dd> ^(The 
16110 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
16120 4f 4b 41 53 49 44 45 20 6f 70 74 69 6f 6e 20 74  OKASIDE option t
16130 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e  akes two argumen
16140 74 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e  ts that determin
16150 65 0a 2a 2a 20 74 68 65 20 64 65 66 61 75 6c 74  e.** the default
16160 20 73 69 7a 65 20 6f 66 20 6c 6f 6f 6b 61 73 69   size of lookasi
16170 64 65 20 6d 65 6d 6f 72 79 20 6f 6e 20 65 61 63  de memory on eac
16180 68 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  h [database conn
16190 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 68 65 20  ection]..** The 
161a0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69  first argument i
161b0 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66  s the.** size of
161c0 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20   each lookaside 
161d0 62 75 66 66 65 72 20 73 6c 6f 74 20 61 6e 64 20  buffer slot and 
161e0 74 68 65 20 73 65 63 6f 6e 64 20 69 73 20 74 68  the second is th
161f0 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73  e number of.** s
16200 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65 64 20 74  lots allocated t
16210 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20  o each database 
16220 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20 20 5e  connection.)^  ^
16230 28 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c  (SQLITE_CONFIG_L
16240 4f 4f 4b 41 53 49 44 45 0a 2a 2a 20 73 65 74 73  OOKASIDE.** sets
16250 20 74 68 65 20 3c 69 3e 64 65 66 61 75 6c 74 3c   the <i>default<
16260 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64 65 20 73 69  /i> lookaside si
16270 7a 65 2e 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  ze. The [SQLITE_
16280 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
16290 44 45 5d 0a 2a 2a 20 6f 70 74 69 6f 6e 20 74 6f  DE].** option to
162a0 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
162b0 66 69 67 28 29 5d 20 63 61 6e 20 62 65 20 75 73  fig()] can be us
162c0 65 64 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65  ed to change the
162d0 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 63 6f   lookaside.** co
162e0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 6e 20 69  nfiguration on i
162f0 6e 64 69 76 69 64 75 61 6c 20 63 6f 6e 6e 65 63  ndividual connec
16300 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e 0a 2a  tions.)^ </dd>.*
16310 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
16320 4e 46 49 47 5f 50 43 41 43 48 45 32 5d 5d 20 3c  NFIG_PCACHE2]] <
16330 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
16340 5f 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a  _PCACHE2</dt>.**
16350 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49   <dd> ^(The SQLI
16360 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
16370 32 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  2 option takes a
16380 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
16390 20 77 68 69 63 68 20 69 73 20 0a 2a 2a 20 61 20   which is .** a 
163a0 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 5b 73  pointer to an [s
163b0 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65  qlite3_pcache_me
163c0 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20  thods2] object. 
163d0 20 54 68 69 73 20 6f 62 6a 65 63 74 20 73 70 65   This object spe
163e0 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 69 6e  cifies.** the in
163f0 74 65 72 66 61 63 65 20 74 6f 20 61 20 63 75 73  terface to a cus
16400 74 6f 6d 20 70 61 67 65 20 63 61 63 68 65 20 69  tom page cache i
16410 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 29 5e  mplementation.)^
16420 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65  .** ^SQLite make
16430 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
16440 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f  [sqlite3_pcache_
16450 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74  methods2] object
16460 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
16470 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
16480 50 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51  PCACHE2]] <dt>SQ
16490 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
164a0 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c  CACHE2</dt>.** <
164b0 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45  dd> ^(The SQLITE
164c0 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48  _CONFIG_GETPCACH
164d0 45 32 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  E2 option takes 
164e0 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
164f0 74 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20  t which.** is a 
16500 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 5b 73  pointer to an [s
16510 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65  qlite3_pcache_me
16520 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20  thods2] object. 
16530 20 53 51 4c 69 74 65 20 63 6f 70 69 65 73 20 6f   SQLite copies o
16540 66 0a 2a 2a 20 74 68 65 20 63 75 72 72 65 6e 74  f.** the current
16550 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c   page cache impl
16560 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74 6f 20  ementation into 
16570 74 68 61 74 20 6f 62 6a 65 63 74 2e 29 5e 20 3c  that object.)^ <
16580 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
16590 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 5d 5d  ITE_CONFIG_LOG]]
165a0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
165b0 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c  IG_LOG</dt>.** <
165c0 64 64 3e 20 54 68 65 20 53 51 4c 49 54 45 5f 43  dd> The SQLITE_C
165d0 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e  ONFIG_LOG option
165e0 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f 6e 66   is used to conf
165f0 69 67 75 72 65 20 74 68 65 20 53 51 4c 69 74 65  igure the SQLite
16600 0a 2a 2a 20 67 6c 6f 62 61 6c 20 5b 65 72 72 6f  .** global [erro
16610 72 20 6c 6f 67 5d 2e 0a 2a 2a 20 28 5e 54 68 65  r log]..** (^The
16620 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c   SQLITE_CONFIG_L
16630 4f 47 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  OG option takes 
16640 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 3a 20 61  two arguments: a
16650 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a 2a 2a   pointer to a.**
16660 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61   function with a
16670 20 63 61 6c 6c 20 73 69 67 6e 61 74 75 72 65 20   call signature 
16680 6f 66 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  of void(*)(void*
16690 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a  ,int,const char*
166a0 29 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 70 6f 69  ), .** and a poi
166b0 6e 74 65 72 20 74 6f 20 76 6f 69 64 2e 20 5e 49  nter to void. ^I
166c0 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70  f the function p
166d0 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55  ointer is not NU
166e0 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 69 6e 76  LL, it is.** inv
166f0 6f 6b 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  oked by [sqlite3
16700 5f 6c 6f 67 28 29 5d 20 74 6f 20 70 72 6f 63 65  _log()] to proce
16710 73 73 20 65 61 63 68 20 6c 6f 67 67 69 6e 67 20  ss each logging 
16720 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a  event.  ^If the.
16730 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e  ** function poin
16740 74 65 72 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65  ter is NULL, the
16750 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d   [sqlite3_log()]
16760 20 69 6e 74 65 72 66 61 63 65 20 62 65 63 6f 6d   interface becom
16770 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e  es a no-op..** ^
16780 54 68 65 20 76 6f 69 64 20 70 6f 69 6e 74 65 72  The void pointer
16790 20 74 68 61 74 20 69 73 20 74 68 65 20 73 65 63   that is the sec
167a0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ond argument to 
167b0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
167c0 47 20 69 73 0a 2a 2a 20 70 61 73 73 65 64 20 74  G is.** passed t
167d0 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 66 69  hrough as the fi
167e0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
167f0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
16800 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a  -defined logger.
16810 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 6e  ** function when
16820 65 76 65 72 20 74 68 61 74 20 66 75 6e 63 74 69  ever that functi
16830 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20  on is invoked.  
16840 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61  ^The second para
16850 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20  meter to.** the 
16860 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 20  logger function 
16870 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  is a copy of the
16880 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
16890 20 74 6f 20 74 68 65 20 63 6f 72 72 65 73 70 6f   to the correspo
168a0 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  nding.** [sqlite
168b0 33 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c 20 61 6e  3_log()] call an
168c0 64 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f  d is intended to
168d0 20 62 65 20 61 20 5b 72 65 73 75 6c 74 20 63 6f   be a [result co
168e0 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 78  de] or an.** [ex
168f0 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
16900 64 65 5d 2e 20 20 5e 54 68 65 20 74 68 69 72 64  de].  ^The third
16910 20 70 61 72 61 6d 65 74 65 72 20 70 61 73 73 65   parameter passe
16920 64 20 74 6f 20 74 68 65 20 6c 6f 67 67 65 72 20  d to the logger 
16930 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73 61 67  is.** log messag
16940 65 20 61 66 74 65 72 20 66 6f 72 6d 61 74 74 69  e after formatti
16950 6e 67 20 76 69 61 20 5b 73 71 6c 69 74 65 33 5f  ng via [sqlite3_
16960 73 6e 70 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a 20  snprintf()]..** 
16970 54 68 65 20 53 51 4c 69 74 65 20 6c 6f 67 67 69  The SQLite loggi
16980 6e 67 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  ng interface is 
16990 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 3b 20 74  not reentrant; t
169a0 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69  he logger functi
169b0 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20 62  on.** supplied b
169c0 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  y the applicatio
169d0 6e 20 6d 75 73 74 20 6e 6f 74 20 69 6e 76 6f 6b  n must not invok
169e0 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74  e any SQLite int
169f0 65 72 66 61 63 65 2e 0a 2a 2a 20 49 6e 20 61 20  erface..** In a 
16a00 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 20 61  multi-threaded a
16a10 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65 20  pplication, the 
16a20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
16a30 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75  ned logger.** fu
16a40 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 74  nction must be t
16a50 68 72 65 61 64 73 61 66 65 2e 20 3c 2f 64 64 3e  hreadsafe. </dd>
16a60 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
16a70 43 4f 4e 46 49 47 5f 55 52 49 5d 5d 20 3c 64 74  CONFIG_URI]] <dt
16a80 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55  >SQLITE_CONFIG_U
16a90 52 49 0a 2a 2a 20 3c 64 64 3e 5e 28 54 68 65 20  RI.** <dd>^(The 
16aa0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52  SQLITE_CONFIG_UR
16ab0 49 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  I option takes a
16ac0 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
16ad0 20 6f 66 20 74 79 70 65 20 69 6e 74 2e 0a 2a 2a   of type int..**
16ae0 20 49 66 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68   If non-zero, th
16af0 65 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20  en URI handling 
16b00 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62  is globally enab
16b10 6c 65 64 2e 20 49 66 20 74 68 65 20 70 61 72 61  led. If the para
16b20 6d 65 74 65 72 20 69 73 20 7a 65 72 6f 2c 0a 2a  meter is zero,.*
16b30 2a 20 74 68 65 6e 20 55 52 49 20 68 61 6e 64 6c  * then URI handl
16b40 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20  ing is globally 
16b50 64 69 73 61 62 6c 65 64 2e 29 5e 20 5e 49 66 20  disabled.)^ ^If 
16b60 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20  URI handling is 
16b70 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 65 6e 61 62  globally.** enab
16b80 6c 65 64 2c 20 61 6c 6c 20 66 69 6c 65 6e 61 6d  led, all filenam
16b90 65 73 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71  es passed to [sq
16ba0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b  lite3_open()], [
16bb0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
16bc0 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
16bd0 6f 70 65 6e 31 36 28 29 5d 20 6f 72 0a 2a 2a 20  open16()] or.** 
16be0 73 70 65 63 69 66 69 65 64 20 61 73 20 70 61 72  specified as par
16bf0 74 20 6f 66 20 5b 41 54 54 41 43 48 5d 20 63 6f  t of [ATTACH] co
16c00 6d 6d 61 6e 64 73 20 61 72 65 20 69 6e 74 65 72  mmands are inter
16c10 70 72 65 74 65 64 20 61 73 20 55 52 49 73 2c 20  preted as URIs, 
16c20 72 65 67 61 72 64 6c 65 73 73 0a 2a 2a 20 6f 66  regardless.** of
16c30 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
16c40 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  the [SQLITE_OPEN
16c50 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 20 73 65  _URI] flag is se
16c60 74 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62  t when the datab
16c70 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
16c80 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 5e 49 66  n is opened. ^If
16c90 20 69 74 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20   it is globally 
16ca0 64 69 73 61 62 6c 65 64 2c 20 66 69 6c 65 6e 61  disabled, filena
16cb0 6d 65 73 20 61 72 65 0a 2a 2a 20 6f 6e 6c 79 20  mes are.** only 
16cc0 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55  interpreted as U
16cd0 52 49 73 20 69 66 20 74 68 65 20 53 51 4c 49 54  RIs if the SQLIT
16ce0 45 5f 4f 50 45 4e 5f 55 52 49 20 66 6c 61 67 20  E_OPEN_URI flag 
16cf0 69 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 0a  is set when the.
16d00 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
16d10 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64  ection is opened
16d20 2e 20 5e 28 42 79 20 64 65 66 61 75 6c 74 2c 20  . ^(By default, 
16d30 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20  URI handling is 
16d40 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 64 69 73 61  globally.** disa
16d50 62 6c 65 64 2e 20 54 68 65 20 64 65 66 61 75 6c  bled. The defaul
16d60 74 20 76 61 6c 75 65 20 6d 61 79 20 62 65 20 63  t value may be c
16d70 68 61 6e 67 65 64 20 62 79 20 63 6f 6d 70 69 6c  hanged by compil
16d80 69 6e 67 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  ing with the.** 
16d90 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d  [SQLITE_USE_URI]
16da0 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e   symbol defined.
16db0 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
16dc0 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e  E_CONFIG_COVERIN
16dd0 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 5d 20 3c  G_INDEX_SCAN]] <
16de0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
16df0 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f  _COVERING_INDEX_
16e00 53 43 41 4e 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65  SCAN.** <dd>^The
16e10 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43   SQLITE_CONFIG_C
16e20 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43  OVERING_INDEX_SC
16e30 41 4e 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  AN option takes 
16e40 61 20 73 69 6e 67 6c 65 20 69 6e 74 65 67 65 72  a single integer
16e50 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 77 68 69  .** argument whi
16e60 63 68 20 69 73 20 69 6e 74 65 72 70 72 65 74 65  ch is interprete
16e70 64 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e 20 69  d as a boolean i
16e80 6e 20 6f 72 64 65 72 20 74 6f 20 65 6e 61 62 6c  n order to enabl
16e90 65 20 6f 72 20 64 69 73 61 62 6c 65 0a 2a 2a 20  e or disable.** 
16ea0 74 68 65 20 75 73 65 20 6f 66 20 63 6f 76 65 72  the use of cover
16eb0 69 6e 67 20 69 6e 64 69 63 65 73 20 66 6f 72 20  ing indices for 
16ec0 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e 73  full table scans
16ed0 20 69 6e 20 74 68 65 20 71 75 65 72 79 20 6f 70   in the query op
16ee0 74 69 6d 69 7a 65 72 2e 0a 2a 2a 20 5e 54 68 65  timizer..** ^The
16ef0 20 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67   default setting
16f00 20 69 73 20 64 65 74 65 72 6d 69 6e 65 64 0a 2a   is determined.*
16f10 2a 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45  * by the [SQLITE
16f20 5f 41 4c 4c 4f 57 5f 43 4f 56 45 52 49 4e 47 5f  _ALLOW_COVERING_
16f30 49 4e 44 45 58 5f 53 43 41 4e 5d 20 63 6f 6d 70  INDEX_SCAN] comp
16f40 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c  ile-time option,
16f50 20 6f 72 20 69 73 20 22 6f 6e 22 0a 2a 2a 20 69   or is "on".** i
16f60 66 20 74 68 61 74 20 63 6f 6d 70 69 6c 65 2d 74  f that compile-t
16f70 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6d  ime option is om
16f80 69 74 74 65 64 2e 0a 2a 2a 20 54 68 65 20 61 62  itted..** The ab
16f90 69 6c 69 74 79 20 74 6f 20 64 69 73 61 62 6c 65  ility to disable
16fa0 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f 76 65   the use of cove
16fb0 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66 6f 72  ring indices for
16fc0 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e   full table scan
16fd0 73 0a 2a 2a 20 69 73 20 62 65 63 61 75 73 65 20  s.** is because 
16fe0 73 6f 6d 65 20 69 6e 63 6f 72 72 65 63 74 6c 79  some incorrectly
16ff0 20 63 6f 64 65 64 20 6c 65 67 61 63 79 20 61 70   coded legacy ap
17000 70 6c 69 63 61 74 69 6f 6e 73 20 6d 69 67 68 74  plications might
17010 20 6d 61 6c 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20   malfunction.** 
17020 77 68 65 6e 20 74 68 65 20 6f 70 74 69 6d 69 7a  when the optimiz
17030 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64  ation is enabled
17040 2e 20 20 50 72 6f 76 69 64 69 6e 67 20 74 68 65  .  Providing the
17050 20 61 62 69 6c 69 74 79 20 74 6f 0a 2a 2a 20 64   ability to.** d
17060 69 73 61 62 6c 65 20 74 68 65 20 6f 70 74 69 6d  isable the optim
17070 69 7a 61 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 74  ization allows t
17080 68 65 20 6f 6c 64 65 72 2c 20 62 75 67 67 79 20  he older, buggy 
17090 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65  application code
170a0 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69 74 68   to work.** with
170b0 6f 75 74 20 63 68 61 6e 67 65 20 65 76 65 6e 20  out change even 
170c0 77 69 74 68 20 6e 65 77 65 72 20 76 65 72 73 69  with newer versi
170d0 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ons of SQLite..*
170e0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
170f0 4e 46 49 47 5f 50 43 41 43 48 45 5d 5d 20 5b 5b  NFIG_PCACHE]] [[
17100 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
17110 54 50 43 41 43 48 45 5d 5d 0a 2a 2a 20 3c 64 74  TPCACHE]].** <dt
17120 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  >SQLITE_CONFIG_P
17130 43 41 43 48 45 20 61 6e 64 20 53 51 4c 49 54 45  CACHE and SQLITE
17140 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48  _CONFIG_GETPCACH
17150 45 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 73 65 20  E.** <dd> These 
17160 6f 70 74 69 6f 6e 73 20 61 72 65 20 6f 62 73 6f  options are obso
17170 6c 65 74 65 20 61 6e 64 20 73 68 6f 75 6c 64 20  lete and should 
17180 6e 6f 74 20 62 65 20 75 73 65 64 20 62 79 20 6e  not be used by n
17190 65 77 20 63 6f 64 65 2e 0a 2a 2a 20 54 68 65 79  ew code..** They
171a0 20 61 72 65 20 72 65 74 61 69 6e 65 64 20 66 6f   are retained fo
171b0 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70  r backwards comp
171c0 61 74 69 62 69 6c 69 74 79 20 62 75 74 20 61 72  atibility but ar
171d0 65 20 6e 6f 77 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a  e now no-ops..**
171e0 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
171f0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c  QLITE_CONFIG_SQL
17200 4c 4f 47 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c  LOG]].** <dt>SQL
17210 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f  ITE_CONFIG_SQLLO
17220 47 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70  G.** <dd>This op
17230 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61  tion is only ava
17240 69 6c 61 62 6c 65 20 69 66 20 73 71 6c 69 74 65  ilable if sqlite
17250 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
17260 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  h the.** [SQLITE
17270 5f 45 4e 41 42 4c 45 5f 53 51 4c 4c 4f 47 5d 20  _ENABLE_SQLLOG] 
17280 70 72 65 2d 70 72 6f 63 65 73 73 6f 72 20 6d 61  pre-processor ma
17290 63 72 6f 20 64 65 66 69 6e 65 64 2e 20 54 68 65  cro defined. The
172a0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
172b0 73 68 6f 75 6c 64 0a 2a 2a 20 62 65 20 61 20 70  should.** be a p
172c0 6f 69 6e 74 65 72 20 74 6f 20 61 20 66 75 6e 63  ointer to a func
172d0 74 69 6f 6e 20 6f 66 20 74 79 70 65 20 76 6f 69  tion of type voi
172e0 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74  d(*)(void*,sqlit
172f0 65 33 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  e3*,const char*,
17300 20 69 6e 74 29 2e 0a 2a 2a 20 54 68 65 20 73 65   int)..** The se
17310 63 6f 6e 64 20 73 68 6f 75 6c 64 20 62 65 20 6f  cond should be o
17320 66 20 74 79 70 65 20 28 76 6f 69 64 2a 29 2e 20  f type (void*). 
17330 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  The callback is 
17340 69 6e 76 6f 6b 65 64 20 62 79 20 74 68 65 20 6c  invoked by the l
17350 69 62 72 61 72 79 0a 2a 2a 20 69 6e 20 74 68 72  ibrary.** in thr
17360 65 65 20 73 65 70 61 72 61 74 65 20 63 69 72 63  ee separate circ
17370 75 6d 73 74 61 6e 63 65 73 2c 20 69 64 65 6e 74  umstances, ident
17380 69 66 69 65 64 20 62 79 20 74 68 65 20 76 61 6c  ified by the val
17390 75 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  ue passed as the
173a0 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61 72 61 6d  .** fourth param
173b0 65 74 65 72 2e 20 49 66 20 74 68 65 20 66 6f 75  eter. If the fou
173c0 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  rth parameter is
173d0 20 30 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74   0, then the dat
173e0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
173f0 0a 2a 2a 20 70 61 73 73 65 64 20 61 73 20 74 68  .** passed as th
17400 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
17410 74 20 68 61 73 20 6a 75 73 74 20 62 65 65 6e 20  t has just been 
17420 6f 70 65 6e 65 64 2e 20 54 68 65 20 74 68 69 72  opened. The thir
17430 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 70 6f  d argument.** po
17440 69 6e 74 73 20 74 6f 20 61 20 62 75 66 66 65 72  ints to a buffer
17450 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
17460 6e 61 6d 65 20 6f 66 20 74 68 65 20 6d 61 69 6e  name of the main
17470 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 20   database file. 
17480 49 66 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68  If the.** fourth
17490 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 31 2c   parameter is 1,
174a0 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20 73 74   then the SQL st
174b0 61 74 65 6d 65 6e 74 20 74 68 61 74 20 74 68 65  atement that the
174c0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
174d0 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20 68 61  .** points to ha
174e0 73 20 6a 75 73 74 20 62 65 65 6e 20 65 78 65 63  s just been exec
174f0 75 74 65 64 2e 20 4f 72 2c 20 69 66 20 74 68 65  uted. Or, if the
17500 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
17510 72 20 69 73 20 32 2c 20 74 68 65 6e 0a 2a 2a 20  r is 2, then.** 
17520 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62  the connection b
17530 65 69 6e 67 20 70 61 73 73 65 64 20 61 73 20 74  eing passed as t
17540 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
17550 74 65 72 20 69 73 20 62 65 69 6e 67 20 63 6c 6f  ter is being clo
17560 73 65 64 2e 20 54 68 65 0a 2a 2a 20 74 68 69 72  sed. The.** thir
17570 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70  d parameter is p
17580 61 73 73 65 64 20 4e 55 4c 4c 20 49 6e 20 74 68  assed NULL In th
17590 69 73 20 63 61 73 65 2e 20 20 41 6e 20 65 78 61  is case.  An exa
175a0 6d 70 6c 65 20 6f 66 20 75 73 69 6e 67 20 74 68  mple of using th
175b0 69 73 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74  is.** configurat
175c0 69 6f 6e 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62  ion option can b
175d0 65 20 73 65 65 6e 20 69 6e 20 74 68 65 20 22 74  e seen in the "t
175e0 65 73 74 5f 73 71 6c 6c 6f 67 2e 63 22 20 73 6f  est_sqllog.c" so
175f0 75 72 63 65 20 66 69 6c 65 20 69 6e 0a 2a 2a 20  urce file in.** 
17600 74 68 65 20 63 61 6e 6f 6e 69 63 61 6c 20 53 51  the canonical SQ
17610 4c 69 74 65 20 73 6f 75 72 63 65 20 74 72 65 65  Lite source tree
17620 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
17630 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41  QLITE_CONFIG_MMA
17640 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e  P_SIZE]].** <dt>
17650 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d  SQLITE_CONFIG_MM
17660 41 50 5f 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e  AP_SIZE.** <dd>^
17670 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d  SQLITE_CONFIG_MM
17680 41 50 5f 53 49 5a 45 20 74 61 6b 65 73 20 74 77  AP_SIZE takes tw
17690 6f 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72  o 64-bit integer
176a0 20 28 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29   (sqlite3_int64)
176b0 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20   values.** that 
176c0 61 72 65 20 74 68 65 20 64 65 66 61 75 6c 74 20  are the default 
176d0 6d 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69 74 20  mmap size limit 
176e0 28 74 68 65 20 64 65 66 61 75 6c 74 20 73 65 74  (the default set
176f0 74 69 6e 67 20 66 6f 72 0a 2a 2a 20 5b 50 52 41  ting for.** [PRA
17700 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 29 20  GMA mmap_size]) 
17710 61 6e 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20  and the maximum 
17720 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a  allowed mmap siz
17730 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 54 68 65  e limit..** ^The
17740 20 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67   default setting
17750 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64   can be overridd
17760 65 6e 20 62 79 20 65 61 63 68 20 64 61 74 61 62  en by each datab
17770 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 75  ase connection u
17780 73 69 6e 67 0a 2a 2a 20 65 69 74 68 65 72 20 74  sing.** either t
17790 68 65 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f  he [PRAGMA mmap_
177a0 73 69 7a 65 5d 20 63 6f 6d 6d 61 6e 64 2c 20 6f  size] command, o
177b0 72 20 62 79 20 75 73 69 6e 67 20 74 68 65 0a 2a  r by using the.*
177c0 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  * [SQLITE_FCNTL_
177d0 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c 65 20  MMAP_SIZE] file 
177e0 63 6f 6e 74 72 6f 6c 2e 20 20 5e 28 54 68 65 20  control.  ^(The 
177f0 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20  maximum allowed 
17800 6d 6d 61 70 20 73 69 7a 65 0a 2a 2a 20 77 69 6c  mmap size.** wil
17810 6c 20 62 65 20 73 69 6c 65 6e 74 6c 79 20 74 72  l be silently tr
17820 75 6e 63 61 74 65 64 20 69 66 20 6e 65 63 65 73  uncated if neces
17830 73 61 72 79 20 73 6f 20 74 68 61 74 20 69 74 20  sary so that it 
17840 64 6f 65 73 20 6e 6f 74 20 65 78 63 65 65 64 20  does not exceed 
17850 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74  the.** compile-t
17860 69 6d 65 20 6d 61 78 69 6d 75 6d 20 6d 6d 61 70  ime maximum mmap
17870 20 73 69 7a 65 20 73 65 74 20 62 79 20 74 68 65   size set by the
17880 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f  .** [SQLITE_MAX_
17890 4d 4d 41 50 5f 53 49 5a 45 5d 20 63 6f 6d 70 69  MMAP_SIZE] compi
178a0 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 29  le-time option.)
178b0 5e 0a 2a 2a 20 5e 49 66 20 65 69 74 68 65 72 20  ^.** ^If either 
178c0 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 69 73  argument to this
178d0 20 6f 70 74 69 6f 6e 20 69 73 20 6e 65 67 61 74   option is negat
178e0 69 76 65 2c 20 74 68 65 6e 20 74 68 61 74 20 61  ive, then that a
178f0 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 63 68  rgument is.** ch
17900 61 6e 67 65 64 20 74 6f 20 69 74 73 20 63 6f 6d  anged to its com
17910 70 69 6c 65 2d 74 69 6d 65 20 64 65 66 61 75 6c  pile-time defaul
17920 74 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  t..**.** [[SQLIT
17930 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48  E_CONFIG_WIN32_H
17940 45 41 50 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74  EAPSIZE]].** <dt
17950 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57  >SQLITE_CONFIG_W
17960 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 0a 2a 2a  IN32_HEAPSIZE.**
17970 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45   <dd>^The SQLITE
17980 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45  _CONFIG_WIN32_HE
17990 41 50 53 49 5a 45 20 6f 70 74 69 6f 6e 20 69 73  APSIZE option is
179a0 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20   only available 
179b0 69 66 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20  if SQLite is.** 
179c0 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 57 69 6e  compiled for Win
179d0 64 6f 77 73 20 77 69 74 68 20 74 68 65 20 5b 53  dows with the [S
179e0 51 4c 49 54 45 5f 57 49 4e 33 32 5f 4d 41 4c 4c  QLITE_WIN32_MALL
179f0 4f 43 5d 20 70 72 65 2d 70 72 6f 63 65 73 73 6f  OC] pre-processo
17a00 72 20 6d 61 63 72 6f 0a 2a 2a 20 64 65 66 69 6e  r macro.** defin
17a10 65 64 2e 20 5e 53 51 4c 49 54 45 5f 43 4f 4e 46  ed. ^SQLITE_CONF
17a20 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a  IG_WIN32_HEAPSIZ
17a30 45 20 74 61 6b 65 73 20 61 20 33 32 2d 62 69 74  E takes a 32-bit
17a40 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65   unsigned intege
17a50 72 20 76 61 6c 75 65 0a 2a 2a 20 74 68 61 74 20  r value.** that 
17a60 73 70 65 63 69 66 69 65 73 20 74 68 65 20 6d 61  specifies the ma
17a70 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 74 68  ximum size of th
17a80 65 20 63 72 65 61 74 65 64 20 68 65 61 70 2e 0a  e created heap..
17a90 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
17aa0 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52  ONFIG_PCACHE_HDR
17ab0 53 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  SZ]].** <dt>SQLI
17ac0 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
17ad0 5f 48 44 52 53 5a 0a 2a 2a 20 3c 64 64 3e 5e 54  _HDRSZ.** <dd>^T
17ae0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
17af0 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 20 6f 70  _PCACHE_HDRSZ op
17b00 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
17b10 67 6c 65 20 70 61 72 61 6d 65 74 65 72 20 77 68  gle parameter wh
17b20 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e  ich.** is a poin
17b30 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ter to an intege
17b40 72 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e 74  r and writes int
17b50 6f 20 74 68 61 74 20 69 6e 74 65 67 65 72 20 74  o that integer t
17b60 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 78 74  he number of ext
17b70 72 61 0a 2a 2a 20 62 79 74 65 73 20 70 65 72 20  ra.** bytes per 
17b80 70 61 67 65 20 72 65 71 75 69 72 65 64 20 66 6f  page required fo
17b90 72 20 65 61 63 68 20 70 61 67 65 20 69 6e 20 5b  r each page in [
17ba0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
17bb0 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65  GECACHE]..** The
17bc0 20 61 6d 6f 75 6e 74 20 6f 66 20 65 78 74 72 61   amount of extra
17bd0 20 73 70 61 63 65 20 72 65 71 75 69 72 65 64 20   space required 
17be0 63 61 6e 20 63 68 61 6e 67 65 20 64 65 70 65 6e  can change depen
17bf0 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6d 70  ding on the comp
17c00 69 6c 65 72 2c 0a 2a 2a 20 74 61 72 67 65 74 20  iler,.** target 
17c10 70 6c 61 74 66 6f 72 6d 2c 20 61 6e 64 20 53 51  platform, and SQ
17c20 4c 69 74 65 20 76 65 72 73 69 6f 6e 2e 0a 2a 2a  Lite version..**
17c30 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
17c40 46 49 47 5f 50 4d 41 53 5a 5d 5d 0a 2a 2a 20 3c  FIG_PMASZ]].** <
17c50 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
17c60 5f 50 4d 41 53 5a 0a 2a 2a 20 3c 64 64 3e 5e 54  _PMASZ.** <dd>^T
17c70 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
17c80 5f 50 4d 41 53 5a 20 6f 70 74 69 6f 6e 20 74 61  _PMASZ option ta
17c90 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 70 61 72  kes a single par
17ca0 61 6d 65 74 65 72 20 77 68 69 63 68 0a 2a 2a 20  ameter which.** 
17cb0 69 73 20 61 6e 20 75 6e 73 69 67 6e 65 64 20 69  is an unsigned i
17cc0 6e 74 65 67 65 72 20 61 6e 64 20 73 65 74 73 20  nteger and sets 
17cd0 74 68 65 20 22 4d 69 6e 69 6d 75 6d 20 50 4d 41  the "Minimum PMA
17ce0 20 53 69 7a 65 22 20 66 6f 72 20 74 68 65 20 6d   Size" for the m
17cf0 75 6c 74 69 74 68 72 65 61 64 65 64 0a 2a 2a 20  ultithreaded.** 
17d00 73 6f 72 74 65 72 20 74 6f 20 74 68 61 74 20 69  sorter to that i
17d10 6e 74 65 67 65 72 2e 20 20 54 68 65 20 64 65 66  nteger.  The def
17d20 61 75 6c 74 20 6d 69 6e 69 6d 75 6d 20 50 4d 41  ault minimum PMA
17d30 20 53 69 7a 65 20 69 73 20 73 65 74 20 62 79 20   Size is set by 
17d40 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53  the.** [SQLITE_S
17d50 4f 52 54 45 52 5f 50 4d 41 53 5a 5d 20 63 6f 6d  ORTER_PMASZ] com
17d60 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
17d70 2e 20 20 4e 65 77 20 74 68 72 65 61 64 73 20 61  .  New threads a
17d80 72 65 20 6c 61 75 6e 63 68 65 64 0a 2a 2a 20 74  re launched.** t
17d90 6f 20 68 65 6c 70 20 77 69 74 68 20 73 6f 72 74  o help with sort
17da0 20 6f 70 65 72 61 74 69 6f 6e 73 20 77 68 65 6e   operations when
17db0 20 6d 75 6c 74 69 74 68 72 65 61 64 65 64 20 73   multithreaded s
17dc0 6f 72 74 69 6e 67 0a 2a 2a 20 69 73 20 65 6e 61  orting.** is ena
17dd0 62 6c 65 64 20 28 75 73 69 6e 67 20 74 68 65 20  bled (using the 
17de0 5b 50 52 41 47 4d 41 20 74 68 72 65 61 64 73 5d  [PRAGMA threads]
17df0 20 63 6f 6d 6d 61 6e 64 29 20 61 6e 64 20 74 68   command) and th
17e00 65 20 61 6d 6f 75 6e 74 20 6f 66 20 63 6f 6e 74  e amount of cont
17e10 65 6e 74 0a 2a 2a 20 74 6f 20 62 65 20 73 6f 72  ent.** to be sor
17e20 74 65 64 20 65 78 63 65 65 64 73 20 74 68 65 20  ted exceeds the 
17e30 70 61 67 65 20 73 69 7a 65 20 74 69 6d 65 73 20  page size times 
17e40 74 68 65 20 6d 69 6e 69 6d 75 6d 20 6f 66 20 74  the minimum of t
17e50 68 65 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 63 61  he.** [PRAGMA ca
17e60 63 68 65 5f 73 69 7a 65 5d 20 73 65 74 74 69 6e  che_size] settin
17e70 67 20 61 6e 64 20 74 68 69 73 20 76 61 6c 75 65  g and this value
17e80 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64  ..** </dl>.*/.#d
17e90 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
17ea0 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
17eb0 20 20 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23    1  /* nil */.#
17ec0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
17ed0 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44  NFIG_MULTITHREAD
17ee0 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a     2  /* nil */.
17ef0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
17f00 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44  ONFIG_SERIALIZED
17f10 20 20 20 20 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f      3  /* nil */
17f20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
17f30 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 20 20  CONFIG_MALLOC   
17f40 20 20 20 20 20 34 20 20 2f 2a 20 73 71 6c 69 74       4  /* sqlit
17f50 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20  e3_mem_methods* 
17f60 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
17f70 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c  E_CONFIG_GETMALL
17f80 4f 43 20 20 20 20 20 35 20 20 2f 2a 20 73 71 6c  OC     5  /* sql
17f90 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
17fa0 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
17fb0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54  ITE_CONFIG_SCRAT
17fc0 43 48 20 20 20 20 20 20 20 36 20 20 2f 2a 20 76  CH       6  /* v
17fd0 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e  oid*, int sz, in
17fe0 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  t N */.#define S
17ff0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
18000 45 43 41 43 48 45 20 20 20 20 20 37 20 20 2f 2a  ECACHE     7  /*
18010 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20   void*, int sz, 
18020 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65  int N */.#define
18030 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48   SQLITE_CONFIG_H
18040 45 41 50 20 20 20 20 20 20 20 20 20 20 38 20 20  EAP          8  
18050 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 42  /* void*, int nB
18060 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a  yte, int min */.
18070 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
18080 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20  ONFIG_MEMSTATUS 
18090 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f 6c 65 61      9  /* boolea
180a0 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  n */.#define SQL
180b0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
180c0 20 20 20 20 20 20 20 20 31 30 20 20 2f 2a 20 73          10  /* s
180d0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
180e0 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  hods* */.#define
180f0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
18100 45 54 4d 55 54 45 58 20 20 20 20 20 31 31 20 20  ETMUTEX     11  
18110 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  /* sqlite3_mutex
18120 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20  _methods* */./* 
18130 70 72 65 76 69 6f 75 73 6c 79 20 53 51 4c 49 54  previously SQLIT
18140 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e 4b 41 4c  E_CONFIG_CHUNKAL
18150 4c 4f 43 20 31 32 20 77 68 69 63 68 20 69 73 20  LOC 12 which is 
18160 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a 2f 20 0a  now unused. */ .
18170 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
18180 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20  ONFIG_LOOKASIDE 
18190 20 20 20 31 33 20 20 2f 2a 20 69 6e 74 20 69 6e     13  /* int in
181a0 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
181b0 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
181c0 45 20 20 20 20 20 20 20 31 34 20 20 2f 2a 20 6e  E       14  /* n
181d0 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20  o-op */.#define 
181e0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
181f0 54 50 43 41 43 48 45 20 20 20 20 31 35 20 20 2f  TPCACHE    15  /
18200 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69  * no-op */.#defi
18210 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
18220 5f 4c 4f 47 20 20 20 20 20 20 20 20 20 20 31 36  _LOG          16
18230 20 20 2f 2a 20 78 46 75 6e 63 2c 20 76 6f 69 64    /* xFunc, void
18240 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
18250 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 20 20  ITE_CONFIG_URI  
18260 20 20 20 20 20 20 20 20 31 37 20 20 2f 2a 20 69          17  /* i
18270 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  nt */.#define SQ
18280 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
18290 48 45 32 20 20 20 20 20 20 31 38 20 20 2f 2a 20  HE2      18  /* 
182a0 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d  sqlite3_pcache_m
182b0 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 66  ethods2* */.#def
182c0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
182d0 47 5f 47 45 54 50 43 41 43 48 45 32 20 20 20 31  G_GETPCACHE2   1
182e0 39 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63  9  /* sqlite3_pc
182f0 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a  ache_methods2* *
18300 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
18310 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47  _CONFIG_COVERING
18320 5f 49 4e 44 45 58 5f 53 43 41 4e 20 32 30 20 20  _INDEX_SCAN 20  
18330 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e  /* int */.#defin
18340 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
18350 53 51 4c 4c 4f 47 20 20 20 20 20 20 20 32 31 20  SQLLOG       21 
18360 20 2f 2a 20 78 53 71 6c 6c 6f 67 2c 20 76 6f 69   /* xSqllog, voi
18370 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  d* */.#define SQ
18380 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50  LITE_CONFIG_MMAP
18390 5f 53 49 5a 45 20 20 20 20 32 32 20 20 2f 2a 20  _SIZE    22  /* 
183a0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c 20 73  sqlite3_int64, s
183b0 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 2f 0a  qlite3_int64 */.
183c0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
183d0 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50  ONFIG_WIN32_HEAP
183e0 53 49 5a 45 20 20 20 20 20 20 32 33 20 20 2f 2a  SIZE      23  /*
183f0 20 69 6e 74 20 6e 42 79 74 65 20 2a 2f 0a 23 64   int nByte */.#d
18400 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
18410 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a  FIG_PCACHE_HDRSZ
18420 20 20 20 20 20 20 20 20 32 34 20 20 2f 2a 20 69          24  /* i
18430 6e 74 20 2a 70 73 7a 20 2a 2f 0a 23 64 65 66 69  nt *psz */.#defi
18440 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
18450 5f 50 4d 41 53 5a 20 20 20 20 20 20 20 20 20 20  _PMASZ          
18460 20 20 20 20 20 32 35 20 20 2f 2a 20 75 6e 73 69       25  /* unsi
18470 67 6e 65 64 20 69 6e 74 20 73 7a 50 6d 61 20 2a  gned int szPma *
18480 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
18490 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e  F: Database Conn
184a0 65 63 74 69 6f 6e 20 43 6f 6e 66 69 67 75 72 61  ection Configura
184b0 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a  tion Options.**.
184c0 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
184d0 74 73 20 61 72 65 20 74 68 65 20 61 76 61 69 6c  ts are the avail
184e0 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  able integer con
184f0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
18500 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62  ns that.** can b
18510 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
18520 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
18530 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
18540 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74  db_config()] int
18550 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65  erface..**.** Ne
18560 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  w configuration 
18570 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61  options may be a
18580 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72  dded in future r
18590 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74  eleases of SQLit
185a0 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63  e..** Existing c
185b0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
185c0 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69  ions might be di
185d0 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70  scontinued.  App
185e0 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f  lications.** sho
185f0 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 65  uld check the re
18600 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b  turn code from [
18610 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
18620 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72  g()] to make sur
18630 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61  e that.** the ca
18640 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 5e 54 68 65  ll worked.  ^The
18650 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
18660 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  fig()] interface
18670 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a   will return a.*
18680 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f  * non-zero [erro
18690 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73  r code] if a dis
186a0 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73  continued or uns
186b0 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75  upported configu
186c0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a  ration option.**
186d0 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a   is invoked..**.
186e0 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53  ** <dl>.** <dt>S
186f0 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
18700 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a  OOKASIDE</dt>.**
18710 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69   <dd> ^This opti
18720 6f 6e 20 74 61 6b 65 73 20 74 68 72 65 65 20 61  on takes three a
18730 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65  dditional argume
18740 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d 69  nts that determi
18750 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b  ne the .** [look
18760 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  aside memory all
18770 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72  ocator] configur
18780 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64  ation for the [d
18790 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
187a0 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72  on]..** ^The fir
187b0 73 74 20 61 72 67 75 6d 65 6e 74 20 28 74 68 65  st argument (the
187c0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
187d0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f   to [sqlite3_db_
187e0 63 6f 6e 66 69 67 28 29 5d 20 69 73 20 61 0a 2a  config()] is a.*
187f0 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d  * pointer to a m
18800 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 6f 20  emory buffer to 
18810 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64  use for lookasid
18820 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68  e memory..** ^Th
18830 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
18840 20 61 66 74 65 72 20 74 68 65 20 53 51 4c 49 54   after the SQLIT
18850 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
18860 53 49 44 45 20 76 65 72 62 0a 2a 2a 20 6d 61 79  SIDE verb.** may
18870 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63   be NULL in whic
18880 68 20 63 61 73 65 20 53 51 4c 69 74 65 20 77 69  h case SQLite wi
18890 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a  ll allocate the.
188a0 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66  ** lookaside buf
188b0 66 65 72 20 69 74 73 65 6c 66 20 75 73 69 6e 67  fer itself using
188c0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
188d0 28 29 5d 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64  ()]. ^The second
188e0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
188f0 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68  .** size of each
18900 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65   lookaside buffe
18910 72 20 73 6c 6f 74 2e 20 20 5e 54 68 65 20 74 68  r slot.  ^The th
18920 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ird argument is 
18930 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
18940 20 73 6c 6f 74 73 2e 20 20 54 68 65 20 73 69 7a   slots.  The siz
18950 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20  e of the buffer 
18960 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67  in the first arg
18970 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 67 72  ument must be gr
18980 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72  eater than.** or
18990 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20 70 72   equal to the pr
189a0 6f 64 75 63 74 20 6f 66 20 74 68 65 20 73 65 63  oduct of the sec
189b0 6f 6e 64 20 61 6e 64 20 74 68 69 72 64 20 61 72  ond and third ar
189c0 67 75 6d 65 6e 74 73 2e 20 20 54 68 65 20 62 75  guments.  The bu
189d0 66 66 65 72 0a 2a 2a 20 6d 75 73 74 20 62 65 20  ffer.** must be 
189e0 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d  aligned to an 8-
189f0 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2e 20 20  byte boundary.  
18a00 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61  ^If the second a
18a10 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 51  rgument to.** SQ
18a20 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
18a30 4f 4b 41 53 49 44 45 20 69 73 20 6e 6f 74 20 61  OKASIDE is not a
18a40 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20   multiple of 8, 
18a50 69 74 20 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79  it is internally
18a60 0a 2a 2a 20 72 6f 75 6e 64 65 64 20 64 6f 77 6e  .** rounded down
18a70 20 74 6f 20 74 68 65 20 6e 65 78 74 20 73 6d 61   to the next sma
18a80 6c 6c 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66  ller multiple of
18a90 20 38 2e 20 20 5e 28 54 68 65 20 6c 6f 6f 6b 61   8.  ^(The looka
18aa0 73 69 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63  side memory.** c
18ab0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72  onfiguration for
18ac0 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e   a database conn
18ad0 65 63 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20  ection can only 
18ae0 62 65 20 63 68 61 6e 67 65 64 20 77 68 65 6e 20  be changed when 
18af0 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  that.** connecti
18b00 6f 6e 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e  on is not curren
18b10 74 6c 79 20 75 73 69 6e 67 20 6c 6f 6f 6b 61 73  tly using lookas
18b20 69 64 65 20 6d 65 6d 6f 72 79 2c 20 6f 72 20 69  ide memory, or i
18b30 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 0a 2a 2a  n other words.**
18b40 20 77 68 65 6e 20 74 68 65 20 22 63 75 72 72 65   when the "curre
18b50 6e 74 20 76 61 6c 75 65 22 20 72 65 74 75 72 6e  nt value" return
18b60 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65  ed by.** [sqlite
18b70 33 5f 64 62 5f 73 74 61 74 75 73 5d 28 44 2c 5b  3_db_status](D,[
18b80 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
18b90 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29 20 69 73  OKASIDE],...) is
18ba0 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74   zero..** Any at
18bb0 74 65 6d 70 74 20 74 6f 20 63 68 61 6e 67 65 20  tempt to change 
18bc0 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  the lookaside me
18bd0 6d 6f 72 79 20 63 6f 6e 66 69 67 75 72 61 74 69  mory configurati
18be0 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61 73 69 64  on when lookasid
18bf0 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69 73 20 69  e.** memory is i
18c00 6e 20 75 73 65 20 6c 65 61 76 65 73 20 74 68 65  n use leaves the
18c10 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75   configuration u
18c20 6e 63 68 61 6e 67 65 64 20 61 6e 64 20 72 65 74  nchanged and ret
18c30 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45  urns .** [SQLITE
18c40 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a  _BUSY].)^</dd>.*
18c50 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
18c60 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f  DBCONFIG_ENABLE_
18c70 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  FKEY</dt>.** <dd
18c80 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69  > ^This option i
18c90 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65  s used to enable
18ca0 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65 20   or disable the 
18cb0 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 66 0a 2a  enforcement of.*
18cc0 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 63  * [foreign key c
18cd0 6f 6e 73 74 72 61 69 6e 74 73 5d 2e 20 20 54 68  onstraints].  Th
18ce0 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77  ere should be tw
18cf0 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67  o additional arg
18d00 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66  uments..** The f
18d10 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73  irst argument is
18d20 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63   an integer whic
18d30 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c  h is 0 to disabl
18d40 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74  e FK enforcement
18d50 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f  ,.** positive to
18d60 20 65 6e 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72   enable FK enfor
18d70 63 65 6d 65 6e 74 20 6f 72 20 6e 65 67 61 74 69  cement or negati
18d80 76 65 20 74 6f 20 6c 65 61 76 65 20 46 4b 20 65  ve to leave FK e
18d90 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e  nforcement.** un
18da0 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20 73 65  changed.  The se
18db0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
18dc0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
18dd0 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77  n integer into w
18de0 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74  hich.** is writt
18df0 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64  en 0 or 1 to ind
18e00 69 63 61 74 65 20 77 68 65 74 68 65 72 20 46 4b  icate whether FK
18e10 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 69 73 20   enforcement is 
18e20 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c  off or on.** fol
18e30 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c  lowing this call
18e40 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  .  The second pa
18e50 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61  rameter may be a
18e60 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69   NULL pointer, i
18e70 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20  n.** which case 
18e80 74 68 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65  the FK enforceme
18e90 6e 74 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f  nt setting is no
18ea0 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e  t reported back.
18eb0 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74   </dd>.**.** <dt
18ec0 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  >SQLITE_DBCONFIG
18ed0 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 3c  _ENABLE_TRIGGER<
18ee0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
18ef0 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  is option is use
18f00 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64  d to enable or d
18f10 69 73 61 62 6c 65 20 5b 43 52 45 41 54 45 20 54  isable [CREATE T
18f20 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 72  RIGGER | trigger
18f30 73 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f  s]..** There sho
18f40 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74  uld be two addit
18f50 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e  ional arguments.
18f60 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
18f70 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74  gument is an int
18f80 65 67 65 72 20 77 68 69 63 68 20 69 73 20 30 20  eger which is 0 
18f90 74 6f 20 64 69 73 61 62 6c 65 20 74 72 69 67 67  to disable trigg
18fa0 65 72 73 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65  ers,.** positive
18fb0 20 74 6f 20 65 6e 61 62 6c 65 20 74 72 69 67 67   to enable trigg
18fc0 65 72 73 20 6f 72 20 6e 65 67 61 74 69 76 65 20  ers or negative 
18fd0 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65 74  to leave the set
18fe0 74 69 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a  ting unchanged..
18ff0 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  ** The second pa
19000 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69  rameter is a poi
19010 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67  nter to an integ
19020 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a  er into which.**
19030 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72   is written 0 or
19040 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77   1 to indicate w
19050 68 65 74 68 65 72 20 74 72 69 67 67 65 72 73 20  hether triggers 
19060 61 72 65 20 64 69 73 61 62 6c 65 64 20 6f 72 20  are disabled or 
19070 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f  enabled.** follo
19080 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20  wing this call. 
19090 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
190a0 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e  meter may be a N
190b0 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a  ULL pointer, in.
190c0 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 68  ** which case th
190d0 65 20 74 72 69 67 67 65 72 20 73 65 74 74 69 6e  e trigger settin
190e0 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65  g is not reporte
190f0 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a  d back. </dd>.**
19100 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65  .** </dl>.*/.#de
19110 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f  fine SQLITE_DBCO
19120 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20  NFIG_LOOKASIDE  
19130 20 20 20 20 20 31 30 30 31 20 20 2f 2a 20 76 6f       1001  /* vo
19140 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23  id* int int */.#
19150 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42  define SQLITE_DB
19160 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b  CONFIG_ENABLE_FK
19170 45 59 20 20 20 20 20 31 30 30 32 20 20 2f 2a 20  EY     1002  /* 
19180 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66  int int* */.#def
19190 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ine SQLITE_DBCON
191a0 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47  FIG_ENABLE_TRIGG
191b0 45 52 20 20 31 30 30 33 20 20 2f 2a 20 69 6e 74  ER  1003  /* int
191c0 20 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a   int* */.../*.**
191d0 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c   CAPI3REF: Enabl
191e0 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74  e Or Disable Ext
191f0 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64  ended Result Cod
19200 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  es.**.** ^The sq
19210 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72  lite3_extended_r
19220 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f  esult_codes() ro
19230 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72  utine enables or
19240 20 64 69 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a   disables the.**
19250 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
19260 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75 72 65  t codes] feature
19270 20 6f 66 20 53 51 4c 69 74 65 2e 20 5e 54 68 65   of SQLite. ^The
19280 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
19290 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65 20 64 69  .** codes are di
192a0 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  sabled by defaul
192b0 74 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c  t for historical
192c0 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a   compatibility..
192d0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
192e0 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
192f0 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65   sqlite3_extende
19300 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 73  d_result_codes(s
19310 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f  qlite3*, int ono
19320 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ff);../*.** CAPI
19330 33 52 45 46 3a 20 4c 61 73 74 20 49 6e 73 65 72  3REF: Last Inser
19340 74 20 52 6f 77 69 64 0a 2a 2a 0a 2a 2a 20 5e 45  t Rowid.**.** ^E
19350 61 63 68 20 65 6e 74 72 79 20 69 6e 20 6d 6f 73  ach entry in mos
19360 74 20 53 51 4c 69 74 65 20 74 61 62 6c 65 73 20  t SQLite tables 
19370 28 65 78 63 65 70 74 20 66 6f 72 20 5b 57 49 54  (except for [WIT
19380 48 4f 55 54 20 52 4f 57 49 44 5d 20 74 61 62 6c  HOUT ROWID] tabl
19390 65 73 29 0a 2a 2a 20 68 61 73 20 61 20 75 6e 69  es).** has a uni
193a0 71 75 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65  que 64-bit signe
193b0 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79  d.** integer key
193c0 20 63 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57   called the [ROW
193d0 49 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20 5e  ID | "rowid"]. ^
193e0 54 68 65 20 72 6f 77 69 64 20 69 73 20 61 6c 77  The rowid is alw
193f0 61 79 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a  ays available.**
19400 20 61 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 65   as an undeclare
19410 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52  d column named R
19420 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52  OWID, OID, or _R
19430 4f 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73  OWID_ as long as
19440 20 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20   those.** names 
19450 61 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65  are not also use
19460 64 20 62 79 20 65 78 70 6c 69 63 69 74 6c 79 20  d by explicitly 
19470 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73  declared columns
19480 2e 20 5e 49 66 0a 2a 2a 20 74 68 65 20 74 61 62  . ^If.** the tab
19490 6c 65 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20  le has a column 
194a0 6f 66 20 74 79 70 65 20 5b 49 4e 54 45 47 45 52  of type [INTEGER
194b0 20 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 74 68   PRIMARY KEY] th
194c0 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a  en that column.*
194d0 2a 20 69 73 20 61 6e 6f 74 68 65 72 20 61 6c 69  * is another ali
194e0 61 73 20 66 6f 72 20 74 68 65 20 72 6f 77 69 64  as for the rowid
194f0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
19500 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74  ite3_last_insert
19510 5f 72 6f 77 69 64 28 44 29 20 69 6e 74 65 72 66  _rowid(D) interf
19520 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
19530 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 0a  [rowid] of the .
19540 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 73  ** most recent s
19550 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52  uccessful [INSER
19560 54 5d 20 69 6e 74 6f 20 61 20 72 6f 77 69 64 20  T] into a rowid 
19570 74 61 62 6c 65 20 6f 72 20 5b 76 69 72 74 75 61  table or [virtua
19580 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 6f 6e 20 64  l table].** on d
19590 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
195a0 6f 6e 20 44 2e 0a 2a 2a 20 5e 49 6e 73 65 72 74  on D..** ^Insert
195b0 73 20 69 6e 74 6f 20 5b 57 49 54 48 4f 55 54 20  s into [WITHOUT 
195c0 52 4f 57 49 44 5d 20 74 61 62 6c 65 73 20 61 72  ROWID] tables ar
195d0 65 20 6e 6f 74 20 72 65 63 6f 72 64 65 64 2e 0a  e not recorded..
195e0 2a 2a 20 5e 49 66 20 6e 6f 20 73 75 63 63 65 73  ** ^If no succes
195f0 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 73 20 69  sful [INSERT]s i
19600 6e 74 6f 20 72 6f 77 69 64 20 74 61 62 6c 65 73  nto rowid tables
19610 0a 2a 2a 20 68 61 76 65 20 65 76 65 72 20 6f 63  .** have ever oc
19620 63 75 72 72 65 64 20 6f 6e 20 74 68 65 20 64 61  curred on the da
19630 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
19640 6e 20 44 2c 20 0a 2a 2a 20 74 68 65 6e 20 73 71  n D, .** then sq
19650 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72  lite3_last_inser
19660 74 5f 72 6f 77 69 64 28 44 29 20 72 65 74 75 72  t_rowid(D) retur
19670 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e  ns zero..**.** ^
19680 28 49 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20  (If an [INSERT] 
19690 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 20  occurs within a 
196a0 74 72 69 67 67 65 72 20 6f 72 20 77 69 74 68 69  trigger or withi
196b0 6e 20 61 20 5b 76 69 72 74 75 61 6c 20 74 61 62  n a [virtual tab
196c0 6c 65 5d 0a 2a 2a 20 6d 65 74 68 6f 64 2c 20 74  le].** method, t
196d0 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65  hen this routine
196e0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 74 68 65   will return the
196f0 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20   [rowid] of the 
19700 69 6e 73 65 72 74 65 64 0a 2a 2a 20 72 6f 77 20  inserted.** row 
19710 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74  as long as the t
19720 72 69 67 67 65 72 20 6f 72 20 76 69 72 74 75 61  rigger or virtua
19730 6c 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 69  l table method i
19740 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75  s running..** Bu
19750 74 20 6f 6e 63 65 20 74 68 65 20 74 72 69 67 67  t once the trigg
19760 65 72 20 6f 72 20 76 69 72 74 75 61 6c 20 74 61  er or virtual ta
19770 62 6c 65 20 6d 65 74 68 6f 64 20 65 6e 64 73 2c  ble method ends,
19780 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
19790 6e 65 64 20 0a 2a 2a 20 62 79 20 74 68 69 73 20  ned .** by this 
197a0 72 6f 75 74 69 6e 65 20 72 65 76 65 72 74 73 20  routine reverts 
197b0 74 6f 20 77 68 61 74 20 69 74 20 77 61 73 20 62  to what it was b
197c0 65 66 6f 72 65 20 74 68 65 20 74 72 69 67 67 65  efore the trigge
197d0 72 20 6f 72 20 76 69 72 74 75 61 6c 0a 2a 2a 20  r or virtual.** 
197e0 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 62 65 67  table method beg
197f0 61 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20  an.)^.**.** ^An 
19800 5b 49 4e 53 45 52 54 5d 20 74 68 61 74 20 66 61  [INSERT] that fa
19810 69 6c 73 20 64 75 65 20 74 6f 20 61 20 63 6f 6e  ils due to a con
19820 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f  straint violatio
19830 6e 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75  n is not a.** su
19840 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54  ccessful [INSERT
19850 5d 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63  ] and does not c
19860 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 20  hange the value 
19870 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73  returned by this
19880 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20 5e 54  .** routine.  ^T
19890 68 75 73 20 49 4e 53 45 52 54 20 4f 52 20 46 41  hus INSERT OR FA
198a0 49 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20 49 47  IL, INSERT OR IG
198b0 4e 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f 52 20  NORE, INSERT OR 
198c0 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64  ROLLBACK,.** and
198d0 20 49 4e 53 45 52 54 20 4f 52 20 41 42 4f 52 54   INSERT OR ABORT
198e0 20 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73   make no changes
198f0 20 74 6f 20 74 68 65 20 72 65 74 75 72 6e 20 76   to the return v
19900 61 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20  alue of this.** 
19910 72 6f 75 74 69 6e 65 20 77 68 65 6e 20 74 68 65  routine when the
19920 69 72 20 69 6e 73 65 72 74 69 6f 6e 20 66 61 69  ir insertion fai
19930 6c 73 2e 20 20 5e 28 57 68 65 6e 20 49 4e 53 45  ls.  ^(When INSE
19940 52 54 20 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a  RT OR REPLACE.**
19950 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 20 63 6f   encounters a co
19960 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69  nstraint violati
19970 6f 6e 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74 20  on, it does not 
19980 66 61 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e  fail.  The.** IN
19990 53 45 52 54 20 63 6f 6e 74 69 6e 75 65 73 20 74  SERT continues t
199a0 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74  o completion aft
199b0 65 72 20 64 65 6c 65 74 69 6e 67 20 72 6f 77 73  er deleting rows
199c0 20 74 68 61 74 20 63 61 75 73 65 64 0a 2a 2a 20   that caused.** 
199d0 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 70  the constraint p
199e0 72 6f 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54  roblem so INSERT
199f0 20 4f 52 20 52 45 50 4c 41 43 45 20 77 69 6c 6c   OR REPLACE will
19a00 20 61 6c 77 61 79 73 20 63 68 61 6e 67 65 0a 2a   always change.*
19a10 2a 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  * the return val
19a20 75 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72  ue of this inter
19a30 66 61 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46  face.)^.**.** ^F
19a40 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65 73 20  or the purposes 
19a50 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c  of this routine,
19a60 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 69 73 20   an [INSERT] is 
19a70 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a  considered to.**
19a80 20 62 65 20 73 75 63 63 65 73 73 66 75 6c 20 65   be successful e
19a90 76 65 6e 20 69 66 20 69 74 20 69 73 20 73 75 62  ven if it is sub
19aa0 73 65 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64  sequently rolled
19ab0 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69   back..**.** Thi
19ac0 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 63  s function is ac
19ad0 63 65 73 73 69 62 6c 65 20 74 6f 20 53 51 4c 20  cessible to SQL 
19ae0 73 74 61 74 65 6d 65 6e 74 73 20 76 69 61 20 74  statements via t
19af0 68 65 0a 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73 65  he.** [last_inse
19b00 72 74 5f 72 6f 77 69 64 28 29 20 53 51 4c 20 66  rt_rowid() SQL f
19b10 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20  unction]..**.** 
19b20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68  If a separate th
19b30 72 65 61 64 20 70 65 72 66 6f 72 6d 73 20 61 20  read performs a 
19b40 6e 65 77 20 5b 49 4e 53 45 52 54 5d 20 6f 6e 20  new [INSERT] on 
19b50 74 68 65 20 73 61 6d 65 0a 2a 2a 20 64 61 74 61  the same.** data
19b60 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
19b70 77 68 69 6c 65 20 74 68 65 20 5b 73 71 6c 69 74  while the [sqlit
19b80 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  e3_last_insert_r
19b90 6f 77 69 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 74  owid()].** funct
19ba0 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20 61  ion is running a
19bb0 6e 64 20 74 68 75 73 20 63 68 61 6e 67 65 73 20  nd thus changes 
19bc0 74 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74 20  the last insert 
19bd0 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e  [rowid],.** then
19be0 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
19bf0 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
19c00 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
19c10 64 28 29 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 65  d()] is.** unpre
19c20 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6d 69 67  dictable and mig
19c30 68 74 20 6e 6f 74 20 65 71 75 61 6c 20 65 69 74  ht not equal eit
19c40 68 65 72 20 74 68 65 20 6f 6c 64 20 6f 72 20 74  her the old or t
19c50 68 65 20 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 69  he new.** last i
19c60 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a  nsert [rowid]..*
19c70 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c  /.SQLITE_API sql
19c80 69 74 65 33 5f 69 6e 74 36 34 20 53 51 4c 49 54  ite3_int64 SQLIT
19c90 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
19ca0 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  3_last_insert_ro
19cb0 77 69 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  wid(sqlite3*);..
19cc0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
19cd0 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62 65 72  Count The Number
19ce0 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65   Of Rows Modifie
19cf0 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75  d.**.** ^This fu
19d00 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74  nction returns t
19d10 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77  he number of row
19d20 73 20 6d 6f 64 69 66 69 65 64 2c 20 69 6e 73 65  s modified, inse
19d30 72 74 65 64 20 6f 72 0a 2a 2a 20 64 65 6c 65 74  rted or.** delet
19d40 65 64 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72  ed by the most r
19d50 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65  ecently complete
19d60 64 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  d INSERT, UPDATE
19d70 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74   or DELETE.** st
19d80 61 74 65 6d 65 6e 74 20 6f 6e 20 74 68 65 20 64  atement on the d
19d90 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
19da0 6f 6e 20 73 70 65 63 69 66 69 65 64 20 62 79 20  on specified by 
19db0 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74  the only paramet
19dc0 65 72 2e 0a 2a 2a 20 5e 45 78 65 63 75 74 69 6e  er..** ^Executin
19dd0 67 20 61 6e 79 20 6f 74 68 65 72 20 74 79 70 65  g any other type
19de0 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   of SQL statemen
19df0 74 20 64 6f 65 73 20 6e 6f 74 20 6d 6f 64 69 66  t does not modif
19e00 79 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72  y the value.** r
19e10 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 20  eturned by this 
19e20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  function..**.** 
19e30 5e 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 6d 61  ^Only changes ma
19e40 64 65 20 64 69 72 65 63 74 6c 79 20 62 79 20 74  de directly by t
19e50 68 65 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  he INSERT, UPDAT
19e60 45 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74  E or DELETE stat
19e70 65 6d 65 6e 74 20 61 72 65 0a 2a 2a 20 63 6f 6e  ement are.** con
19e80 73 69 64 65 72 65 64 20 2d 20 61 75 78 69 6c 69  sidered - auxili
19e90 61 72 79 20 63 68 61 6e 67 65 73 20 63 61 75 73  ary changes caus
19ea0 65 64 20 62 79 20 5b 43 52 45 41 54 45 20 54 52  ed by [CREATE TR
19eb0 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 73  IGGER | triggers
19ec0 5d 2c 20 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20  ], .** [foreign 
19ed0 6b 65 79 20 61 63 74 69 6f 6e 73 5d 20 6f 72 20  key actions] or 
19ee0 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72  [REPLACE] constr
19ef0 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20  aint resolution 
19f00 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e  are not counted.
19f10 0a 2a 2a 20 0a 2a 2a 20 43 68 61 6e 67 65 73 20  .** .** Changes 
19f20 74 6f 20 61 20 76 69 65 77 20 74 68 61 74 20 61  to a view that a
19f30 72 65 20 69 6e 74 65 72 63 65 70 74 65 64 20 62  re intercepted b
19f40 79 20 0a 2a 2a 20 5b 49 4e 53 54 45 41 44 20 4f  y .** [INSTEAD O
19f50 46 20 74 72 69 67 67 65 72 20 7c 20 49 4e 53 54  F trigger | INST
19f60 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 73 5d  EAD OF triggers]
19f70 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64   are not counted
19f80 2e 20 5e 54 68 65 20 76 61 6c 75 65 20 0a 2a 2a  . ^The value .**
19f90 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
19fa0 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 69  ite3_changes() i
19fb0 6d 6d 65 64 69 61 74 65 6c 79 20 61 66 74 65 72  mmediately after
19fc0 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41   an INSERT, UPDA
19fd0 54 45 20 6f 72 20 0a 2a 2a 20 44 45 4c 45 54 45  TE or .** DELETE
19fe0 20 73 74 61 74 65 6d 65 6e 74 20 72 75 6e 20 6f   statement run o
19ff0 6e 20 61 20 76 69 65 77 20 69 73 20 61 6c 77 61  n a view is alwa
1a000 79 73 20 7a 65 72 6f 2e 20 4f 6e 6c 79 20 63 68  ys zero. Only ch
1a010 61 6e 67 65 73 20 6d 61 64 65 20 74 6f 20 72 65  anges made to re
1a020 61 6c 20 0a 2a 2a 20 74 61 62 6c 65 73 20 61 72  al .** tables ar
1a030 65 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a  e counted..**.**
1a040 20 54 68 69 6e 67 73 20 61 72 65 20 6d 6f 72 65   Things are more
1a050 20 63 6f 6d 70 6c 69 63 61 74 65 64 20 69 66 20   complicated if 
1a060 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e  the sqlite3_chan
1a070 67 65 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 69  ges() function i
1a080 73 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 77 68  s.** executed wh
1a090 69 6c 65 20 61 20 74 72 69 67 67 65 72 20 70 72  ile a trigger pr
1a0a0 6f 67 72 61 6d 20 69 73 20 72 75 6e 6e 69 6e 67  ogram is running
1a0b0 2e 20 54 68 69 73 20 6d 61 79 20 68 61 70 70 65  . This may happe
1a0c0 6e 20 69 66 20 74 68 65 0a 2a 2a 20 70 72 6f 67  n if the.** prog
1a0d0 72 61 6d 20 75 73 65 73 20 74 68 65 20 5b 63 68  ram uses the [ch
1a0e0 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63  anges() SQL func
1a0f0 74 69 6f 6e 5d 2c 20 6f 72 20 69 66 20 73 6f 6d  tion], or if som
1a100 65 20 6f 74 68 65 72 20 63 61 6c 6c 62 61 63 6b  e other callback
1a110 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 6e 76  .** function inv
1a120 6f 6b 65 73 20 73 71 6c 69 74 65 33 5f 63 68 61  okes sqlite3_cha
1a130 6e 67 65 73 28 29 20 64 69 72 65 63 74 6c 79 2e  nges() directly.
1a140 20 45 73 73 65 6e 74 69 61 6c 6c 79 3a 0a 2a 2a   Essentially:.**
1a150 20 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c   .** <ul>.**   <
1a160 6c 69 3e 20 5e 28 42 65 66 6f 72 65 20 65 6e 74  li> ^(Before ent
1a170 65 72 69 6e 67 20 61 20 74 72 69 67 67 65 72 20  ering a trigger 
1a180 70 72 6f 67 72 61 6d 20 74 68 65 20 76 61 6c 75  program the valu
1a190 65 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  e returned by.**
1a1a0 20 20 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f          sqlite3_
1a1b0 63 68 61 6e 67 65 73 28 29 20 66 75 6e 63 74 69  changes() functi
1a1c0 6f 6e 20 69 73 20 73 61 76 65 64 2e 20 41 66 74  on is saved. Aft
1a1d0 65 72 20 74 68 65 20 74 72 69 67 67 65 72 20 70  er the trigger p
1a1e0 72 6f 67 72 61 6d 20 0a 2a 2a 20 20 20 20 20 20  rogram .**      
1a1f0 20 20 68 61 73 20 66 69 6e 69 73 68 65 64 2c 20    has finished, 
1a200 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 76 61 6c  the original val
1a210 75 65 20 69 73 20 72 65 73 74 6f 72 65 64 2e 29  ue is restored.)
1a220 5e 0a 2a 2a 20 0a 2a 2a 20 20 20 3c 6c 69 3e 20  ^.** .**   <li> 
1a230 5e 28 57 69 74 68 69 6e 20 61 20 74 72 69 67 67  ^(Within a trigg
1a240 65 72 20 70 72 6f 67 72 61 6d 20 65 61 63 68 20  er program each 
1a250 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 61  INSERT, UPDATE a
1a260 6e 64 20 44 45 4c 45 54 45 20 0a 2a 2a 20 20 20  nd DELETE .**   
1a270 20 20 20 20 20 73 74 61 74 65 6d 65 6e 74 20 73       statement s
1a280 65 74 73 20 74 68 65 20 76 61 6c 75 65 20 72 65  ets the value re
1a290 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
1a2a0 33 5f 63 68 61 6e 67 65 73 28 29 20 0a 2a 2a 20  3_changes() .** 
1a2b0 20 20 20 20 20 20 20 75 70 6f 6e 20 63 6f 6d 70         upon comp
1a2c0 6c 65 74 69 6f 6e 20 61 73 20 6e 6f 72 6d 61 6c  letion as normal
1a2d0 2e 20 4f 66 20 63 6f 75 72 73 65 2c 20 74 68 69  . Of course, thi
1a2e0 73 20 76 61 6c 75 65 20 77 69 6c 6c 20 6e 6f 74  s value will not
1a2f0 20 69 6e 63 6c 75 64 65 20 0a 2a 2a 20 20 20 20   include .**    
1a300 20 20 20 20 61 6e 79 20 63 68 61 6e 67 65 73 20      any changes 
1a310 70 65 72 66 6f 72 6d 65 64 20 62 79 20 73 75 62  performed by sub
1a320 2d 74 72 69 67 67 65 72 73 2c 20 61 73 20 74 68  -triggers, as th
1a330 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65  e sqlite3_change
1a340 73 28 29 20 0a 2a 2a 20 20 20 20 20 20 20 20 76  s() .**        v
1a350 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 73 61 76  alue will be sav
1a360 65 64 20 61 6e 64 20 72 65 73 74 6f 72 65 64 20  ed and restored 
1a370 61 66 74 65 72 20 65 61 63 68 20 73 75 62 2d 74  after each sub-t
1a380 72 69 67 67 65 72 20 68 61 73 20 72 75 6e 2e 29  rigger has run.)
1a390 5e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 0a 2a  ^.** </ul>.** .*
1a3a0 2a 20 5e 54 68 69 73 20 6d 65 61 6e 73 20 74 68  * ^This means th
1a3b0 61 74 20 69 66 20 74 68 65 20 63 68 61 6e 67 65  at if the change
1a3c0 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  s() SQL function
1a3d0 20 28 6f 72 20 73 69 6d 69 6c 61 72 29 20 69 73   (or similar) is
1a3e0 20 75 73 65 64 0a 2a 2a 20 62 79 20 74 68 65 20   used.** by the 
1a3f0 66 69 72 73 74 20 49 4e 53 45 52 54 2c 20 55 50  first INSERT, UP
1a400 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73  DATE or DELETE s
1a410 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20  tatement within 
1a420 61 20 74 72 69 67 67 65 72 2c 20 69 74 20 0a 2a  a trigger, it .*
1a430 2a 20 72 65 74 75 72 6e 73 20 74 68 65 20 76 61  * returns the va
1a440 6c 75 65 20 61 73 20 73 65 74 20 77 68 65 6e 20  lue as set when 
1a450 74 68 65 20 63 61 6c 6c 69 6e 67 20 73 74 61 74  the calling stat
1a460 65 6d 65 6e 74 20 62 65 67 61 6e 20 65 78 65 63  ement began exec
1a470 75 74 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 69 74  uting..** ^If it
1a480 20 69 73 20 75 73 65 64 20 62 79 20 74 68 65 20   is used by the 
1a490 73 65 63 6f 6e 64 20 6f 72 20 73 75 62 73 65 71  second or subseq
1a4a0 75 65 6e 74 20 73 75 63 68 20 73 74 61 74 65 6d  uent such statem
1a4b0 65 6e 74 20 77 69 74 68 69 6e 20 61 20 74 72 69  ent within a tri
1a4c0 67 67 65 72 20 0a 2a 2a 20 70 72 6f 67 72 61 6d  gger .** program
1a4d0 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  , the value retu
1a4e0 72 6e 65 64 20 72 65 66 6c 65 63 74 73 20 74 68  rned reflects th
1a4f0 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73  e number of rows
1a500 20 6d 6f 64 69 66 69 65 64 20 62 79 20 74 68 65   modified by the
1a510 20 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 49 4e   .** previous IN
1a520 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20  SERT, UPDATE or 
1a530 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74  DELETE statement
1a540 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65   within the same
1a550 20 74 72 69 67 67 65 72 2e 0a 2a 2a 0a 2a 2a 20   trigger..**.** 
1a560 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71  See also the [sq
1a570 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
1a580 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ges()] interface
1a590 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f  , the.** [count_
1a5a0 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c  changes pragma],
1a5b0 20 61 6e 64 20 74 68 65 20 5b 63 68 61 6e 67 65   and the [change
1a5c0 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  s() SQL function
1a5d0 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65  ]..**.** If a se
1a5e0 70 61 72 61 74 65 20 74 68 72 65 61 64 20 6d 61  parate thread ma
1a5f0 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74  kes changes on t
1a600 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
1a610 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77   connection.** w
1a620 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63 68  hile [sqlite3_ch
1a630 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e  anges()] is runn
1a640 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c  ing then the val
1a650 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69  ue returned.** i
1a660 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20  s unpredictable 
1a670 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66  and not meaningf
1a680 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ul..*/.SQLITE_AP
1a690 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  I int SQLITE_STD
1a6a0 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 68 61  CALL sqlite3_cha
1a6b0 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a  nges(sqlite3*);.
1a6c0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1a6d0 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66   Total Number Of
1a6e0 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a   Rows Modified.*
1a6f0 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74  *.** ^This funct
1a700 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  ion returns the 
1a710 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20  total number of 
1a720 72 6f 77 73 20 69 6e 73 65 72 74 65 64 2c 20 6d  rows inserted, m
1a730 6f 64 69 66 69 65 64 20 6f 72 0a 2a 2a 20 64 65  odified or.** de
1a740 6c 65 74 65 64 20 62 79 20 61 6c 6c 20 5b 49 4e  leted by all [IN
1a750 53 45 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d 20  SERT], [UPDATE] 
1a760 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74  or [DELETE] stat
1a770 65 6d 65 6e 74 73 20 63 6f 6d 70 6c 65 74 65 64  ements completed
1a780 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 64 61  .** since the da
1a790 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1a7a0 6e 20 77 61 73 20 6f 70 65 6e 65 64 2c 20 69 6e  n was opened, in
1a7b0 63 6c 75 64 69 6e 67 20 74 68 6f 73 65 20 65 78  cluding those ex
1a7c0 65 63 75 74 65 64 20 61 73 0a 2a 2a 20 70 61 72  ecuted as.** par
1a7d0 74 20 6f 66 20 74 72 69 67 67 65 72 20 70 72 6f  t of trigger pro
1a7e0 67 72 61 6d 73 2e 20 5e 45 78 65 63 75 74 69 6e  grams. ^Executin
1a7f0 67 20 61 6e 79 20 6f 74 68 65 72 20 74 79 70 65  g any other type
1a800 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   of SQL statemen
1a810 74 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 61 66  t.** does not af
1a820 66 65 63 74 20 74 68 65 20 76 61 6c 75 65 20 72  fect the value r
1a830 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
1a840 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
1a850 28 29 2e 0a 2a 2a 20 0a 2a 2a 20 5e 43 68 61 6e  ()..** .** ^Chan
1a860 67 65 73 20 6d 61 64 65 20 61 73 20 70 61 72 74  ges made as part
1a870 20 6f 66 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79   of [foreign key
1a880 20 61 63 74 69 6f 6e 73 5d 20 61 72 65 20 69 6e   actions] are in
1a890 63 6c 75 64 65 64 20 69 6e 20 74 68 65 0a 2a 2a  cluded in the.**
1a8a0 20 63 6f 75 6e 74 2c 20 62 75 74 20 74 68 6f 73   count, but thos
1a8b0 65 20 6d 61 64 65 20 61 73 20 70 61 72 74 20 6f  e made as part o
1a8c0 66 20 52 45 50 4c 41 43 45 20 63 6f 6e 73 74 72  f REPLACE constr
1a8d0 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20  aint resolution 
1a8e0 61 72 65 0a 2a 2a 20 6e 6f 74 2e 20 5e 43 68 61  are.** not. ^Cha
1a8f0 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77 20 74  nges to a view t
1a900 68 61 74 20 61 72 65 20 69 6e 74 65 72 63 65 70  hat are intercep
1a910 74 65 64 20 62 79 20 49 4e 53 54 45 41 44 20 4f  ted by INSTEAD O
1a920 46 20 74 72 69 67 67 65 72 73 20 0a 2a 2a 20 61  F triggers .** a
1a930 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 0a  re not counted..
1a940 2a 2a 20 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20  ** .** See also 
1a950 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61  the [sqlite3_cha
1a960 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63  nges()] interfac
1a970 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74  e, the.** [count
1a980 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d  _changes pragma]
1a990 2c 20 61 6e 64 20 74 68 65 20 5b 74 6f 74 61 6c  , and the [total
1a9a0 5f 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66  _changes() SQL f
1a9b0 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20  unction]..**.** 
1a9c0 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68  If a separate th
1a9d0 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67  read makes chang
1a9e0 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64  es on the same d
1a9f0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1aa00 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c  on.** while [sql
1aa10 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
1aa20 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67  es()] is running
1aa30 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 0a   then the value.
1aa40 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 73 20 75  ** returned is u
1aa50 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64  npredictable and
1aa60 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e   not meaningful.
1aa70 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
1aa80 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  nt SQLITE_STDCAL
1aa90 4c 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f  L sqlite3_total_
1aaa0 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a  changes(sqlite3*
1aab0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1aac0 45 46 3a 20 49 6e 74 65 72 72 75 70 74 20 41 20  EF: Interrupt A 
1aad0 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65  Long-Running Que
1aae0 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66  ry.**.** ^This f
1aaf0 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20 61  unction causes a
1ab00 6e 79 20 70 65 6e 64 69 6e 67 20 64 61 74 61 62  ny pending datab
1ab10 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f  ase operation to
1ab20 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65   abort and.** re
1ab30 74 75 72 6e 20 61 74 20 69 74 73 20 65 61 72 6c  turn at its earl
1ab40 69 65 73 74 20 6f 70 70 6f 72 74 75 6e 69 74 79  iest opportunity
1ab50 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69  . This routine i
1ab60 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63  s typically.** c
1ab70 61 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e 73  alled in respons
1ab80 65 20 74 6f 20 61 20 75 73 65 72 20 61 63 74 69  e to a user acti
1ab90 6f 6e 20 73 75 63 68 20 61 73 20 70 72 65 73 73  on such as press
1aba0 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20  ing "Cancel".** 
1abb0 6f 72 20 43 74 72 6c 2d 43 20 77 68 65 72 65 20  or Ctrl-C where 
1abc0 74 68 65 20 75 73 65 72 20 77 61 6e 74 73 20 61  the user wants a
1abd0 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70 65 72   long query oper
1abe0 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a  ation to halt.**
1abf0 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a   immediately..**
1ac00 0a 2a 2a 20 5e 49 74 20 69 73 20 73 61 66 65 20  .** ^It is safe 
1ac10 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75  to call this rou
1ac20 74 69 6e 65 20 66 72 6f 6d 20 61 20 74 68 72 65  tine from a thre
1ac30 61 64 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f  ad different fro
1ac40 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65 61 64 20  m the.** thread 
1ac50 74 68 61 74 20 69 73 20 63 75 72 72 65 6e 74 6c  that is currentl
1ac60 79 20 72 75 6e 6e 69 6e 67 20 74 68 65 20 64 61  y running the da
1ac70 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e  tabase operation
1ac80 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20 69 73 20  .  But it.** is 
1ac90 6e 6f 74 20 73 61 66 65 20 74 6f 20 63 61 6c 6c  not safe to call
1aca0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69   this routine wi
1acb0 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  th a [database c
1acc0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 0a  onnection] that.
1acd0 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f 72 20  ** is closed or 
1ace0 6d 69 67 68 74 20 63 6c 6f 73 65 20 62 65 66 6f  might close befo
1acf0 72 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  re sqlite3_inter
1ad00 72 75 70 74 28 29 20 72 65 74 75 72 6e 73 2e 0a  rupt() returns..
1ad10 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 53 51 4c  **.** ^If an SQL
1ad20 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 76 65   operation is ve
1ad30 72 79 20 6e 65 61 72 6c 79 20 66 69 6e 69 73 68  ry nearly finish
1ad40 65 64 20 61 74 20 74 68 65 20 74 69 6d 65 20 77  ed at the time w
1ad50 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69  hen.** sqlite3_i
1ad60 6e 74 65 72 72 75 70 74 28 29 20 69 73 20 63 61  nterrupt() is ca
1ad70 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74 20 6d 69  lled, then it mi
1ad80 67 68 74 20 6e 6f 74 20 68 61 76 65 20 61 6e 20  ght not have an 
1ad90 6f 70 70 6f 72 74 75 6e 69 74 79 0a 2a 2a 20 74  opportunity.** t
1ada0 6f 20 62 65 20 69 6e 74 65 72 72 75 70 74 65 64  o be interrupted
1adb0 20 61 6e 64 20 6d 69 67 68 74 20 63 6f 6e 74 69   and might conti
1adc0 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f  nue to completio
1add0 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51 4c  n..**.** ^An SQL
1ade0 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20   operation that 
1adf0 69 73 20 69 6e 74 65 72 72 75 70 74 65 64 20 77  is interrupted w
1ae00 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  ill return [SQLI
1ae10 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a  TE_INTERRUPT]..*
1ae20 2a 20 5e 49 66 20 74 68 65 20 69 6e 74 65 72 72  * ^If the interr
1ae30 75 70 74 65 64 20 53 51 4c 20 6f 70 65 72 61 74  upted SQL operat
1ae40 69 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45 52 54  ion is an INSERT
1ae50 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c  , UPDATE, or DEL
1ae60 45 54 45 0a 2a 2a 20 74 68 61 74 20 69 73 20 69  ETE.** that is i
1ae70 6e 73 69 64 65 20 61 6e 20 65 78 70 6c 69 63 69  nside an explici
1ae80 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74  t transaction, t
1ae90 68 65 6e 20 74 68 65 20 65 6e 74 69 72 65 20 74  hen the entire t
1aea0 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20 77 69  ransaction.** wi
1aeb0 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63  ll be rolled bac
1aec0 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e  k automatically.
1aed0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1aee0 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29  te3_interrupt(D)
1aef0 20 63 61 6c 6c 20 69 73 20 69 6e 20 65 66 66 65   call is in effe
1af00 63 74 20 75 6e 74 69 6c 20 61 6c 6c 20 63 75 72  ct until all cur
1af10 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 0a 2a  rently running.*
1af20 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  * SQL statements
1af30 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f   on [database co
1af40 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 63 6f 6d 70  nnection] D comp
1af50 6c 65 74 65 2e 20 20 5e 41 6e 79 20 6e 65 77 20  lete.  ^Any new 
1af60 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
1af70 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74  * that are start
1af80 65 64 20 61 66 74 65 72 20 74 68 65 20 73 71 6c  ed after the sql
1af90 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
1afa0 20 63 61 6c 6c 20 61 6e 64 20 62 65 66 6f 72 65   call and before
1afb0 20 74 68 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67   the .** running
1afc0 20 73 74 61 74 65 6d 65 6e 74 73 20 72 65 61 63   statements reac
1afd0 68 65 73 20 7a 65 72 6f 20 61 72 65 20 69 6e 74  hes zero are int
1afe0 65 72 72 75 70 74 65 64 20 61 73 20 69 66 20 74  errupted as if t
1aff0 68 65 79 20 68 61 64 20 62 65 65 6e 0a 2a 2a 20  hey had been.** 
1b000 72 75 6e 6e 69 6e 67 20 70 72 69 6f 72 20 74 6f  running prior to
1b010 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74   the sqlite3_int
1b020 65 72 72 75 70 74 28 29 20 63 61 6c 6c 2e 20 20  errupt() call.  
1b030 5e 4e 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65  ^New SQL stateme
1b040 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20  nts.** that are 
1b050 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68  started after th
1b060 65 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d  e running statem
1b070 65 6e 74 20 63 6f 75 6e 74 20 72 65 61 63 68 65  ent count reache
1b080 73 20 7a 65 72 6f 20 61 72 65 0a 2a 2a 20 6e 6f  s zero are.** no
1b090 74 20 65 66 66 65 63 74 65 64 20 62 79 20 74 68  t effected by th
1b0a0 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
1b0b0 75 70 74 28 29 2e 0a 2a 2a 20 5e 41 20 63 61 6c  upt()..** ^A cal
1b0c0 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 74  l to sqlite3_int
1b0d0 65 72 72 75 70 74 28 44 29 20 74 68 61 74 20 6f  errupt(D) that o
1b0e0 63 63 75 72 73 20 77 68 65 6e 20 74 68 65 72 65  ccurs when there
1b0f0 20 61 72 65 20 6e 6f 20 72 75 6e 6e 69 6e 67 0a   are no running.
1b100 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
1b110 73 20 69 73 20 61 20 6e 6f 2d 6f 70 20 61 6e 64  s is a no-op and
1b120 20 68 61 73 20 6e 6f 20 65 66 66 65 63 74 20 6f   has no effect o
1b130 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  n SQL statements
1b140 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61  .** that are sta
1b150 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20 73  rted after the s
1b160 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
1b170 28 29 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e  () call returns.
1b180 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 64 61  .**.** If the da
1b190 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1b1a0 6e 20 63 6c 6f 73 65 73 20 77 68 69 6c 65 20 5b  n closes while [
1b1b0 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
1b1c0 74 28 29 5d 0a 2a 2a 20 69 73 20 72 75 6e 6e 69  t()].** is runni
1b1d0 6e 67 20 74 68 65 6e 20 62 61 64 20 74 68 69 6e  ng then bad thin
1b1e0 67 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 68  gs will likely h
1b1f0 61 70 70 65 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45  appen..*/.SQLITE
1b200 5f 41 50 49 20 76 6f 69 64 20 53 51 4c 49 54 45  _API void SQLITE
1b210 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
1b220 5f 69 6e 74 65 72 72 75 70 74 28 73 71 6c 69 74  _interrupt(sqlit
1b230 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
1b240 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65  I3REF: Determine
1b250 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65   If An SQL State
1b260 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74 65  ment Is Complete
1b270 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
1b280 74 69 6e 65 73 20 61 72 65 20 75 73 65 66 75 6c  tines are useful
1b290 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d   during command-
1b2a0 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f 20 64 65  line input to de
1b2b0 74 65 72 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a  termine if the.*
1b2c0 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65  * currently ente
1b2d0 72 65 64 20 74 65 78 74 20 73 65 65 6d 73 20 74  red text seems t
1b2e0 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c 65 74  o form a complet
1b2f0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
1b300 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74 69 6f  or.** if additio
1b310 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e 65 65  nal input is nee
1b320 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e 64 69  ded before sendi
1b330 6e 67 20 74 68 65 20 74 65 78 74 20 69 6e 74 6f  ng the text into
1b340 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72 20 70  .** SQLite for p
1b350 61 72 73 69 6e 67 2e 20 20 5e 54 68 65 73 65 20  arsing.  ^These 
1b360 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
1b370 31 20 69 66 20 74 68 65 20 69 6e 70 75 74 20 73  1 if the input s
1b380 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73  tring.** appears
1b390 20 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65 74   to be a complet
1b3a0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  e SQL statement.
1b3b0 20 20 5e 41 20 73 74 61 74 65 6d 65 6e 74 20 69    ^A statement i
1b3c0 73 20 6a 75 64 67 65 64 20 74 6f 20 62 65 0a 2a  s judged to be.*
1b3d0 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 20 69 74  * complete if it
1b3e0 20 65 6e 64 73 20 77 69 74 68 20 61 20 73 65 6d   ends with a sem
1b3f0 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64  icolon token and
1b400 20 69 73 20 6e 6f 74 20 61 20 70 72 65 66 69 78   is not a prefix
1b410 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f   of a.** well-fo
1b420 72 6d 65 64 20 43 52 45 41 54 45 20 54 52 49 47  rmed CREATE TRIG
1b430 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  GER statement.  
1b440 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74  ^Semicolons that
1b450 20 61 72 65 20 65 6d 62 65 64 64 65 64 20 77 69   are embedded wi
1b460 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c  thin.** string l
1b470 69 74 65 72 61 6c 73 20 6f 72 20 71 75 6f 74 65  iterals or quote
1b480 64 20 69 64 65 6e 74 69 66 69 65 72 20 6e 61 6d  d identifier nam
1b490 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61  es or comments a
1b4a0 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65  re not.** indepe
1b4b0 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68  ndent tokens (th
1b4c0 65 79 20 61 72 65 20 70 61 72 74 20 6f 66 20 74  ey are part of t
1b4d0 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63  he token in whic
1b4e0 68 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d  h they are.** em
1b4f0 62 65 64 64 65 64 29 20 61 6e 64 20 74 68 75 73  bedded) and thus
1b500 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73   do not count as
1b510 20 61 20 73 74 61 74 65 6d 65 6e 74 20 74 65 72   a statement ter
1b520 6d 69 6e 61 74 6f 72 2e 20 20 5e 57 68 69 74 65  minator.  ^White
1b530 73 70 61 63 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d  space.** and com
1b540 6d 65 6e 74 73 20 74 68 61 74 20 66 6f 6c 6c 6f  ments that follo
1b550 77 20 74 68 65 20 66 69 6e 61 6c 20 73 65 6d 69  w the final semi
1b560 63 6f 6c 6f 6e 20 61 72 65 20 69 67 6e 6f 72 65  colon are ignore
1b570 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  d..**.** ^These 
1b580 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
1b590 30 20 69 66 20 74 68 65 20 73 74 61 74 65 6d 65  0 if the stateme
1b5a0 6e 74 20 69 73 20 69 6e 63 6f 6d 70 6c 65 74 65  nt is incomplete
1b5b0 2e 20 20 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f  .  ^If a.** memo
1b5c0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61  ry allocation fa
1b5d0 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c 49 54 45  ils, then SQLITE
1b5e0 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74 75 72 6e  _NOMEM is return
1b5f0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  ed..**.** ^These
1b600 20 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74   routines do not
1b610 20 70 61 72 73 65 20 74 68 65 20 53 51 4c 20 73   parse the SQL s
1b620 74 61 74 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a  tatements thus.*
1b630 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63  * will not detec
1b640 74 20 73 79 6e 74 61 63 74 69 63 61 6c 6c 79 20  t syntactically 
1b650 69 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a  incorrect SQL..*
1b660 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c 69 74 65  *.** ^(If SQLite
1b670 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 69 6e   has not been in
1b680 69 74 69 61 6c 69 7a 65 64 20 75 73 69 6e 67 20  itialized using 
1b690 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c  [sqlite3_initial
1b6a0 69 7a 65 28 29 5d 20 70 72 69 6f 72 20 0a 2a 2a  ize()] prior .**
1b6b0 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20 73 71 6c   to invoking sql
1b6c0 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
1b6d0 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 69  ) then sqlite3_i
1b6e0 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69  nitialize() is i
1b6f0 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d 61  nvoked.** automa
1b700 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74  tically by sqlit
1b710 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 2e  e3_complete16().
1b720 20 20 49 66 20 74 68 61 74 20 69 6e 69 74 69 61    If that initia
1b730 6c 69 7a 61 74 69 6f 6e 20 66 61 69 6c 73 2c 0a  lization fails,.
1b740 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74 75  ** then the retu
1b750 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71  rn value from sq
1b760 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
1b770 28 29 20 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a  () will be non-z
1b780 65 72 6f 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73  ero.** regardles
1b790 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  s of whether or 
1b7a0 6e 6f 74 20 74 68 65 20 69 6e 70 75 74 20 53 51  not the input SQ
1b7b0 4c 20 69 73 20 63 6f 6d 70 6c 65 74 65 2e 29 5e  L is complete.)^
1b7c0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74  .**.** The input
1b7d0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d   to [sqlite3_com
1b7e0 70 6c 65 74 65 28 29 5d 20 6d 75 73 74 20 62 65  plete()] must be
1b7f0 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
1b800 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73 74 72 69  ed.** UTF-8 stri
1b810 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e  ng..**.** The in
1b820 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  put to [sqlite3_
1b830 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d 75  complete16()] mu
1b840 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72  st be a zero-ter
1b850 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31  minated.** UTF-1
1b860 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69  6 string in nati
1b870 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a  ve byte order..*
1b880 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
1b890 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
1b8a0 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
1b8b0 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  (const char *sql
1b8c0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
1b8d0 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
1b8e0 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
1b8f0 65 31 36 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a  e16(const void *
1b900 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  sql);../*.** CAP
1b910 49 33 52 45 46 3a 20 52 65 67 69 73 74 65 72 20  I3REF: Register 
1b920 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61  A Callback To Ha
1b930 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42 55 53 59  ndle SQLITE_BUSY
1b940 20 45 72 72 6f 72 73 0a 2a 2a 20 4b 45 59 57 4f   Errors.** KEYWO
1b950 52 44 53 3a 20 7b 62 75 73 79 2d 68 61 6e 64 6c  RDS: {busy-handl
1b960 65 72 20 63 61 6c 6c 62 61 63 6b 7d 20 7b 62 75  er callback} {bu
1b970 73 79 20 68 61 6e 64 6c 65 72 7d 0a 2a 2a 0a 2a  sy handler}.**.*
1b980 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62  * ^The sqlite3_b
1b990 75 73 79 5f 68 61 6e 64 6c 65 72 28 44 2c 58 2c  usy_handler(D,X,
1b9a0 50 29 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20  P) routine sets 
1b9b0 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  a callback funct
1b9c0 69 6f 6e 20 58 0a 2a 2a 20 74 68 61 74 20 6d 69  ion X.** that mi
1b9d0 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77  ght be invoked w
1b9e0 69 74 68 20 61 72 67 75 6d 65 6e 74 20 50 20 77  ith argument P w
1b9f0 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74  henever.** an at
1ba00 74 65 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f  tempt is made to
1ba10 20 61 63 63 65 73 73 20 61 20 64 61 74 61 62 61   access a databa
1ba20 73 65 20 74 61 62 6c 65 20 61 73 73 6f 63 69 61  se table associa
1ba30 74 65 64 20 77 69 74 68 0a 2a 2a 20 5b 64 61 74  ted with.** [dat
1ba40 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1ba50 5d 20 44 20 77 68 65 6e 20 61 6e 6f 74 68 65 72  ] D when another
1ba60 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72   thread.** or pr
1ba70 6f 63 65 73 73 20 68 61 73 20 74 68 65 20 74 61  ocess has the ta
1ba80 62 6c 65 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 20 54  ble locked..** T
1ba90 68 65 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  he sqlite3_busy_
1baa0 68 61 6e 64 6c 65 72 28 29 20 69 6e 74 65 72 66  handler() interf
1bab0 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 69  ace is used to i
1bac0 6d 70 6c 65 6d 65 6e 74 0a 2a 2a 20 5b 73 71 6c  mplement.** [sql
1bad0 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
1bae0 74 28 29 5d 20 61 6e 64 20 5b 50 52 41 47 4d 41  t()] and [PRAGMA
1baf0 20 62 75 73 79 5f 74 69 6d 65 6f 75 74 5d 2e 0a   busy_timeout]..
1bb00 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 62 75  **.** ^If the bu
1bb10 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e  sy callback is N
1bb20 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54  ULL, then [SQLIT
1bb30 45 5f 42 55 53 59 5d 0a 2a 2a 20 69 73 20 72 65  E_BUSY].** is re
1bb40 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65  turned immediate
1bb50 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65  ly upon encounte
1bb60 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20 20  ring the lock.  
1bb70 5e 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c  ^If the busy cal
1bb80 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20  lback.** is not 
1bb90 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 63  NULL, then the c
1bba0 61 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 62 65  allback might be
1bbb0 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 77   invoked with tw
1bbc0 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a  o arguments..**.
1bbd0 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
1bbe0 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 62 75  gument to the bu
1bbf0 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 61 20  sy handler is a 
1bc00 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64  copy of the void
1bc10 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 0a  * pointer which.
1bc20 2a 2a 20 69 73 20 74 68 65 20 74 68 69 72 64 20  ** is the third 
1bc30 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
1bc40 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
1bc50 28 29 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64  ().  ^The second
1bc60 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
1bc70 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
1bc80 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65   callback is the
1bc90 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73   number of times
1bca0 20 74 68 61 74 20 74 68 65 20 62 75 73 79 20 68   that the busy h
1bcb0 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65  andler has.** be
1bcc0 65 6e 20 69 6e 76 6f 6b 65 64 20 70 72 65 76 69  en invoked previ
1bcd0 6f 75 73 6c 79 20 66 6f 72 20 74 68 65 20 73 61  ously for the sa
1bce0 6d 65 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74  me locking event
1bcf0 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 62 75  .  ^If the.** bu
1bd00 73 79 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  sy callback retu
1bd10 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61  rns 0, then no a
1bd20 64 64 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70  dditional attemp
1bd30 74 73 20 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a  ts are made to.*
1bd40 2a 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74  * access the dat
1bd50 61 62 61 73 65 20 61 6e 64 20 5b 53 51 4c 49 54  abase and [SQLIT
1bd60 45 5f 42 55 53 59 5d 20 69 73 20 72 65 74 75 72  E_BUSY] is retur
1bd70 6e 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 61 70  ned.** to the ap
1bd80 70 6c 69 63 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49  plication..** ^I
1bd90 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  f the callback r
1bda0 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  eturns non-zero,
1bdb0 20 74 68 65 6e 20 61 6e 6f 74 68 65 72 20 61 74   then another at
1bdc0 74 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65  tempt.** is made
1bdd0 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 64   to access the d
1bde0 61 74 61 62 61 73 65 20 61 6e 64 20 74 68 65 20  atabase and the 
1bdf0 63 79 63 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a  cycle repeats..*
1be00 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73 65 6e 63  *.** The presenc
1be10 65 20 6f 66 20 61 20 62 75 73 79 20 68 61 6e 64  e of a busy hand
1be20 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20 67 75 61  ler does not gua
1be30 72 61 6e 74 65 65 20 74 68 61 74 20 69 74 20 77  rantee that it w
1be40 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a  ill be invoked.*
1be50 2a 20 77 68 65 6e 20 74 68 65 72 65 20 69 73 20  * when there is 
1be60 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e  lock contention.
1be70 20 5e 49 66 20 53 51 4c 69 74 65 20 64 65 74 65   ^If SQLite dete
1be80 72 6d 69 6e 65 73 20 74 68 61 74 20 69 6e 76 6f  rmines that invo
1be90 6b 69 6e 67 20 74 68 65 20 62 75 73 79 0a 2a 2a  king the busy.**
1bea0 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72   handler could r
1beb0 65 73 75 6c 74 20 69 6e 20 61 20 64 65 61 64 6c  esult in a deadl
1bec0 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f 20  ock, it will go 
1bed0 61 68 65 61 64 20 61 6e 64 20 72 65 74 75 72 6e  ahead and return
1bee0 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a   [SQLITE_BUSY].*
1bef0 2a 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61  * to the applica
1bf00 74 69 6f 6e 20 69 6e 73 74 65 61 64 20 6f 66 20  tion instead of 
1bf10 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 0a 2a 2a  invoking the .**
1bf20 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a   busy handler..*
1bf30 2a 20 43 6f 6e 73 69 64 65 72 20 61 20 73 63 65  * Consider a sce
1bf40 6e 61 72 69 6f 20 77 68 65 72 65 20 6f 6e 65 20  nario where one 
1bf50 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69  process is holdi
1bf60 6e 67 20 61 20 72 65 61 64 20 6c 6f 63 6b 20 74  ng a read lock t
1bf70 68 61 74 0a 2a 2a 20 69 74 20 69 73 20 74 72 79  hat.** it is try
1bf80 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74  ing to promote t
1bf90 6f 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63  o a reserved loc
1bfa0 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e  k and.** a secon
1bfb0 64 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c  d process is hol
1bfc0 64 69 6e 67 20 61 20 72 65 73 65 72 76 65 64 20  ding a reserved 
1bfd0 6c 6f 63 6b 20 74 68 61 74 20 69 74 20 69 73 20  lock that it is 
1bfe0 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f  trying.** to pro
1bff0 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78 63 6c 75  mote to an exclu
1c000 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20  sive lock.  The 
1c010 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 63 61  first process ca
1c020 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20  nnot proceed.** 
1c030 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c  because it is bl
1c040 6f 63 6b 65 64 20 62 79 20 74 68 65 20 73 65 63  ocked by the sec
1c050 6f 6e 64 20 61 6e 64 20 74 68 65 20 73 65 63 6f  ond and the seco
1c060 6e 64 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f  nd process canno
1c070 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62 65 63  t.** proceed bec
1c080 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b  ause it is block
1c090 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 2e  ed by the first.
1c0a0 20 20 49 66 20 62 6f 74 68 20 70 72 6f 63 65 73    If both proces
1c0b0 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68  ses.** invoke th
1c0c0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2c  e busy handlers,
1c0d0 20 6e 65 69 74 68 65 72 20 77 69 6c 6c 20 6d 61   neither will ma
1c0e0 6b 65 20 61 6e 79 20 70 72 6f 67 72 65 73 73 2e  ke any progress.
1c0f0 20 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20    Therefore,.** 
1c100 53 51 4c 69 74 65 20 72 65 74 75 72 6e 73 20 5b  SQLite returns [
1c110 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f 72  SQLITE_BUSY] for
1c120 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65   the first proce
1c130 73 73 2c 20 68 6f 70 69 6e 67 20 74 68 61 74 20  ss, hoping that 
1c140 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64  this.** will ind
1c150 75 63 65 20 74 68 65 20 66 69 72 73 74 20 70 72  uce the first pr
1c160 6f 63 65 73 73 20 74 6f 20 72 65 6c 65 61 73 65  ocess to release
1c170 20 69 74 73 20 72 65 61 64 20 6c 6f 63 6b 20 61   its read lock a
1c180 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20  nd allow.** the 
1c190 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 74  second process t
1c1a0 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a  o proceed..**.**
1c1b0 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 62 75   ^The default bu
1c1c0 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e  sy callback is N
1c1d0 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ULL..**.** ^(The
1c1e0 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61  re can only be a
1c1f0 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e   single busy han
1c200 64 6c 65 72 20 64 65 66 69 6e 65 64 20 66 6f 72  dler defined for
1c210 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61   each.** [databa
1c220 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20  se connection]. 
1c230 20 53 65 74 74 69 6e 67 20 61 20 6e 65 77 20 62   Setting a new b
1c240 75 73 79 20 68 61 6e 64 6c 65 72 20 63 6c 65 61  usy handler clea
1c250 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f  rs any.** previo
1c260 75 73 6c 79 20 73 65 74 20 68 61 6e 64 6c 65 72  usly set handler
1c270 2e 29 5e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20  .)^  ^Note that 
1c280 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
1c290 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d  _busy_timeout()]
1c2a0 0a 2a 2a 20 6f 72 20 65 76 61 6c 75 61 74 69 6e  .** or evaluatin
1c2b0 67 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f 74  g [PRAGMA busy_t
1c2c0 69 6d 65 6f 75 74 3d 4e 5d 20 77 69 6c 6c 20 63  imeout=N] will c
1c2d0 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 62 75 73  hange the.** bus
1c2e0 79 20 68 61 6e 64 6c 65 72 20 61 6e 64 20 74 68  y handler and th
1c2f0 75 73 20 63 6c 65 61 72 20 61 6e 79 20 70 72 65  us clear any pre
1c300 76 69 6f 75 73 6c 79 20 73 65 74 20 62 75 73 79  viously set busy
1c310 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20   handler..**.** 
1c320 54 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63  The busy callbac
1c330 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b  k should not tak
1c340 65 20 61 6e 79 20 61 63 74 69 6f 6e 73 20 77 68  e any actions wh
1c350 69 63 68 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a  ich modify the.*
1c360 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
1c370 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b  ction that invok
1c380 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ed the busy hand
1c390 6c 65 72 2e 20 20 49 6e 20 6f 74 68 65 72 20 77  ler.  In other w
1c3a0 6f 72 64 73 2c 0a 2a 2a 20 74 68 65 20 62 75 73  ords,.** the bus
1c3b0 79 20 68 61 6e 64 6c 65 72 20 69 73 20 6e 6f 74  y handler is not
1c3c0 20 72 65 65 6e 74 72 61 6e 74 2e 20 20 41 6e 79   reentrant.  Any
1c3d0 20 73 75 63 68 20 61 63 74 69 6f 6e 73 0a 2a 2a   such actions.**
1c3e0 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66   result in undef
1c3f0 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a  ined behavior..*
1c400 2a 20 0a 2a 2a 20 41 20 62 75 73 79 20 68 61 6e  * .** A busy han
1c410 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c  dler must not cl
1c420 6f 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65  ose the database
1c430 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f   connection.** o
1c440 72 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  r [prepared stat
1c450 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f  ement] that invo
1c460 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e  ked the busy han
1c470 64 6c 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  dler..*/.SQLITE_
1c480 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  API int SQLITE_S
1c490 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62  TDCALL sqlite3_b
1c4a0 75 73 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69  usy_handler(sqli
1c4b0 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69  te3*, int(*)(voi
1c4c0 64 2a 2c 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b  d*,int), void*);
1c4d0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1c4e0 3a 20 53 65 74 20 41 20 42 75 73 79 20 54 69 6d  : Set A Busy Tim
1c4f0 65 6f 75 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  eout.**.** ^This
1c500 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20   routine sets a 
1c510 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61  [sqlite3_busy_ha
1c520 6e 64 6c 65 72 20 7c 20 62 75 73 79 20 68 61 6e  ndler | busy han
1c530 64 6c 65 72 5d 20 74 68 61 74 20 73 6c 65 65 70  dler] that sleep
1c540 73 0a 2a 2a 20 66 6f 72 20 61 20 73 70 65 63 69  s.** for a speci
1c550 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74  fied amount of t
1c560 69 6d 65 20 77 68 65 6e 20 61 20 74 61 62 6c 65  ime when a table
1c570 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20 5e 54 68   is locked.  ^Th
1c580 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c  e handler.** wil
1c590 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65  l sleep multiple
1c5a0 20 74 69 6d 65 73 20 75 6e 74 69 6c 20 61 74 20   times until at 
1c5b0 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69  least "ms" milli
1c5c0 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70  seconds of sleep
1c5d0 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61 63 63 75  ing.** have accu
1c5e0 6d 75 6c 61 74 65 64 2e 20 20 5e 41 66 74 65 72  mulated.  ^After
1c5f0 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d   at least "ms" m
1c600 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73  illiseconds of s
1c610 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20  leeping,.** the 
1c620 68 61 6e 64 6c 65 72 20 72 65 74 75 72 6e 73 20  handler returns 
1c630 30 20 77 68 69 63 68 20 63 61 75 73 65 73 20 5b  0 which causes [
1c640 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1c650 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51  to return.** [SQ
1c660 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 0a 2a  LITE_BUSY]..**.*
1c670 2a 20 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73 20  * ^Calling this 
1c680 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 6e 20  routine with an 
1c690 61 72 67 75 6d 65 6e 74 20 6c 65 73 73 20 74 68  argument less th
1c6a0 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a  an or equal to z
1c6b0 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66  ero.** turns off
1c6c0 20 61 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c 65   all busy handle
1c6d0 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72  rs..**.** ^(Ther
1c6e0 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20  e can only be a 
1c6f0 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64  single busy hand
1c700 6c 65 72 20 66 6f 72 20 61 20 70 61 72 74 69 63  ler for a partic
1c710 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73  ular.** [databas
1c720 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74  e connection] at
1c730 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e   any given momen
1c740 74 2e 20 20 49 66 20 61 6e 6f 74 68 65 72 20 62  t.  If another b
1c750 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77  usy handler.** w
1c760 61 73 20 64 65 66 69 6e 65 64 20 20 28 75 73 69  as defined  (usi
1c770 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  ng [sqlite3_busy
1c780 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20 70 72 69  _handler()]) pri
1c790 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a  or to calling.**
1c7a0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 74   this routine, t
1c7b0 68 61 74 20 6f 74 68 65 72 20 62 75 73 79 20 68  hat other busy h
1c7c0 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 61 72 65  andler is cleare
1c7d0 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  d.)^.**.** See a
1c7e0 6c 73 6f 3a 20 20 5b 50 52 41 47 4d 41 20 62 75  lso:  [PRAGMA bu
1c7f0 73 79 5f 74 69 6d 65 6f 75 74 5d 0a 2a 2f 0a 53  sy_timeout].*/.S
1c800 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51  QLITE_API int SQ
1c810 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
1c820 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
1c830 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20  t(sqlite3*, int 
1c840 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ms);../*.** CAPI
1c850 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63  3REF: Convenienc
1c860 65 20 52 6f 75 74 69 6e 65 73 20 46 6f 72 20 52  e Routines For R
1c870 75 6e 6e 69 6e 67 20 51 75 65 72 69 65 73 0a 2a  unning Queries.*
1c880 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20 6c  *.** This is a l
1c890 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 20  egacy interface 
1c8a0 74 68 61 74 20 69 73 20 70 72 65 73 65 72 76 65  that is preserve
1c8b0 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20  d for backwards 
1c8c0 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a  compatibility..*
1c8d0 2a 20 55 73 65 20 6f 66 20 74 68 69 73 20 69 6e  * Use of this in
1c8e0 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 72  terface is not r
1c8f0 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a  ecommended..**.*
1c900 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20  * Definition: A 
1c910 3c 62 3e 72 65 73 75 6c 74 20 74 61 62 6c 65 3c  <b>result table<
1c920 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64 61  /b> is memory da
1c930 74 61 20 73 74 72 75 63 74 75 72 65 20 63 72 65  ta structure cre
1c940 61 74 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b  ated by the.** [
1c950 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
1c960 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20  e()] interface. 
1c970 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
1c980 72 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63  records the.** c
1c990 6f 6d 70 6c 65 74 65 20 71 75 65 72 79 20 72 65  omplete query re
1c9a0 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f  sults from one o
1c9b0 72 20 6d 6f 72 65 20 71 75 65 72 69 65 73 2e 0a  r more queries..
1c9c0 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20  **.** The table 
1c9d0 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68 61 73  conceptually has
1c9e0 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77   a number of row
1c9f0 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20  s and columns.  
1ca00 42 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d  But.** these num
1ca10 62 65 72 73 20 61 72 65 20 6e 6f 74 20 70 61 72  bers are not par
1ca20 74 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  t of the result 
1ca30 74 61 62 6c 65 20 69 74 73 65 6c 66 2e 20 20 54  table itself.  T
1ca40 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20  hese.** numbers 
1ca50 61 72 65 20 6f 62 74 61 69 6e 65 64 20 73 65 70  are obtained sep
1ca60 61 72 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20  arately.  Let N 
1ca70 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  be the number of
1ca80 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62   rows.** and M b
1ca90 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  e the number of 
1caa0 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41  columns..**.** A
1cab0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73   result table is
1cac0 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
1cad0 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65  nters to zero-te
1cae0 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73  rminated UTF-8 s
1caf0 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 65  trings..** There
1cb00 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65   are (N+1)*M ele
1cb10 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 61 72 72  ments in the arr
1cb20 61 79 2e 20 20 54 68 65 20 66 69 72 73 74 20 4d  ay.  The first M
1cb30 20 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74 0a   pointers point.
1cb40 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69  ** to zero-termi
1cb50 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68  nated strings th
1cb60 61 74 20 20 63 6f 6e 74 61 69 6e 20 74 68 65 20  at  contain the 
1cb70 6e 61 6d 65 73 20 6f 66 20 74 68 65 20 63 6f 6c  names of the col
1cb80 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d  umns..** The rem
1cb90 61 69 6e 69 6e 67 20 65 6e 74 72 69 65 73 20 61  aining entries a
1cba0 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75 65 72  ll point to quer
1cbb0 79 20 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c  y results.  NULL
1cbc0 20 76 61 6c 75 65 73 20 72 65 73 75 6c 74 0a 2a   values result.*
1cbd0 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  * in NULL pointe
1cbe0 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 76  rs.  All other v
1cbf0 61 6c 75 65 73 20 61 72 65 20 69 6e 20 74 68 65  alues are in the
1cc00 69 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65  ir UTF-8 zero-te
1cc10 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69  rminated.** stri
1cc20 6e 67 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f  ng representatio
1cc30 6e 20 61 73 20 72 65 74 75 72 6e 65 64 20 62 79  n as returned by
1cc40 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
1cc50 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _text()]..**.** 
1cc60 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 6d  A result table m
1cc70 69 67 68 74 20 63 6f 6e 73 69 73 74 20 6f 66 20  ight consist of 
1cc80 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f  one or more memo
1cc90 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a  ry allocations..
1cca0 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66  ** It is not saf
1ccb0 65 20 74 6f 20 70 61 73 73 20 61 20 72 65 73 75  e to pass a resu
1ccc0 6c 74 20 74 61 62 6c 65 20 64 69 72 65 63 74 6c  lt table directl
1ccd0 79 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72  y to [sqlite3_fr
1cce0 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75  ee()]..** A resu
1ccf0 6c 74 20 74 61 62 6c 65 20 73 68 6f 75 6c 64 20  lt table should 
1cd00 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 75  be deallocated u
1cd10 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72  sing [sqlite3_fr
1cd20 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a  ee_table()]..**.
1cd30 2a 2a 20 5e 28 41 73 20 61 6e 20 65 78 61 6d 70  ** ^(As an examp
1cd40 6c 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  le of the result
1cd50 20 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c 20 73   table format, s
1cd60 75 70 70 6f 73 65 20 61 20 71 75 65 72 79 20 72  uppose a query r
1cd70 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73 20 66  esult.** is as f
1cd80 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ollows:.**.** <b
1cd90 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
1cda0 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d 65 20 20  **        Name  
1cdb0 20 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20        | Age.**  
1cdc0 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d        ----------
1cdd0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a  -------------.**
1cde0 20 20 20 20 20 20 20 20 41 6c 69 63 65 20 20 20          Alice   
1cdf0 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20      | 43.**     
1ce00 20 20 20 42 6f 62 20 20 20 20 20 20 20 20 20 7c     Bob         |
1ce10 20 32 38 0a 2a 2a 20 20 20 20 20 20 20 20 43 69   28.**        Ci
1ce20 6e 64 79 20 20 20 20 20 20 20 7c 20 32 31 0a 2a  ndy       | 21.*
1ce30 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
1ce40 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72  uote>.**.** Ther
1ce50 65 20 61 72 65 20 74 77 6f 20 63 6f 6c 75 6d 6e  e are two column
1ce60 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68 72 65   (M==2) and thre
1ce70 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 20  e rows (N==3).  
1ce80 54 68 75 73 20 74 68 65 0a 2a 2a 20 72 65 73 75  Thus the.** resu
1ce90 6c 74 20 74 61 62 6c 65 20 68 61 73 20 38 20 65  lt table has 8 e
1cea0 6e 74 72 69 65 73 2e 20 20 53 75 70 70 6f 73 65  ntries.  Suppose
1ceb0 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
1cec0 65 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69  e is stored.** i
1ced0 6e 20 61 6e 20 61 72 72 61 79 20 6e 61 6d 65 73  n an array names
1cee0 20 61 7a 52 65 73 75 6c 74 2e 20 20 54 68 65 6e   azResult.  Then
1cef0 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64 73 20   azResult holds 
1cf00 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a  this content:.**
1cf10 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
1cf20 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20  <pre>.**        
1cf30 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 30 5d 20  azResult&#91;0] 
1cf40 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 20  = "Name";.**    
1cf50 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
1cf60 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20  ;1] = "Age";.** 
1cf70 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
1cf80 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65 22  #91;2] = "Alice"
1cf90 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
1cfa0 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22 34  sult&#91;3] = "4
1cfb0 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  3";.**        az
1cfc0 52 65 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d 20  Result&#91;4] = 
1cfd0 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20 20  "Bob";.**       
1cfe0 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 35 5d   azResult&#91;5]
1cff0 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20   = "28";.**     
1d000 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
1d010 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a  6] = "Cindy";.**
1d020 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
1d030 26 23 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b 0a  &#91;7] = "21";.
1d040 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
1d050 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  quote>)^.**.** ^
1d060 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
1d070 74 61 62 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e  table() function
1d080 20 65 76 61 6c 75 61 74 65 73 20 6f 6e 65 20 6f   evaluates one o
1d090 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 6f  r more.** semico
1d0a0 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 20 53 51  lon-separated SQ
1d0b0 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20  L statements in 
1d0c0 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  the zero-termina
1d0d0 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72  ted UTF-8.** str
1d0e0 69 6e 67 20 6f 66 20 69 74 73 20 32 6e 64 20 70  ing of its 2nd p
1d0f0 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74  arameter and ret
1d100 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20 74 61  urns a result ta
1d110 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20 70 6f  ble to the.** po
1d120 69 6e 74 65 72 20 67 69 76 65 6e 20 69 6e 20 69  inter given in i
1d130 74 73 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  ts 3rd parameter
1d140 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68  ..**.** After th
1d150 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 68 61  e application ha
1d160 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20  s finished with 
1d170 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 20  the result from 
1d180 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
1d190 65 28 29 2c 0a 2a 2a 20 69 74 20 6d 75 73 74 20  e(),.** it must 
1d1a0 70 61 73 73 20 74 68 65 20 72 65 73 75 6c 74 20  pass the result 
1d1b0 74 61 62 6c 65 20 70 6f 69 6e 74 65 72 20 74 6f  table pointer to
1d1c0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61   sqlite3_free_ta
1d1d0 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 72 20 74  ble() in order t
1d1e0 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74 68 65  o.** release the
1d1f0 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 77 61 73   memory that was
1d200 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61   malloced.  Beca
1d210 75 73 65 20 6f 66 20 74 68 65 20 77 61 79 20 74  use of the way t
1d220 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  he.** [sqlite3_m
1d230 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e 73  alloc()] happens
1d240 20 77 69 74 68 69 6e 20 73 71 6c 69 74 65 33 5f   within sqlite3_
1d250 67 65 74 5f 74 61 62 6c 65 28 29 2c 20 74 68 65  get_table(), the
1d260 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63   calling.** func
1d270 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72  tion must not tr
1d280 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74  y to call [sqlit
1d290 65 33 5f 66 72 65 65 28 29 5d 20 64 69 72 65 63  e3_free()] direc
1d2a0 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73  tly.  Only.** [s
1d2b0 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c  qlite3_free_tabl
1d2c0 65 28 29 5d 20 69 73 20 61 62 6c 65 20 74 6f 20  e()] is able to 
1d2d0 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f  release the memo
1d2e0 72 79 20 70 72 6f 70 65 72 6c 79 20 61 6e 64 20  ry properly and 
1d2f0 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68  safely..**.** Th
1d300 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  e sqlite3_get_ta
1d310 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  ble() interface 
1d320 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61  is implemented a
1d330 73 20 61 20 77 72 61 70 70 65 72 20 61 72 6f 75  s a wrapper arou
1d340 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  nd.** [sqlite3_e
1d350 78 65 63 28 29 5d 2e 20 20 54 68 65 20 73 71 6c  xec()].  The sql
1d360 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
1d370 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f   routine does no
1d380 74 20 68 61 76 65 20 61 63 63 65 73 73 0a 2a 2a  t have access.**
1d390 20 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c   to any internal
1d3a0 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65 73   data structures
1d3b0 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 49 74 20   of SQLite.  It 
1d3c0 75 73 65 73 20 6f 6e 6c 79 20 74 68 65 20 70 75  uses only the pu
1d3d0 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63  blic.** interfac
1d3e0 65 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 20  e defined here. 
1d3f0 20 41 73 20 61 20 63 6f 6e 73 65 71 75 65 6e 63   As a consequenc
1d400 65 2c 20 65 72 72 6f 72 73 20 74 68 61 74 20 6f  e, errors that o
1d410 63 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77  ccur in the.** w
1d420 72 61 70 70 65 72 20 6c 61 79 65 72 20 6f 75 74  rapper layer out
1d430 73 69 64 65 20 6f 66 20 74 68 65 20 69 6e 74 65  side of the inte
1d440 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78  rnal [sqlite3_ex
1d450 65 63 28 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e  ec()] call are n
1d460 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64 20  ot.** reflected 
1d470 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  in subsequent ca
1d480 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
1d490 65 72 72 63 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a  errcode()] or.**
1d4a0 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
1d4b0 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ()]..*/.SQLITE_A
1d4c0 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54  PI int SQLITE_ST
1d4d0 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 67 65  DCALL sqlite3_ge
1d4e0 74 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c 69 74  t_table(.  sqlit
1d4f0 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
1d500 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61   /* An open data
1d510 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  base */.  const 
1d520 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20  char *zSql,     
1d530 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61  /* SQL to be eva
1d540 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63 68 61 72  luated */.  char
1d550 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20   ***pazResult,  
1d560 20 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66 20    /* Results of 
1d570 74 68 65 20 71 75 65 72 79 20 2a 2f 0a 20 20 69  the query */.  i
1d580 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20  nt *pnRow,      
1d590 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f       /* Number o
1d5a0 66 20 72 65 73 75 6c 74 20 72 6f 77 73 20 77 72  f result rows wr
1d5b0 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20  itten here */.  
1d5c0 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20  int *pnColumn,  
1d5d0 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20        /* Number 
1d5e0 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  of result column
1d5f0 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a  s written here *
1d600 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72  /.  char **pzErr
1d610 6d 73 67 20 20 20 20 20 20 20 2f 2a 20 45 72 72  msg       /* Err
1d620 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68  or msg written h
1d630 65 72 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45  ere */.);.SQLITE
1d640 5f 41 50 49 20 76 6f 69 64 20 53 51 4c 49 54 45  _API void SQLITE
1d650 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
1d660 5f 66 72 65 65 5f 74 61 62 6c 65 28 63 68 61 72  _free_table(char
1d670 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a   **result);../*.
1d680 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6f 72  ** CAPI3REF: For
1d690 6d 61 74 74 65 64 20 53 74 72 69 6e 67 20 50 72  matted String Pr
1d6a0 69 6e 74 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73  inting Functions
1d6b0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
1d6c0 74 69 6e 65 73 20 61 72 65 20 77 6f 72 6b 2d 61  tines are work-a
1d6d0 6c 69 6b 65 73 20 6f 66 20 74 68 65 20 22 70 72  likes of the "pr
1d6e0 69 6e 74 66 28 29 22 20 66 61 6d 69 6c 79 20 6f  intf()" family o
1d6f0 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66  f functions.** f
1d700 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64  rom the standard
1d710 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 54   C library..** T
1d720 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 75 6e  hese routines un
1d730 64 65 72 73 74 61 6e 64 20 6d 6f 73 74 20 6f 66  derstand most of
1d740 20 74 68 65 20 63 6f 6d 6d 6f 6e 20 4b 26 52 20   the common K&R 
1d750 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f  formatting optio
1d760 6e 73 2c 0a 2a 2a 20 70 6c 75 73 20 73 6f 6d 65  ns,.** plus some
1d770 20 61 64 64 69 74 69 6f 6e 61 6c 20 6e 6f 6e 2d   additional non-
1d780 73 74 61 6e 64 61 72 64 20 66 6f 72 6d 61 74 73  standard formats
1d790 2c 20 64 65 74 61 69 6c 65 64 20 62 65 6c 6f 77  , detailed below
1d7a0 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 73  ..** Note that s
1d7b0 6f 6d 65 20 6f 66 20 74 68 65 20 6d 6f 72 65 20  ome of the more 
1d7c0 6f 62 73 63 75 72 65 20 66 6f 72 6d 61 74 74 69  obscure formatti
1d7d0 6e 67 20 6f 70 74 69 6f 6e 73 20 66 72 6f 6d 20  ng options from 
1d7e0 72 65 63 65 6e 74 0a 2a 2a 20 43 2d 6c 69 62 72  recent.** C-libr
1d7f0 61 72 79 20 73 74 61 6e 64 61 72 64 73 20 61 72  ary standards ar
1d800 65 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74  e omitted from t
1d810 68 69 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  his implementati
1d820 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  on..**.** ^The s
1d830 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29  qlite3_mprintf()
1d840 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d 70   and sqlite3_vmp
1d850 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 73  rintf() routines
1d860 20 77 72 69 74 65 20 74 68 65 69 72 0a 2a 2a 20   write their.** 
1d870 72 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d  results into mem
1d880 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
1d890 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
1d8a0 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72  c()]..** The str
1d8b0 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79  ings returned by
1d8c0 20 74 68 65 73 65 20 74 77 6f 20 72 6f 75 74 69   these two routi
1d8d0 6e 65 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a  nes should be.**
1d8e0 20 72 65 6c 65 61 73 65 64 20 62 79 20 5b 73 71   released by [sq
1d8f0 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 20 20  lite3_free()].  
1d900 5e 42 6f 74 68 20 72 6f 75 74 69 6e 65 73 20 72  ^Both routines r
1d910 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20  eturn a.** NULL 
1d920 70 6f 69 6e 74 65 72 20 69 66 20 5b 73 71 6c 69  pointer if [sqli
1d930 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73  te3_malloc()] is
1d940 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63   unable to alloc
1d950 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65  ate enough.** me
1d960 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65  mory to hold the
1d970 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e   resulting strin
1d980 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73  g..**.** ^(The s
1d990 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
1d9a0 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d  ) routine is sim
1d9b0 69 6c 61 72 20 74 6f 20 22 73 6e 70 72 69 6e 74  ilar to "snprint
1d9c0 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65  f()" from.** the
1d9d0 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72   standard C libr
1d9e0 61 72 79 2e 20 20 54 68 65 20 72 65 73 75 6c 74  ary.  The result
1d9f0 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f   is written into
1da00 20 74 68 65 0a 2a 2a 20 62 75 66 66 65 72 20 73   the.** buffer s
1da10 75 70 70 6c 69 65 64 20 61 73 20 74 68 65 20 73  upplied as the s
1da20 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
1da30 77 68 6f 73 65 20 73 69 7a 65 20 69 73 20 67 69  whose size is gi
1da40 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66 69  ven by.** the fi
1da50 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20 4e  rst parameter. N
1da60 6f 74 65 20 74 68 61 74 20 74 68 65 20 6f 72 64  ote that the ord
1da70 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72  er of the.** fir
1da80 73 74 20 74 77 6f 20 70 61 72 61 6d 65 74 65 72  st two parameter
1da90 73 20 69 73 20 72 65 76 65 72 73 65 64 20 66 72  s is reversed fr
1daa0 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e 29 5e  om snprintf().)^
1dab0 20 20 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20    This is an.** 
1dac0 68 69 73 74 6f 72 69 63 61 6c 20 61 63 63 69 64  historical accid
1dad0 65 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f 74 20  ent that cannot 
1dae0 62 65 20 66 69 78 65 64 20 77 69 74 68 6f 75 74  be fixed without
1daf0 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63   breaking.** bac
1db00 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
1db10 6c 69 74 79 2e 20 20 5e 28 4e 6f 74 65 20 61 6c  lity.  ^(Note al
1db20 73 6f 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f  so that sqlite3_
1db30 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65  snprintf().** re
1db40 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
1db50 74 6f 20 69 74 73 20 62 75 66 66 65 72 20 69 6e  to its buffer in
1db60 73 74 65 61 64 20 6f 66 20 74 68 65 20 6e 75 6d  stead of the num
1db70 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63  ber of.** charac
1db80 74 65 72 73 20 61 63 74 75 61 6c 6c 79 20 77 72  ters actually wr
1db90 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 62  itten into the b
1dba0 75 66 66 65 72 2e 29 5e 20 20 57 65 20 61 64 6d  uffer.)^  We adm
1dbb0 69 74 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e  it that.** the n
1dbc0 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74  umber of charact
1dbd0 65 72 73 20 77 72 69 74 74 65 6e 20 77 6f 75 6c  ers written woul
1dbe0 64 20 62 65 20 61 20 6d 6f 72 65 20 75 73 65 66  d be a more usef
1dbf0 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c  ul return.** val
1dc00 75 65 20 62 75 74 20 77 65 20 63 61 6e 6e 6f 74  ue but we cannot
1dc10 20 63 68 61 6e 67 65 20 74 68 65 20 69 6d 70 6c   change the impl
1dc20 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71  ementation of sq
1dc30 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
1dc40 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74 20  .** now without 
1dc50 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69  breaking compati
1dc60 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41  bility..**.** ^A
1dc70 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 62 75  s long as the bu
1dc80 66 66 65 72 20 73 69 7a 65 20 69 73 20 67 72 65  ffer size is gre
1dc90 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20  ater than zero, 
1dca0 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
1dcb0 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73  ().** guarantees
1dcc0 20 74 68 61 74 20 74 68 65 20 62 75 66 66 65 72   that the buffer
1dcd0 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d   is always zero-
1dce0 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68  terminated.  ^Th
1dcf0 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d  e first.** param
1dd00 65 74 65 72 20 22 6e 22 20 69 73 20 74 68 65 20  eter "n" is the 
1dd10 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20 74 68  total size of th
1dd20 65 20 62 75 66 66 65 72 2c 20 69 6e 63 6c 75 64  e buffer, includ
1dd30 69 6e 67 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a  ing space for.**
1dd40 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e   the zero termin
1dd50 61 74 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f  ator.  So the lo
1dd60 6e 67 65 73 74 20 73 74 72 69 6e 67 20 74 68 61  ngest string tha
1dd70 74 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74  t can be complet
1dd80 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77  ely.** written w
1dd90 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61 72 61  ill be n-1 chara
1dda0 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  cters..**.** ^Th
1ddb0 65 20 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 69  e sqlite3_vsnpri
1ddc0 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73  ntf() routine is
1ddd0 20 61 20 76 61 72 61 72 67 73 20 76 65 72 73 69   a varargs versi
1dde0 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e  on of sqlite3_sn
1ddf0 70 72 69 6e 74 66 28 29 2e 0a 2a 2a 0a 2a 2a 20  printf()..**.** 
1de00 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
1de10 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d  ll implement som
1de20 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 6f 72  e additional for
1de30 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f  matting.** optio
1de40 6e 73 20 74 68 61 74 20 61 72 65 20 75 73 65 66  ns that are usef
1de50 75 6c 20 66 6f 72 20 63 6f 6e 73 74 72 75 63 74  ul for construct
1de60 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ing SQL statemen
1de70 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 68  ts..** All of th
1de80 65 20 75 73 75 61 6c 20 70 72 69 6e 74 66 28 29  e usual printf()
1de90 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69   formatting opti
1dea0 6f 6e 73 20 61 70 70 6c 79 2e 20 20 49 6e 20 61  ons apply.  In a
1deb0 64 64 69 74 69 6f 6e 2c 20 74 68 65 72 65 0a 2a  ddition, there.*
1dec0 2a 20 69 73 20 61 72 65 20 22 25 71 22 2c 20 22  * is are "%q", "
1ded0 25 51 22 2c 20 22 25 77 22 20 61 6e 64 20 22 25  %Q", "%w" and "%
1dee0 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  z" options..**.*
1def0 2a 20 5e 28 54 68 65 20 25 71 20 6f 70 74 69 6f  * ^(The %q optio
1df00 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73 20  n works like %s 
1df10 69 6e 20 74 68 61 74 20 69 74 20 73 75 62 73 74  in that it subst
1df20 69 74 75 74 65 73 20 61 20 6e 75 6c 2d 74 65 72  itutes a nul-ter
1df30 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e  minated.** strin
1df40 67 20 66 72 6f 6d 20 74 68 65 20 61 72 67 75 6d  g from the argum
1df50 65 6e 74 20 6c 69 73 74 2e 20 20 42 75 74 20 25  ent list.  But %
1df60 71 20 61 6c 73 6f 20 64 6f 75 62 6c 65 73 20 65  q also doubles e
1df70 76 65 72 79 20 27 5c 27 27 20 63 68 61 72 61 63  very '\'' charac
1df80 74 65 72 2e 0a 2a 2a 20 25 71 20 69 73 20 64 65  ter..** %q is de
1df90 73 69 67 6e 65 64 20 66 6f 72 20 75 73 65 20 69  signed for use i
1dfa0 6e 73 69 64 65 20 61 20 73 74 72 69 6e 67 20 6c  nside a string l
1dfb0 69 74 65 72 61 6c 2e 29 5e 20 20 42 79 20 64 6f  iteral.)^  By do
1dfc0 75 62 6c 69 6e 67 20 65 61 63 68 20 27 5c 27 27  ubling each '\''
1dfd0 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 20 69 74  .** character it
1dfe0 20 65 73 63 61 70 65 73 20 74 68 61 74 20 63 68   escapes that ch
1dff0 61 72 61 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f  aracter and allo
1e000 77 73 20 69 74 20 74 6f 20 62 65 20 69 6e 73 65  ws it to be inse
1e010 72 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65  rted into.** the
1e020 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46   string..**.** F
1e030 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 73 73 75  or example, assu
1e040 6d 65 20 74 68 65 20 73 74 72 69 6e 67 20 76 61  me the string va
1e050 72 69 61 62 6c 65 20 7a 54 65 78 74 20 63 6f 6e  riable zText con
1e060 74 61 69 6e 73 20 74 65 78 74 20 61 73 20 66 6f  tains text as fo
1e070 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  llows:.**.** <bl
1e080 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
1e090 2a 20 20 63 68 61 72 20 2a 7a 54 65 78 74 20 3d  *  char *zText =
1e0a0 20 22 49 74 27 73 20 61 20 68 61 70 70 79 20 64   "It's a happy d
1e0b0 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  ay!";.** </pre><
1e0c0 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
1e0d0 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65 20 74  ** One can use t
1e0e0 68 69 73 20 74 65 78 74 20 69 6e 20 61 6e 20 53  his text in an S
1e0f0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20  QL statement as 
1e100 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c  follows:.**.** <
1e110 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
1e120 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20  .**  char *zSQL 
1e130 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74  = sqlite3_mprint
1e140 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74  f("INSERT INTO t
1e150 61 62 6c 65 20 56 41 4c 55 45 53 28 27 25 71 27  able VALUES('%q'
1e160 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20  )", zText);.**  
1e170 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c  sqlite3_exec(db,
1e180 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b   zSQL, 0, 0, 0);
1e190 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65  .**  sqlite3_fre
1e1a0 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72  e(zSQL);.** </pr
1e1b0 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
1e1c0 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68  **.** Because th
1e1d0 65 20 25 71 20 66 6f 72 6d 61 74 20 73 74 72 69  e %q format stri
1e1e0 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68 65 20  ng is used, the 
1e1f0 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 20 69  '\'' character i
1e200 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20 65 73  n zText.** is es
1e210 63 61 70 65 64 20 61 6e 64 20 74 68 65 20 53 51  caped and the SQ
1e220 4c 20 67 65 6e 65 72 61 74 65 64 20 69 73 20 61  L generated is a
1e230 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a  s follows:.**.**
1e240 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
1e250 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e  e>.**  INSERT IN
1e260 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53  TO table1 VALUES
1e270 28 27 49 74 27 27 73 20 61 20 68 61 70 70 79 20  ('It''s a happy 
1e280 64 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e  day!').** </pre>
1e290 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
1e2a0 0a 2a 2a 20 54 68 69 73 20 69 73 20 63 6f 72 72  .** This is corr
1e2b0 65 63 74 2e 20 20 48 61 64 20 77 65 20 75 73 65  ect.  Had we use
1e2c0 64 20 25 73 20 69 6e 73 74 65 61 64 20 6f 66 20  d %s instead of 
1e2d0 25 71 2c 20 74 68 65 20 67 65 6e 65 72 61 74 65  %q, the generate
1e2e0 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68  d SQL.** would h
1e2f0 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20  ave looked like 
1e300 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  this:.**.** <blo
1e310 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
1e320 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61    INSERT INTO ta
1e330 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27  ble1 VALUES('It'
1e340 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29  s a happy day!')
1e350 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
1e360 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
1e370 68 69 73 20 73 65 63 6f 6e 64 20 65 78 61 6d 70  his second examp
1e380 6c 65 20 69 73 20 61 6e 20 53 51 4c 20 73 79 6e  le is an SQL syn
1e390 74 61 78 20 65 72 72 6f 72 2e 20 20 41 73 20 61  tax error.  As a
1e3a0 20 67 65 6e 65 72 61 6c 20 72 75 6c 65 20 79 6f   general rule yo
1e3b0 75 20 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61  u should.** alwa
1e3c0 79 73 20 75 73 65 20 25 71 20 69 6e 73 74 65 61  ys use %q instea
1e3d0 64 20 6f 66 20 25 73 20 77 68 65 6e 20 69 6e 73  d of %s when ins
1e3e0 65 72 74 69 6e 67 20 74 65 78 74 20 69 6e 74 6f  erting text into
1e3f0 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61   a string litera
1e400 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25  l..**.** ^(The %
1e410 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c  Q option works l
1e420 69 6b 65 20 25 71 20 65 78 63 65 70 74 20 69 74  ike %q except it
1e430 20 61 6c 73 6f 20 61 64 64 73 20 73 69 6e 67 6c   also adds singl
1e440 65 20 71 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a  e quotes around.
1e450 2a 2a 20 74 68 65 20 6f 75 74 73 69 64 65 20 6f  ** the outside o
1e460 66 20 74 68 65 20 74 6f 74 61 6c 20 73 74 72 69  f the total stri
1e470 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 6c  ng.  Additionall
1e480 79 2c 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  y, if the parame
1e490 74 65 72 20 69 6e 20 74 68 65 0a 2a 2a 20 61 72  ter in the.** ar
1e4a0 67 75 6d 65 6e 74 20 6c 69 73 74 20 69 73 20 61  gument list is a
1e4b0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25   NULL pointer, %
1e4c0 51 20 73 75 62 73 74 69 74 75 74 65 73 20 74 68  Q substitutes th
1e4d0 65 20 74 65 78 74 20 22 4e 55 4c 4c 22 20 28 77  e text "NULL" (w
1e4e0 69 74 68 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c 65  ithout.** single
1e4f0 20 71 75 6f 74 65 73 29 2e 29 5e 20 20 53 6f 2c   quotes).)^  So,
1e500 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 6f 6e   for example, on
1e510 65 20 63 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a  e could say:.**.
1e520 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
1e530 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a  pre>.**  char *z
1e540 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70  SQL = sqlite3_mp
1e550 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e  rintf("INSERT IN
1e560 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28  TO table VALUES(
1e570 25 51 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a  %Q)", zText);.**
1e580 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64    sqlite3_exec(d
1e590 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30  b, zSQL, 0, 0, 0
1e5a0 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66  );.**  sqlite3_f
1e5b0 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f  ree(zSQL);.** </
1e5c0 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
1e5d0 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65  >.**.** The code
1e5e0 20 61 62 6f 76 65 20 77 69 6c 6c 20 72 65 6e 64   above will rend
1e5f0 65 72 20 61 20 63 6f 72 72 65 63 74 20 53 51 4c  er a correct SQL
1e600 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68   statement in th
1e610 65 20 7a 53 51 4c 0a 2a 2a 20 76 61 72 69 61 62  e zSQL.** variab
1e620 6c 65 20 65 76 65 6e 20 69 66 20 74 68 65 20 7a  le even if the z
1e630 54 65 78 74 20 76 61 72 69 61 62 6c 65 20 69 73  Text variable is
1e640 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
1e650 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 22 25 77  .**.** ^(The "%w
1e660 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74  " formatting opt
1e670 69 6f 6e 20 69 73 20 6c 69 6b 65 20 22 25 71 22  ion is like "%q"
1e680 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20   except that it 
1e690 65 78 70 65 63 74 73 20 74 6f 0a 2a 2a 20 62 65  expects to.** be
1e6a0 20 63 6f 6e 74 61 69 6e 65 64 20 77 69 74 68 69   contained withi
1e6b0 6e 20 64 6f 75 62 6c 65 2d 71 75 6f 74 65 73 20  n double-quotes 
1e6c0 69 6e 73 74 65 61 64 20 6f 66 20 73 69 6e 67 6c  instead of singl
1e6d0 65 20 71 75 6f 74 65 73 2c 20 61 6e 64 20 69 74  e quotes, and it
1e6e0 0a 2a 2a 20 65 73 63 61 70 65 73 20 74 68 65 20  .** escapes the 
1e6f0 64 6f 75 62 6c 65 2d 71 75 6f 74 65 20 63 68 61  double-quote cha
1e700 72 61 63 74 65 72 20 69 6e 73 74 65 61 64 20 6f  racter instead o
1e710 66 20 74 68 65 20 73 69 6e 67 6c 65 2d 71 75 6f  f the single-quo
1e720 74 65 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 2e  te.** character.
1e730 29 5e 20 20 54 68 65 20 22 25 77 22 20 66 6f 72  )^  The "%w" for
1e740 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 69  matting option i
1e750 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 73  s intended for s
1e760 61 66 65 6c 79 20 69 6e 73 65 72 74 69 6e 67 0a  afely inserting.
1e770 2a 2a 20 74 61 62 6c 65 20 61 6e 64 20 63 6f 6c  ** table and col
1e780 75 6d 6e 20 6e 61 6d 65 73 20 69 6e 74 6f 20 61  umn names into a
1e790 20 63 6f 6e 73 74 72 75 63 74 65 64 20 53 51 4c   constructed SQL
1e7a0 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a   statement..**.*
1e7b0 2a 20 5e 28 54 68 65 20 22 25 7a 22 20 66 6f 72  * ^(The "%z" for
1e7c0 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77  matting option w
1e7d0 6f 72 6b 73 20 6c 69 6b 65 20 22 25 73 22 20 62  orks like "%s" b
1e7e0 75 74 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 61  ut with the.** a
1e7f0 64 64 69 74 69 6f 6e 20 74 68 61 74 20 61 66 74  ddition that aft
1e800 65 72 20 74 68 65 20 73 74 72 69 6e 67 20 68 61  er the string ha
1e810 73 20 62 65 65 6e 20 72 65 61 64 20 61 6e 64 20  s been read and 
1e820 63 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74  copied into.** t
1e830 68 65 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69  he result, [sqli
1e840 74 65 33 5f 66 72 65 65 28 29 5d 20 69 73 20 63  te3_free()] is c
1e850 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e 70  alled on the inp
1e860 75 74 20 73 74 72 69 6e 67 2e 29 5e 0a 2a 2f 0a  ut string.)^.*/.
1e870 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61 72 20  SQLITE_API char 
1e880 2a 53 51 4c 49 54 45 5f 43 44 45 43 4c 20 73 71  *SQLITE_CDECL sq
1e890 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f  lite3_mprintf(co
1e8a0 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a  nst char*,...);.
1e8b0 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61 72 20  SQLITE_API char 
1e8c0 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20  *SQLITE_STDCALL 
1e8d0 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66  sqlite3_vmprintf
1e8e0 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61  (const char*, va
1e8f0 5f 6c 69 73 74 29 3b 0a 53 51 4c 49 54 45 5f 41  _list);.SQLITE_A
1e900 50 49 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f  PI char *SQLITE_
1e910 43 44 45 43 4c 20 73 71 6c 69 74 65 33 5f 73 6e  CDECL sqlite3_sn
1e920 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a  printf(int,char*
1e930 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e  ,const char*, ..
1e940 2e 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  .);.SQLITE_API c
1e950 68 61 72 20 2a 53 51 4c 49 54 45 5f 53 54 44 43  har *SQLITE_STDC
1e960 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 73 6e 70  ALL sqlite3_vsnp
1e970 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c  rintf(int,char*,
1e980 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f  const char*, va_
1e990 6c 69 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  list);../*.** CA
1e9a0 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41  PI3REF: Memory A
1e9b0 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73 79 73  llocation Subsys
1e9c0 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51  tem.**.** The SQ
1e9d0 4c 69 74 65 20 63 6f 72 65 20 75 73 65 73 20 74  Lite core uses t
1e9e0 68 65 73 65 20 74 68 72 65 65 20 72 6f 75 74 69  hese three routi
1e9f0 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69  nes for all of i
1ea00 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e  ts own.** intern
1ea10 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  al memory alloca
1ea20 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72  tion needs. "Cor
1ea30 65 22 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f  e" in the previo
1ea40 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64  us sentence.** d
1ea50 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20  oes not include 
1ea60 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d  operating-system
1ea70 20 73 70 65 63 69 66 69 63 20 56 46 53 20 69 6d   specific VFS im
1ea80 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54  plementation.  T
1ea90 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46  he.** Windows VF
1eaa0 53 20 75 73 65 73 20 6e 61 74 69 76 65 20 6d 61  S uses native ma
1eab0 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28  lloc() and free(
1eac0 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61  ) for some opera
1ead0 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  tions..**.** ^Th
1eae0 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  e sqlite3_malloc
1eaf0 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
1eb00 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
1eb10 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65  a block.** of me
1eb20 6d 6f 72 79 20 61 74 20 6c 65 61 73 74 20 4e 20  mory at least N 
1eb30 62 79 74 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c  bytes in length,
1eb40 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20   where N is the 
1eb50 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49  parameter..** ^I
1eb60 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  f sqlite3_malloc
1eb70 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  () is unable to 
1eb80 6f 62 74 61 69 6e 20 73 75 66 66 69 63 69 65 6e  obtain sufficien
1eb90 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79  t free.** memory
1eba0 2c 20 69 74 20 72 65 74 75 72 6e 73 20 61 20 4e  , it returns a N
1ebb0 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 49  ULL pointer.  ^I
1ebc0 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
1ebd0 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  N to.** sqlite3_
1ebe0 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f  malloc() is zero
1ebf0 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 68 65   or negative the
1ec00 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  n sqlite3_malloc
1ec10 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20  () returns.** a 
1ec20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
1ec30 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1ec40 5f 6d 61 6c 6c 6f 63 36 34 28 4e 29 20 72 6f 75  _malloc64(N) rou
1ec50 74 69 6e 65 20 77 6f 72 6b 73 20 6a 75 73 74 20  tine works just 
1ec60 6c 69 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  like.** sqlite3_
1ec70 6d 61 6c 6c 6f 63 28 4e 29 20 65 78 63 65 70 74  malloc(N) except
1ec80 20 74 68 61 74 20 4e 20 69 73 20 61 6e 20 75 6e   that N is an un
1ec90 73 69 67 6e 65 64 20 36 34 2d 62 69 74 20 69 6e  signed 64-bit in
1eca0 74 65 67 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a  teger instead.**
1ecb0 20 6f 66 20 61 20 73 69 67 6e 65 64 20 33 32 2d   of a signed 32-
1ecc0 62 69 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a  bit integer..**.
1ecd0 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69  ** ^Calling sqli
1ece0 74 65 33 5f 66 72 65 65 28 29 20 77 69 74 68 20  te3_free() with 
1ecf0 61 20 70 6f 69 6e 74 65 72 20 70 72 65 76 69 6f  a pointer previo
1ed00 75 73 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a  usly returned.**
1ed10 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c   by sqlite3_mall
1ed20 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  oc() or sqlite3_
1ed30 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73  realloc() releas
1ed40 65 73 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 73  es that memory s
1ed50 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d 69 67  o.** that it mig
1ed60 68 74 20 62 65 20 72 65 75 73 65 64 2e 20 20 5e  ht be reused.  ^
1ed70 54 68 65 20 73 71 6c 69 74 65 33 5f 66 72 65 65  The sqlite3_free
1ed80 28 29 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a  () routine is.**
1ed90 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63   a no-op if is c
1eda0 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c  alled with a NUL
1edb0 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50 61 73 73  L pointer.  Pass
1edc0 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ing a NULL point
1edd0 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33  er.** to sqlite3
1ede0 5f 66 72 65 65 28 29 20 69 73 20 68 61 72 6d 6c  _free() is harml
1edf0 65 73 73 2e 20 20 41 66 74 65 72 20 62 65 69 6e  ess.  After bein
1ee00 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a  g freed, memory.
1ee10 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74 68 65  ** should neithe
1ee20 72 20 62 65 20 72 65 61 64 20 6e 6f 72 20 77 72  r be read nor wr
1ee30 69 74 74 65 6e 2e 20 20 45 76 65 6e 20 72 65 61  itten.  Even rea
1ee40 64 69 6e 67 20 70 72 65 76 69 6f 75 73 6c 79 20  ding previously 
1ee50 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20  freed.** memory 
1ee60 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 6e 20  might result in 
1ee70 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66  a segmentation f
1ee80 61 75 6c 74 20 6f 72 20 6f 74 68 65 72 20 73 65  ault or other se
1ee90 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d  vere error..** M
1eea0 65 6d 6f 72 79 20 63 6f 72 72 75 70 74 69 6f 6e  emory corruption
1eeb0 2c 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e  , a segmentation
1eec0 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72   fault, or other
1eed0 20 73 65 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a   severe error.**
1eee0 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 66   might result if
1eef0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
1ef00 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61  is called with a
1ef10 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65   non-NULL pointe
1ef20 72 20 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f  r that.** was no
1ef30 74 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  t obtained from 
1ef40 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1ef50 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   or sqlite3_real
1ef60 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  loc()..**.** ^Th
1ef70 65 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  e sqlite3_reallo
1ef80 63 28 58 2c 4e 29 20 69 6e 74 65 72 66 61 63 65  c(X,N) interface
1ef90 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 73   attempts to res
1efa0 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d  ize a.** prior m
1efb0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
1efc0 20 58 20 74 6f 20 62 65 20 61 74 20 6c 65 61 73   X to be at leas
1efd0 74 20 4e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49  t N bytes..** ^I
1efe0 66 20 74 68 65 20 58 20 70 61 72 61 6d 65 74 65  f the X paramete
1eff0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61  r to sqlite3_rea
1f000 6c 6c 6f 63 28 58 2c 4e 29 0a 2a 2a 20 69 73 20  lloc(X,N).** is 
1f010 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  a NULL pointer t
1f020 68 65 6e 20 69 74 73 20 62 65 68 61 76 69 6f 72  hen its behavior
1f030 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74 6f   is identical to
1f040 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69   calling.** sqli
1f050 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 2e 0a 2a  te3_malloc(N)..*
1f060 2a 20 5e 49 66 20 74 68 65 20 4e 20 70 61 72 61  * ^If the N para
1f070 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
1f080 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 69 73  _realloc(X,N) is
1f090 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61   zero or.** nega
1f0a0 74 69 76 65 20 74 68 65 6e 20 74 68 65 20 62 65  tive then the be
1f0b0 68 61 76 69 6f 72 20 69 73 20 65 78 61 63 74 6c  havior is exactl
1f0c0 79 20 74 68 65 20 73 61 6d 65 20 61 73 20 63 61  y the same as ca
1f0d0 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33  lling.** sqlite3
1f0e0 5f 66 72 65 65 28 58 29 2e 0a 2a 2a 20 5e 73 71  _free(X)..** ^sq
1f0f0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c  lite3_realloc(X,
1f100 4e 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  N) returns a poi
1f110 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79  nter to a memory
1f120 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f   allocation.** o
1f130 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74  f at least N byt
1f140 65 73 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55  es in size or NU
1f150 4c 4c 20 69 66 20 69 6e 73 75 66 66 69 63 69 65  LL if insufficie
1f160 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20 61 76 61  nt memory is ava
1f170 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d  ilable..** ^If M
1f180 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20   is the size of 
1f190 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  the prior alloca
1f1a0 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e  tion, then min(N
1f1b0 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20  ,M) bytes.** of 
1f1c0 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  the prior alloca
1f1d0 74 69 6f 6e 20 61 72 65 20 63 6f 70 69 65 64 20  tion are copied 
1f1e0 69 6e 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69  into the beginni
1f1f0 6e 67 20 6f 66 20 62 75 66 66 65 72 20 72 65 74  ng of buffer ret
1f200 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69  urned.** by sqli
1f210 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29  te3_realloc(X,N)
1f220 20 61 6e 64 20 74 68 65 20 70 72 69 6f 72 20 61   and the prior a
1f230 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66 72 65  llocation is fre
1f240 65 64 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74  ed..** ^If sqlit
1f250 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20  e3_realloc(X,N) 
1f260 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64  returns NULL and
1f270 20 4e 20 69 73 20 70 6f 73 69 74 69 76 65 2c 20   N is positive, 
1f280 74 68 65 6e 20 74 68 65 0a 2a 2a 20 70 72 69 6f  then the.** prio
1f290 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20  r allocation is 
1f2a0 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a  not freed..**.**
1f2b0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
1f2c0 61 6c 6c 6f 63 36 34 28 58 2c 4e 29 20 69 6e 74  alloc64(X,N) int
1f2d0 65 72 66 61 63 65 73 20 77 6f 72 6b 73 20 74 68  erfaces works th
1f2e0 65 20 73 61 6d 65 20 61 73 0a 2a 2a 20 73 71 6c  e same as.** sql
1f2f0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e  ite3_realloc(X,N
1f300 29 20 65 78 63 65 70 74 20 74 68 61 74 20 4e 20  ) except that N 
1f310 69 73 20 61 20 36 34 2d 62 69 74 20 75 6e 73 69  is a 64-bit unsi
1f320 67 6e 65 64 20 69 6e 74 65 67 65 72 20 69 6e 73  gned integer ins
1f330 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20 33 32 2d  tead.** of a 32-
1f340 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67  bit signed integ
1f350 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 58 20  er..**.** ^If X 
1f360 69 73 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  is a memory allo
1f370 63 61 74 69 6f 6e 20 70 72 65 76 69 6f 75 73 6c  cation previousl
1f380 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
1f390 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1f3a0 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c  ,.** sqlite3_mal
1f3b0 6c 6f 63 36 34 28 29 2c 20 73 71 6c 69 74 65 33  loc64(), sqlite3
1f3c0 5f 72 65 61 6c 6c 6f 63 28 29 2c 20 6f 72 20 73  _realloc(), or s
1f3d0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34  qlite3_realloc64
1f3e0 28 29 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69  (), then.** sqli
1f3f0 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 72 65 74  te3_msize(X) ret
1f400 75 72 6e 73 20 74 68 65 20 73 69 7a 65 20 6f 66  urns the size of
1f410 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 61 6c 6c   that memory all
1f420 6f 63 61 74 69 6f 6e 20 69 6e 20 62 79 74 65 73  ocation in bytes
1f430 2e 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 20  ..** ^The value 
1f440 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
1f450 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 6d 69 67  te3_msize(X) mig
1f460 68 74 20 62 65 20 6c 61 72 67 65 72 20 74 68 61  ht be larger tha
1f470 6e 20 74 68 65 20 6e 75 6d 62 65 72 0a 2a 2a 20  n the number.** 
1f480 6f 66 20 62 79 74 65 73 20 72 65 71 75 65 73 74  of bytes request
1f490 65 64 20 77 68 65 6e 20 58 20 77 61 73 20 61 6c  ed when X was al
1f4a0 6c 6f 63 61 74 65 64 2e 20 20 5e 49 66 20 58 20  located.  ^If X 
1f4b0 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
1f4c0 72 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65  r then.** sqlite
1f4d0 33 5f 6d 73 69 7a 65 28 58 29 20 72 65 74 75 72  3_msize(X) retur
1f4e0 6e 73 20 7a 65 72 6f 2e 20 20 49 66 20 58 20 70  ns zero.  If X p
1f4f0 6f 69 6e 74 73 20 74 6f 20 73 6f 6d 65 74 68 69  oints to somethi
1f500 6e 67 20 74 68 61 74 20 69 73 20 6e 6f 74 0a 2a  ng that is not.*
1f510 2a 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20  * the beginning 
1f520 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  of memory alloca
1f530 74 69 6f 6e 2c 20 6f 72 20 69 66 20 69 74 20 70  tion, or if it p
1f540 6f 69 6e 74 73 20 74 6f 20 61 20 66 6f 72 6d 65  oints to a forme
1f550 72 6c 79 0a 2a 2a 20 76 61 6c 69 64 20 6d 65 6d  rly.** valid mem
1f560 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74  ory allocation t
1f570 68 61 74 20 68 61 73 20 6e 6f 77 20 62 65 65 6e  hat has now been
1f580 20 66 72 65 65 64 2c 20 74 68 65 6e 20 74 68 65   freed, then the
1f590 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20   behavior.** of 
1f5a0 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29  sqlite3_msize(X)
1f5b0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e   is undefined an
1f5c0 64 20 70 6f 73 73 69 62 6c 79 20 68 61 72 6d 66  d possibly harmf
1f5d0 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d  ul..**.** ^The m
1f5e0 65 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 20 62  emory returned b
1f5f0 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  y sqlite3_malloc
1f600 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  (), sqlite3_real
1f610 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65  loc(),.** sqlite
1f620 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c 20 61 6e  3_malloc64(), an
1f630 64 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  d sqlite3_reallo
1f640 63 36 34 28 29 0a 2a 2a 20 69 73 20 61 6c 77 61  c64().** is alwa
1f650 79 73 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 74  ys aligned to at
1f660 20 6c 65 61 73 74 20 61 6e 20 38 20 62 79 74 65   least an 8 byte
1f670 20 62 6f 75 6e 64 61 72 79 2c 20 6f 72 20 74 6f   boundary, or to
1f680 20 61 0a 2a 2a 20 34 20 62 79 74 65 20 62 6f 75   a.** 4 byte bou
1f690 6e 64 61 72 79 20 69 66 20 74 68 65 20 5b 53 51  ndary if the [SQ
1f6a0 4c 49 54 45 5f 34 5f 42 59 54 45 5f 41 4c 49 47  LITE_4_BYTE_ALIG
1f6b0 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f 6d 70  NED_MALLOC] comp
1f6c0 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69  ile-time.** opti
1f6d0 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a  on is used..**.*
1f6e0 2a 20 49 6e 20 53 51 4c 69 74 65 20 76 65 72 73  * In SQLite vers
1f6f0 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e  ion 3.5.0 and 3.
1f700 35 2e 31 2c 20 69 74 20 77 61 73 20 70 6f 73 73  5.1, it was poss
1f710 69 62 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a  ible to define.*
1f720 2a 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49  * the SQLITE_OMI
1f730 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54  T_MEMORY_ALLOCAT
1f740 49 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c 64 20  ION which would 
1f750 63 61 75 73 65 20 74 68 65 20 62 75 69 6c 74 2d  cause the built-
1f760 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  in.** implementa
1f770 74 69 6f 6e 20 6f 66 20 74 68 65 73 65 20 72 6f  tion of these ro
1f780 75 74 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69  utines to be omi
1f790 74 74 65 64 2e 20 20 54 68 61 74 20 63 61 70 61  tted.  That capa
1f7a0 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20  bility.** is no 
1f7b0 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64 65 64 2e  longer provided.
1f7c0 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20    Only built-in 
1f7d0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
1f7e0 73 20 63 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a  s can be used..*
1f7f0 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f 20 53 51  *.** Prior to SQ
1f800 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37  Lite version 3.7
1f810 2e 31 30 2c 20 74 68 65 20 57 69 6e 64 6f 77 73  .10, the Windows
1f820 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61   OS interface la
1f830 79 65 72 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 68  yer called.** th
1f840 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28  e system malloc(
1f850 29 20 61 6e 64 20 66 72 65 65 28 29 20 64 69 72  ) and free() dir
1f860 65 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65  ectly when conve
1f870 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d  rting.** filenam
1f880 65 73 20 62 65 74 77 65 65 6e 20 74 68 65 20 55  es between the U
1f890 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75 73  TF-8 encoding us
1f8a0 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20  ed by SQLite.** 
1f8b0 61 6e 64 20 77 68 61 74 65 76 65 72 20 66 69 6c  and whatever fil
1f8c0 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69  ename encoding i
1f8d0 73 20 75 73 65 64 20 62 79 20 74 68 65 20 70 61  s used by the pa
1f8e0 72 74 69 63 75 6c 61 72 20 57 69 6e 64 6f 77 73  rticular Windows
1f8f0 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e  .** installation
1f900 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  .  Memory alloca
1f910 74 69 6f 6e 20 65 72 72 6f 72 73 20 77 65 72 65  tion errors were
1f920 20 64 65 74 65 63 74 65 64 2c 20 62 75 74 0a 2a   detected, but.*
1f930 2a 20 74 68 65 79 20 77 65 72 65 20 72 65 70 6f  * they were repo
1f940 72 74 65 64 20 62 61 63 6b 20 61 73 20 5b 53 51  rted back as [SQ
1f950 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f  LITE_CANTOPEN] o
1f960 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45  r.** [SQLITE_IOE
1f970 52 52 5d 20 72 61 74 68 65 72 20 74 68 61 6e 20  RR] rather than 
1f980 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a  [SQLITE_NOMEM]..
1f990 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65  **.** The pointe
1f9a0 72 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b  r arguments to [
1f9b0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
1f9c0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61  and [sqlite3_rea
1f9d0 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 20  lloc()].** must 
1f9e0 62 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f  be either NULL o
1f9f0 72 20 65 6c 73 65 20 70 6f 69 6e 74 65 72 73 20  r else pointers 
1fa00 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 20  obtained from a 
1fa10 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61 74  prior.** invocat
1fa20 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ion of [sqlite3_
1fa30 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71  malloc()] or [sq
1fa40 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
1fa50 20 74 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e 6f   that have.** no
1fa60 74 20 79 65 74 20 62 65 65 6e 20 72 65 6c 65 61  t yet been relea
1fa70 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61  sed..**.** The a
1fa80 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
1fa90 6e 6f 74 20 72 65 61 64 20 6f 72 20 77 72 69 74  not read or writ
1faa0 65 20 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a  e any part of.**
1fab0 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f   a block of memo
1fac0 72 79 20 61 66 74 65 72 20 69 74 20 68 61 73 20  ry after it has 
1fad0 62 65 65 6e 20 72 65 6c 65 61 73 65 64 20 75 73  been released us
1fae0 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
1faf0 66 72 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69  free()] or [sqli
1fb00 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a  te3_realloc()]..
1fb10 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  */.SQLITE_API vo
1fb20 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41  id *SQLITE_STDCA
1fb30 4c 4c 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  LL sqlite3_mallo
1fb40 63 28 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41  c(int);.SQLITE_A
1fb50 50 49 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f  PI void *SQLITE_
1fb60 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
1fb70 6d 61 6c 6c 6f 63 36 34 28 73 71 6c 69 74 65 33  malloc64(sqlite3
1fb80 5f 75 69 6e 74 36 34 29 3b 0a 53 51 4c 49 54 45  _uint64);.SQLITE
1fb90 5f 41 50 49 20 76 6f 69 64 20 2a 53 51 4c 49 54  _API void *SQLIT
1fba0 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
1fbb0 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c  3_realloc(void*,
1fbc0 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50   int);.SQLITE_AP
1fbd0 49 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53  I void *SQLITE_S
1fbe0 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 72  TDCALL sqlite3_r
1fbf0 65 61 6c 6c 6f 63 36 34 28 76 6f 69 64 2a 2c 20  ealloc64(void*, 
1fc00 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 3b  sqlite3_uint64);
1fc10 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
1fc20 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
1fc30 73 71 6c 69 74 65 33 5f 66 72 65 65 28 76 6f 69  sqlite3_free(voi
1fc40 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  d*);.SQLITE_API 
1fc50 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 53  sqlite3_uint64 S
1fc60 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
1fc70 6c 69 74 65 33 5f 6d 73 69 7a 65 28 76 6f 69 64  lite3_msize(void
1fc80 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
1fc90 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f  REF: Memory Allo
1fca0 63 61 74 6f 72 20 53 74 61 74 69 73 74 69 63 73  cator Statistics
1fcb0 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72  .**.** SQLite pr
1fcc0 6f 76 69 64 65 73 20 74 68 65 73 65 20 74 77 6f  ovides these two
1fcd0 20 69 6e 74 65 72 66 61 63 65 73 20 66 6f 72 20   interfaces for 
1fce0 72 65 70 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65  reporting on the
1fcf0 20 73 74 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68   status.** of th
1fd00 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  e [sqlite3_mallo
1fd10 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66  c()], [sqlite3_f
1fd20 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c  ree()], and [sql
1fd30 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a  ite3_realloc()].
1fd40 2a 2a 20 72 6f 75 74 69 6e 65 73 2c 20 77 68 69  ** routines, whi
1fd50 63 68 20 66 6f 72 6d 20 74 68 65 20 62 75 69 6c  ch form the buil
1fd60 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  t-in memory allo
1fd70 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d  cation subsystem
1fd80 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71  ..**.** ^The [sq
1fd90 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
1fda0 64 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74  d()] routine ret
1fdb0 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
1fdc0 6f 66 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 6d  of bytes.** of m
1fdd0 65 6d 6f 72 79 20 63 75 72 72 65 6e 74 6c 79 20  emory currently 
1fde0 6f 75 74 73 74 61 6e 64 69 6e 67 20 28 6d 61 6c  outstanding (mal
1fdf0 6c 6f 63 65 64 20 62 75 74 20 6e 6f 74 20 66 72  loced but not fr
1fe00 65 65 64 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73  eed)..** ^The [s
1fe10 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
1fe20 67 68 77 61 74 65 72 28 29 5d 20 72 6f 75 74 69  ghwater()] routi
1fe30 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6d  ne returns the m
1fe40 61 78 69 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65 20  aximum.** value 
1fe50 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  of [sqlite3_memo
1fe60 72 79 5f 75 73 65 64 28 29 5d 20 73 69 6e 63 65  ry_used()] since
1fe70 20 74 68 65 20 68 69 67 68 2d 77 61 74 65 72 20   the high-water 
1fe80 6d 61 72 6b 0a 2a 2a 20 77 61 73 20 6c 61 73 74  mark.** was last
1fe90 20 72 65 73 65 74 2e 20 20 5e 54 68 65 20 76 61   reset.  ^The va
1fea0 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79  lues returned by
1feb0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
1fec0 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20  _used()] and.** 
1fed0 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
1fee0 68 69 67 68 77 61 74 65 72 28 29 5d 20 69 6e 63  highwater()] inc
1fef0 6c 75 64 65 20 61 6e 79 20 6f 76 65 72 68 65 61  lude any overhea
1ff00 64 0a 2a 2a 20 61 64 64 65 64 20 62 79 20 53 51  d.** added by SQ
1ff10 4c 69 74 65 20 69 6e 20 69 74 73 20 69 6d 70 6c  Lite in its impl
1ff20 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 73  ementation of [s
1ff30 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
1ff40 2c 0a 2a 2a 20 62 75 74 20 6e 6f 74 20 6f 76 65  ,.** but not ove
1ff50 72 68 65 61 64 20 61 64 64 65 64 20 62 79 20 74  rhead added by t
1ff60 68 65 20 61 6e 79 20 75 6e 64 65 72 6c 79 69 6e  he any underlyin
1ff70 67 20 73 79 73 74 65 6d 20 6c 69 62 72 61 72 79  g system library
1ff80 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74 68 61  .** routines tha
1ff90 74 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  t [sqlite3_mallo
1ffa0 63 28 29 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a  c()] may call..*
1ffb0 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79  *.** ^The memory
1ffc0 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b   high-water mark
1ffd0 20 69 73 20 72 65 73 65 74 20 74 6f 20 74 68 65   is reset to the
1ffe0 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f   current value o
1fff0 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65  f.** [sqlite3_me
20000 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 69 66 20  mory_used()] if 
20010 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20  and only if the 
20020 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
20030 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
20040 68 69 67 68 77 61 74 65 72 28 29 5d 20 69 73 20  highwater()] is 
20050 74 72 75 65 2e 20 20 5e 54 68 65 20 76 61 6c 75  true.  ^The valu
20060 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79  e returned.** by
20070 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
20080 5f 68 69 67 68 77 61 74 65 72 28 31 29 5d 20 69  _highwater(1)] i
20090 73 20 74 68 65 20 68 69 67 68 2d 77 61 74 65 72  s the high-water
200a0 20 6d 61 72 6b 0a 2a 2a 20 70 72 69 6f 72 20 74   mark.** prior t
200b0 6f 20 74 68 65 20 72 65 73 65 74 2e 0a 2a 2f 0a  o the reset..*/.
200c0 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74  SQLITE_API sqlit
200d0 65 33 5f 69 6e 74 36 34 20 53 51 4c 49 54 45 5f  e3_int64 SQLITE_
200e0 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
200f0 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69 64  memory_used(void
20100 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71  );.SQLITE_API sq
20110 6c 69 74 65 33 5f 69 6e 74 36 34 20 53 51 4c 49  lite3_int64 SQLI
20120 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
20130 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
20140 74 65 72 28 69 6e 74 20 72 65 73 65 74 46 6c 61  ter(int resetFla
20150 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  g);../*.** CAPI3
20160 52 45 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64  REF: Pseudo-Rand
20170 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65 72 61  om Number Genera
20180 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  tor.**.** SQLite
20190 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 69 67 68   contains a high
201a0 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64 6f 2d  -quality pseudo-
201b0 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65  random number ge
201c0 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 29 20 75  nerator (PRNG) u
201d0 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74  sed to.** select
201e0 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44 20 7c   random [ROWID |
201f0 20 52 4f 57 49 44 73 5d 20 77 68 65 6e 20 69 6e   ROWIDs] when in
20200 73 65 72 74 69 6e 67 20 6e 65 77 20 72 65 63 6f  serting new reco
20210 72 64 73 20 69 6e 74 6f 20 61 20 74 61 62 6c 65  rds into a table
20220 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79   that.** already
20230 20 75 73 65 73 20 74 68 65 20 6c 61 72 67 65 73   uses the larges
20240 74 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f 57 49  t possible [ROWI
20250 44 5d 2e 20 20 54 68 65 20 50 52 4e 47 20 69 73  D].  The PRNG is
20260 20 61 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a   also used for.*
20270 2a 20 74 68 65 20 62 75 69 6c 64 2d 69 6e 20 72  * the build-in r
20280 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64  andom() and rand
20290 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e  omblob() SQL fun
202a0 63 74 69 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e  ctions.  This in
202b0 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a  terface allows.*
202c0 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  * applications t
202d0 6f 20 61 63 63 65 73 73 20 74 68 65 20 73 61 6d  o access the sam
202e0 65 20 50 52 4e 47 20 66 6f 72 20 6f 74 68 65 72  e PRNG for other
202f0 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a   purposes..**.**
20300 20 5e 41 20 63 61 6c 6c 20 74 6f 20 74 68 69 73   ^A call to this
20310 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20   routine stores 
20320 4e 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f  N bytes of rando
20330 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 66 66 65  mness into buffe
20340 72 20 50 2e 0a 2a 2a 20 5e 54 68 65 20 50 20 70  r P..** ^The P p
20350 61 72 61 6d 65 74 65 72 20 63 61 6e 20 62 65 20  arameter can be 
20360 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
20370 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 69 73 20 72  **.** ^If this r
20380 6f 75 74 69 6e 65 20 68 61 73 20 6e 6f 74 20 62  outine has not b
20390 65 65 6e 20 70 72 65 76 69 6f 75 73 6c 79 20 63  een previously c
203a0 61 6c 6c 65 64 20 6f 72 20 69 66 20 74 68 65 20  alled or if the 
203b0 70 72 65 76 69 6f 75 73 0a 2a 2a 20 63 61 6c 6c  previous.** call
203c0 20 68 61 64 20 4e 20 6c 65 73 73 20 74 68 61 6e   had N less than
203d0 20 6f 6e 65 20 6f 72 20 61 20 4e 55 4c 4c 20 70   one or a NULL p
203e0 6f 69 6e 74 65 72 20 66 6f 72 20 50 2c 20 74 68  ointer for P, th
203f0 65 6e 20 74 68 65 20 50 52 4e 47 20 69 73 0a 2a  en the PRNG is.*
20400 2a 20 73 65 65 64 65 64 20 75 73 69 6e 67 20 72  * seeded using r
20410 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e  andomness obtain
20420 65 64 20 66 72 6f 6d 20 74 68 65 20 78 52 61 6e  ed from the xRan
20430 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f  domness method o
20440 66 0a 2a 2a 20 74 68 65 20 64 65 66 61 75 6c 74  f.** the default
20450 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
20460 62 6a 65 63 74 2e 0a 2a 2a 20 5e 49 66 20 74 68  bject..** ^If th
20470 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20  e previous call 
20480 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  to this routine 
20490 68 61 64 20 61 6e 20 4e 20 6f 66 20 31 20 6f 72  had an N of 1 or
204a0 20 6d 6f 72 65 20 61 6e 64 20 61 0a 2a 2a 20 6e   more and a.** n
204b0 6f 6e 2d 4e 55 4c 4c 20 50 20 74 68 65 6e 20 74  on-NULL P then t
204c0 68 65 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d  he pseudo-random
204d0 6e 65 73 73 20 69 73 20 67 65 6e 65 72 61 74 65  ness is generate
204e0 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 20  d.** internally 
204f0 61 6e 64 20 77 69 74 68 6f 75 74 20 72 65 63 6f  and without reco
20500 75 72 73 65 20 74 6f 20 74 68 65 20 5b 73 71 6c  urse to the [sql
20510 69 74 65 33 5f 76 66 73 5d 20 78 52 61 6e 64 6f  ite3_vfs] xRando
20520 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e  mness.** method.
20530 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  .*/.SQLITE_API v
20540 6f 69 64 20 53 51 4c 49 54 45 5f 53 54 44 43 41  oid SQLITE_STDCA
20550 4c 4c 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f  LL sqlite3_rando
20560 6d 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69  mness(int N, voi
20570 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  d *P);../*.** CA
20580 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d  PI3REF: Compile-
20590 54 69 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 69  Time Authorizati
205a0 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a  on Callbacks.**.
205b0 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65  ** ^This routine
205c0 20 72 65 67 69 73 74 65 72 73 20 61 6e 20 61 75   registers an au
205d0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
205e0 6b 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75  k with a particu
205f0 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  lar.** [database
20600 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75   connection], su
20610 70 70 6c 69 65 64 20 69 6e 20 74 68 65 20 66 69  pplied in the fi
20620 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  rst argument..**
20630 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72   ^The authorizer
20640 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
20650 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61 74  oked as SQL stat
20660 65 6d 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67  ements are being
20670 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20   compiled.** by 
20680 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
20690 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61  ()] or its varia
206a0 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  nts [sqlite3_pre
206b0 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b  pare_v2()],.** [
206c0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
206d0 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  6()] and [sqlite
206e0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
206f0 5d 2e 20 20 5e 41 74 20 76 61 72 69 6f 75 73 0a  ].  ^At various.
20700 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72 69 6e 67  ** points during
20710 20 74 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e   the compilation
20720 20 70 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67   process, as log
20730 69 63 20 69 73 20 62 65 69 6e 67 20 63 72 65 61  ic is being crea
20740 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72  ted.** to perfor
20750 6d 20 76 61 72 69 6f 75 73 20 61 63 74 69 6f 6e  m various action
20760 73 2c 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  s, the authorize
20770 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  r callback is in
20780 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20  voked to.** see 
20790 69 66 20 74 68 6f 73 65 20 61 63 74 69 6f 6e 73  if those actions
207a0 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20 5e   are allowed.  ^
207b0 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  The authorizer c
207c0 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a  allback should.*
207d0 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  * return [SQLITE
207e0 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68  _OK] to allow th
207f0 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54  e action, [SQLIT
20800 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73  E_IGNORE] to dis
20810 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65  allow the.** spe
20820 63 69 66 69 63 20 61 63 74 69 6f 6e 20 62 75 74  cific action but
20830 20 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20 73   allow the SQL s
20840 74 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74  tatement to cont
20850 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f  inue to be.** co
20860 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49  mpiled, or [SQLI
20870 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75 73  TE_DENY] to caus
20880 65 20 74 68 65 20 65 6e 74 69 72 65 20 53 51 4c  e the entire SQL
20890 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65   statement to be
208a0 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20 77 69 74  .** rejected wit
208b0 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 49 66  h an error.  ^If
208c0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
208d0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
208e0 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f 74  .** any value ot
208f0 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
20900 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54  _IGNORE], [SQLIT
20910 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  E_OK], or [SQLIT
20920 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20  E_DENY].** then 
20930 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  the [sqlite3_pre
20940 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71  pare_v2()] or eq
20950 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68  uivalent call th
20960 61 74 20 74 72 69 67 67 65 72 65 64 0a 2a 2a 20  at triggered.** 
20970 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 77  the authorizer w
20980 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e  ill fail with an
20990 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a   error message..
209a0 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63  **.** When the c
209b0 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
209c0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61  [SQLITE_OK], tha
209d0 74 20 6d 65 61 6e 73 20 74 68 65 20 6f 70 65 72  t means the oper
209e0 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74  ation.** request
209f0 65 64 20 69 73 20 6f 6b 2e 20 20 5e 57 68 65 6e  ed is ok.  ^When
20a00 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
20a10 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45  turns [SQLITE_DE
20a20 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  NY], the.** [sql
20a30 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
20a40 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74  )] or equivalent
20a50 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67   call that trigg
20a60 65 72 65 64 20 74 68 65 0a 2a 2a 20 61 75 74 68  ered the.** auth
20a70 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c  orizer will fail
20a80 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d   with an error m
20a90 65 73 73 61 67 65 20 65 78 70 6c 61 69 6e 69 6e  essage explainin
20aa0 67 20 74 68 61 74 0a 2a 2a 20 61 63 63 65 73 73  g that.** access
20ab0 20 69 73 20 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a   is denied. .**.
20ac0 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70 61  ** ^The first pa
20ad0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61  rameter to the a
20ae0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
20af0 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  ck is a copy of 
20b00 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72  the third.** par
20b10 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
20b20 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
20b30 69 7a 65 72 28 29 20 69 6e 74 65 72 66 61 63 65  izer() interface
20b40 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61  . ^The second pa
20b50 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68  rameter.** to th
20b60 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e  e callback is an
20b70 20 69 6e 74 65 67 65 72 20 5b 53 51 4c 49 54 45   integer [SQLITE
20b80 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 63  _COPY | action c
20b90 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63 69 66  ode] that specif
20ba0 69 65 73 0a 2a 2a 20 74 68 65 20 70 61 72 74 69  ies.** the parti
20bb0 63 75 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f 20  cular action to 
20bc0 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 5e  be authorized. ^
20bd0 54 68 65 20 74 68 69 72 64 20 74 68 72 6f 75 67  The third throug
20be0 68 20 73 69 78 74 68 20 70 61 72 61 6d 65 74 65  h sixth paramete
20bf0 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c  rs.** to the cal
20c00 6c 62 61 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74  lback are zero-t
20c10 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67  erminated string
20c20 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61  s that contain a
20c30 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74  dditional.** det
20c40 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61  ails about the a
20c50 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68  ction to be auth
20c60 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  orized..**.** ^I
20c70 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64  f the action cod
20c80 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 41  e is [SQLITE_REA
20c90 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63 61  D].** and the ca
20ca0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b  llback returns [
20cb0 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74  SQLITE_IGNORE] t
20cc0 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70  hen the.** [prep
20cd0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
20ce0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e  statement is con
20cf0 73 74 72 75 63 74 65 64 20 74 6f 20 73 75 62 73  structed to subs
20d00 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c  titute.** a NULL
20d10 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20   value in place 
20d20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c  of the table col
20d30 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68  umn that would h
20d40 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64  ave.** been read
20d50 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20   if [SQLITE_OK] 
20d60 68 61 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65  had been returne
20d70 64 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  d.  The [SQLITE_
20d80 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72  IGNORE].** retur
20d90 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  n can be used to
20da0 20 64 65 6e 79 20 61 6e 20 75 6e 74 72 75 73 74   deny an untrust
20db0 65 64 20 75 73 65 72 20 61 63 63 65 73 73 20 74  ed user access t
20dc0 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20  o individual.** 
20dd0 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61 62  columns of a tab
20de0 6c 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61  le..** ^If the a
20df0 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53  ction code is [S
20e00 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e  QLITE_DELETE] an
20e10 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  d the callback r
20e20 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54  eturns.** [SQLIT
20e30 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74  E_IGNORE] then t
20e40 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72  he [DELETE] oper
20e50 61 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 20 62  ation proceeds b
20e60 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63  ut the.** [trunc
20e70 61 74 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e  ate optimization
20e80 5d 20 69 73 20 64 69 73 61 62 6c 65 64 20 61 6e  ] is disabled an
20e90 64 20 61 6c 6c 20 72 6f 77 73 20 61 72 65 20 64  d all rows are d
20ea0 65 6c 65 74 65 64 20 69 6e 64 69 76 69 64 75 61  eleted individua
20eb0 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75  lly..**.** An au
20ec0 74 68 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64  thorizer is used
20ed0 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70   when [sqlite3_p
20ee0 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 69  repare | prepari
20ef0 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  ng].** SQL state
20f00 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e  ments from an un
20f10 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 2c 20  trusted source, 
20f20 74 6f 20 65 6e 73 75 72 65 20 74 68 61 74 20 74  to ensure that t
20f30 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
20f40 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20  s.** do not try 
20f50 74 6f 20 61 63 63 65 73 73 20 64 61 74 61 20 74  to access data t
20f60 68 65 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f  hey are not allo
20f70 77 65 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 74  wed to see, or t
20f80 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a  hat they do not.
20f90 2a 2a 20 74 72 79 20 74 6f 20 65 78 65 63 75 74  ** try to execut
20fa0 65 20 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 74  e malicious stat
20fb0 65 6d 65 6e 74 73 20 74 68 61 74 20 64 61 6d 61  ements that dama
20fc0 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2e  ge the database.
20fd0 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65    For.** example
20fe0 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  , an application
20ff0 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 65   may allow a use
21000 72 20 74 6f 20 65 6e 74 65 72 20 61 72 62 69 74  r to enter arbit
21010 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72  rary.** SQL quer
21020 69 65 73 20 66 6f 72 20 65 76 61 6c 75 61 74 69  ies for evaluati
21030 6f 6e 20 62 79 20 61 20 64 61 74 61 62 61 73 65  on by a database
21040 2e 20 20 42 75 74 20 74 68 65 20 61 70 70 6c 69  .  But the appli
21050 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e  cation does.** n
21060 6f 74 20 77 61 6e 74 20 74 68 65 20 75 73 65 72  ot want the user
21070 20 74 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 6d   to be able to m
21080 61 6b 65 20 61 72 62 69 74 72 61 72 79 20 63 68  ake arbitrary ch
21090 61 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20  anges to the.** 
210a0 64 61 74 61 62 61 73 65 2e 20 20 41 6e 20 61 75  database.  An au
210b0 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 74  thorizer could t
210c0 68 65 6e 20 62 65 20 70 75 74 20 69 6e 20 70 6c  hen be put in pl
210d0 61 63 65 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a  ace while the.**
210e0 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51   user-entered SQ
210f0 4c 20 69 73 20 62 65 69 6e 67 20 5b 73 71 6c 69  L is being [sqli
21100 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72  te3_prepare | pr
21110 65 70 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20  epared] that.** 
21120 64 69 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 74  disallows everyt
21130 68 69 6e 67 20 65 78 63 65 70 74 20 5b 53 45 4c  hing except [SEL
21140 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e  ECT] statements.
21150 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  .**.** Applicati
21160 6f 6e 73 20 74 68 61 74 20 6e 65 65 64 20 74 6f  ons that need to
21170 20 70 72 6f 63 65 73 73 20 53 51 4c 20 66 72 6f   process SQL fro
21180 6d 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72  m untrusted sour
21190 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73  ces.** might als
211a0 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72  o consider lower
211b0 69 6e 67 20 72 65 73 6f 75 72 63 65 20 6c 69 6d  ing resource lim
211c0 69 74 73 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  its using [sqlit
211d0 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61  e3_limit()].** a
211e0 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64 61 74 61  nd limiting data
211f0 62 61 73 65 20 73 69 7a 65 20 75 73 69 6e 67 20  base size using 
21200 74 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f  the [max_page_co
21210 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a  unt] [PRAGMA].**
21220 20 69 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f 20   in addition to 
21230 75 73 69 6e 67 20 61 6e 20 61 75 74 68 6f 72 69  using an authori
21240 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c  zer..**.** ^(Onl
21250 79 20 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f  y a single autho
21260 72 69 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20  rizer can be in 
21270 70 6c 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62  place on a datab
21280 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
21290 2a 20 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61  * at a time.  Ea
212a0 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  ch call to sqlit
212b0 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
212c0 72 20 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a  r overrides the.
212d0 2a 2a 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c  ** previous call
212e0 2e 29 5e 20 20 5e 44 69 73 61 62 6c 65 20 74 68  .)^  ^Disable th
212f0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 62 79 20  e authorizer by 
21300 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c  installing a NUL
21310 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54  L callback..** T
21320 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73  he authorizer is
21330 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66   disabled by def
21340 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ault..**.** The 
21350 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
21360 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20  ack must not do 
21370 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69  anything that wi
21380 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65  ll modify.** the
21390 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
213a0 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65  tion that invoke
213b0 64 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  d the authorizer
213c0 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f   callback..** No
213d0 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33  te that [sqlite3
213e0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
213f0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  nd [sqlite3_step
21400 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20  ()] both modify 
21410 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73  their.** databas
21420 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f  e connections fo
21430 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66  r the meaning of
21440 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69   "modify" in thi
21450 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a  s paragraph..**.
21460 2a 2a 20 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65  ** ^When [sqlite
21470 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
21480 69 73 20 75 73 65 64 20 74 6f 20 70 72 65 70 61  is used to prepa
21490 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 20  re a statement, 
214a0 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  the.** statement
214b0 20 6d 69 67 68 74 20 62 65 20 72 65 2d 70 72 65   might be re-pre
214c0 70 61 72 65 64 20 64 75 72 69 6e 67 20 5b 73 71  pared during [sq
214d0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 64 75  lite3_step()] du
214e0 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d  e to a .** schem
214f0 61 20 63 68 61 6e 67 65 2e 20 20 48 65 6e 63 65  a change.  Hence
21500 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  , the applicatio
21510 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75 72 65 20  n should ensure 
21520 74 68 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72  that the.** corr
21530 65 63 74 20 61 75 74 68 6f 72 69 7a 65 72 20 63  ect authorizer c
21540 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73 20  allback remains 
21550 69 6e 20 70 6c 61 63 65 20 64 75 72 69 6e 67 20  in place during 
21560 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  the [sqlite3_ste
21570 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74  p()]..**.** ^Not
21580 65 20 74 68 61 74 20 74 68 65 20 61 75 74 68 6f  e that the autho
21590 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
215a0 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64  s invoked only d
215b0 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  uring.** [sqlite
215c0 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20  3_prepare()] or 
215d0 69 74 73 20 76 61 72 69 61 6e 74 73 2e 20 20 41  its variants.  A
215e0 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20  uthorization is 
215f0 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64  not.** performed
21600 20 64 75 72 69 6e 67 20 73 74 61 74 65 6d 65 6e   during statemen
21610 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20  t evaluation in 
21620 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
21630 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73  , unless.** as s
21640 74 61 74 65 64 20 69 6e 20 74 68 65 20 70 72 65  tated in the pre
21650 76 69 6f 75 73 20 70 61 72 61 67 72 61 70 68 2c  vious paragraph,
21660 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
21670 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74  invokes.** sqlit
21680 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20  e3_prepare_v2() 
21690 74 6f 20 72 65 70 72 65 70 61 72 65 20 61 20 73  to reprepare a s
216a0 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 61  tatement after a
216b0 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a   schema change..
216c0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
216d0 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
216e0 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74   sqlite3_set_aut
216f0 68 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c 69 74  horizer(.  sqlit
21700 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75  e3*,.  int (*xAu
21710 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  th)(void*,int,co
21720 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20  nst char*,const 
21730 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
21740 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a  *,const char*),.
21750 20 20 76 6f 69 64 20 2a 70 55 73 65 72 44 61 74    void *pUserDat
21760 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  a.);../*.** CAPI
21770 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72  3REF: Authorizer
21780 20 52 65 74 75 72 6e 20 43 6f 64 65 73 0a 2a 2a   Return Codes.**
21790 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
217a0 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20  _set_authorizer 
217b0 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  | authorizer cal
217c0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20  lback function] 
217d0 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65  must.** return e
217e0 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b  ither [SQLITE_OK
217f0 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 73  ] or one of thes
21800 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20  e two constants 
21810 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73  in order.** to s
21820 69 67 6e 61 6c 20 53 51 4c 69 74 65 20 77 68 65  ignal SQLite whe
21830 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20  ther or not the 
21840 61 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74  action is permit
21850 74 65 64 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a  ted.  See the.**
21860 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
21870 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f  thorizer | autho
21880 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61 74  rizer documentat
21890 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74 69 6f  ion] for additio
218a0 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  nal.** informati
218b0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  on..**.** Note t
218c0 68 61 74 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52  hat SQLITE_IGNOR
218d0 45 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20 61  E is also used a
218e0 73 20 61 20 5b 63 6f 6e 66 6c 69 63 74 20 72 65  s a [conflict re
218f0 73 6f 6c 75 74 69 6f 6e 20 6d 6f 64 65 5d 0a 2a  solution mode].*
21900 2a 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20  * returned from 
21910 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 74 61  the [sqlite3_vta
21920 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d  b_on_conflict()]
21930 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23   interface..*/.#
21940 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45  define SQLITE_DE
21950 4e 59 20 20 20 31 20 20 20 2f 2a 20 41 62 6f 72  NY   1   /* Abor
21960 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  t the SQL statem
21970 65 6e 74 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ent with an erro
21980 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  r */.#define SQL
21990 49 54 45 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f  ITE_IGNORE 2   /
219a0 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63  * Don't allow ac
219b0 63 65 73 73 2c 20 62 75 74 20 64 6f 6e 27 74 20  cess, but don't 
219c0 67 65 6e 65 72 61 74 65 20 61 6e 20 65 72 72 6f  generate an erro
219d0 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  r */../*.** CAPI
219e0 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72  3REF: Authorizer
219f0 20 41 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a   Action Codes.**
21a00 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
21a10 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28  _set_authorizer(
21a20 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 67  )] interface reg
21a30 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63  isters a callbac
21a40 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68  k function.** th
21a50 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f  at is invoked to
21a60 20 61 75 74 68 6f 72 69 7a 65 20 63 65 72 74 61   authorize certa
21a70 69 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  in SQL statement
21a80 20 61 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a   actions.  The.*
21a90 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  * second paramet
21aa0 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  er to the callba
21ab0 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ck is an integer
21ac0 20 63 6f 64 65 20 74 68 61 74 20 73 70 65 63 69   code that speci
21ad0 66 69 65 73 0a 2a 2a 20 77 68 61 74 20 61 63 74  fies.** what act
21ae0 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 61 75 74  ion is being aut
21af0 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 73 65 20  horized.  These 
21b00 61 72 65 20 74 68 65 20 69 6e 74 65 67 65 72 20  are the integer 
21b10 61 63 74 69 6f 6e 20 63 6f 64 65 73 20 74 68 61  action codes tha
21b20 74 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69  t.** the authori
21b30 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79  zer callback may
21b40 20 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a   be passed..**.*
21b50 2a 20 54 68 65 73 65 20 61 63 74 69 6f 6e 20 63  * These action c
21b60 6f 64 65 20 76 61 6c 75 65 73 20 73 69 67 6e 69  ode values signi
21b70 66 79 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20  fy what kind of 
21b80 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 74 6f 20  operation is to 
21b90 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64  be.** authorized
21ba0 2e 20 20 54 68 65 20 33 72 64 20 61 6e 64 20 34  .  The 3rd and 4
21bb0 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  th parameters to
21bc0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69   the authorizati
21bd0 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66  on.** callback f
21be0 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20  unction will be 
21bf0 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55  parameters or NU
21c00 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  LL depending on 
21c10 77 68 69 63 68 20 6f 66 20 74 68 65 73 65 0a 2a  which of these.*
21c20 2a 20 63 6f 64 65 73 20 69 73 20 75 73 65 64 20  * codes is used 
21c30 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  as the second pa
21c40 72 61 6d 65 74 65 72 2e 20 20 5e 28 54 68 65 20  rameter.  ^(The 
21c50 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  5th parameter to
21c60 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a   the.** authoriz
21c70 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74  er callback is t
21c80 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64  he name of the d
21c90 61 74 61 62 61 73 65 20 28 22 6d 61 69 6e 22 2c  atabase ("main",
21ca0 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e   "temp",.** etc.
21cb0 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65 2e  ) if applicable.
21cc0 29 5e 20 20 5e 54 68 65 20 36 74 68 20 70 61 72  )^  ^The 6th par
21cd0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75  ameter to the au
21ce0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
21cf0 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65  k.** is the name
21d00 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f   of the inner-mo
21d10 73 74 20 74 72 69 67 67 65 72 20 6f 72 20 76 69  st trigger or vi
21d20 65 77 20 74 68 61 74 20 69 73 20 72 65 73 70 6f  ew that is respo
21d30 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68  nsible for.** th
21d40 65 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74  e access attempt
21d50 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73   or NULL if this
21d60 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20   access attempt 
21d70 69 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d  is directly from
21d80 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51  .** top-level SQ
21d90 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a  L code..*/./****
21da0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
21db0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
21dc0 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a  ******* 3rd ****
21dd0 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a  ******** 4th ***
21de0 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e  ********/.#defin
21df0 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
21e00 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 31  INDEX          1
21e10 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
21e20 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65        Table Name
21e30 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
21e40 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
21e50 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 20  ABLE          2 
21e60 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
21e70 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
21e80 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
21e90 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45  SQLITE_CREATE_TE
21ea0 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 33 20 20  MP_INDEX     3  
21eb0 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
21ec0 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
21ed0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
21ee0 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d  QLITE_CREATE_TEM
21ef0 50 5f 54 41 42 4c 45 20 20 20 20 20 34 20 20 20  P_TABLE     4   
21f00 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
21f10 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
21f20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
21f30 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
21f40 5f 54 52 49 47 47 45 52 20 20 20 35 20 20 20 2f  _TRIGGER   5   /
21f50 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20  * Trigger Name  
21f60 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
21f70 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
21f80 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f  ITE_CREATE_TEMP_
21f90 56 49 45 57 20 20 20 20 20 20 36 20 20 20 2f 2a  VIEW      6   /*
21fa0 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20   View Name      
21fb0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
21fc0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
21fd0 54 45 5f 43 52 45 41 54 45 5f 54 52 49 47 47 45  TE_CREATE_TRIGGE
21fe0 52 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20  R        7   /* 
21ff0 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20  Trigger Name    
22000 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
22010 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
22020 45 5f 43 52 45 41 54 45 5f 56 49 45 57 20 20 20  E_CREATE_VIEW   
22030 20 20 20 20 20 20 20 20 38 20 20 20 2f 2a 20 56          8   /* V
22040 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e  iew Name       N
22050 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
22060 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
22070 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20  _DELETE         
22080 20 20 20 20 20 20 20 39 20 20 20 2f 2a 20 54 61         9   /* Ta
22090 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
220a0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
220b0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
220c0 44 52 4f 50 5f 49 4e 44 45 58 20 20 20 20 20 20  DROP_INDEX      
220d0 20 20 20 20 20 31 30 20 20 20 2f 2a 20 49 6e 64       10   /* Ind
220e0 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62  ex Name      Tab
220f0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
22100 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
22110 52 4f 50 5f 54 41 42 4c 45 20 20 20 20 20 20 20  ROP_TABLE       
22120 20 20 20 20 31 31 20 20 20 2f 2a 20 54 61 62 6c      11   /* Tabl
22130 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
22140 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
22150 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
22160 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20  OP_TEMP_INDEX   
22170 20 20 20 31 32 20 20 20 2f 2a 20 49 6e 64 65 78     12   /* Index
22180 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
22190 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
221a0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
221b0 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20  P_TEMP_TABLE    
221c0 20 20 31 33 20 20 20 2f 2a 20 54 61 62 6c 65 20    13   /* Table 
221d0 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
221e0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
221f0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
22200 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20  _TEMP_TRIGGER   
22210 20 31 34 20 20 20 2f 2a 20 54 72 69 67 67 65 72   14   /* Trigger
22220 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e   Name    Table N
22230 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
22240 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
22250 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 20  TEMP_VIEW       
22260 31 35 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d  15   /* View Nam
22270 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  e       NULL    
22280 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
22290 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
222a0 52 49 47 47 45 52 20 20 20 20 20 20 20 20 20 31  RIGGER         1
222b0 36 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  6   /* Trigger N
222c0 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
222d0 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
222e0 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49  e SQLITE_DROP_VI
222f0 45 57 20 20 20 20 20 20 20 20 20 20 20 20 31 37  EW            17
22300 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
22310 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
22320 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
22330 20 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 20 20   SQLITE_INSERT  
22340 20 20 20 20 20 20 20 20 20 20 20 20 20 31 38 20               18 
22350 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
22360 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
22370 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
22380 53 51 4c 49 54 45 5f 50 52 41 47 4d 41 20 20 20  SQLITE_PRAGMA   
22390 20 20 20 20 20 20 20 20 20 20 20 20 31 39 20 20              19  
223a0 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65 20   /* Pragma Name 
223b0 20 20 20 20 31 73 74 20 61 72 67 20 6f 72 20 4e      1st arg or N
223c0 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ULL */.#define S
223d0 51 4c 49 54 45 5f 52 45 41 44 20 20 20 20 20 20  QLITE_READ      
223e0 20 20 20 20 20 20 20 20 20 20 20 32 30 20 20 20             20   
223f0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
22400 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20     Column Name  
22410 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
22420 4c 49 54 45 5f 53 45 4c 45 43 54 20 20 20 20 20  LITE_SELECT     
22430 20 20 20 20 20 20 20 20 20 20 32 31 20 20 20 2f            21   /
22440 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20  * NULL          
22450 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
22460 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
22470 49 54 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20  ITE_TRANSACTION 
22480 20 20 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a           22   /*
22490 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20   Operation      
224a0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
224b0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
224c0 54 45 5f 55 50 44 41 54 45 20 20 20 20 20 20 20  TE_UPDATE       
224d0 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20          23   /* 
224e0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
224f0 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20  Column Name     
22500 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
22510 45 5f 41 54 54 41 43 48 20 20 20 20 20 20 20 20  E_ATTACH        
22520 20 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 46         24   /* F
22530 69 6c 65 6e 61 6d 65 20 20 20 20 20 20 20 20 4e  ilename        N
22540 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
22550 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
22560 5f 44 45 54 41 43 48 20 20 20 20 20 20 20 20 20  _DETACH         
22570 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 44 61        25   /* Da
22580 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 4e 55  tabase Name   NU
22590 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
225a0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
225b0 41 4c 54 45 52 5f 54 41 42 4c 45 20 20 20 20 20  ALTER_TABLE     
225c0 20 20 20 20 20 32 36 20 20 20 2f 2a 20 44 61 74       26   /* Dat
225d0 61 62 61 73 65 20 4e 61 6d 65 20 20 20 54 61 62  abase Name   Tab
225e0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
225f0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
22600 45 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20  EINDEX          
22610 20 20 20 20 32 37 20 20 20 2f 2a 20 49 6e 64 65      27   /* Inde
22620 78 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  x Name      NULL
22630 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
22640 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e  define SQLITE_AN
22650 41 4c 59 5a 45 20 20 20 20 20 20 20 20 20 20 20  ALYZE           
22660 20 20 20 32 38 20 20 20 2f 2a 20 54 61 62 6c 65     28   /* Table
22670 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
22680 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
22690 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
226a0 41 54 45 5f 56 54 41 42 4c 45 20 20 20 20 20 20  ATE_VTABLE      
226b0 20 20 32 39 20 20 20 2f 2a 20 54 61 62 6c 65 20    29   /* Table 
226c0 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65  Name      Module
226d0 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65   Name     */.#de
226e0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
226f0 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  _VTABLE         
22700 20 33 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   30   /* Table N
22710 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20  ame      Module 
22720 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66  Name     */.#def
22730 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e 43 54  ine SQLITE_FUNCT
22740 49 4f 4e 20 20 20 20 20 20 20 20 20 20 20 20 20  ION             
22750 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20  31   /* NULL    
22760 20 20 20 20 20 20 20 20 46 75 6e 63 74 69 6f 6e          Function
22770 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69   Name   */.#defi
22780 6e 65 20 53 51 4c 49 54 45 5f 53 41 56 45 50 4f  ne SQLITE_SAVEPO
22790 49 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 33  INT            3
227a0 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e  2   /* Operation
227b0 20 20 20 20 20 20 20 53 61 76 65 70 6f 69 6e 74         Savepoint
227c0 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e   Name  */.#defin
227d0 65 20 53 51 4c 49 54 45 5f 43 4f 50 59 20 20 20  e SQLITE_COPY   
227e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
227f0 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20     /* No longer 
22800 75 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  used */.#define 
22810 53 51 4c 49 54 45 5f 52 45 43 55 52 53 49 56 45  SQLITE_RECURSIVE
22820 20 20 20 20 20 20 20 20 20 20 20 20 33 33 20 20              33  
22830 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20   /* NULL        
22840 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
22850 20 20 20 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41      */../*.** CA
22860 50 49 33 52 45 46 3a 20 54 72 61 63 69 6e 67 20  PI3REF: Tracing 
22870 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 46 75  And Profiling Fu
22880 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  nctions.**.** Th
22890 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67  ese routines reg
228a0 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66  ister callback f
228b0 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61  unctions that ca
228c0 6e 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a  n be used for.**
228d0 20 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f   tracing and pro
228e0 66 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75  filing the execu
228f0 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74  tion of SQL stat
22900 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ements..**.** ^T
22910 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  he callback func
22920 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20  tion registered 
22930 62 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  by sqlite3_trace
22940 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 74  () is invoked at
22950 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 6d 65  .** various time
22960 73 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 73 74  s when an SQL st
22970 61 74 65 6d 65 6e 74 20 69 73 20 62 65 69 6e 67  atement is being
22980 20 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 65 33   run by [sqlite3
22990 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68  _step()]..** ^Th
229a0 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28  e sqlite3_trace(
229b0 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  ) callback is in
229c0 76 6f 6b 65 64 20 77 69 74 68 20 61 20 55 54 46  voked with a UTF
229d0 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20  -8 rendering of 
229e0 74 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  the.** SQL state
229f0 6d 65 6e 74 20 74 65 78 74 20 61 73 20 74 68 65  ment text as the
22a00 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73 74   statement first
22a10 20 62 65 67 69 6e 73 20 65 78 65 63 75 74 69 6e   begins executin
22a20 67 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69 6f 6e  g..** ^(Addition
22a30 61 6c 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  al sqlite3_trace
22a40 28 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d 69 67  () callbacks mig
22a50 68 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65  ht occur.** as e
22a60 61 63 68 20 74 72 69 67 67 65 72 65 64 20 73 75  ach triggered su
22a70 62 70 72 6f 67 72 61 6d 20 69 73 20 65 6e 74 65  bprogram is ente
22a80 72 65 64 2e 20 20 54 68 65 20 63 61 6c 6c 62 61  red.  The callba
22a90 63 6b 73 20 66 6f 72 20 74 72 69 67 67 65 72 73  cks for triggers
22aa0 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55 54  .** contain a UT
22ab0 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20  F-8 SQL comment 
22ac0 74 68 61 74 20 69 64 65 6e 74 69 66 69 65 73 20  that identifies 
22ad0 74 68 65 20 74 72 69 67 67 65 72 2e 29 5e 0a 2a  the trigger.)^.*
22ae0 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  *.** The [SQLITE
22af0 5f 54 52 41 43 45 5f 53 49 5a 45 5f 4c 49 4d 49  _TRACE_SIZE_LIMI
22b00 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  T] compile-time 
22b10 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73  option can be us
22b20 65 64 20 74 6f 20 6c 69 6d 69 74 0a 2a 2a 20 74  ed to limit.** t
22b30 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 5b 62 6f  he length of [bo
22b40 75 6e 64 20 70 61 72 61 6d 65 74 65 72 5d 20 65  und parameter] e
22b50 78 70 61 6e 73 69 6f 6e 20 69 6e 20 74 68 65 20  xpansion in the 
22b60 6f 75 74 70 75 74 20 6f 66 20 73 71 6c 69 74 65  output of sqlite
22b70 33 5f 74 72 61 63 65 28 29 2e 0a 2a 2a 0a 2a 2a  3_trace()..**.**
22b80 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66   ^The callback f
22b90 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72  unction register
22ba0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70 72  ed by sqlite3_pr
22bb0 6f 66 69 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b  ofile() is invok
22bc0 65 64 0a 2a 2a 20 61 73 20 65 61 63 68 20 53 51  ed.** as each SQ
22bd0 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69  L statement fini
22be0 73 68 65 73 2e 20 20 5e 54 68 65 20 70 72 6f 66  shes.  ^The prof
22bf0 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e  ile callback con
22c00 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69  tains.** the ori
22c10 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 20  ginal statement 
22c20 74 65 78 74 20 61 6e 64 20 61 6e 20 65 73 74 69  text and an esti
22c30 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f  mate of wall-clo
22c40 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f  ck time.** of ho
22c50 77 20 6c 6f 6e 67 20 74 68 61 74 20 73 74 61 74  w long that stat
22c60 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75  ement took to ru
22c70 6e 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65  n.  ^The profile
22c80 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d   callback.** tim
22c90 65 20 69 73 20 69 6e 20 75 6e 69 74 73 20 6f 66  e is in units of
22ca0 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c 20 68 6f   nanoseconds, ho
22cb0 77 65 76 65 72 20 74 68 65 20 63 75 72 72 65 6e  wever the curren
22cc0 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  t implementation
22cd0 0a 2a 2a 20 69 73 20 6f 6e 6c 79 20 63 61 70 61  .** is only capa
22ce0 62 6c 65 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f  ble of milliseco
22cf0 6e 64 20 72 65 73 6f 6c 75 74 69 6f 6e 20 73 6f  nd resolution so
22d00 20 74 68 65 20 73 69 78 20 6c 65 61 73 74 20 73   the six least s
22d10 69 67 6e 69 66 69 63 61 6e 74 0a 2a 2a 20 64 69  ignificant.** di
22d20 67 69 74 73 20 69 6e 20 74 68 65 20 74 69 6d 65  gits in the time
22d30 20 61 72 65 20 6d 65 61 6e 69 6e 67 6c 65 73 73   are meaningless
22d40 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f  .  Future versio
22d50 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20  ns of SQLite.** 
22d60 6d 69 67 68 74 20 70 72 6f 76 69 64 65 20 67 72  might provide gr
22d70 65 61 74 65 72 20 72 65 73 6f 6c 75 74 69 6f 6e  eater resolution
22d80 20 6f 6e 20 74 68 65 20 70 72 6f 66 69 6c 65 72   on the profiler
22d90 20 63 61 6c 6c 62 61 63 6b 2e 20 20 54 68 65 0a   callback.  The.
22da0 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69  ** sqlite3_profi
22db0 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73  le() function is
22dc0 20 63 6f 6e 73 69 64 65 72 65 64 20 65 78 70 65   considered expe
22dd0 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 0a  rimental and is.
22de0 2a 2a 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68  ** subject to ch
22df0 61 6e 67 65 20 69 6e 20 66 75 74 75 72 65 20 76  ange in future v
22e00 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
22e10 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  e..*/.SQLITE_API
22e20 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54   void *SQLITE_ST
22e30 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 74 72  DCALL sqlite3_tr
22e40 61 63 65 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f  ace(sqlite3*, vo
22e50 69 64 28 2a 78 54 72 61 63 65 29 28 76 6f 69 64  id(*xTrace)(void
22e60 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20  *,const char*), 
22e70 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 41  void*);.SQLITE_A
22e80 50 49 20 53 51 4c 49 54 45 5f 45 58 50 45 52 49  PI SQLITE_EXPERI
22e90 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a 53 51 4c  MENTAL void *SQL
22ea0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
22eb0 74 65 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69  te3_profile(sqli
22ec0 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78  te3*,.   void(*x
22ed0 50 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63  Profile)(void*,c
22ee0 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74  onst char*,sqlit
22ef0 65 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69 64  e3_uint64), void
22f00 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
22f10 52 45 46 3a 20 51 75 65 72 79 20 50 72 6f 67 72  REF: Query Progr
22f20 65 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a  ess Callbacks.**
22f30 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
22f40 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65  _progress_handle
22f50 72 28 44 2c 4e 2c 58 2c 50 29 20 69 6e 74 65 72  r(D,N,X,P) inter
22f60 66 61 63 65 20 63 61 75 73 65 73 20 74 68 65 20  face causes the 
22f70 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63  callback.** func
22f80 74 69 6f 6e 20 58 20 74 6f 20 62 65 20 69 6e 76  tion X to be inv
22f90 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c  oked periodicall
22fa0 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 20 72 75  y during long ru
22fb0 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 0a 2a  nning calls to.*
22fc0 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  * [sqlite3_exec(
22fd0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  )], [sqlite3_ste
22fe0 70 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  p()] and [sqlite
22ff0 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 66  3_get_table()] f
23000 6f 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  or.** database c
23010 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 20 41 6e  onnection D.  An
23020 20 65 78 61 6d 70 6c 65 20 75 73 65 20 66 6f 72   example use for
23030 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61   this.** interfa
23040 63 65 20 69 73 20 74 6f 20 6b 65 65 70 20 61 20  ce is to keep a 
23050 47 55 49 20 75 70 64 61 74 65 64 20 64 75 72 69  GUI updated duri
23060 6e 67 20 61 20 6c 61 72 67 65 20 71 75 65 72 79  ng a large query
23070 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 61 72  ..**.** ^The par
23080 61 6d 65 74 65 72 20 50 20 69 73 20 70 61 73 73  ameter P is pass
23090 65 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 68  ed through as th
230a0 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72  e only parameter
230b0 20 74 6f 20 74 68 65 20 0a 2a 2a 20 63 61 6c 6c   to the .** call
230c0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 2e  back function X.
230d0 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72    ^The parameter
230e0 20 4e 20 69 73 20 74 68 65 20 61 70 70 72 6f 78   N is the approx
230f0 69 6d 61 74 65 20 6e 75 6d 62 65 72 20 6f 66 20  imate number of 
23100 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 6d 61 63  .** [virtual mac
23110 68 69 6e 65 20 69 6e 73 74 72 75 63 74 69 6f 6e  hine instruction
23120 73 5d 20 74 68 61 74 20 61 72 65 20 65 76 61 6c  s] that are eval
23130 75 61 74 65 64 20 62 65 74 77 65 65 6e 20 73 75  uated between su
23140 63 63 65 73 73 69 76 65 0a 2a 2a 20 69 6e 76 6f  ccessive.** invo
23150 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 63  cations of the c
23160 61 6c 6c 62 61 63 6b 20 58 2e 20 20 5e 49 66 20  allback X.  ^If 
23170 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 6f  N is less than o
23180 6e 65 20 74 68 65 6e 20 74 68 65 20 70 72 6f 67  ne then the prog
23190 72 65 73 73 0a 2a 2a 20 68 61 6e 64 6c 65 72 20  ress.** handler 
231a0 69 73 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a  is disabled..**.
231b0 2a 2a 20 5e 4f 6e 6c 79 20 61 20 73 69 6e 67 6c  ** ^Only a singl
231c0 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  e progress handl
231d0 65 72 20 6d 61 79 20 62 65 20 64 65 66 69 6e 65  er may be define
231e0 64 20 61 74 20 6f 6e 65 20 74 69 6d 65 20 70 65  d at one time pe
231f0 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  r.** [database c
23200 6f 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73 65 74 74  onnection]; sett
23210 69 6e 67 20 61 20 6e 65 77 20 70 72 6f 67 72 65  ing a new progre
23220 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6e 63 65  ss handler cance
23230 6c 73 20 74 68 65 0a 2a 2a 20 6f 6c 64 20 6f 6e  ls the.** old on
23240 65 2e 20 20 5e 53 65 74 74 69 6e 67 20 70 61 72  e.  ^Setting par
23250 61 6d 65 74 65 72 20 58 20 74 6f 20 4e 55 4c 4c  ameter X to NULL
23260 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 70 72   disables the pr
23270 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a  ogress handler..
23280 2a 2a 20 5e 54 68 65 20 70 72 6f 67 72 65 73 73  ** ^The progress
23290 20 68 61 6e 64 6c 65 72 20 69 73 20 61 6c 73 6f   handler is also
232a0 20 64 69 73 61 62 6c 65 64 20 62 79 20 73 65 74   disabled by set
232b0 74 69 6e 67 20 4e 20 74 6f 20 61 20 76 61 6c 75  ting N to a valu
232c0 65 20 6c 65 73 73 0a 2a 2a 20 74 68 61 6e 20 31  e less.** than 1
232d0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
232e0 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63  progress callbac
232f0 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65  k returns non-ze
23300 72 6f 2c 20 74 68 65 20 6f 70 65 72 61 74 69 6f  ro, the operatio
23310 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72 75 70  n is.** interrup
23320 74 65 64 2e 20 20 54 68 69 73 20 66 65 61 74 75  ted.  This featu
23330 72 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  re can be used t
23340 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a  o implement a.**
23350 20 22 43 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e   "Cancel" button
23360 20 6f 6e 20 61 20 47 55 49 20 70 72 6f 67 72 65   on a GUI progre
23370 73 73 20 64 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a  ss dialog box..*
23380 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72 65 73  *.** The progres
23390 73 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61  s handler callba
233a0 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61  ck must not do a
233b0 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c  nything that wil
233c0 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20  l modify.** the 
233d0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
233e0 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64  ion that invoked
233f0 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 61   the progress ha
23400 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74  ndler..** Note t
23410 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  hat [sqlite3_pre
23420 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b  pare_v2()] and [
23430 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
23440 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69  both modify thei
23450 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  r.** database co
23460 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68  nnections for th
23470 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f  e meaning of "mo
23480 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61  dify" in this pa
23490 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 53  ragraph..**.*/.S
234a0 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 53  QLITE_API void S
234b0 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
234c0 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68  lite3_progress_h
234d0 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c  andler(sqlite3*,
234e0 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69   int, int(*)(voi
234f0 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  d*), void*);../*
23500 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70  .** CAPI3REF: Op
23510 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74 61  ening A New Data
23520 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a  base Connection.
23530 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
23540 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53 51  tines open an SQ
23550 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 66 69  Lite database fi
23560 6c 65 20 61 73 20 73 70 65 63 69 66 69 65 64 20  le as specified 
23570 62 79 20 74 68 65 20 0a 2a 2a 20 66 69 6c 65 6e  by the .** filen
23580 61 6d 65 20 61 72 67 75 6d 65 6e 74 2e 20 5e 54  ame argument. ^T
23590 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75  he filename argu
235a0 6d 65 6e 74 20 69 73 20 69 6e 74 65 72 70 72 65  ment is interpre
235b0 74 65 64 20 61 73 20 55 54 46 2d 38 20 66 6f 72  ted as UTF-8 for
235c0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  .** sqlite3_open
235d0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f  () and sqlite3_o
235e0 70 65 6e 5f 76 32 28 29 20 61 6e 64 20 61 73 20  pen_v2() and as 
235f0 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61  UTF-16 in the na
23600 74 69 76 65 20 62 79 74 65 0a 2a 2a 20 6f 72 64  tive byte.** ord
23610 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  er for sqlite3_o
23620 70 65 6e 31 36 28 29 2e 20 5e 28 41 20 5b 64 61  pen16(). ^(A [da
23630 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
23640 6e 5d 20 68 61 6e 64 6c 65 20 69 73 20 75 73 75  n] handle is usu
23650 61 6c 6c 79 0a 2a 2a 20 72 65 74 75 72 6e 65 64  ally.** returned
23660 20 69 6e 20 2a 70 70 44 62 2c 20 65 76 65 6e 20   in *ppDb, even 
23670 69 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75  if an error occu
23680 72 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 65 78  rs.  The only ex
23690 63 65 70 74 69 6f 6e 20 69 73 20 74 68 61 74 0a  ception is that.
236a0 2a 2a 20 69 66 20 53 51 4c 69 74 65 20 69 73 20  ** if SQLite is 
236b0 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61  unable to alloca
236c0 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c  te memory to hol
236d0 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20  d the [sqlite3] 
236e0 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c  object,.** a NUL
236f0 4c 20 77 69 6c 6c 20 62 65 20 77 72 69 74 74 65  L will be writte
23700 6e 20 69 6e 74 6f 20 2a 70 70 44 62 20 69 6e 73  n into *ppDb ins
23710 74 65 61 64 20 6f 66 20 61 20 70 6f 69 6e 74 65  tead of a pointe
23720 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  r to the [sqlite
23730 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e 29 5e 20  3].** object.)^ 
23740 5e 28 49 66 20 74 68 65 20 64 61 74 61 62 61 73  ^(If the databas
23750 65 20 69 73 20 6f 70 65 6e 65 64 20 28 61 6e 64  e is opened (and
23760 2f 6f 72 20 63 72 65 61 74 65 64 29 20 73 75 63  /or created) suc
23770 63 65 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e 0a  cessfully, then.
23780 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69  ** [SQLITE_OK] i
23790 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68  s returned.  Oth
237a0 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72  erwise an [error
237b0 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e   code] is return
237c0 65 64 2e 29 5e 20 5e 54 68 65 0a 2a 2a 20 5b 73  ed.)^ ^The.** [s
237d0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
237e0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72   or [sqlite3_err
237f0 6d 73 67 31 36 28 29 5d 20 72 6f 75 74 69 6e 65  msg16()] routine
23800 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  s can be used to
23810 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e   obtain.** an En
23820 67 6c 69 73 68 20 6c 61 6e 67 75 61 67 65 20 64  glish language d
23830 65 73 63 72 69 70 74 69 6f 6e 20 6f 66 20 74 68  escription of th
23840 65 20 65 72 72 6f 72 20 66 6f 6c 6c 6f 77 69 6e  e error followin
23850 67 20 61 20 66 61 69 6c 75 72 65 20 6f 66 20 61  g a failure of a
23860 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c  ny.** of the sql
23870 69 74 65 33 5f 6f 70 65 6e 28 29 20 72 6f 75 74  ite3_open() rout
23880 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ines..**.** ^The
23890 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e   default encodin
238a0 67 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 38 20  g will be UTF-8 
238b0 66 6f 72 20 64 61 74 61 62 61 73 65 73 20 63 72  for databases cr
238c0 65 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20 73  eated using.** s
238d0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72  qlite3_open() or
238e0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
238f0 28 29 2e 20 20 5e 54 68 65 20 64 65 66 61 75 6c  ().  ^The defaul
23900 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 64  t encoding for d
23910 61 74 61 62 61 73 65 73 0a 2a 2a 20 63 72 65 61  atabases.** crea
23920 74 65 64 20 75 73 69 6e 67 20 73 71 6c 69 74 65  ted using sqlite
23930 33 5f 6f 70 65 6e 31 36 28 29 20 77 69 6c 6c 20  3_open16() will 
23940 62 65 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65  be UTF-16 in the
23950 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
23960 65 72 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65  er..**.** Whethe
23970 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f  r or not an erro
23980 72 20 6f 63 63 75 72 73 20 77 68 65 6e 20 69 74  r occurs when it
23990 20 69 73 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f   is opened, reso
239a0 75 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61  urces.** associa
239b0 74 65 64 20 77 69 74 68 20 74 68 65 20 5b 64 61  ted with the [da
239c0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
239d0 6e 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64  n] handle should
239e0 20 62 65 20 72 65 6c 65 61 73 65 64 20 62 79 0a   be released by.
239f0 2a 2a 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f  ** passing it to
23a00 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28   [sqlite3_close(
23a10 29 5d 20 77 68 65 6e 20 69 74 20 69 73 20 6e 6f  )] when it is no
23a20 20 6c 6f 6e 67 65 72 20 72 65 71 75 69 72 65 64   longer required
23a30 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
23a40 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e  te3_open_v2() in
23a50 74 65 72 66 61 63 65 20 77 6f 72 6b 73 20 6c 69  terface works li
23a60 6b 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ke sqlite3_open(
23a70 29 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74  ).** except that
23a80 20 69 74 20 61 63 63 65 70 74 73 20 74 77 6f 20   it accepts two 
23a90 61 64 64 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d  additional param
23aa0 65 74 65 72 73 20 66 6f 72 20 61 64 64 69 74 69  eters for additi
23ab0 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20  onal control.** 
23ac0 6f 76 65 72 20 74 68 65 20 6e 65 77 20 64 61 74  over the new dat
23ad0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
23ae0 2e 20 20 5e 28 54 68 65 20 66 6c 61 67 73 20 70  .  ^(The flags p
23af0 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 73  arameter to.** s
23b00 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
23b10 20 63 61 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66   can take one of
23b20 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e  .** the followin
23b30 67 20 74 68 72 65 65 20 76 61 6c 75 65 73 2c 20  g three values, 
23b40 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69  optionally combi
23b50 6e 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a  ned with the .**
23b60 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f   [SQLITE_OPEN_NO
23b70 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f  MUTEX], [SQLITE_
23b80 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c  OPEN_FULLMUTEX],
23b90 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48   [SQLITE_OPEN_SH
23ba0 41 52 45 44 43 41 43 48 45 5d 2c 0a 2a 2a 20 5b  AREDCACHE],.** [
23bb0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56  SQLITE_OPEN_PRIV
23bc0 41 54 45 43 41 43 48 45 5d 2c 20 61 6e 64 2f 6f  ATECACHE], and/o
23bd0 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55  r [SQLITE_OPEN_U
23be0 52 49 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a  RI] flags:)^.**.
23bf0 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74  ** <dl>.** ^(<dt
23c00 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45  >[SQLITE_OPEN_RE
23c10 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20  ADONLY]</dt>.** 
23c20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65  <dd>The database
23c30 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 72 65   is opened in re
23c40 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49  ad-only mode.  I
23c50 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 64  f the database d
23c60 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61  oes not.** alrea
23c70 64 79 20 65 78 69 73 74 2c 20 61 6e 20 65 72 72  dy exist, an err
23c80 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c  or is returned.<
23c90 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c  /dd>)^.**.** ^(<
23ca0 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  dt>[SQLITE_OPEN_
23cb0 52 45 41 44 57 52 49 54 45 5d 3c 2f 64 74 3e 0a  READWRITE]</dt>.
23cc0 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62  ** <dd>The datab
23cd0 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f  ase is opened fo
23ce0 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72  r reading and wr
23cf0 69 74 69 6e 67 20 69 66 20 70 6f 73 73 69 62 6c  iting if possibl
23d00 65 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a 2a 2a  e, or reading.**
23d10 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 66 69 6c   only if the fil
23d20 65 20 69 73 20 77 72 69 74 65 20 70 72 6f 74 65  e is write prote
23d30 63 74 65 64 20 62 79 20 74 68 65 20 6f 70 65 72  cted by the oper
23d40 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 49  ating system.  I
23d50 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63 61 73 65  n either.** case
23d60 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6d 75   the database mu
23d70 73 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74  st already exist
23d80 2c 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 65  , otherwise an e
23d90 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64  rror is returned
23da0 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  .</dd>)^.**.** ^
23db0 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45  (<dt>[SQLITE_OPE
23dc0 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b  N_READWRITE] | [
23dd0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
23de0 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TE]</dt>.** <dd>
23df0 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  The database is 
23e00 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69  opened for readi
23e10 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 2c 20  ng and writing, 
23e20 61 6e 64 20 69 73 20 63 72 65 61 74 65 64 20 69  and is created i
23e30 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74  f.** it does not
23e40 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2e 20   already exist. 
23e50 54 68 69 73 20 69 73 20 74 68 65 20 62 65 68 61  This is the beha
23e60 76 69 6f 72 20 74 68 61 74 20 69 73 20 61 6c 77  vior that is alw
23e70 61 79 73 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20  ays used for.** 
23e80 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61  sqlite3_open() a
23e90 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  nd sqlite3_open1
23ea0 36 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c  6().</dd>)^.** <
23eb0 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  /dl>.**.** If th
23ec0 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  e 3rd parameter 
23ed0 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
23ee0 76 32 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20  v2() is not one 
23ef0 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e  of the.** combin
23f00 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f  ations shown abo
23f10 76 65 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f  ve optionally co
23f20 6d 62 69 6e 65 64 20 77 69 74 68 20 6f 74 68 65  mbined with othe
23f30 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45  r.** [SQLITE_OPE
23f40 4e 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 53 51 4c  N_READONLY | SQL
23f50 49 54 45 5f 4f 50 45 4e 5f 2a 20 62 69 74 73 5d  ITE_OPEN_* bits]
23f60 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68  .** then the beh
23f70 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e  avior is undefin
23f80 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ed..**.** ^If th
23f90 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e  e [SQLITE_OPEN_N
23fa0 4f 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20  OMUTEX] flag is 
23fb0 73 65 74 2c 20 74 68 65 6e 20 74 68 65 20 64 61  set, then the da
23fc0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
23fd0 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68  n.** opens in th
23fe0 65 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b  e multi-thread [
23ff0 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
24000 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 73  as long as the s
24010 69 6e 67 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20  ingle-thread.** 
24020 6d 6f 64 65 20 68 61 73 20 6e 6f 74 20 62 65 65  mode has not bee
24030 6e 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65  n set at compile
24040 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74  -time or start-t
24050 69 6d 65 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a  ime.  ^If the.**
24060 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55   [SQLITE_OPEN_FU
24070 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73  LLMUTEX] flag is
24080 20 73 65 74 20 74 68 65 6e 20 74 68 65 20 64 61   set then the da
24090 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
240a0 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68  n opens.** in th
240b0 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68  e serialized [th
240c0 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e  reading mode] un
240d0 6c 65 73 73 20 73 69 6e 67 6c 65 2d 74 68 72 65  less single-thre
240e0 61 64 20 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f  ad was.** previo
240f0 75 73 6c 79 20 73 65 6c 65 63 74 65 64 20 61 74  usly selected at
24100 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72   compile-time or
24110 20 73 74 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20   start-time..** 
24120 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  ^The [SQLITE_OPE
24130 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d 20 66  N_SHAREDCACHE] f
24140 6c 61 67 20 63 61 75 73 65 73 20 74 68 65 20 64  lag causes the d
24150 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
24160 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 65 6c 69 67  on to be.** elig
24170 69 62 6c 65 20 74 6f 20 75 73 65 20 5b 73 68 61  ible to use [sha
24180 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c  red cache mode],
24190 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77   regardless of w
241a0 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68  hether or not sh
241b0 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 69 73  ared.** cache is
241c0 20 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 20 5b   enabled using [
241d0 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73  sqlite3_enable_s
241e0 68 61 72 65 64 5f 63 61 63 68 65 28 29 5d 2e 20  hared_cache()]. 
241f0 20 5e 54 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45   ^The.** [SQLITE
24200 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43  _OPEN_PRIVATECAC
24210 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20  HE] flag causes 
24220 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
24230 6e 65 63 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a  nection to not.*
24240 2a 20 70 61 72 74 69 63 69 70 61 74 65 20 69 6e  * participate in
24250 20 5b 73 68 61 72 65 64 20 63 61 63 68 65 20 6d   [shared cache m
24260 6f 64 65 5d 20 65 76 65 6e 20 69 66 20 69 74 20  ode] even if it 
24270 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a  is enabled..**.*
24280 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61  * ^The fourth pa
24290 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
242a0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20  e3_open_v2() is 
242b0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a  the name of the.
242c0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  ** [sqlite3_vfs]
242d0 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66   object that def
242e0 69 6e 65 73 20 74 68 65 20 6f 70 65 72 61 74 69  ines the operati
242f0 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66  ng system interf
24300 61 63 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ace that.** the 
24310 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e  new database con
24320 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75  nection should u
24330 73 65 2e 20 20 5e 49 66 20 74 68 65 20 66 6f 75  se.  ^If the fou
24340 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  rth parameter is
24350 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  .** a NULL point
24360 65 72 20 74 68 65 6e 20 74 68 65 20 64 65 66 61  er then the defa
24370 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  ult [sqlite3_vfs
24380 5d 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64  ] object is used
24390 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
243a0 66 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65  filename is ":me
243b0 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 20 70  mory:", then a p
243c0 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72  rivate, temporar
243d0 79 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61  y in-memory data
243e0 62 61 73 65 0a 2a 2a 20 69 73 20 63 72 65 61 74  base.** is creat
243f0 65 64 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65  ed for the conne
24400 63 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 69 6e  ction.  ^This in
24410 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65  -memory database
24420 20 77 69 6c 6c 20 76 61 6e 69 73 68 20 77 68 65   will vanish whe
24430 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  n.** the databas
24440 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
24450 63 6c 6f 73 65 64 2e 20 20 46 75 74 75 72 65 20  closed.  Future 
24460 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
24470 74 65 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65  te might.** make
24480 20 75 73 65 20 6f 66 20 61 64 64 69 74 69 6f 6e   use of addition
24490 61 6c 20 73 70 65 63 69 61 6c 20 66 69 6c 65 6e  al special filen
244a0 61 6d 65 73 20 74 68 61 74 20 62 65 67 69 6e 20  ames that begin 
244b0 77 69 74 68 20 74 68 65 20 22 3a 22 20 63 68 61  with the ":" cha
244c0 72 61 63 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73  racter..** It is
244d0 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61   recommended tha
244e0 74 20 77 68 65 6e 20 61 20 64 61 74 61 62 61 73  t when a databas
244f0 65 20 66 69 6c 65 6e 61 6d 65 20 61 63 74 75 61  e filename actua
24500 6c 6c 79 20 64 6f 65 73 20 62 65 67 69 6e 20 77  lly does begin w
24510 69 74 68 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61  ith.** a ":" cha
24520 72 61 63 74 65 72 20 79 6f 75 20 73 68 6f 75 6c  racter you shoul
24530 64 20 70 72 65 66 69 78 20 74 68 65 20 66 69 6c  d prefix the fil
24540 65 6e 61 6d 65 20 77 69 74 68 20 61 20 70 61 74  ename with a pat
24550 68 6e 61 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a  hname such as.**
24560 20 22 2e 2f 22 20 74 6f 20 61 76 6f 69 64 20 61   "./" to avoid a
24570 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20  mbiguity..**.** 
24580 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  ^If the filename
24590 20 69 73 20 61 6e 20 65 6d 70 74 79 20 73 74 72   is an empty str
245a0 69 6e 67 2c 20 74 68 65 6e 20 61 20 70 72 69 76  ing, then a priv
245b0 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a  ate, temporary.*
245c0 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62 61  * on-disk databa
245d0 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65 61 74  se will be creat
245e0 65 64 2e 20 20 5e 54 68 69 73 20 70 72 69 76 61  ed.  ^This priva
245f0 74 65 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c  te database will
24600 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63   be.** automatic
24610 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 61 73 20  ally deleted as 
24620 73 6f 6f 6e 20 61 73 20 74 68 65 20 64 61 74 61  soon as the data
24630 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
24640 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a  is closed..**.**
24650 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73   [[URI filenames
24660 20 69 6e 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   in sqlite3_open
24670 28 29 5d 5d 20 3c 68 33 3e 55 52 49 20 46 69 6c  ()]] <h3>URI Fil
24680 65 6e 61 6d 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a  enames</h3>.**.*
24690 2a 20 5e 49 66 20 5b 55 52 49 20 66 69 6c 65 6e  * ^If [URI filen
246a0 61 6d 65 5d 20 69 6e 74 65 72 70 72 65 74 61 74  ame] interpretat
246b0 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2c 20  ion is enabled, 
246c0 61 6e 64 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  and the filename
246d0 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 62 65 67   argument.** beg
246e0 69 6e 73 20 77 69 74 68 20 22 66 69 6c 65 3a 22  ins with "file:"
246f0 2c 20 74 68 65 6e 20 74 68 65 20 66 69 6c 65 6e  , then the filen
24700 61 6d 65 20 69 73 20 69 6e 74 65 72 70 72 65 74  ame is interpret
24710 65 64 20 61 73 20 61 20 55 52 49 2e 20 5e 55 52  ed as a URI. ^UR
24720 49 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 6e  I.** filename in
24730 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20  terpretation is 
24740 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65 20 5b  enabled if the [
24750 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d  SQLITE_OPEN_URI]
24760 20 66 6c 61 67 20 69 73 0a 2a 2a 20 73 65 74 20   flag is.** set 
24770 69 6e 20 74 68 65 20 66 6f 75 72 74 68 20 61 72  in the fourth ar
24780 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
24790 33 5f 6f 70 65 6e 5f 76 32 28 29 2c 20 6f 72 20  3_open_v2(), or 
247a0 69 66 20 69 74 20 68 61 73 0a 2a 2a 20 62 65 65  if it has.** bee
247b0 6e 20 65 6e 61 62 6c 65 64 20 67 6c 6f 62 61 6c  n enabled global
247c0 6c 79 20 75 73 69 6e 67 20 74 68 65 20 5b 53 51  ly using the [SQ
247d0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d  LITE_CONFIG_URI]
247e0 20 6f 70 74 69 6f 6e 20 77 69 74 68 20 74 68 65   option with the
247f0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
24800 66 69 67 28 29 5d 20 6d 65 74 68 6f 64 20 6f 72  fig()] method or
24810 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   by the [SQLITE_
24820 55 53 45 5f 55 52 49 5d 20 63 6f 6d 70 69 6c 65  USE_URI] compile
24830 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a  -time option..**
24840 20 41 73 20 6f 66 20 53 51 4c 69 74 65 20 76 65   As of SQLite ve
24850 72 73 69 6f 6e 20 33 2e 37 2e 37 2c 20 55 52 49  rsion 3.7.7, URI
24860 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70   filename interp
24870 72 65 74 61 74 69 6f 6e 20 69 73 20 74 75 72 6e  retation is turn
24880 65 64 20 6f 66 66 0a 2a 2a 20 62 79 20 64 65 66  ed off.** by def
24890 61 75 6c 74 2c 20 62 75 74 20 66 75 74 75 72 65  ault, but future
248a0 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c   releases of SQL
248b0 69 74 65 20 6d 69 67 68 74 20 65 6e 61 62 6c 65  ite might enable
248c0 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a   URI filename.**
248d0 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20   interpretation 
248e0 62 79 20 64 65 66 61 75 6c 74 2e 20 20 53 65 65  by default.  See
248f0 20 22 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73   "[URI filenames
24900 5d 22 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  ]" for additiona
24910 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  l.** information
24920 2e 0a 2a 2a 0a 2a 2a 20 55 52 49 20 66 69 6c 65  ..**.** URI file
24930 6e 61 6d 65 73 20 61 72 65 20 70 61 72 73 65 64  names are parsed
24940 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 52 46   according to RF
24950 43 20 33 39 38 36 2e 20 5e 49 66 20 74 68 65 20  C 3986. ^If the 
24960 55 52 49 20 63 6f 6e 74 61 69 6e 73 20 61 6e 0a  URI contains an.
24970 2a 2a 20 61 75 74 68 6f 72 69 74 79 2c 20 74 68  ** authority, th
24980 65 6e 20 69 74 20 6d 75 73 74 20 62 65 20 65 69  en it must be ei
24990 74 68 65 72 20 61 6e 20 65 6d 70 74 79 20 73 74  ther an empty st
249a0 72 69 6e 67 20 6f 72 20 74 68 65 20 73 74 72 69  ring or the stri
249b0 6e 67 20 0a 2a 2a 20 22 6c 6f 63 61 6c 68 6f 73  ng .** "localhos
249c0 74 22 2e 20 5e 49 66 20 74 68 65 20 61 75 74 68  t". ^If the auth
249d0 6f 72 69 74 79 20 69 73 20 6e 6f 74 20 61 6e 20  ority is not an 
249e0 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20  empty string or 
249f0 22 6c 6f 63 61 6c 68 6f 73 74 22 2c 20 61 6e 20  "localhost", an 
24a00 0a 2a 2a 20 65 72 72 6f 72 20 69 73 20 72 65 74  .** error is ret
24a10 75 72 6e 65 64 20 74 6f 20 74 68 65 20 63 61 6c  urned to the cal
24a20 6c 65 72 2e 20 5e 54 68 65 20 66 72 61 67 6d 65  ler. ^The fragme
24a30 6e 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20  nt component of 
24a40 61 20 55 52 49 2c 20 69 66 20 0a 2a 2a 20 70 72  a URI, if .** pr
24a50 65 73 65 6e 74 2c 20 69 73 20 69 67 6e 6f 72 65  esent, is ignore
24a60 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65  d..**.** ^SQLite
24a70 20 75 73 65 73 20 74 68 65 20 70 61 74 68 20 63   uses the path c
24a80 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 74 68 65 20  omponent of the 
24a90 55 52 49 20 61 73 20 74 68 65 20 6e 61 6d 65 20  URI as the name 
24aa0 6f 66 20 74 68 65 20 64 69 73 6b 20 66 69 6c 65  of the disk file
24ab0 0a 2a 2a 20 77 68 69 63 68 20 63 6f 6e 74 61 69  .** which contai
24ac0 6e 73 20 74 68 65 20 64 61 74 61 62 61 73 65 2e  ns the database.
24ad0 20 5e 49 66 20 74 68 65 20 70 61 74 68 20 62 65   ^If the path be
24ae0 67 69 6e 73 20 77 69 74 68 20 61 20 27 2f 27 20  gins with a '/' 
24af0 63 68 61 72 61 63 74 65 72 2c 20 0a 2a 2a 20 74  character, .** t
24b00 68 65 6e 20 69 74 20 69 73 20 69 6e 74 65 72 70  hen it is interp
24b10 72 65 74 65 64 20 61 73 20 61 6e 20 61 62 73 6f  reted as an abso
24b20 6c 75 74 65 20 70 61 74 68 2e 20 5e 49 66 20 74  lute path. ^If t
24b30 68 65 20 70 61 74 68 20 64 6f 65 73 20 6e 6f 74  he path does not
24b40 20 62 65 67 69 6e 20 0a 2a 2a 20 77 69 74 68 20   begin .** with 
24b50 61 20 27 2f 27 20 28 6d 65 61 6e 69 6e 67 20 74  a '/' (meaning t
24b60 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 74  hat the authorit
24b70 79 20 73 65 63 74 69 6f 6e 20 69 73 20 6f 6d 69  y section is omi
24b80 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 55 52  tted from the UR
24b90 49 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 70  I).** then the p
24ba0 61 74 68 20 69 73 20 69 6e 74 65 72 70 72 65 74  ath is interpret
24bb0 65 64 20 61 73 20 61 20 72 65 6c 61 74 69 76 65  ed as a relative
24bc0 20 70 61 74 68 2e 20 0a 2a 2a 20 5e 28 4f 6e 20   path. .** ^(On 
24bd0 77 69 6e 64 6f 77 73 2c 20 74 68 65 20 66 69 72  windows, the fir
24be0 73 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20  st component of 
24bf0 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68  an absolute path
24c00 20 0a 2a 2a 20 69 73 20 61 20 64 72 69 76 65 20   .** is a drive 
24c10 73 70 65 63 69 66 69 63 61 74 69 6f 6e 20 28 65  specification (e
24c20 2e 67 2e 20 22 43 3a 22 29 2e 29 5e 0a 2a 2a 0a  .g. "C:").)^.**.
24c30 2a 2a 20 5b 5b 63 6f 72 65 20 55 52 49 20 71 75  ** [[core URI qu
24c40 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 5d 5d  ery parameters]]
24c50 0a 2a 2a 20 54 68 65 20 71 75 65 72 79 20 63 6f  .** The query co
24c60 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49  mponent of a URI
24c70 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 70 61 72   may contain par
24c80 61 6d 65 74 65 72 73 20 74 68 61 74 20 61 72 65  ameters that are
24c90 20 69 6e 74 65 72 70 72 65 74 65 64 0a 2a 2a 20   interpreted.** 
24ca0 65 69 74 68 65 72 20 62 79 20 53 51 4c 69 74 65  either by SQLite
24cb0 20 69 74 73 65 6c 66 2c 20 6f 72 20 62 79 20 61   itself, or by a
24cc0 20 5b 56 46 53 20 7c 20 63 75 73 74 6f 6d 20 56   [VFS | custom V
24cd0 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
24ce0 6e 5d 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 61 6e  n]..** SQLite an
24cf0 64 20 69 74 73 20 62 75 69 6c 74 2d 69 6e 20 5b  d its built-in [
24d00 56 46 53 65 73 5d 20 69 6e 74 65 72 70 72 65 74  VFSes] interpret
24d10 20 74 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e   the.** followin
24d20 67 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  g query paramete
24d30 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  rs:.**.** <ul>.*
24d40 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 76 66 73 3c  *   <li> <b>vfs<
24d50 2f 62 3e 3a 20 5e 54 68 65 20 22 76 66 73 22 20  /b>: ^The "vfs" 
24d60 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65  parameter may be
24d70 20 75 73 65 64 20 74 6f 20 73 70 65 63 69 66 79   used to specify
24d80 20 74 68 65 20 6e 61 6d 65 20 6f 66 0a 2a 2a 20   the name of.** 
24d90 20 20 20 20 61 20 56 46 53 20 6f 62 6a 65 63 74      a VFS object
24da0 20 74 68 61 74 20 70 72 6f 76 69 64 65 73 20 74   that provides t
24db0 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  he operating sys
24dc0 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68  tem interface th
24dd0 61 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 20 20 20  at should.**    
24de0 20 62 65 20 75 73 65 64 20 74 6f 20 61 63 63 65   be used to acce
24df0 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ss the database 
24e00 66 69 6c 65 20 6f 6e 20 64 69 73 6b 2e 20 5e 49  file on disk. ^I
24e10 66 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73  f this option is
24e20 20 73 65 74 20 74 6f 0a 2a 2a 20 20 20 20 20 61   set to.**     a
24e30 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 74  n empty string t
24e40 68 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 6f  he default VFS o
24e50 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e 20 5e  bject is used. ^
24e60 53 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e  Specifying an un
24e70 6b 6e 6f 77 6e 0a 2a 2a 20 20 20 20 20 56 46 53  known.**     VFS
24e80 20 69 73 20 61 6e 20 65 72 72 6f 72 2e 20 5e 49   is an error. ^I
24e90 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  f sqlite3_open_v
24ea0 32 28 29 20 69 73 20 75 73 65 64 20 61 6e 64 20  2() is used and 
24eb0 74 68 65 20 76 66 73 20 6f 70 74 69 6f 6e 20 69  the vfs option i
24ec0 73 0a 2a 2a 20 20 20 20 20 70 72 65 73 65 6e 74  s.**     present
24ed0 2c 20 74 68 65 6e 20 74 68 65 20 56 46 53 20 73  , then the VFS s
24ee0 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
24ef0 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 70 72 65  option takes pre
24f00 63 65 64 65 6e 63 65 20 6f 76 65 72 0a 2a 2a 20  cedence over.** 
24f10 20 20 20 20 74 68 65 20 76 61 6c 75 65 20 70 61      the value pa
24f20 73 73 65 64 20 61 73 20 74 68 65 20 66 6f 75 72  ssed as the four
24f30 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
24f40 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
24f50 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20  )..**.**   <li> 
24f60 3c 62 3e 6d 6f 64 65 3c 2f 62 3e 3a 20 5e 28 54  <b>mode</b>: ^(T
24f70 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65  he mode paramete
24f80 72 20 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20  r may be set to 
24f90 65 69 74 68 65 72 20 22 72 6f 22 2c 20 22 72 77  either "ro", "rw
24fa0 22 2c 0a 2a 2a 20 20 20 20 20 22 72 77 63 22 2c  ",.**     "rwc",
24fb0 20 6f 72 20 22 6d 65 6d 6f 72 79 22 2e 20 41 74   or "memory". At
24fc0 74 65 6d 70 74 69 6e 67 20 74 6f 20 73 65 74 20  tempting to set 
24fd0 69 74 20 74 6f 20 61 6e 79 20 6f 74 68 65 72 20  it to any other 
24fe0 76 61 6c 75 65 20 69 73 0a 2a 2a 20 20 20 20 20  value is.**     
24ff0 61 6e 20 65 72 72 6f 72 29 5e 2e 20 0a 2a 2a 20  an error)^. .** 
25000 20 20 20 20 5e 49 66 20 22 72 6f 22 20 69 73 20      ^If "ro" is 
25010 73 70 65 63 69 66 69 65 64 2c 20 74 68 65 6e 20  specified, then 
25020 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  the database is 
25030 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d  opened for read-
25040 6f 6e 6c 79 20 0a 2a 2a 20 20 20 20 20 61 63 63  only .**     acc
25050 65 73 73 2c 20 6a 75 73 74 20 61 73 20 69 66 20  ess, just as if 
25060 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  the [SQLITE_OPEN
25070 5f 52 45 41 44 4f 4e 4c 59 5d 20 66 6c 61 67 20  _READONLY] flag 
25080 68 61 64 20 62 65 65 6e 20 73 65 74 20 69 6e 20  had been set in 
25090 74 68 65 20 0a 2a 2a 20 20 20 20 20 74 68 69 72  the .**     thir
250a0 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  d argument to sq
250b0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
250c0 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20 6f 70   ^If the mode op
250d0 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 20 0a  tion is set to .
250e0 2a 2a 20 20 20 20 20 22 72 77 22 2c 20 74 68 65  **     "rw", the
250f0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  n the database i
25100 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61  s opened for rea
25110 64 2d 77 72 69 74 65 20 28 62 75 74 20 6e 6f 74  d-write (but not
25120 20 63 72 65 61 74 65 29 20 0a 2a 2a 20 20 20 20   create) .**    
25130 20 61 63 63 65 73 73 2c 20 61 73 20 69 66 20 53   access, as if S
25140 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
25150 52 49 54 45 20 28 62 75 74 20 6e 6f 74 20 53 51  RITE (but not SQ
25160 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
25170 29 20 68 61 64 20 0a 2a 2a 20 20 20 20 20 62 65  ) had .**     be
25180 65 6e 20 73 65 74 2e 20 5e 56 61 6c 75 65 20 22  en set. ^Value "
25190 72 77 63 22 20 69 73 20 65 71 75 69 76 61 6c 65  rwc" is equivale
251a0 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 62 6f  nt to setting bo
251b0 74 68 20 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54  th .**     SQLIT
251c0 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
251d0 20 61 6e 64 20 53 51 4c 49 54 45 5f 4f 50 45 4e   and SQLITE_OPEN
251e0 5f 43 52 45 41 54 45 2e 20 20 5e 49 66 20 74 68  _CREATE.  ^If th
251f0 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73  e mode option is
25200 0a 2a 2a 20 20 20 20 20 73 65 74 20 74 6f 20 22  .**     set to "
25210 6d 65 6d 6f 72 79 22 20 74 68 65 6e 20 61 20 70  memory" then a p
25220 75 72 65 20 5b 69 6e 2d 6d 65 6d 6f 72 79 20 64  ure [in-memory d
25230 61 74 61 62 61 73 65 5d 20 74 68 61 74 20 6e 65  atabase] that ne
25240 76 65 72 20 72 65 61 64 73 0a 2a 2a 20 20 20 20  ver reads.**    
25250 20 6f 72 20 77 72 69 74 65 73 20 66 72 6f 6d 20   or writes from 
25260 64 69 73 6b 20 69 73 20 75 73 65 64 2e 20 5e 49  disk is used. ^I
25270 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20 74 6f  t is an error to
25280 20 73 70 65 63 69 66 79 20 61 20 76 61 6c 75 65   specify a value
25290 20 66 6f 72 0a 2a 2a 20 20 20 20 20 74 68 65 20   for.**     the 
252a0 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72 20 74  mode parameter t
252b0 68 61 74 20 69 73 20 6c 65 73 73 20 72 65 73 74  hat is less rest
252c0 72 69 63 74 69 76 65 20 74 68 61 6e 20 74 68 61  rictive than tha
252d0 74 20 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a  t specified by.*
252e0 2a 20 20 20 20 20 74 68 65 20 66 6c 61 67 73 20  *     the flags 
252f0 70 61 73 73 65 64 20 69 6e 20 74 68 65 20 74 68  passed in the th
25300 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
25310 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
25320 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e  ()..**.**   <li>
25330 20 3c 62 3e 63 61 63 68 65 3c 2f 62 3e 3a 20 5e   <b>cache</b>: ^
25340 54 68 65 20 63 61 63 68 65 20 70 61 72 61 6d 65  The cache parame
25350 74 65 72 20 6d 61 79 20 62 65 20 73 65 74 20 74  ter may be set t
25360 6f 20 65 69 74 68 65 72 20 22 73 68 61 72 65 64  o either "shared
25370 22 20 6f 72 0a 2a 2a 20 20 20 20 20 22 70 72 69  " or.**     "pri
25380 76 61 74 65 22 2e 20 5e 53 65 74 74 69 6e 67 20  vate". ^Setting 
25390 69 74 20 74 6f 20 22 73 68 61 72 65 64 22 20 69  it to "shared" i
253a0 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20  s equivalent to 
253b0 73 65 74 74 69 6e 67 20 74 68 65 0a 2a 2a 20 20  setting the.**  
253c0 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53     SQLITE_OPEN_S
253d0 48 41 52 45 44 43 41 43 48 45 20 62 69 74 20 69  HAREDCACHE bit i
253e0 6e 20 74 68 65 20 66 6c 61 67 73 20 61 72 67 75  n the flags argu
253f0 6d 65 6e 74 20 70 61 73 73 65 64 20 74 6f 0a 2a  ment passed to.*
25400 2a 20 20 20 20 20 73 71 6c 69 74 65 33 5f 6f 70  *     sqlite3_op
25410 65 6e 5f 76 32 28 29 2e 20 5e 53 65 74 74 69 6e  en_v2(). ^Settin
25420 67 20 74 68 65 20 63 61 63 68 65 20 70 61 72 61  g the cache para
25430 6d 65 74 65 72 20 74 6f 20 22 70 72 69 76 61 74  meter to "privat
25440 65 22 20 69 73 20 0a 2a 2a 20 20 20 20 20 65 71  e" is .**     eq
25450 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74  uivalent to sett
25460 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f 4f  ing the SQLITE_O
25470 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45  PEN_PRIVATECACHE
25480 20 62 69 74 2e 0a 2a 2a 20 20 20 20 20 5e 49 66   bit..**     ^If
25490 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
254a0 28 29 20 69 73 20 75 73 65 64 20 61 6e 64 20 74  () is used and t
254b0 68 65 20 22 63 61 63 68 65 22 20 70 61 72 61 6d  he "cache" param
254c0 65 74 65 72 20 69 73 20 70 72 65 73 65 6e 74 20  eter is present 
254d0 69 6e 0a 2a 2a 20 20 20 20 20 61 20 55 52 49 20  in.**     a URI 
254e0 66 69 6c 65 6e 61 6d 65 2c 20 69 74 73 20 76 61  filename, its va
254f0 6c 75 65 20 6f 76 65 72 72 69 64 65 73 20 61 6e  lue overrides an
25500 79 20 62 65 68 61 76 69 6f 72 20 72 65 71 75 65  y behavior reque
25510 73 74 65 64 20 62 79 20 73 65 74 74 69 6e 67 0a  sted by setting.
25520 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50  **     SQLITE_OP
25530 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 20  EN_PRIVATECACHE 
25540 6f 72 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53  or SQLITE_OPEN_S
25550 48 41 52 45 44 43 41 43 48 45 20 66 6c 61 67 2e  HAREDCACHE flag.
25560 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e  .**.**  <li> <b>
25570 70 73 6f 77 3c 2f 62 3e 3a 20 5e 54 68 65 20 70  psow</b>: ^The p
25580 73 6f 77 20 70 61 72 61 6d 65 74 65 72 20 69 6e  sow parameter in
25590 64 69 63 61 74 65 73 20 77 68 65 74 68 65 72 20  dicates whether 
255a0 6f 72 20 6e 6f 74 20 74 68 65 0a 2a 2a 20 20 20  or not the.**   
255b0 20 20 5b 70 6f 77 65 72 73 61 66 65 20 6f 76 65    [powersafe ove
255c0 72 77 72 69 74 65 5d 20 70 72 6f 70 65 72 74 79  rwrite] property
255d0 20 64 6f 65 73 20 6f 72 20 64 6f 65 73 20 6e 6f   does or does no
255e0 74 20 61 70 70 6c 79 20 74 6f 20 74 68 65 0a 2a  t apply to the.*
255f0 2a 20 20 20 20 20 73 74 6f 72 61 67 65 20 6d 65  *     storage me
25600 64 69 61 20 6f 6e 20 77 68 69 63 68 20 74 68 65  dia on which the
25610 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 72   database file r
25620 65 73 69 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 20 3c  esides..**.**  <
25630 6c 69 3e 20 3c 62 3e 6e 6f 6c 6f 63 6b 3c 2f 62  li> <b>nolock</b
25640 3e 3a 20 5e 54 68 65 20 6e 6f 6c 6f 63 6b 20 70  >: ^The nolock p
25650 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 62 6f  arameter is a bo
25660 6f 6c 65 61 6e 20 71 75 65 72 79 20 70 61 72 61  olean query para
25670 6d 65 74 65 72 0a 2a 2a 20 20 20 20 20 77 68 69  meter.**     whi
25680 63 68 20 69 66 20 73 65 74 20 64 69 73 61 62 6c  ch if set disabl
25690 65 73 20 66 69 6c 65 20 6c 6f 63 6b 69 6e 67 20  es file locking 
256a0 69 6e 20 72 6f 6c 6c 62 61 63 6b 20 6a 6f 75 72  in rollback jour
256b0 6e 61 6c 20 6d 6f 64 65 73 2e 20 20 54 68 69 73  nal modes.  This
256c0 0a 2a 2a 20 20 20 20 20 69 73 20 75 73 65 66 75  .**     is usefu
256d0 6c 20 66 6f 72 20 61 63 63 65 73 73 69 6e 67 20  l for accessing 
256e0 61 20 64 61 74 61 62 61 73 65 20 6f 6e 20 61 20  a database on a 
256f0 66 69 6c 65 73 79 73 74 65 6d 20 74 68 61 74 20  filesystem that 
25700 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 20 20 20 20  does not.**     
25710 73 75 70 70 6f 72 74 20 6c 6f 63 6b 69 6e 67 2e  support locking.
25720 20 20 43 61 75 74 69 6f 6e 3a 20 20 44 61 74 61    Caution:  Data
25730 62 61 73 65 20 63 6f 72 72 75 70 74 69 6f 6e 20  base corruption 
25740 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 66 20  might result if 
25750 74 77 6f 0a 2a 2a 20 20 20 20 20 6f 72 20 6d 6f  two.**     or mo
25760 72 65 20 70 72 6f 63 65 73 73 65 73 20 77 72 69  re processes wri
25770 74 65 20 74 6f 20 74 68 65 20 73 61 6d 65 20 64  te to the same d
25780 61 74 61 62 61 73 65 20 61 6e 64 20 61 6e 79 20  atabase and any 
25790 6f 6e 65 20 6f 66 20 74 68 6f 73 65 0a 2a 2a 20  one of those.** 
257a0 20 20 20 20 70 72 6f 63 65 73 73 65 73 20 75 73      processes us
257b0 65 73 20 6e 6f 6c 6f 63 6b 3d 31 2e 0a 2a 2a 0a  es nolock=1..**.
257c0 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 69 6d 6d 75  **  <li> <b>immu
257d0 74 61 62 6c 65 3c 2f 62 3e 3a 20 5e 54 68 65 20  table</b>: ^The 
257e0 69 6d 6d 75 74 61 62 6c 65 20 70 61 72 61 6d 65  immutable parame
257f0 74 65 72 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e  ter is a boolean
25800 20 71 75 65 72 79 0a 2a 2a 20 20 20 20 20 70 61   query.**     pa
25810 72 61 6d 65 74 65 72 20 74 68 61 74 20 69 6e 64  rameter that ind
25820 69 63 61 74 65 73 20 74 68 61 74 20 74 68 65 20  icates that the 
25830 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 73  database file is
25840 20 73 74 6f 72 65 64 20 6f 6e 0a 2a 2a 20 20 20   stored on.**   
25850 20 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 64 69    read-only medi
25860 61 2e 20 20 5e 57 68 65 6e 20 69 6d 6d 75 74 61  a.  ^When immuta
25870 62 6c 65 20 69 73 20 73 65 74 2c 20 53 51 4c 69  ble is set, SQLi
25880 74 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20  te assumes that 
25890 74 68 65 0a 2a 2a 20 20 20 20 20 64 61 74 61 62  the.**     datab
258a0 61 73 65 20 66 69 6c 65 20 63 61 6e 6e 6f 74 20  ase file cannot 
258b0 62 65 20 63 68 61 6e 67 65 64 2c 20 65 76 65 6e  be changed, even
258c0 20 62 79 20 61 20 70 72 6f 63 65 73 73 20 77 69   by a process wi
258d0 74 68 20 68 69 67 68 65 72 0a 2a 2a 20 20 20 20  th higher.**    
258e0 20 70 72 69 76 69 6c 65 67 65 2c 20 61 6e 64 20   privilege, and 
258f0 73 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20  so the database 
25900 69 73 20 6f 70 65 6e 65 64 20 72 65 61 64 2d 6f  is opened read-o
25910 6e 6c 79 20 61 6e 64 20 61 6c 6c 20 6c 6f 63 6b  nly and all lock
25920 69 6e 67 0a 2a 2a 20 20 20 20 20 61 6e 64 20 63  ing.**     and c
25930 68 61 6e 67 65 20 64 65 74 65 63 74 69 6f 6e 20  hange detection 
25940 69 73 20 64 69 73 61 62 6c 65 64 2e 20 20 43 61  is disabled.  Ca
25950 75 74 69 6f 6e 3a 20 53 65 74 74 69 6e 67 20 74  ution: Setting t
25960 68 65 20 69 6d 6d 75 74 61 62 6c 65 0a 2a 2a 20  he immutable.** 
25970 20 20 20 20 70 72 6f 70 65 72 74 79 20 6f 6e 20      property on 
25980 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  a database file 
25990 74 68 61 74 20 64 6f 65 73 20 69 6e 20 66 61 63  that does in fac
259a0 74 20 63 68 61 6e 67 65 20 63 61 6e 20 72 65 73  t change can res
259b0 75 6c 74 0a 2a 2a 20 20 20 20 20 69 6e 20 69 6e  ult.**     in in
259c0 63 6f 72 72 65 63 74 20 71 75 65 72 79 20 72 65  correct query re
259d0 73 75 6c 74 73 20 61 6e 64 2f 6f 72 20 5b 53 51  sults and/or [SQ
259e0 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 20 65 72  LITE_CORRUPT] er
259f0 72 6f 72 73 2e 0a 2a 2a 20 20 20 20 20 53 65 65  rors..**     See
25a00 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 49   also: [SQLITE_I
25a10 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 5d 2e  OCAP_IMMUTABLE].
25a20 0a 2a 2a 20 20 20 20 20 20 20 0a 2a 2a 20 3c 2f  .**       .** </
25a30 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53 70 65 63 69  ul>.**.** ^Speci
25a40 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e  fying an unknown
25a50 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68   parameter in th
25a60 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e  e query componen
25a70 74 20 6f 66 20 61 20 55 52 49 20 69 73 20 6e 6f  t of a URI is no
25a80 74 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 2e 20 20  t an.** error.  
25a90 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  Future versions 
25aa0 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20  of SQLite might 
25ab0 75 6e 64 65 72 73 74 61 6e 64 20 61 64 64 69 74  understand addit
25ac0 69 6f 6e 61 6c 20 71 75 65 72 79 0a 2a 2a 20 70  ional query.** p
25ad0 61 72 61 6d 65 74 65 72 73 2e 20 20 53 65 65 20  arameters.  See 
25ae0 22 5b 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  "[query paramete
25af0 72 73 20 77 69 74 68 20 73 70 65 63 69 61 6c 20  rs with special 
25b00 6d 65 61 6e 69 6e 67 20 74 6f 20 53 51 4c 69 74  meaning to SQLit
25b10 65 5d 22 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74  e]" for.** addit
25b20 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f  ional informatio
25b30 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66  n..**.** [[URI f
25b40 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73  ilename examples
25b50 5d 5d 20 3c 68 33 3e 55 52 49 20 66 69 6c 65 6e  ]] <h3>URI filen
25b60 61 6d 65 20 65 78 61 6d 70 6c 65 73 3c 2f 68 33  ame examples</h3
25b70 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61 62 6c 65 20 62  >.**.** <table b
25b80 6f 72 64 65 72 3d 22 31 22 20 61 6c 69 67 6e 3d  order="1" align=
25b90 63 65 6e 74 65 72 20 63 65 6c 6c 70 61 64 64 69  center cellpaddi
25ba0 6e 67 3d 35 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68  ng=5>.** <tr><th
25bb0 3e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20  > URI filenames 
25bc0 3c 74 68 3e 20 52 65 73 75 6c 74 73 0a 2a 2a 20  <th> Results.** 
25bd0 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61  <tr><td> file:da
25be0 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20  ta.db <td> .**  
25bf0 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65          Open the
25c00 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20   file "data.db" 
25c10 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 64  in the current d
25c20 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 20 3c 74 72  irectory..** <tr
25c30 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65  ><td> file:/home
25c40 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3c 62 72  /fred/data.db<br
25c50 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69  >.**          fi
25c60 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f 66 72 65 64 2f  le:///home/fred/
25c70 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 0a 2a 2a  data.db <br> .**
25c80 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f            file:/
25c90 2f 6c 6f 63 61 6c 68 6f 73 74 2f 68 6f 6d 65 2f  /localhost/home/
25ca0 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72  fred/data.db <br
25cb0 3e 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20  > <td> .**      
25cc0 20 20 20 20 4f 70 65 6e 20 74 68 65 20 64 61 74      Open the dat
25cd0 61 62 61 73 65 20 66 69 6c 65 20 22 2f 68 6f 6d  abase file "/hom
25ce0 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e  e/fred/data.db".
25cf0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c  .** <tr><td> fil
25d00 65 3a 2f 2f 64 61 72 6b 73 74 61 72 2f 68 6f 6d  e://darkstar/hom
25d10 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c  e/fred/data.db <
25d20 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  td> .**         
25d30 20 41 6e 20 65 72 72 6f 72 2e 20 22 64 61 72 6b   An error. "dark
25d40 73 74 61 72 22 20 69 73 20 6e 6f 74 20 61 20 72  star" is not a r
25d50 65 63 6f 67 6e 69 7a 65 64 20 61 75 74 68 6f 72  ecognized author
25d60 69 74 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 20  ity..** <tr><td 
25d70 73 74 79 6c 65 3d 22 77 68 69 74 65 2d 73 70 61  style="white-spa
25d80 63 65 3a 6e 6f 77 72 61 70 22 3e 20 0a 2a 2a 20  ce:nowrap"> .** 
25d90 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f           file://
25da0 2f 43 3a 2f 44 6f 63 75 6d 65 6e 74 73 25 32 30  /C:/Documents%20
25db0 61 6e 64 25 32 30 53 65 74 74 69 6e 67 73 2f 66  and%20Settings/f
25dc0 72 65 64 2f 44 65 73 6b 74 6f 70 2f 64 61 74 61  red/Desktop/data
25dd0 2e 64 62 0a 2a 2a 20 20 20 20 20 3c 74 64 3e 20  .db.**     <td> 
25de0 57 69 6e 64 6f 77 73 20 6f 6e 6c 79 3a 20 4f 70  Windows only: Op
25df0 65 6e 20 74 68 65 20 66 69 6c 65 20 22 64 61 74  en the file "dat
25e00 61 2e 64 62 22 20 6f 6e 20 66 72 65 64 27 73 20  a.db" on fred's 
25e10 64 65 73 6b 74 6f 70 20 6f 6e 20 64 72 69 76 65  desktop on drive
25e20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 43 3a 2e  .**          C:.
25e30 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 25   Note that the %
25e40 32 30 20 65 73 63 61 70 69 6e 67 20 69 6e 20 74  20 escaping in t
25e50 68 69 73 20 65 78 61 6d 70 6c 65 20 69 73 20 6e  his example is n
25e60 6f 74 20 73 74 72 69 63 74 6c 79 20 0a 2a 2a 20  ot strictly .** 
25e70 20 20 20 20 20 20 20 20 20 6e 65 63 65 73 73 61           necessa
25e80 72 79 20 2d 20 73 70 61 63 65 20 63 68 61 72 61  ry - space chara
25e90 63 74 65 72 73 20 63 61 6e 20 62 65 20 75 73 65  cters can be use
25ea0 64 20 6c 69 74 65 72 61 6c 6c 79 0a 2a 2a 20 20  d literally.**  
25eb0 20 20 20 20 20 20 20 20 69 6e 20 55 52 49 20 66          in URI f
25ec0 69 6c 65 6e 61 6d 65 73 2e 0a 2a 2a 20 3c 74 72  ilenames..** <tr
25ed0 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e  ><td> file:data.
25ee0 64 62 3f 6d 6f 64 65 3d 72 6f 26 63 61 63 68 65  db?mode=ro&cache
25ef0 3d 70 72 69 76 61 74 65 20 3c 74 64 3e 20 0a 2a  =private <td> .*
25f00 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20  *          Open 
25f10 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 69  file "data.db" i
25f20 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 69  n the current di
25f30 72 65 63 74 6f 72 79 20 66 6f 72 20 72 65 61 64  rectory for read
25f40 2d 6f 6e 6c 79 20 61 63 63 65 73 73 2e 0a 2a 2a  -only access..**
25f50 20 20 20 20 20 20 20 20 20 20 52 65 67 61 72 64            Regard
25f60 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20  less of whether 
25f70 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 2d 63 61  or not shared-ca
25f80 63 68 65 20 6d 6f 64 65 20 69 73 20 65 6e 61 62  che mode is enab
25f90 6c 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20  led by.**       
25fa0 20 20 20 64 65 66 61 75 6c 74 2c 20 75 73 65 20     default, use 
25fb0 61 20 70 72 69 76 61 74 65 20 63 61 63 68 65 2e  a private cache.
25fc0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c  .** <tr><td> fil
25fd0 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74  e:/home/fred/dat
25fe0 61 2e 64 62 3f 76 66 73 3d 75 6e 69 78 2d 64 6f  a.db?vfs=unix-do
25ff0 74 66 69 6c 65 20 3c 74 64 3e 0a 2a 2a 20 20 20  tfile <td>.**   
26000 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65         Open file
26010 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74   "/home/fred/dat
26020 61 2e 64 62 22 2e 20 55 73 65 20 74 68 65 20 73  a.db". Use the s
26030 70 65 63 69 61 6c 20 56 46 53 20 22 75 6e 69 78  pecial VFS "unix
26040 2d 64 6f 74 66 69 6c 65 22 0a 2a 2a 20 20 20 20  -dotfile".**    
26050 20 20 20 20 20 20 74 68 61 74 20 75 73 65 73 20        that uses 
26060 64 6f 74 2d 66 69 6c 65 73 20 69 6e 20 70 6c 61  dot-files in pla
26070 63 65 20 6f 66 20 70 6f 73 69 78 20 61 64 76 69  ce of posix advi
26080 73 6f 72 79 20 6c 6f 63 6b 69 6e 67 2e 0a 2a 2a  sory locking..**
26090 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64   <tr><td> file:d
260a0 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 65 61 64  ata.db?mode=read
260b0 6f 6e 6c 79 20 3c 74 64 3e 20 0a 2a 2a 20 20 20  only <td> .**   
260c0 20 20 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e         An error.
260d0 20 22 72 65 61 64 6f 6e 6c 79 22 20 69 73 20 6e   "readonly" is n
260e0 6f 74 20 61 20 76 61 6c 69 64 20 6f 70 74 69 6f  ot a valid optio
260f0 6e 20 66 6f 72 20 74 68 65 20 22 6d 6f 64 65 22  n for the "mode"
26100 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 3c   parameter..** <
26110 2f 74 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55  /table>.**.** ^U
26120 52 49 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65  RI hexadecimal e
26130 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 73 20  scape sequences 
26140 28 25 48 48 29 20 61 72 65 20 73 75 70 70 6f 72  (%HH) are suppor
26150 74 65 64 20 77 69 74 68 69 6e 20 74 68 65 20 70  ted within the p
26160 61 74 68 20 61 6e 64 0a 2a 2a 20 71 75 65 72 79  ath and.** query
26170 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61   components of a
26180 20 55 52 49 2e 20 41 20 68 65 78 61 64 65 63 69   URI. A hexadeci
26190 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65  mal escape seque
261a0 6e 63 65 20 63 6f 6e 73 69 73 74 73 20 6f 66 20  nce consists of 
261b0 61 0a 2a 2a 20 70 65 72 63 65 6e 74 20 73 69 67  a.** percent sig
261c0 6e 20 2d 20 22 25 22 20 2d 20 66 6f 6c 6c 6f 77  n - "%" - follow
261d0 65 64 20 62 79 20 65 78 61 63 74 6c 79 20 74 77  ed by exactly tw
261e0 6f 20 68 65 78 61 64 65 63 69 6d 61 6c 20 64 69  o hexadecimal di
261f0 67 69 74 73 20 0a 2a 2a 20 73 70 65 63 69 66 79  gits .** specify
26200 69 6e 67 20 61 6e 20 6f 63 74 65 74 20 76 61 6c  ing an octet val
26210 75 65 2e 20 5e 42 65 66 6f 72 65 20 74 68 65 20  ue. ^Before the 
26220 70 61 74 68 20 6f 72 20 71 75 65 72 79 20 63 6f  path or query co
26230 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61 0a 2a 2a  mponents of a.**
26240 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 61 72   URI filename ar
26250 65 20 69 6e 74 65 72 70 72 65 74 65 64 2c 20 74  e interpreted, t
26260 68 65 79 20 61 72 65 20 65 6e 63 6f 64 65 64 20  hey are encoded 
26270 75 73 69 6e 67 20 55 54 46 2d 38 20 61 6e 64 20  using UTF-8 and 
26280 61 6c 6c 20 0a 2a 2a 20 68 65 78 61 64 65 63 69  all .** hexadeci
26290 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65  mal escape seque
262a0 6e 63 65 73 20 72 65 70 6c 61 63 65 64 20 62 79  nces replaced by
262b0 20 61 20 73 69 6e 67 6c 65 20 62 79 74 65 20 63   a single byte c
262c0 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 0a 2a 2a  ontaining the.**
262d0 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6f   corresponding o
262e0 63 74 65 74 2e 20 49 66 20 74 68 69 73 20 70 72  ctet. If this pr
262f0 6f 63 65 73 73 20 67 65 6e 65 72 61 74 65 73 20  ocess generates 
26300 61 6e 20 69 6e 76 61 6c 69 64 20 55 54 46 2d 38  an invalid UTF-8
26310 20 65 6e 63 6f 64 69 6e 67 2c 0a 2a 2a 20 74 68   encoding,.** th
26320 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
26330 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c  defined..**.** <
26340 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77  b>Note to Window
26350 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68  s users:</b>  Th
26360 65 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20  e encoding used 
26370 66 6f 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  for the filename
26380 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20   argument.** of 
26390 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61  sqlite3_open() a
263a0 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  nd sqlite3_open_
263b0 76 32 28 29 20 6d 75 73 74 20 62 65 20 55 54 46  v2() must be UTF
263c0 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65 76 65 72  -8, not whatever
263d0 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20 69 73 20  .** codepage is 
263e0 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65  currently define
263f0 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f  d.  Filenames co
26400 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61  ntaining interna
26410 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63  tional.** charac
26420 74 65 72 73 20 6d 75 73 74 20 62 65 20 63 6f 6e  ters must be con
26430 76 65 72 74 65 64 20 74 6f 20 55 54 46 2d 38 20  verted to UTF-8 
26440 70 72 69 6f 72 20 74 6f 20 70 61 73 73 69 6e 67  prior to passing
26450 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71   them into.** sq
26460 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20  lite3_open() or 
26470 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
26480 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65  )..**.** <b>Note
26490 20 74 6f 20 57 69 6e 64 6f 77 73 20 52 75 6e 74   to Windows Runt
264a0 69 6d 65 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20  ime users:</b>  
264b0 54 68 65 20 74 65 6d 70 6f 72 61 72 79 20 64 69  The temporary di
264c0 72 65 63 74 6f 72 79 20 6d 75 73 74 20 62 65 20  rectory must be 
264d0 73 65 74 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20  set.** prior to 
264e0 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f  calling sqlite3_
264f0 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65  open() or sqlite
26500 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20 4f 74  3_open_v2().  Ot
26510 68 65 72 77 69 73 65 2c 20 76 61 72 69 6f 75 73  herwise, various
26520 0a 2a 2a 20 66 65 61 74 75 72 65 73 20 74 68 61  .** features tha
26530 74 20 72 65 71 75 69 72 65 20 74 68 65 20 75 73  t require the us
26540 65 20 6f 66 20 74 65 6d 70 6f 72 61 72 79 20 66  e of temporary f
26550 69 6c 65 73 20 6d 61 79 20 66 61 69 6c 2e 0a 2a  iles may fail..*
26560 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
26570 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 72  sqlite3_temp_dir
26580 65 63 74 6f 72 79 5d 0a 2a 2f 0a 53 51 4c 49 54  ectory].*/.SQLIT
26590 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45  E_API int SQLITE
265a0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
265b0 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63  _open(.  const c
265c0 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20  har *filename,  
265d0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c   /* Database fil
265e0 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f  ename (UTF-8) */
265f0 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44  .  sqlite3 **ppD
26600 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55  b          /* OU
26610 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e  T: SQLite db han
26620 64 6c 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45  dle */.);.SQLITE
26630 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f  _API int SQLITE_
26640 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
26650 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20  open16(.  const 
26660 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20  void *filename, 
26670 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69    /* Database fi
26680 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 29 20  lename (UTF-16) 
26690 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70  */.  sqlite3 **p
266a0 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20  pDb          /* 
266b0 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68  OUT: SQLite db h
266c0 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49  andle */.);.SQLI
266d0 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54  TE_API int SQLIT
266e0 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
266f0 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e  3_open_v2(.  con
26700 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d  st char *filenam
26710 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  e,   /* Database
26720 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38   filename (UTF-8
26730 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a  ) */.  sqlite3 *
26740 2a 70 70 44 62 2c 20 20 20 20 20 20 20 20 20 2f  *ppDb,         /
26750 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62  * OUT: SQLite db
26760 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74   handle */.  int
26770 20 66 6c 61 67 73 2c 20 20 20 20 20 20 20 20 20   flags,         
26780 20 20 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f       /* Flags */
26790 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
267a0 56 66 73 20 20 20 20 20 20 20 20 2f 2a 20 4e 61  Vfs        /* Na
267b0 6d 65 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65  me of VFS module
267c0 20 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f   to use */.);../
267d0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
267e0 62 74 61 69 6e 20 56 61 6c 75 65 73 20 46 6f 72  btain Values For
267f0 20 55 52 49 20 50 61 72 61 6d 65 74 65 72 73 0a   URI Parameters.
26800 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20  **.** These are 
26810 75 74 69 6c 69 74 79 20 72 6f 75 74 69 6e 65 73  utility routines
26820 2c 20 75 73 65 66 75 6c 20 74 6f 20 56 46 53 20  , useful to VFS 
26830 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2c  implementations,
26840 20 74 68 61 74 20 63 68 65 63 6b 0a 2a 2a 20 74   that check.** t
26850 6f 20 73 65 65 20 69 66 20 61 20 64 61 74 61 62  o see if a datab
26860 61 73 65 20 66 69 6c 65 20 77 61 73 20 61 20 55  ase file was a U
26870 52 49 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 65  RI that containe
26880 64 20 61 20 73 70 65 63 69 66 69 63 20 71 75 65  d a specific que
26890 72 79 20 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ry .** parameter
268a0 2c 20 61 6e 64 20 69 66 20 73 6f 20 6f 62 74 61  , and if so obta
268b0 69 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66  ins the value of
268c0 20 74 68 61 74 20 71 75 65 72 79 20 70 61 72 61   that query para
268d0 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  meter..**.** If 
268e0 46 20 69 73 20 74 68 65 20 64 61 74 61 62 61 73  F is the databas
268f0 65 20 66 69 6c 65 6e 61 6d 65 20 70 6f 69 6e 74  e filename point
26900 65 72 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74  er passed into t
26910 68 65 20 78 4f 70 65 6e 28 29 20 6d 65 74 68 6f  he xOpen() metho
26920 64 20 6f 66 20 0a 2a 2a 20 61 20 56 46 53 20 69  d of .** a VFS i
26930 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68  mplementation wh
26940 65 6e 20 74 68 65 20 66 6c 61 67 73 20 70 61 72  en the flags par
26950 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 28  ameter to xOpen(
26960 29 20 68 61 73 20 6f 6e 65 20 6f 72 20 0a 2a 2a  ) has one or .**
26970 20 6d 6f 72 65 20 6f 66 20 74 68 65 20 5b 53 51   more of the [SQ
26980 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 6f  LITE_OPEN_URI] o
26990 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d  r [SQLITE_OPEN_M
269a0 41 49 4e 5f 44 42 5d 20 62 69 74 73 20 73 65 74  AIN_DB] bits set
269b0 20 61 6e 64 0a 2a 2a 20 50 20 69 73 20 74 68 65   and.** P is the
269c0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 71 75 65   name of the que
269d0 72 79 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68  ry parameter, th
269e0 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72  en.** sqlite3_ur
269f0 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29  i_parameter(F,P)
26a00 20 72 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c   returns the val
26a10 75 65 20 6f 66 20 74 68 65 20 50 0a 2a 2a 20 70  ue of the P.** p
26a20 61 72 61 6d 65 74 65 72 20 69 66 20 69 74 20 65  arameter if it e
26a30 78 69 73 74 73 20 6f 72 20 61 20 4e 55 4c 4c 20  xists or a NULL 
26a40 70 6f 69 6e 74 65 72 20 69 66 20 50 20 64 6f 65  pointer if P doe
26a50 73 20 6e 6f 74 20 61 70 70 65 61 72 20 61 73 20  s not appear as 
26a60 61 20 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61  a .** query para
26a70 6d 65 74 65 72 20 6f 6e 20 46 2e 20 20 49 66 20  meter on F.  If 
26a80 50 20 69 73 20 61 20 71 75 65 72 79 20 70 61 72  P is a query par
26a90 61 6d 65 74 65 72 20 6f 66 20 46 0a 2a 2a 20 68  ameter of F.** h
26aa0 61 73 20 6e 6f 20 65 78 70 6c 69 63 69 74 20 76  as no explicit v
26ab0 61 6c 75 65 2c 20 74 68 65 6e 20 73 71 6c 69 74  alue, then sqlit
26ac0 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72  e3_uri_parameter
26ad0 28 46 2c 50 29 20 72 65 74 75 72 6e 73 0a 2a 2a  (F,P) returns.**
26ae0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
26af0 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2e 0a 2a   empty string..*
26b00 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
26b10 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50  _uri_boolean(F,P
26b20 2c 42 29 20 72 6f 75 74 69 6e 65 20 61 73 73 75  ,B) routine assu
26b30 6d 65 73 20 74 68 61 74 20 50 20 69 73 20 61 20  mes that P is a 
26b40 62 6f 6f 6c 65 61 6e 0a 2a 2a 20 70 61 72 61 6d  boolean.** param
26b50 65 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73  eter and returns
26b60 20 74 72 75 65 20 28 31 29 20 6f 72 20 66 61 6c   true (1) or fal
26b70 73 65 20 28 30 29 20 61 63 63 6f 72 64 69 6e 67  se (0) according
26b80 20 74 6f 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a   to the value.**
26b90 20 6f 66 20 50 2e 20 20 54 68 65 20 73 71 6c 69   of P.  The sqli
26ba0 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28  te3_uri_boolean(
26bb0 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 20 72  F,P,B) routine r
26bc0 65 74 75 72 6e 73 20 74 72 75 65 20 28 31 29 20  eturns true (1) 
26bd0 69 66 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20  if the.** value 
26be0 6f 66 20 71 75 65 72 79 20 70 61 72 61 6d 65 74  of query paramet
26bf0 65 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 22  er P is one of "
26c00 79 65 73 22 2c 20 22 74 72 75 65 22 2c 20 6f 72  yes", "true", or
26c10 20 22 6f 6e 22 20 69 6e 20 61 6e 79 0a 2a 2a 20   "on" in any.** 
26c20 63 61 73 65 20 6f 72 20 69 66 20 74 68 65 20 76  case or if the v
26c30 61 6c 75 65 20 62 65 67 69 6e 73 20 77 69 74 68  alue begins with
26c40 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 6e 75 6d 62   a non-zero numb
26c50 65 72 2e 20 20 54 68 65 20 0a 2a 2a 20 73 71 6c  er.  The .** sql
26c60 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e  ite3_uri_boolean
26c70 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 73  (F,P,B) routines
26c80 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20 28   returns false (
26c90 30 29 20 69 66 20 74 68 65 20 76 61 6c 75 65 20  0) if the value 
26ca0 6f 66 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61  of.** query para
26cb0 6d 65 74 65 72 20 50 20 69 73 20 6f 6e 65 20 6f  meter P is one o
26cc0 66 20 22 6e 6f 22 2c 20 22 66 61 6c 73 65 22 2c  f "no", "false",
26cd0 20 6f 72 20 22 6f 66 66 22 20 69 6e 20 61 6e 79   or "off" in any
26ce0 20 63 61 73 65 20 6f 72 0a 2a 2a 20 69 66 20 74   case or.** if t
26cf0 68 65 20 76 61 6c 75 65 20 62 65 67 69 6e 73 20  he value begins 
26d00 77 69 74 68 20 61 20 6e 75 6d 65 72 69 63 20 7a  with a numeric z
26d10 65 72 6f 2e 20 20 49 66 20 50 20 69 73 20 6e 6f  ero.  If P is no
26d20 74 20 61 20 71 75 65 72 79 0a 2a 2a 20 70 61 72  t a query.** par
26d30 61 6d 65 74 65 72 20 6f 6e 20 46 20 6f 72 20 69  ameter on F or i
26d40 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50  f the value of P
26d50 20 69 73 20 64 6f 65 73 20 6e 6f 74 20 6d 61 74   is does not mat
26d60 63 68 20 61 6e 79 20 6f 66 20 74 68 65 0a 2a 2a  ch any of the.**
26d70 20 61 62 6f 76 65 2c 20 74 68 65 6e 20 73 71 6c   above, then sql
26d80 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e  ite3_uri_boolean
26d90 28 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20  (F,P,B) returns 
26da0 28 42 21 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 54 68  (B!=0)..**.** Th
26db0 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e  e sqlite3_uri_in
26dc0 74 36 34 28 46 2c 50 2c 44 29 20 72 6f 75 74 69  t64(F,P,D) routi
26dd0 6e 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 20  ne converts the 
26de0 76 61 6c 75 65 20 6f 66 20 50 20 69 6e 74 6f 20  value of P into 
26df0 61 0a 2a 2a 20 36 34 2d 62 69 74 20 73 69 67 6e  a.** 64-bit sign
26e00 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64 20 72  ed integer and r
26e10 65 74 75 72 6e 73 20 74 68 61 74 20 69 6e 74 65  eturns that inte
26e20 67 65 72 2c 20 6f 72 20 44 20 69 66 20 50 20 64  ger, or D if P d
26e30 6f 65 73 20 6e 6f 74 0a 2a 2a 20 65 78 69 73 74  oes not.** exist
26e40 2e 20 20 49 66 20 74 68 65 20 76 61 6c 75 65 20  .  If the value 
26e50 6f 66 20 50 20 69 73 20 73 6f 6d 65 74 68 69 6e  of P is somethin
26e60 67 20 6f 74 68 65 72 20 74 68 61 6e 20 61 6e 20  g other than an 
26e70 69 6e 74 65 67 65 72 2c 20 74 68 65 6e 0a 2a 2a  integer, then.**
26e80 20 7a 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65   zero is returne
26e90 64 2e 0a 2a 2a 20 0a 2a 2a 20 49 66 20 46 20 69  d..** .** If F i
26ea0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
26eb0 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75  , then sqlite3_u
26ec0 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50  ri_parameter(F,P
26ed0 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61  ) returns NULL a
26ee0 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72  nd.** sqlite3_ur
26ef0 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29  i_boolean(F,P,B)
26f00 20 72 65 74 75 72 6e 73 20 42 2e 20 20 49 66 20   returns B.  If 
26f10 46 20 69 73 20 6e 6f 74 20 61 20 4e 55 4c 4c 20  F is not a NULL 
26f20 70 6f 69 6e 74 65 72 20 61 6e 64 0a 2a 2a 20 69  pointer and.** i
26f30 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65  s not a database
26f40 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 70   file pathname p
26f50 6f 69 6e 74 65 72 20 74 68 61 74 20 53 51 4c 69  ointer that SQLi
26f60 74 65 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74  te passed into t
26f70 68 65 20 78 4f 70 65 6e 0a 2a 2a 20 56 46 53 20  he xOpen.** VFS 
26f80 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 65  method, then the
26f90 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 69   behavior of thi
26fa0 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75 6e 64  s routine is und
26fb0 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61  efined and proba
26fc0 62 6c 79 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62  bly.** undesirab
26fd0 6c 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  le..*/.SQLITE_AP
26fe0 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51  I const char *SQ
26ff0 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
27000 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74  ite3_uri_paramet
27010 65 72 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  er(const char *z
27020 46 69 6c 65 6e 61 6d 65 2c 20 63 6f 6e 73 74 20  Filename, const 
27030 63 68 61 72 20 2a 7a 50 61 72 61 6d 29 3b 0a 53  char *zParam);.S
27040 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51  QLITE_API int SQ
27050 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
27060 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e  ite3_uri_boolean
27070 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69  (const char *zFi
27080 6c 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  le, const char *
27090 7a 50 61 72 61 6d 2c 20 69 6e 74 20 62 44 65 66  zParam, int bDef
270a0 61 75 6c 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50  ault);.SQLITE_AP
270b0 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  I sqlite3_int64 
270c0 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
270d0 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 36 34  qlite3_uri_int64
270e0 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 63 6f  (const char*, co
270f0 6e 73 74 20 63 68 61 72 2a 2c 20 73 71 6c 69 74  nst char*, sqlit
27100 65 33 5f 69 6e 74 36 34 29 3b 0a 0a 0a 2f 2a 0a  e3_int64);.../*.
27110 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 72 72  ** CAPI3REF: Err
27120 6f 72 20 43 6f 64 65 73 20 41 6e 64 20 4d 65 73  or Codes And Mes
27130 73 61 67 65 73 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  sages.**.** ^If 
27140 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
27150 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61  sqlite3_* API ca
27160 6c 6c 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ll associated wi
27170 74 68 20 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  th .** [database
27180 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 66   connection] D f
27190 61 69 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20  ailed, then the 
271a0 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
271b0 44 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  D) interface.** 
271c0 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65  returns the nume
271d0 72 69 63 20 5b 72 65 73 75 6c 74 20 63 6f 64 65  ric [result code
271e0 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 72  ] or [extended r
271f0 65 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20  esult code] for 
27200 74 68 61 74 0a 2a 2a 20 41 50 49 20 63 61 6c 6c  that.** API call
27210 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6d 6f 73 74  ..** If the most
27220 20 72 65 63 65 6e 74 20 41 50 49 20 63 61 6c 6c   recent API call
27230 20 77 61 73 20 73 75 63 63 65 73 73 66 75 6c 2c   was successful,
27240 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74  .** then the ret
27250 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73  urn value from s
27260 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
27270 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
27280 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
27290 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28  xtended_errcode(
272a0 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69  ).** interface i
272b0 73 20 74 68 65 20 73 61 6d 65 20 65 78 63 65 70  s the same excep
272c0 74 20 74 68 61 74 20 69 74 20 61 6c 77 61 79 73  t that it always
272d0 20 72 65 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a   returns the .**
272e0 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
272f0 74 20 63 6f 64 65 5d 20 65 76 65 6e 20 77 68 65  t code] even whe
27300 6e 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  n extended resul
27310 74 20 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64  t codes are.** d
27320 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  isabled..**.** ^
27330 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 6d  The sqlite3_errm
27340 73 67 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  sg() and sqlite3
27350 5f 65 72 72 6d 73 67 31 36 28 29 20 72 65 74 75  _errmsg16() retu
27360 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75  rn English-langu
27370 61 67 65 0a 2a 2a 20 74 65 78 74 20 74 68 61 74  age.** text that
27380 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65   describes the e
27390 72 72 6f 72 2c 20 61 73 20 65 69 74 68 65 72 20  rror, as either 
273a0 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20  UTF-8 or UTF-16 
273b0 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a  respectively..**
273c0 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c   ^(Memory to hol
273d0 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  d the error mess
273e0 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61  age string is ma
273f0 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79  naged internally
27400 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
27410 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65  tion does not ne
27420 65 64 20 74 6f 20 77 6f 72 72 79 20 61 62 6f 75  ed to worry abou
27430 74 20 66 72 65 65 69 6e 67 20 74 68 65 20 72 65  t freeing the re
27440 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72  sult..** However
27450 2c 20 74 68 65 20 65 72 72 6f 72 20 73 74 72 69  , the error stri
27460 6e 67 20 6d 69 67 68 74 20 62 65 20 6f 76 65 72  ng might be over
27470 77 72 69 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c  written or deall
27480 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20 73 75 62  ocated by.** sub
27490 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
274a0 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e   other SQLite in
274b0 74 65 72 66 61 63 65 20 66 75 6e 63 74 69 6f 6e  terface function
274c0 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  s.)^.**.** ^The 
274d0 73 71 6c 69 74 65 33 5f 65 72 72 73 74 72 28 29  sqlite3_errstr()
274e0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
274f0 6e 73 20 74 68 65 20 45 6e 67 6c 69 73 68 2d 6c  ns the English-l
27500 61 6e 67 75 61 67 65 20 74 65 78 74 0a 2a 2a 20  anguage text.** 
27510 74 68 61 74 20 64 65 73 63 72 69 62 65 73 20 74  that describes t
27520 68 65 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d  he [result code]
27530 2c 20 61 73 20 55 54 46 2d 38 2e 0a 2a 2a 20 5e  , as UTF-8..** ^
27540 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20  (Memory to hold 
27550 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
27560 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61  e string is mana
27570 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a  ged internally.*
27580 2a 20 61 6e 64 20 6d 75 73 74 20 6e 6f 74 20 62  * and must not b
27590 65 20 66 72 65 65 64 20 62 79 20 74 68 65 20 61  e freed by the a
275a0 70 70 6c 69 63 61 74 69 6f 6e 29 5e 2e 0a 2a 2a  pplication)^..**
275b0 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 73 65 72  .** When the ser
275c0 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69  ialized [threadi
275d0 6e 67 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75  ng mode] is in u
275e0 73 65 2c 20 69 74 20 6d 69 67 68 74 20 62 65 20  se, it might be 
275f0 74 68 65 0a 2a 2a 20 63 61 73 65 20 74 68 61 74  the.** case that
27600 20 61 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20   a second error 
27610 6f 63 63 75 72 73 20 6f 6e 20 61 20 73 65 70 61  occurs on a sepa
27620 72 61 74 65 20 74 68 72 65 61 64 20 69 6e 20 62  rate thread in b
27630 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69  etween.** the ti
27640 6d 65 20 6f 66 20 74 68 65 20 66 69 72 73 74 20  me of the first 
27650 65 72 72 6f 72 20 61 6e 64 20 74 68 65 20 63 61  error and the ca
27660 6c 6c 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65  ll to these inte
27670 72 66 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20  rfaces..** When 
27680 74 68 61 74 20 68 61 70 70 65 6e 73 2c 20 74 68  that happens, th
27690 65 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 77  e second error w
276a0 69 6c 6c 20 62 65 20 72 65 70 6f 72 74 65 64 20  ill be reported 
276b0 73 69 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20 69  since these.** i
276c0 6e 74 65 72 66 61 63 65 73 20 61 6c 77 61 79 73  nterfaces always
276d0 20 72 65 70 6f 72 74 20 74 68 65 20 6d 6f 73 74   report the most
276e0 20 72 65 63 65 6e 74 20 72 65 73 75 6c 74 2e 20   recent result. 
276f0 20 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69   To avoid.** thi
27700 73 2c 20 65 61 63 68 20 74 68 72 65 61 64 20 63  s, each thread c
27710 61 6e 20 6f 62 74 61 69 6e 20 65 78 63 6c 75 73  an obtain exclus
27720 69 76 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b  ive use of the [
27730 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
27740 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76  ion] D.** by inv
27750 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d  oking [sqlite3_m
27760 75 74 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c  utex_enter]([sql
27770 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44  ite3_db_mutex](D
27780 29 29 20 62 65 66 6f 72 65 20 62 65 67 69 6e 6e  )) before beginn
27790 69 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20  ing.** to use D 
277a0 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71  and invoking [sq
277b0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76  lite3_mutex_leav
277c0 65 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d  e]([sqlite3_db_m
277d0 75 74 65 78 5d 28 44 29 29 20 61 66 74 65 72 0a  utex](D)) after.
277e0 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20  ** all calls to 
277f0 74 68 65 20 69 6e 74 65 72 66 61 63 65 73 20 6c  the interfaces l
27800 69 73 74 65 64 20 68 65 72 65 20 61 72 65 20 63  isted here are c
27810 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  ompleted..**.** 
27820 49 66 20 61 6e 20 69 6e 74 65 72 66 61 63 65 20  If an interface 
27830 66 61 69 6c 73 20 77 69 74 68 20 53 51 4c 49 54  fails with SQLIT
27840 45 5f 4d 49 53 55 53 45 2c 20 74 68 61 74 20 6d  E_MISUSE, that m
27850 65 61 6e 73 20 74 68 65 20 69 6e 74 65 72 66 61  eans the interfa
27860 63 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65  ce.** was invoke
27870 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 62 79  d incorrectly by
27880 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
27890 2e 20 20 49 6e 20 74 68 61 74 20 63 61 73 65 2c  .  In that case,
278a0 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f   the.** error co
278b0 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65 20 6d  de and message m
278c0 61 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65  ay or may not be
278d0 20 73 65 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f   set..*/.SQLITE_
278e0 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  API int SQLITE_S
278f0 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 65  TDCALL sqlite3_e
27900 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a  rrcode(sqlite3 *
27910 64 62 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  db);.SQLITE_API 
27920 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41  int SQLITE_STDCA
27930 4c 4c 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  LL sqlite3_exten
27940 64 65 64 5f 65 72 72 63 6f 64 65 28 73 71 6c 69  ded_errcode(sqli
27950 74 65 33 20 2a 64 62 29 3b 0a 53 51 4c 49 54 45  te3 *db);.SQLITE
27960 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20  _API const char 
27970 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20  *SQLITE_STDCALL 
27980 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 73  sqlite3_errmsg(s
27990 71 6c 69 74 65 33 2a 29 3b 0a 53 51 4c 49 54 45  qlite3*);.SQLITE
279a0 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20  _API const void 
279b0 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20  *SQLITE_STDCALL 
279c0 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36  sqlite3_errmsg16
279d0 28 73 71 6c 69 74 65 33 2a 29 3b 0a 53 51 4c 49  (sqlite3*);.SQLI
279e0 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61  TE_API const cha
279f0 72 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  r *SQLITE_STDCAL
27a00 4c 20 73 71 6c 69 74 65 33 5f 65 72 72 73 74 72  L sqlite3_errstr
27a10 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  (int);../*.** CA
27a20 50 49 33 52 45 46 3a 20 53 51 4c 20 53 74 61 74  PI3REF: SQL Stat
27a30 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20  ement Object.** 
27a40 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 65 70 61  KEYWORDS: {prepa
27a50 72 65 64 20 73 74 61 74 65 6d 65 6e 74 7d 20 7b  red statement} {
27a60 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
27a70 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e  nts}.**.** An in
27a80 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f  stance of this o
27a90 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73  bject represents
27aa0 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74   a single SQL st
27ab0 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54 68 69 73  atement..** This
27ac0 20 6f 62 6a 65 63 74 20 69 73 20 76 61 72 69 6f   object is vario
27ad0 75 73 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 61 20  usly known as a 
27ae0 22 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  "prepared statem
27af0 65 6e 74 22 20 6f 72 20 61 0a 2a 2a 20 22 63 6f  ent" or a.** "co
27b00 6d 70 69 6c 65 64 20 53 51 4c 20 73 74 61 74 65  mpiled SQL state
27b10 6d 65 6e 74 22 20 6f 72 20 73 69 6d 70 6c 79 20  ment" or simply 
27b20 61 73 20 61 20 22 73 74 61 74 65 6d 65 6e 74 22  as a "statement"
27b30 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 66 65  ..**.** The life
27b40 20 6f 66 20 61 20 73 74 61 74 65 6d 65 6e 74 20   of a statement 
27b50 6f 62 6a 65 63 74 20 67 6f 65 73 20 73 6f 6d 65  object goes some
27b60 74 68 69 6e 67 20 6c 69 6b 65 20 74 68 69 73 3a  thing like this:
27b70 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c  .**.** <ol>.** <
27b80 6c 69 3e 20 43 72 65 61 74 65 20 74 68 65 20 6f  li> Create the o
27b90 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c  bject using [sql
27ba0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
27bb0 29 5d 20 6f 72 20 61 20 72 65 6c 61 74 65 64 0a  )] or a related.
27bc0 2a 2a 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e  **      function
27bd0 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76  ..** <li> Bind v
27be0 61 6c 75 65 73 20 74 6f 20 5b 68 6f 73 74 20 70  alues to [host p
27bf0 61 72 61 6d 65 74 65 72 73 5d 20 75 73 69 6e 67  arameters] using
27c00 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
27c10 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20 20 69 6e  d_*().**      in
27c20 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69  terfaces..** <li
27c30 3e 20 52 75 6e 20 74 68 65 20 53 51 4c 20 62 79  > Run the SQL by
27c40 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
27c50 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72  3_step()] one or
27c60 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20   more times..** 
27c70 3c 6c 69 3e 20 52 65 73 65 74 20 74 68 65 20 73  <li> Reset the s
27c80 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b  tatement using [
27c90 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
27ca0 20 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a   then go back.**
27cb0 20 20 20 20 20 20 74 6f 20 73 74 65 70 20 32 2e        to step 2.
27cc0 20 20 44 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f    Do this zero o
27cd0 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a  r more times..**
27ce0 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20 74 68   <li> Destroy th
27cf0 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b  e object using [
27d00 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
27d10 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a  ()]..** </ol>.**
27d20 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 64 6f 63  .** Refer to doc
27d30 75 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e 20 69 6e  umentation on in
27d40 64 69 76 69 64 75 61 6c 20 6d 65 74 68 6f 64 73  dividual methods
27d50 20 61 62 6f 76 65 20 66 6f 72 20 61 64 64 69 74   above for addit
27d60 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61  ional.** informa
27d70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  tion..*/.typedef
27d80 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
27d90 73 74 6d 74 20 73 71 6c 69 74 65 33 5f 73 74 6d  stmt sqlite3_stm
27da0 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  t;../*.** CAPI3R
27db0 45 46 3a 20 52 75 6e 2d 74 69 6d 65 20 4c 69 6d  EF: Run-time Lim
27dc0 69 74 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73  its.**.** ^(This
27dd0 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77   interface allow
27de0 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 76 61  s the size of va
27df0 72 69 6f 75 73 20 63 6f 6e 73 74 72 75 63 74 73  rious constructs
27e00 20 74 6f 20 62 65 20 6c 69 6d 69 74 65 64 0a 2a   to be limited.*
27e10 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 74 69 6f  * on a connectio
27e20 6e 20 62 79 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  n by connection 
27e30 62 61 73 69 73 2e 20 20 54 68 65 20 66 69 72 73  basis.  The firs
27e40 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  t parameter is t
27e50 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  he.** [database 
27e60 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 68 6f 73  connection] whos
27e70 65 20 6c 69 6d 69 74 20 69 73 20 74 6f 20 62 65  e limit is to be
27e80 20 73 65 74 20 6f 72 20 71 75 65 72 69 65 64 2e   set or queried.
27e90 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20    The.** second 
27ea0 70 61 72 61 6d 65 74 65 72 20 69 73 20 6f 6e 65  parameter is one
27eb0 20 6f 66 20 74 68 65 20 5b 6c 69 6d 69 74 20 63   of the [limit c
27ec0 61 74 65 67 6f 72 69 65 73 5d 20 74 68 61 74 20  ategories] that 
27ed0 64 65 66 69 6e 65 20 61 0a 2a 2a 20 63 6c 61 73  define a.** clas
27ee0 73 20 6f 66 20 63 6f 6e 73 74 72 75 63 74 73 20  s of constructs 
27ef0 74 6f 20 62 65 20 73 69 7a 65 20 6c 69 6d 69 74  to be size limit
27f00 65 64 2e 20 20 54 68 65 20 74 68 69 72 64 20 70  ed.  The third p
27f10 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a  arameter is the.
27f20 2a 2a 20 6e 65 77 20 6c 69 6d 69 74 20 66 6f 72  ** new limit for
27f30 20 74 68 61 74 20 63 6f 6e 73 74 72 75 63 74 2e   that construct.
27f40 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  )^.**.** ^If the
27f50 20 6e 65 77 20 6c 69 6d 69 74 20 69 73 20 61 20   new limit is a 
27f60 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2c  negative number,
27f70 20 74 68 65 20 6c 69 6d 69 74 20 69 73 20 75 6e   the limit is un
27f80 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 5e 28 46 6f  changed..** ^(Fo
27f90 72 20 65 61 63 68 20 6c 69 6d 69 74 20 63 61 74  r each limit cat
27fa0 65 67 6f 72 79 20 53 51 4c 49 54 45 5f 4c 49 4d  egory SQLITE_LIM
27fb0 49 54 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 20 74  IT_<i>NAME</i> t
27fc0 68 65 72 65 20 69 73 20 61 20 0a 2a 2a 20 5b 6c  here is a .** [l
27fd0 69 6d 69 74 73 20 7c 20 68 61 72 64 20 75 70 70  imits | hard upp
27fe0 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73 65 74  er bound].** set
27ff0 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65   at compile-time
28000 20 62 79 20 61 20 43 20 70 72 65 70 72 6f 63 65   by a C preproce
28010 73 73 6f 72 20 6d 61 63 72 6f 20 63 61 6c 6c 65  ssor macro calle
28020 64 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 53  d.** [limits | S
28030 51 4c 49 54 45 5f 4d 41 58 5f 3c 69 3e 4e 41 4d  QLITE_MAX_<i>NAM
28040 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28 54 68 65 20  E</i>]..** (The 
28050 22 5f 4c 49 4d 49 54 5f 22 20 69 6e 20 74 68 65  "_LIMIT_" in the
28060 20 6e 61 6d 65 20 69 73 20 63 68 61 6e 67 65 64   name is changed
28070 20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29 29 5e 0a   to "_MAX_".))^.
28080 2a 2a 20 5e 41 74 74 65 6d 70 74 73 20 74 6f 20  ** ^Attempts to 
28090 69 6e 63 72 65 61 73 65 20 61 20 6c 69 6d 69 74  increase a limit
280a0 20 61 62 6f 76 65 20 69 74 73 20 68 61 72 64 20   above its hard 
280b0 75 70 70 65 72 20 62 6f 75 6e 64 20 61 72 65 0a  upper bound are.
280c0 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e  ** silently trun
280d0 63 61 74 65 64 20 74 6f 20 74 68 65 20 68 61 72  cated to the har
280e0 64 20 75 70 70 65 72 20 62 6f 75 6e 64 2e 0a 2a  d upper bound..*
280f0 2a 0a 2a 2a 20 5e 52 65 67 61 72 64 6c 65 73 73  *.** ^Regardless
28100 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e   of whether or n
28110 6f 74 20 74 68 65 20 6c 69 6d 69 74 20 77 61 73  ot the limit was
28120 20 63 68 61 6e 67 65 64 2c 20 74 68 65 20 0a 2a   changed, the .*
28130 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  * [sqlite3_limit
28140 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  ()] interface re
28150 74 75 72 6e 73 20 74 68 65 20 70 72 69 6f 72 20  turns the prior 
28160 76 61 6c 75 65 20 6f 66 20 74 68 65 20 6c 69 6d  value of the lim
28170 69 74 2e 0a 2a 2a 20 5e 48 65 6e 63 65 2c 20 74  it..** ^Hence, t
28180 6f 20 66 69 6e 64 20 74 68 65 20 63 75 72 72 65  o find the curre
28190 6e 74 20 76 61 6c 75 65 20 6f 66 20 61 20 6c 69  nt value of a li
281a0 6d 69 74 20 77 69 74 68 6f 75 74 20 63 68 61 6e  mit without chan
281b0 67 69 6e 67 20 69 74 2c 0a 2a 2a 20 73 69 6d 70  ging it,.** simp
281c0 6c 79 20 69 6e 76 6f 6b 65 20 74 68 69 73 20 69  ly invoke this i
281d0 6e 74 65 72 66 61 63 65 20 77 69 74 68 20 74 68  nterface with th
281e0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
281f0 72 20 73 65 74 20 74 6f 20 2d 31 2e 0a 2a 2a 0a  r set to -1..**.
28200 2a 2a 20 52 75 6e 2d 74 69 6d 65 20 6c 69 6d 69  ** Run-time limi
28210 74 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20  ts are intended 
28220 66 6f 72 20 75 73 65 20 69 6e 20 61 70 70 6c 69  for use in appli
28230 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6d 61 6e  cations that man
28240 61 67 65 0a 2a 2a 20 62 6f 74 68 20 74 68 65 69  age.** both thei
28250 72 20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c 20 64  r own internal d
28260 61 74 61 62 61 73 65 20 61 6e 64 20 61 6c 73 6f  atabase and also
28270 20 64 61 74 61 62 61 73 65 73 20 74 68 61 74 20   databases that 
28280 61 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a  are controlled.*
28290 2a 20 62 79 20 75 6e 74 72 75 73 74 65 64 20 65  * by untrusted e
282a0 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 2e  xternal sources.
282b0 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 61 70 70    An example app
282c0 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68 74 20 62  lication might b
282d0 65 20 61 0a 2a 2a 20 77 65 62 20 62 72 6f 77 73  e a.** web brows
282e0 65 72 20 74 68 61 74 20 68 61 73 20 69 74 73 20  er that has its 
282f0 6f 77 6e 20 64 61 74 61 62 61 73 65 73 20 66 6f  own databases fo
28300 72 20 73 74 6f 72 69 6e 67 20 68 69 73 74 6f 72  r storing histor
28310 79 20 61 6e 64 0a 2a 2a 20 73 65 70 61 72 61 74  y and.** separat
28320 65 20 64 61 74 61 62 61 73 65 73 20 63 6f 6e 74  e databases cont
28330 72 6f 6c 6c 65 64 20 62 79 20 4a 61 76 61 53 63  rolled by JavaSc
28340 72 69 70 74 20 61 70 70 6c 69 63 61 74 69 6f 6e  ript application
28350 73 20 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20  s downloaded.** 
28360 6f 66 66 20 74 68 65 20 49 6e 74 65 72 6e 65 74  off the Internet
28370 2e 20 20 54 68 65 20 69 6e 74 65 72 6e 61 6c 20  .  The internal 
28380 64 61 74 61 62 61 73 65 73 20 63 61 6e 20 62 65  databases can be
28390 20 67 69 76 65 6e 20 74 68 65 0a 2a 2a 20 6c 61   given the.** la
283a0 72 67 65 2c 20 64 65 66 61 75 6c 74 20 6c 69 6d  rge, default lim
283b0 69 74 73 2e 20 20 44 61 74 61 62 61 73 65 73 20  its.  Databases 
283c0 6d 61 6e 61 67 65 64 20 62 79 20 65 78 74 65 72  managed by exter
283d0 6e 61 6c 20 73 6f 75 72 63 65 73 20 63 61 6e 0a  nal sources can.
283e0 2a 2a 20 62 65 20 67 69 76 65 6e 20 6d 75 63 68  ** be given much
283f0 20 73 6d 61 6c 6c 65 72 20 6c 69 6d 69 74 73 20   smaller limits 
28400 64 65 73 69 67 6e 65 64 20 74 6f 20 70 72 65 76  designed to prev
28410 65 6e 74 20 61 20 64 65 6e 69 61 6c 20 6f 66 20  ent a denial of 
28420 73 65 72 76 69 63 65 0a 2a 2a 20 61 74 74 61 63  service.** attac
28430 6b 2e 20 20 44 65 76 65 6c 6f 70 65 72 73 20 6d  k.  Developers m
28440 69 67 68 74 20 61 6c 73 6f 20 77 61 6e 74 20 74  ight also want t
28450 6f 20 75 73 65 20 74 68 65 20 5b 73 71 6c 69 74  o use the [sqlit
28460 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
28470 72 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63  r()].** interfac
28480 65 20 74 6f 20 66 75 72 74 68 65 72 20 63 6f 6e  e to further con
28490 74 72 6f 6c 20 75 6e 74 72 75 73 74 65 64 20 53  trol untrusted S
284a0 51 4c 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66  QL.  The size of
284b0 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
284c0 20 63 72 65 61 74 65 64 20 62 79 20 61 6e 20 75   created by an u
284d0 6e 74 72 75 73 74 65 64 20 73 63 72 69 70 74 20  ntrusted script 
284e0 63 61 6e 20 62 65 20 63 6f 6e 74 61 69 6e 65 64  can be contained
284f0 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d   using the.** [m
28500 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b  ax_page_count] [
28510 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e  PRAGMA]..**.** N
28520 65 77 20 72 75 6e 2d 74 69 6d 65 20 6c 69 6d 69  ew run-time limi
28530 74 20 63 61 74 65 67 6f 72 69 65 73 20 6d 61 79  t categories may
28540 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74   be added in fut
28550 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2f  ure releases..*/
28560 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
28570 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
28580 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c  qlite3_limit(sql
28590 69 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69  ite3*, int id, i
285a0 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a  nt newVal);../*.
285b0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e  ** CAPI3REF: Run
285c0 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43 61 74 65  -Time Limit Cate
285d0 67 6f 72 69 65 73 0a 2a 2a 20 4b 45 59 57 4f 52  gories.** KEYWOR
285e0 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65 67  DS: {limit categ
285f0 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74 20 63 61 74  ory} {*limit cat
28600 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54  egories}.**.** T
28610 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 64  hese constants d
28620 65 66 69 6e 65 20 76 61 72 69 6f 75 73 20 70 65  efine various pe
28630 72 66 6f 72 6d 61 6e 63 65 20 6c 69 6d 69 74 73  rformance limits
28640 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20  .** that can be 
28650 6c 6f 77 65 72 65 64 20 61 74 20 72 75 6e 2d 74  lowered at run-t
28660 69 6d 65 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ime using [sqlit
28670 65 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20  e3_limit()]..** 
28680 54 68 65 20 73 79 6e 6f 70 73 69 73 20 6f 66 20  The synopsis of 
28690 74 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20  the meanings of 
286a0 74 68 65 20 76 61 72 69 6f 75 73 20 6c 69 6d 69  the various limi
286b0 74 73 20 69 73 20 73 68 6f 77 6e 20 62 65 6c 6f  ts is shown belo
286c0 77 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c  w..** Additional
286d0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20   information is 
286e0 61 76 61 69 6c 61 62 6c 65 20 61 74 20 5b 6c 69  available at [li
286f0 6d 69 74 73 20 7c 20 4c 69 6d 69 74 73 20 69 6e  mits | Limits in
28700 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20   SQLite]..**.** 
28710 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  <dl>.** [[SQLITE
28720 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 5d 20  _LIMIT_LENGTH]] 
28730 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
28740 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a  IT_LENGTH</dt>.*
28750 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
28760 6d 20 73 69 7a 65 20 6f 66 20 61 6e 79 20 73 74  m size of any st
28770 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20  ring or BLOB or 
28780 74 61 62 6c 65 20 72 6f 77 2c 20 69 6e 20 62 79  table row, in by
28790 74 65 73 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  tes.<dd>)^.**.**
287a0 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
287b0 53 51 4c 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c  SQL_LENGTH]] ^(<
287c0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
287d0 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a  SQL_LENGTH</dt>.
287e0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
287f0 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20  um length of an 
28800 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 69  SQL statement, i
28810 6e 20 62 79 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a  n bytes.</dd>)^.
28820 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
28830 49 4d 49 54 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e 28  IMIT_COLUMN]] ^(
28840 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
28850 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20  _COLUMN</dt>.** 
28860 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
28870 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
28880 73 20 69 6e 20 61 20 74 61 62 6c 65 20 64 65 66  s in a table def
28890 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68  inition or in th
288a0 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65 74 20  e.** result set 
288b0 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 6f 72  of a [SELECT] or
288c0 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d   the maximum num
288d0 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
288e0 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72  n an index.** or
288f0 20 69 6e 20 61 6e 20 4f 52 44 45 52 20 42 59 20   in an ORDER BY 
28900 6f 72 20 47 52 4f 55 50 20 42 59 20 63 6c 61 75  or GROUP BY clau
28910 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  se.</dd>)^.**.**
28920 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
28930 45 58 50 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c  EXPR_DEPTH]] ^(<
28940 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
28950 45 58 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a  EXPR_DEPTH</dt>.
28960 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
28970 75 6d 20 64 65 70 74 68 20 6f 66 20 74 68 65 20  um depth of the 
28980 70 61 72 73 65 20 74 72 65 65 20 6f 6e 20 61 6e  parse tree on an
28990 79 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64  y expression.</d
289a0 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
289b0 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55  ITE_LIMIT_COMPOU
289c0 4e 44 5f 53 45 4c 45 43 54 5d 5d 20 5e 28 3c 64  ND_SELECT]] ^(<d
289d0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  t>SQLITE_LIMIT_C
289e0 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f  OMPOUND_SELECT</
289f0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
28a00 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
28a10 20 74 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70   terms in a comp
28a20 6f 75 6e 64 20 53 45 4c 45 43 54 20 73 74 61 74  ound SELECT stat
28a30 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ement.</dd>)^.**
28a40 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
28a50 49 54 5f 56 44 42 45 5f 4f 50 5d 5d 20 5e 28 3c  IT_VDBE_OP]] ^(<
28a60 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
28a70 56 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20  VDBE_OP</dt>.** 
28a80 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
28a90 6e 75 6d 62 65 72 20 6f 66 20 69 6e 73 74 72 75  number of instru
28aa0 63 74 69 6f 6e 73 20 69 6e 20 61 20 76 69 72 74  ctions in a virt
28ab0 75 61 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f 67  ual machine prog
28ac0 72 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69  ram.** used to i
28ad0 6d 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20  mplement an SQL 
28ae0 73 74 61 74 65 6d 65 6e 74 2e 20 20 54 68 69 73  statement.  This
28af0 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 63 75   limit is not cu
28b00 72 72 65 6e 74 6c 79 0a 2a 2a 20 65 6e 66 6f 72  rrently.** enfor
28b10 63 65 64 2c 20 74 68 6f 75 67 68 20 74 68 61 74  ced, though that
28b20 20 6d 69 67 68 74 20 62 65 20 61 64 64 65 64 20   might be added 
28b30 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72  in some future r
28b40 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c  elease of.** SQL
28b50 69 74 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ite.</dd>)^.**.*
28b60 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
28b70 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 5d 20  _FUNCTION_ARG]] 
28b80 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
28b90 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c  IT_FUNCTION_ARG<
28ba0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
28bb0 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
28bc0 66 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61  f arguments on a
28bd0 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29   function.</dd>)
28be0 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
28bf0 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 5d  _LIMIT_ATTACHED]
28c00 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
28c10 49 4d 49 54 5f 41 54 54 41 43 48 45 44 3c 2f 64  IMIT_ATTACHED</d
28c20 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
28c30 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
28c40 5b 41 54 54 41 43 48 20 7c 20 61 74 74 61 63 68  [ATTACH | attach
28c50 65 64 20 64 61 74 61 62 61 73 65 73 5d 2e 29 5e  ed databases].)^
28c60 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
28c70 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f  LITE_LIMIT_LIKE_
28c80 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 5d 5d  PATTERN_LENGTH]]
28c90 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  .** ^(<dt>SQLITE
28ca0 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54  _LIMIT_LIKE_PATT
28cb0 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a  ERN_LENGTH</dt>.
28cc0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
28cd0 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65  um length of the
28ce0 20 70 61 74 74 65 72 6e 20 61 72 67 75 6d 65 6e   pattern argumen
28cf0 74 20 74 6f 20 74 68 65 20 5b 4c 49 4b 45 5d 20  t to the [LIKE] 
28d00 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65  or.** [GLOB] ope
28d10 72 61 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a  rators.</dd>)^.*
28d20 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
28d30 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d  MIT_VARIABLE_NUM
28d40 42 45 52 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53  BER]].** ^(<dt>S
28d50 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49  QLITE_LIMIT_VARI
28d60 41 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e  ABLE_NUMBER</dt>
28d70 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
28d80 6d 75 6d 20 69 6e 64 65 78 20 6e 75 6d 62 65 72  mum index number
28d90 20 6f 66 20 61 6e 79 20 5b 70 61 72 61 6d 65 74   of any [paramet
28da0 65 72 5d 20 69 6e 20 61 6e 20 53 51 4c 20 73 74  er] in an SQL st
28db0 61 74 65 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a  atement.)^.**.**
28dc0 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
28dd0 54 52 49 47 47 45 52 5f 44 45 50 54 48 5d 5d 20  TRIGGER_DEPTH]] 
28de0 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
28df0 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48  IT_TRIGGER_DEPTH
28e00 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
28e10 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f   maximum depth o
28e20 66 20 72 65 63 75 72 73 69 6f 6e 20 66 6f 72 20  f recursion for 
28e30 74 72 69 67 67 65 72 73 2e 3c 2f 64 64 3e 29 5e  triggers.</dd>)^
28e40 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
28e50 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52  LIMIT_WORKER_THR
28e60 45 41 44 53 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  EADS]] ^(<dt>SQL
28e70 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52  ITE_LIMIT_WORKER
28e80 5f 54 48 52 45 41 44 53 3c 2f 64 74 3e 0a 2a 2a  _THREADS</dt>.**
28e90 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
28ea0 20 6e 75 6d 62 65 72 20 6f 66 20 61 75 78 69 6c   number of auxil
28eb0 69 61 72 79 20 77 6f 72 6b 65 72 20 74 68 72 65  iary worker thre
28ec0 61 64 73 20 74 68 61 74 20 61 20 73 69 6e 67 6c  ads that a singl
28ed0 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
28ee0 74 61 74 65 6d 65 6e 74 5d 20 6d 61 79 20 73 74  tatement] may st
28ef0 61 72 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c  art.</dd>)^.** <
28f00 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  /dl>.*/.#define 
28f10 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e  SQLITE_LIMIT_LEN
28f20 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20  GTH             
28f30 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65         0.#define
28f40 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51   SQLITE_LIMIT_SQ
28f50 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20  L_LENGTH        
28f60 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e          1.#defin
28f70 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  e SQLITE_LIMIT_C
28f80 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20 20 20 20  OLUMN           
28f90 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69           2.#defi
28fa0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
28fb0 45 58 50 52 5f 44 45 50 54 48 20 20 20 20 20 20  EXPR_DEPTH      
28fc0 20 20 20 20 20 20 20 20 20 20 33 0a 23 64 65 66            3.#def
28fd0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
28fe0 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54  _COMPOUND_SELECT
28ff0 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65             4.#de
29000 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
29010 54 5f 56 44 42 45 5f 4f 50 20 20 20 20 20 20 20  T_VDBE_OP       
29020 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 64              5.#d
29030 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
29040 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20  IT_FUNCTION_ARG 
29050 20 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 23               6.#
29060 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
29070 4d 49 54 5f 41 54 54 41 43 48 45 44 20 20 20 20  MIT_ATTACHED    
29080 20 20 20 20 20 20 20 20 20 20 20 20 20 20 37 0a                7.
29090 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
290a0 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52  IMIT_LIKE_PATTER
290b0 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 38  N_LENGTH       8
290c0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
290d0 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e  LIMIT_VARIABLE_N
290e0 55 4d 42 45 52 20 20 20 20 20 20 20 20 20 20 20  UMBER           
290f0 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  9.#define SQLITE
29100 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44  _LIMIT_TRIGGER_D
29110 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20  EPTH            
29120 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  10.#define SQLIT
29130 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54  E_LIMIT_WORKER_T
29140 48 52 45 41 44 53 20 20 20 20 20 20 20 20 20 20  HREADS          
29150 20 31 31 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   11../*.** CAPI3
29160 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41  REF: Compiling A
29170 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a  n SQL Statement.
29180 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51  ** KEYWORDS: {SQ
29190 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70  L statement comp
291a0 69 6c 65 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65  iler}.**.** To e
291b0 78 65 63 75 74 65 20 61 6e 20 53 51 4c 20 71 75  xecute an SQL qu
291c0 65 72 79 2c 20 69 74 20 6d 75 73 74 20 66 69 72  ery, it must fir
291d0 73 74 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 69  st be compiled i
291e0 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f 64 65 0a  nto a byte-code.
291f0 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 69 6e 67  ** program using
29200 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 72 6f   one of these ro
29210 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  utines..**.** Th
29220 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
29230 2c 20 22 64 62 22 2c 20 69 73 20 61 20 5b 64 61  , "db", is a [da
29240 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
29250 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  n] obtained from
29260 20 61 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63 63   a.** prior succ
29270 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b  essful call to [
29280 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
29290 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
292a0 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  2()] or.** [sqli
292b0 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20  te3_open16()].  
292c0 54 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  The database con
292d0 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  nection must not
292e0 20 68 61 76 65 20 62 65 65 6e 20 63 6c 6f 73 65   have been close
292f0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63  d..**.** The sec
29300 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a  ond argument, "z
29310 53 71 6c 22 2c 20 69 73 20 74 68 65 20 73 74 61  Sql", is the sta
29320 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d  tement to be com
29330 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a  piled, encoded.*
29340 2a 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d  * as either UTF-
29350 38 20 6f 72 20 55 54 46 2d 31 36 2e 20 20 54 68  8 or UTF-16.  Th
29360 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  e sqlite3_prepar
29370 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  e() and sqlite3_
29380 70 72 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20  prepare_v2().** 
29390 69 6e 74 65 72 66 61 63 65 73 20 75 73 65 20 55  interfaces use U
293a0 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69 74 65  TF-8, and sqlite
293b0 33 5f 70 72 65 70 61 72 65 31 36 28 29 20 61 6e  3_prepare16() an
293c0 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  d sqlite3_prepar
293d0 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20  e16_v2().** use 
293e0 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49  UTF-16..**.** ^I
293f0 66 20 74 68 65 20 6e 42 79 74 65 20 61 72 67 75  f the nByte argu
29400 6d 65 6e 74 20 69 73 20 6e 65 67 61 74 69 76 65  ment is negative
29410 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20 72  , then zSql is r
29420 65 61 64 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a  ead up to the.**
29430 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d   first zero term
29440 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e 42 79 74  inator. ^If nByt
29450 65 20 69 73 20 70 6f 73 69 74 69 76 65 2c 20 74  e is positive, t
29460 68 65 6e 20 69 74 20 69 73 20 74 68 65 0a 2a 2a  hen it is the.**
29470 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
29480 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e   read from zSql.
29490 20 20 5e 49 66 20 6e 42 79 74 65 20 69 73 20 7a    ^If nByte is z
294a0 65 72 6f 2c 20 74 68 65 6e 20 6e 6f 20 70 72 65  ero, then no pre
294b0 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65  pared.** stateme
294c0 6e 74 20 69 73 20 67 65 6e 65 72 61 74 65 64 2e  nt is generated.
294d0 0a 2a 2a 20 49 66 20 74 68 65 20 63 61 6c 6c 65  .** If the calle
294e0 72 20 6b 6e 6f 77 73 20 74 68 61 74 20 74 68 65  r knows that the
294f0 20 73 75 70 70 6c 69 65 64 20 73 74 72 69 6e 67   supplied string
29500 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74   is nul-terminat
29510 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 72  ed, then.** ther
29520 65 20 69 73 20 61 20 73 6d 61 6c 6c 20 70 65 72  e is a small per
29530 66 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e 74 61  formance advanta
29540 67 65 20 74 6f 20 70 61 73 73 69 6e 67 20 61 6e  ge to passing an
29550 20 6e 42 79 74 65 20 70 61 72 61 6d 65 74 65 72   nByte parameter
29560 20 74 68 61 74 0a 2a 2a 20 69 73 20 74 68 65 20   that.** is the 
29570 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
29580 69 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72  in the input str
29590 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67  ing <i>including
295a0 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d  </i>.** the nul-
295b0 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a  terminator..**.*
295c0 2a 20 5e 49 66 20 70 7a 54 61 69 6c 20 69 73 20  * ^If pzTail is 
295d0 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 2a 70  not NULL then *p
295e0 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20 74 6f  zTail is made to
295f0 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 66 69   point to the fi
29600 72 73 74 20 62 79 74 65 0a 2a 2a 20 70 61 73 74  rst byte.** past
29610 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20   the end of the 
29620 66 69 72 73 74 20 53 51 4c 20 73 74 61 74 65 6d  first SQL statem
29630 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68  ent in zSql.  Th
29640 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c  ese routines onl
29650 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 68 65  y.** compile the
29660 20 66 69 72 73 74 20 73 74 61 74 65 6d 65 6e 74   first statement
29670 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a   in zSql, so *pz
29680 54 61 69 6c 20 69 73 20 6c 65 66 74 20 70 6f 69  Tail is left poi
29690 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20 77 68 61 74  nting to.** what
296a0 20 72 65 6d 61 69 6e 73 20 75 6e 63 6f 6d 70 69   remains uncompi
296b0 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53  led..**.** ^*ppS
296c0 74 6d 74 20 69 73 20 6c 65 66 74 20 70 6f 69 6e  tmt is left poin
296d0 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c  ting to a compil
296e0 65 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ed [prepared sta
296f0 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 63 61 6e  tement] that can
29700 20 62 65 0a 2a 2a 20 65 78 65 63 75 74 65 64 20   be.** executed 
29710 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73  using [sqlite3_s
29720 74 65 70 28 29 5d 2e 20 20 5e 49 66 20 74 68 65  tep()].  ^If the
29730 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72 2c 20  re is an error, 
29740 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 0a 2a  *ppStmt is set.*
29750 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66 20  * to NULL.  ^If 
29760 74 68 65 20 69 6e 70 75 74 20 74 65 78 74 20 63  the input text c
29770 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28  ontains no SQL (
29780 69 66 20 74 68 65 20 69 6e 70 75 74 20 69 73 20  if the input is 
29790 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74 72 69  an empty.** stri
297a0 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29  ng or a comment)
297b0 20 74 68 65 6e 20 2a 70 70 53 74 6d 74 20 69 73   then *ppStmt is
297c0 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a   set to NULL..**
297d0 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 70 72 6f   The calling pro
297e0 63 65 64 75 72 65 20 69 73 20 72 65 73 70 6f 6e  cedure is respon
297f0 73 69 62 6c 65 20 66 6f 72 20 64 65 6c 65 74 69  sible for deleti
29800 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 0a  ng the compiled.
29810 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
29820 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
29830 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66 74 65  finalize()] afte
29840 72 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65  r it has finishe
29850 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a 20 70 70  d with it..** pp
29860 53 74 6d 74 20 6d 61 79 20 6e 6f 74 20 62 65 20  Stmt may not be 
29870 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20  NULL..**.** ^On 
29880 73 75 63 63 65 73 73 2c 20 74 68 65 20 73 71 6c  success, the sql
29890 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 66  ite3_prepare() f
298a0 61 6d 69 6c 79 20 6f 66 20 72 6f 75 74 69 6e 65  amily of routine
298b0 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  s return [SQLITE
298c0 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77 69  _OK];.** otherwi
298d0 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64  se an [error cod
298e0 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  e] is returned..
298f0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
29900 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 61  3_prepare_v2() a
29910 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
29920 72 65 31 36 5f 76 32 28 29 20 69 6e 74 65 72 66  re16_v2() interf
29930 61 63 65 73 20 61 72 65 0a 2a 2a 20 72 65 63 6f  aces are.** reco
29940 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20  mmended for all 
29950 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e 20 54 68  new programs. Th
29960 65 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e 74 65  e two older inte
29970 72 66 61 63 65 73 20 61 72 65 20 72 65 74 61 69  rfaces are retai
29980 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63 6b 77  ned.** for backw
29990 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
299a0 74 79 2c 20 62 75 74 20 74 68 65 69 72 20 75 73  ty, but their us
299b0 65 20 69 73 20 64 69 73 63 6f 75 72 61 67 65 64  e is discouraged
299c0 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 22 76 32  ..** ^In the "v2
299d0 22 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68  " interfaces, th
299e0 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
299f0 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73 20  ment.** that is 
29a00 72 65 74 75 72 6e 65 64 20 28 74 68 65 20 5b 73  returned (the [s
29a10 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a  qlite3_stmt] obj
29a20 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 20 61 20  ect) contains a 
29a30 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f  copy of the.** o
29a40 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74  riginal SQL text
29a50 2e 20 54 68 69 73 20 63 61 75 73 65 73 20 74 68  . This causes th
29a60 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  e [sqlite3_step(
29a70 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f 0a  )] interface to.
29a80 2a 2a 20 62 65 68 61 76 65 20 64 69 66 66 65 72  ** behave differ
29a90 65 6e 74 6c 79 20 69 6e 20 74 68 72 65 65 20 77  ently in three w
29aa0 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a  ays:.**.** <ol>.
29ab0 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74  ** <li>.** ^If t
29ac0 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65  he database sche
29ad0 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 6e 73 74  ma changes, inst
29ae0 65 61 64 20 6f 66 20 72 65 74 75 72 6e 69 6e 67  ead of returning
29af0 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d   [SQLITE_SCHEMA]
29b00 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73   as it.** always
29b10 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71   used to do, [sq
29b20 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69  lite3_step()] wi
29b30 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ll automatically
29b40 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 65 20 53   recompile the S
29b50 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  QL.** statement 
29b60 61 6e 64 20 74 72 79 20 74 6f 20 72 75 6e 20 69  and try to run i
29b70 74 20 61 67 61 69 6e 2e 20 41 73 20 6d 61 6e 79  t again. As many
29b80 20 61 73 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f   as [SQLITE_MAX_
29b90 53 43 48 45 4d 41 5f 52 45 54 52 59 5d 0a 2a 2a  SCHEMA_RETRY].**
29ba0 20 72 65 74 72 69 65 73 20 77 69 6c 6c 20 6f 63   retries will oc
29bb0 63 75 72 20 62 65 66 6f 72 65 20 73 71 6c 69 74  cur before sqlit
29bc0 65 33 5f 73 74 65 70 28 29 20 67 69 76 65 73 20  e3_step() gives 
29bd0 75 70 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61  up and returns a
29be0 6e 20 65 72 72 6f 72 2e 0a 2a 2a 20 3c 2f 6c 69  n error..** </li
29bf0 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20  >.**.** <li>.** 
29c00 5e 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f  ^When an error o
29c10 63 63 75 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f  ccurs, [sqlite3_
29c20 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 72 65 74  step()] will ret
29c30 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 64  urn one of the d
29c40 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f  etailed.** [erro
29c50 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74  r codes] or [ext
29c60 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65  ended error code
29c70 73 5d 2e 20 20 5e 54 68 65 20 6c 65 67 61 63 79  s].  ^The legacy
29c80 20 62 65 68 61 76 69 6f 72 20 77 61 73 20 74 68   behavior was th
29c90 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  at.** [sqlite3_s
29ca0 74 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c  tep()] would onl
29cb0 79 20 72 65 74 75 72 6e 20 61 20 67 65 6e 65 72  y return a gener
29cc0 69 63 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ic [SQLITE_ERROR
29cd0 5d 20 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a  ] result code.**
29ce0 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61   and the applica
29cf0 74 69 6f 6e 20 77 6f 75 6c 64 20 68 61 76 65 20  tion would have 
29d00 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64  to make a second
29d10 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
29d20 33 5f 72 65 73 65 74 28 29 5d 0a 2a 2a 20 69 6e  3_reset()].** in
29d30 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 74   order to find t
29d40 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 63 61  he underlying ca
29d50 75 73 65 20 6f 66 20 74 68 65 20 70 72 6f 62 6c  use of the probl
29d60 65 6d 2e 20 57 69 74 68 20 74 68 65 20 22 76 32  em. With the "v2
29d70 22 20 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74  " prepare.** int
29d80 65 72 66 61 63 65 73 2c 20 74 68 65 20 75 6e 64  erfaces, the und
29d90 65 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20 66  erlying reason f
29da0 6f 72 20 74 68 65 20 65 72 72 6f 72 20 69 73 20  or the error is 
29db0 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61  returned immedia
29dc0 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a  tely..** </li>.*
29dd0 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66  *.** <li>.** ^If
29de0 20 74 68 65 20 73 70 65 63 69 66 69 63 20 76 61   the specific va
29df0 6c 75 65 20 62 6f 75 6e 64 20 74 6f 20 5b 70 61  lue bound to [pa
29e00 72 61 6d 65 74 65 72 20 7c 20 68 6f 73 74 20 70  rameter | host p
29e10 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65  arameter] in the
29e20 20 0a 2a 2a 20 57 48 45 52 45 20 63 6c 61 75 73   .** WHERE claus
29e30 65 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63  e might influenc
29e40 65 20 74 68 65 20 63 68 6f 69 63 65 20 6f 66 20  e the choice of 
29e50 71 75 65 72 79 20 70 6c 61 6e 20 66 6f 72 20 61  query plan for a
29e60 20 73 74 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20 74   statement,.** t
29e70 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e  hen the statemen
29e80 74 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61  t will be automa
29e90 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c  tically recompil
29ea0 65 64 2c 20 61 73 20 69 66 20 74 68 65 72 65 20  ed, as if there 
29eb0 68 61 64 20 62 65 65 6e 20 0a 2a 2a 20 61 20 73  had been .** a s
29ec0 63 68 65 6d 61 20 63 68 61 6e 67 65 2c 20 6f 6e  chema change, on
29ed0 20 74 68 65 20 66 69 72 73 74 20 20 5b 73 71 6c   the first  [sql
29ee0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c  ite3_step()] cal
29ef0 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 20  l following any 
29f00 63 68 61 6e 67 65 0a 2a 2a 20 74 6f 20 74 68 65  change.** to the
29f10 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74   [sqlite3_bind_t
29f20 65 78 74 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20  ext | bindings] 
29f30 6f 66 20 74 68 61 74 20 5b 70 61 72 61 6d 65 74  of that [paramet
29f40 65 72 5d 2e 20 0a 2a 2a 20 5e 54 68 65 20 73 70  er]. .** ^The sp
29f50 65 63 69 66 69 63 20 76 61 6c 75 65 20 6f 66 20  ecific value of 
29f60 57 48 45 52 45 2d 63 6c 61 75 73 65 20 5b 70 61  WHERE-clause [pa
29f70 72 61 6d 65 74 65 72 5d 20 6d 69 67 68 74 20 69  rameter] might i
29f80 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 0a 2a 2a  nfluence the .**
29f90 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79   choice of query
29fa0 20 70 6c 61 6e 20 69 66 20 74 68 65 20 70 61 72   plan if the par
29fb0 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6c 65  ameter is the le
29fc0 66 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20  ft-hand side of 
29fd0 61 20 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f 72 20 5b  a [LIKE].** or [
29fe0 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 20 6f  GLOB] operator o
29ff0 72 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  r if the paramet
2a000 65 72 20 69 73 20 63 6f 6d 70 61 72 65 64 20 74  er is compared t
2a010 6f 20 61 6e 20 69 6e 64 65 78 65 64 20 63 6f 6c  o an indexed col
2a020 75 6d 6e 0a 2a 2a 20 61 6e 64 20 74 68 65 20 5b  umn.** and the [
2a030 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 54  SQLITE_ENABLE_ST
2a040 41 54 33 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  AT3] compile-tim
2a050 65 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 62  e option is enab
2a060 6c 65 64 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a  led..** </li>.**
2a070 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 53 51 4c 49 54 45   </ol>.*/.SQLITE
2a080 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f  _API int SQLITE_
2a090 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
2a0a0 70 72 65 70 61 72 65 28 0a 20 20 73 71 6c 69 74  prepare(.  sqlit
2a0b0 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
2a0c0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68     /* Database h
2a0d0 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
2a0e0 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20   char *zSql,    
2a0f0 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d     /* SQL statem
2a100 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64  ent, UTF-8 encod
2a110 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
2a120 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
2a130 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
2a140 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
2a150 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  es. */.  sqlite3
2a160 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
2a170 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
2a180 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
2a190 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61  onst char **pzTa
2a1a0 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
2a1b0 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
2a1c0 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
2a1d0 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50   */.);.SQLITE_AP
2a1e0 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  I int SQLITE_STD
2a1f0 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 70 72 65  CALL sqlite3_pre
2a200 70 61 72 65 5f 76 32 28 0a 20 20 73 71 6c 69 74  pare_v2(.  sqlit
2a210 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
2a220 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68     /* Database h
2a230 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
2a240 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20   char *zSql,    
2a250 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d     /* SQL statem
2a260 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64  ent, UTF-8 encod
2a270 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
2a280 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
2a290 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
2a2a0 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
2a2b0 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  es. */.  sqlite3
2a2c0 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
2a2d0 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
2a2e0 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
2a2f0 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61  onst char **pzTa
2a300 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
2a310 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
2a320 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
2a330 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50   */.);.SQLITE_AP
2a340 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  I int SQLITE_STD
2a350 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 70 72 65  CALL sqlite3_pre
2a360 70 61 72 65 31 36 28 0a 20 20 73 71 6c 69 74 65  pare16(.  sqlite
2a370 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
2a380 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
2a390 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
2a3a0 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20  void *zSql,     
2a3b0 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
2a3c0 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64  nt, UTF-16 encod
2a3d0 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
2a3e0 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
2a3f0 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
2a400 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
2a410 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  es. */.  sqlite3
2a420 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
2a430 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
2a440 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
2a450 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61  onst void **pzTa
2a460 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
2a470 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
2a480 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
2a490 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50   */.);.SQLITE_AP
2a4a0 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  I int SQLITE_STD
2a4b0 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 70 72 65  CALL sqlite3_pre
2a4c0 70 61 72 65 31 36 5f 76 32 28 0a 20 20 73 71 6c  pare16_v2(.  sql
2a4d0 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
2a4e0 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
2a4f0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
2a500 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20  st void *zSql,  
2a510 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
2a520 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e  ement, UTF-16 en
2a530 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e  coded */.  int n
2a540 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20  Byte,           
2a550 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65     /* Maximum le
2a560 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20  ngth of zSql in 
2a570 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69  bytes. */.  sqli
2a580 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d  te3_stmt **ppStm
2a590 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74  t,  /* OUT: Stat
2a5a0 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a  ement handle */.
2a5b0 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70    const void **p
2a5c0 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54  zTail     /* OUT
2a5d0 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75  : Pointer to unu
2a5e0 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a  sed portion of z
2a5f0 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  Sql */.);../*.**
2a600 20 43 41 50 49 33 52 45 46 3a 20 52 65 74 72 69   CAPI3REF: Retri
2a610 65 76 69 6e 67 20 53 74 61 74 65 6d 65 6e 74 20  eving Statement 
2a620 53 51 4c 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  SQL.**.** ^This 
2a630 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65  interface can be
2a640 20 75 73 65 64 20 74 6f 20 72 65 74 72 69 65 76   used to retriev
2a650 65 20 61 20 73 61 76 65 64 20 63 6f 70 79 20 6f  e a saved copy o
2a660 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a 2a  f the original.*
2a670 2a 20 53 51 4c 20 74 65 78 74 20 75 73 65 64 20  * SQL text used 
2a680 74 6f 20 63 72 65 61 74 65 20 61 20 5b 70 72 65  to create a [pre
2a690 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2a6a0 20 69 66 20 74 68 61 74 20 73 74 61 74 65 6d 65   if that stateme
2a6b0 6e 74 20 77 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c  nt was.** compil
2a6c0 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 20  ed using either 
2a6d0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2a6e0 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  _v2()] or [sqlit
2a6f0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
2a700 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  )]..*/.SQLITE_AP
2a710 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51  I const char *SQ
2a720 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
2a730 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 74 65 33  ite3_sql(sqlite3
2a740 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
2a750 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2a760 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20  Determine If An 
2a770 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 57 72  SQL Statement Wr
2a780 69 74 65 73 20 54 68 65 20 44 61 74 61 62 61 73  ites The Databas
2a790 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  e.**.** ^The sql
2a7a0 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e  ite3_stmt_readon
2a7b0 6c 79 28 58 29 20 69 6e 74 65 72 66 61 63 65 20  ly(X) interface 
2a7c0 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f  returns true (no
2a7d0 6e 2d 7a 65 72 6f 29 20 69 66 0a 2a 2a 20 61 6e  n-zero) if.** an
2a7e0 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 5b 70  d only if the [p
2a7f0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2a800 74 5d 20 58 20 6d 61 6b 65 73 20 6e 6f 20 64 69  t] X makes no di
2a810 72 65 63 74 20 63 68 61 6e 67 65 73 20 74 6f 0a  rect changes to.
2a820 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  ** the content o
2a830 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  f the database f
2a840 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  ile..**.** Note 
2a850 74 68 61 74 20 5b 61 70 70 6c 69 63 61 74 69 6f  that [applicatio
2a860 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
2a870 6e 63 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b  nctions] or.** [
2a880 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 20  virtual tables] 
2a890 6d 69 67 68 74 20 63 68 61 6e 67 65 20 74 68 65  might change the
2a8a0 20 64 61 74 61 62 61 73 65 20 69 6e 64 69 72 65   database indire
2a8b0 63 74 6c 79 20 61 73 20 61 20 73 69 64 65 20 65  ctly as a side e
2a8c0 66 66 65 63 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f  ffect.  .** ^(Fo
2a8d0 72 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 61 6e  r example, if an
2a8e0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66   application def
2a8f0 69 6e 65 73 20 61 20 66 75 6e 63 74 69 6f 6e 20  ines a function 
2a900 22 65 76 61 6c 28 29 22 20 74 68 61 74 20 0a 2a  "eval()" that .*
2a910 2a 20 63 61 6c 6c 73 20 5b 73 71 6c 69 74 65 33  * calls [sqlite3
2a920 5f 65 78 65 63 28 29 5d 2c 20 74 68 65 6e 20 74  _exec()], then t
2a930 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c  he following SQL
2a940 20 73 74 61 74 65 6d 65 6e 74 20 77 6f 75 6c 64   statement would
2a950 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 64  .** change the d
2a960 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 68 72  atabase file thr
2a970 6f 75 67 68 20 73 69 64 65 2d 65 66 66 65 63 74  ough side-effect
2a980 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
2a990 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20  uote><pre>.**   
2a9a0 20 53 45 4c 45 43 54 20 65 76 61 6c 28 27 44 45   SELECT eval('DE
2a9b0 4c 45 54 45 20 46 52 4f 4d 20 74 31 27 29 20 46  LETE FROM t1') F
2a9c0 52 4f 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65  ROM t2;.** </pre
2a9d0 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
2a9e0 2a 0a 2a 2a 20 42 75 74 20 62 65 63 61 75 73 65  *.** But because
2a9f0 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74   the [SELECT] st
2aa00 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74  atement does not
2aa10 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61   change the data
2aa20 62 61 73 65 20 66 69 6c 65 0a 2a 2a 20 64 69 72  base file.** dir
2aa30 65 63 74 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73  ectly, sqlite3_s
2aa40 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 77  tmt_readonly() w
2aa50 6f 75 6c 64 20 73 74 69 6c 6c 20 72 65 74 75 72  ould still retur
2aa60 6e 20 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20  n true.)^.**.** 
2aa70 5e 54 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e  ^Transaction con
2aa80 74 72 6f 6c 20 73 74 61 74 65 6d 65 6e 74 73 20  trol statements 
2aa90 73 75 63 68 20 61 73 20 5b 42 45 47 49 4e 5d 2c  such as [BEGIN],
2aaa0 20 5b 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c   [COMMIT], [ROLL
2aab0 42 41 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50  BACK],.** [SAVEP
2aac0 4f 49 4e 54 5d 2c 20 61 6e 64 20 5b 52 45 4c 45  OINT], and [RELE
2aad0 41 53 45 5d 20 63 61 75 73 65 20 73 71 6c 69 74  ASE] cause sqlit
2aae0 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
2aaf0 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75  () to return tru
2ab00 65 2c 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20  e,.** since the 
2ab10 73 74 61 74 65 6d 65 6e 74 73 20 74 68 65 6d 73  statements thems
2ab20 65 6c 76 65 73 20 64 6f 20 6e 6f 74 20 61 63 74  elves do not act
2ab30 75 61 6c 6c 79 20 6d 6f 64 69 66 79 20 74 68 65  ually modify the
2ab40 20 64 61 74 61 62 61 73 65 20 62 75 74 0a 2a 2a   database but.**
2ab50 20 72 61 74 68 65 72 20 74 68 65 79 20 63 6f 6e   rather they con
2ab60 74 72 6f 6c 20 74 68 65 20 74 69 6d 69 6e 67 20  trol the timing 
2ab70 6f 66 20 77 68 65 6e 20 6f 74 68 65 72 20 73 74  of when other st
2ab80 61 74 65 6d 65 6e 74 73 20 6d 6f 64 69 66 79 20  atements modify 
2ab90 74 68 65 20 0a 2a 2a 20 64 61 74 61 62 61 73 65  the .** database
2aba0 2e 20 20 5e 54 68 65 20 5b 41 54 54 41 43 48 5d  .  ^The [ATTACH]
2abb0 20 61 6e 64 20 5b 44 45 54 41 43 48 5d 20 73 74   and [DETACH] st
2abc0 61 74 65 6d 65 6e 74 73 20 61 6c 73 6f 20 63 61  atements also ca
2abd0 75 73 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  use.** sqlite3_s
2abe0 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74  tmt_readonly() t
2abf0 6f 20 72 65 74 75 72 6e 20 74 72 75 65 20 73 69  o return true si
2ac00 6e 63 65 2c 20 77 68 69 6c 65 20 74 68 6f 73 65  nce, while those
2ac10 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 63   statements.** c
2ac20 68 61 6e 67 65 20 74 68 65 20 63 6f 6e 66 69 67  hange the config
2ac30 75 72 61 74 69 6f 6e 20 6f 66 20 61 20 64 61 74  uration of a dat
2ac40 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2ac50 2c 20 74 68 65 79 20 64 6f 20 6e 6f 74 20 6d 61  , they do not ma
2ac60 6b 65 20 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74  ke .** changes t
2ac70 6f 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66  o the content of
2ac80 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
2ac90 6c 65 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a 2f 0a  les on disk..*/.
2aca0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53  SQLITE_API int S
2acb0 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
2acc0 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f  lite3_stmt_reado
2acd0 6e 6c 79 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  nly(sqlite3_stmt
2ace0 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
2acf0 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72   CAPI3REF: Deter
2ad00 6d 69 6e 65 20 49 66 20 41 20 50 72 65 70 61 72  mine If A Prepar
2ad10 65 64 20 53 74 61 74 65 6d 65 6e 74 20 48 61 73  ed Statement Has
2ad20 20 42 65 65 6e 20 52 65 73 65 74 0a 2a 2a 0a 2a   Been Reset.**.*
2ad30 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73  * ^The sqlite3_s
2ad40 74 6d 74 5f 62 75 73 79 28 53 29 20 69 6e 74 65  tmt_busy(S) inte
2ad50 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 72  rface returns tr
2ad60 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66  ue (non-zero) if
2ad70 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
2ad80 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 68  d statement] S h
2ad90 61 73 20 62 65 65 6e 20 73 74 65 70 70 65 64 20  as been stepped 
2ada0 61 74 20 6c 65 61 73 74 20 6f 6e 63 65 20 75 73  at least once us
2adb0 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ing .** [sqlite3
2adc0 5f 73 74 65 70 28 53 29 5d 20 62 75 74 20 68 61  _step(S)] but ha
2add0 73 20 6e 6f 74 20 72 75 6e 20 74 6f 20 63 6f 6d  s not run to com
2ade0 70 6c 65 74 69 6f 6e 20 61 6e 64 2f 6f 72 20 68  pletion and/or h
2adf0 61 73 20 6e 6f 74 20 0a 2a 2a 20 62 65 65 6e 20  as not .** been 
2ae00 72 65 73 65 74 20 75 73 69 6e 67 20 5b 73 71 6c  reset using [sql
2ae10 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 2e 20  ite3_reset(S)]. 
2ae20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74   ^The sqlite3_st
2ae30 6d 74 5f 62 75 73 79 28 53 29 0a 2a 2a 20 69 6e  mt_busy(S).** in
2ae40 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
2ae50 66 61 6c 73 65 20 69 66 20 53 20 69 73 20 61 20  false if S is a 
2ae60 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 49  NULL pointer.  I
2ae70 66 20 53 20 69 73 20 6e 6f 74 20 61 20 0a 2a 2a  f S is not a .**
2ae80 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e   NULL pointer an
2ae90 64 20 69 73 20 6e 6f 74 20 61 20 70 6f 69 6e 74  d is not a point
2aea0 65 72 20 74 6f 20 61 20 76 61 6c 69 64 20 5b 70  er to a valid [p
2aeb0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2aec0 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2c 20 74 68  t].** object, th
2aed0 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
2aee0 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64  is undefined and
2aef0 20 70 72 6f 62 61 62 6c 79 20 75 6e 64 65 73 69   probably undesi
2af00 72 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  rable..**.** Thi
2af10 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20  s interface can 
2af20 62 65 20 75 73 65 64 20 69 6e 20 63 6f 6d 62 69  be used in combi
2af30 6e 61 74 69 6f 6e 20 5b 73 71 6c 69 74 65 33 5f  nation [sqlite3_
2af40 6e 65 78 74 5f 73 74 6d 74 28 29 5d 0a 2a 2a 20  next_stmt()].** 
2af50 74 6f 20 6c 6f 63 61 74 65 20 61 6c 6c 20 70 72  to locate all pr
2af60 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2af70 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  s associated wit
2af80 68 20 61 20 64 61 74 61 62 61 73 65 20 0a 2a 2a  h a database .**
2af90 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74   connection that
2afa0 20 61 72 65 20 69 6e 20 6e 65 65 64 20 6f 66 20   are in need of 
2afb0 62 65 69 6e 67 20 72 65 73 65 74 2e 20 20 54 68  being reset.  Th
2afc0 69 73 20 63 61 6e 20 62 65 20 75 73 65 64 2c 0a  is can be used,.
2afd0 2a 2a 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20  ** for example, 
2afe0 69 6e 20 64 69 61 67 6e 6f 73 74 69 63 20 72 6f  in diagnostic ro
2aff0 75 74 69 6e 65 73 20 74 6f 20 73 65 61 72 63 68  utines to search
2b000 20 66 6f 72 20 70 72 65 70 61 72 65 64 20 0a 2a   for prepared .*
2b010 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61  * statements tha
2b020 74 20 61 72 65 20 68 6f 6c 64 69 6e 67 20 61 20  t are holding a 
2b030 74 72 61 6e 73 61 63 74 69 6f 6e 20 6f 70 65 6e  transaction open
2b040 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
2b050 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41  int SQLITE_STDCA
2b060 4c 4c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  LL sqlite3_stmt_
2b070 62 75 73 79 28 73 71 6c 69 74 65 33 5f 73 74 6d  busy(sqlite3_stm
2b080 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
2b090 33 52 45 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c  3REF: Dynamicall
2b0a0 79 20 54 79 70 65 64 20 56 61 6c 75 65 20 4f 62  y Typed Value Ob
2b0b0 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ject.** KEYWORDS
2b0c0 3a 20 7b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  : {protected sql
2b0d0 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70  ite3_value} {unp
2b0e0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2b0f0 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51  _value}.**.** SQ
2b100 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 73 71  Lite uses the sq
2b110 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
2b120 63 74 20 74 6f 20 72 65 70 72 65 73 65 6e 74 20  ct to represent 
2b130 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68  all values.** th
2b140 61 74 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64  at can be stored
2b150 20 69 6e 20 61 20 64 61 74 61 62 61 73 65 20 74   in a database t
2b160 61 62 6c 65 2e 20 53 51 4c 69 74 65 20 75 73 65  able. SQLite use
2b170 73 20 64 79 6e 61 6d 69 63 20 74 79 70 69 6e 67  s dynamic typing
2b180 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76 61 6c 75  .** for the valu
2b190 65 73 20 69 74 20 73 74 6f 72 65 73 2e 20 20 5e  es it stores.  ^
2b1a0 56 61 6c 75 65 73 20 73 74 6f 72 65 64 20 69 6e  Values stored in
2b1b0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
2b1c0 62 6a 65 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65  bjects.** can be
2b1d0 20 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61 74   integers, float
2b1e0 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 73  ing point values
2b1f0 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73  , strings, BLOBs
2b200 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  , or NULL..**.**
2b210 20 41 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75   An sqlite3_valu
2b220 65 20 6f 62 6a 65 63 74 20 6d 61 79 20 62 65 20  e object may be 
2b230 65 69 74 68 65 72 20 22 70 72 6f 74 65 63 74 65  either "protecte
2b240 64 22 20 6f 72 20 22 75 6e 70 72 6f 74 65 63 74  d" or "unprotect
2b250 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74  ed"..** Some int
2b260 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20  erfaces require 
2b270 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  a protected sqli
2b280 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65  te3_value.  Othe
2b290 72 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  r interfaces.** 
2b2a0 77 69 6c 6c 20 61 63 63 65 70 74 20 65 69 74 68  will accept eith
2b2b0 65 72 20 61 20 70 72 6f 74 65 63 74 65 64 20 6f  er a protected o
2b2c0 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64  r an unprotected
2b2d0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a   sqlite3_value..
2b2e0 2a 2a 20 45 76 65 72 79 20 69 6e 74 65 72 66 61  ** Every interfa
2b2f0 63 65 20 74 68 61 74 20 61 63 63 65 70 74 73 20  ce that accepts 
2b300 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 61 72  sqlite3_value ar
2b310 67 75 6d 65 6e 74 73 20 73 70 65 63 69 66 69 65  guments specifie
2b320 73 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f 72 20  s.** whether or 
2b330 6e 6f 74 20 69 74 20 72 65 71 75 69 72 65 73 20  not it requires 
2b340 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  a protected sqli
2b350 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a  te3_value..**.**
2b360 20 54 68 65 20 74 65 72 6d 73 20 22 70 72 6f 74   The terms "prot
2b370 65 63 74 65 64 22 20 61 6e 64 20 22 75 6e 70 72  ected" and "unpr
2b380 6f 74 65 63 74 65 64 22 20 72 65 66 65 72 20 74  otected" refer t
2b390 6f 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  o whether or not
2b3a0 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69 73 20 68  .** a mutex is h
2b3b0 65 6c 64 2e 20 20 41 6e 20 69 6e 74 65 72 6e 61  eld.  An interna
2b3c0 6c 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20  l mutex is held 
2b3d0 66 6f 72 20 61 20 70 72 6f 74 65 63 74 65 64 0a  for a protected.
2b3e0 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
2b3f0 20 6f 62 6a 65 63 74 20 62 75 74 20 6e 6f 20 6d   object but no m
2b400 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72  utex is held for
2b410 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 0a   an unprotected.
2b420 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
2b430 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 53 51 4c   object.  If SQL
2b440 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
2b450 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d 74 68 72  to be single-thr
2b460 65 61 64 65 64 0a 2a 2a 20 28 77 69 74 68 20 5b  eaded.** (with [
2b470 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
2b480 45 3d 30 5d 20 61 6e 64 20 77 69 74 68 20 5b 73  E=0] and with [s
2b490 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66  qlite3_threadsaf
2b4a0 65 28 29 5d 20 72 65 74 75 72 6e 69 6e 67 20 30  e()] returning 0
2b4b0 29 0a 2a 2a 20 6f 72 20 69 66 20 53 51 4c 69 74  ).** or if SQLit
2b4c0 65 20 69 73 20 72 75 6e 20 69 6e 20 6f 6e 65 20  e is run in one 
2b4d0 6f 66 20 72 65 64 75 63 65 64 20 6d 75 74 65 78  of reduced mutex
2b4e0 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53 51 4c 49   modes .** [SQLI
2b4f0 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
2b500 54 48 52 45 41 44 5d 20 6f 72 20 5b 53 51 4c 49  THREAD] or [SQLI
2b510 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
2b520 48 52 45 41 44 5d 0a 2a 2a 20 74 68 65 6e 20 74  HREAD].** then t
2b530 68 65 72 65 20 69 73 20 6e 6f 20 64 69 73 74 69  here is no disti
2b540 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70  nction between p
2b550 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70  rotected and unp
2b560 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69  rotected.** sqli
2b570 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
2b580 73 20 61 6e 64 20 74 68 65 79 20 63 61 6e 20 62  s and they can b
2b590 65 20 75 73 65 64 20 69 6e 74 65 72 63 68 61 6e  e used interchan
2b5a0 67 65 61 62 6c 79 2e 20 20 48 6f 77 65 76 65 72  geably.  However
2b5b0 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 69 6d 75 6d  ,.** for maximum
2b5c0 20 63 6f 64 65 20 70 6f 72 74 61 62 69 6c 69 74   code portabilit
2b5d0 79 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e  y it is recommen
2b5e0 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61  ded that applica
2b5f0 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d  tions.** still m
2b600 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e 63 74  ake the distinct
2b610 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74  ion between prot
2b620 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74  ected and unprot
2b630 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ected.** sqlite3
2b640 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 65  _value objects e
2b650 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20 73 74 72  ven when not str
2b660 69 63 74 6c 79 20 72 65 71 75 69 72 65 64 2e 0a  ictly required..
2b670 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2b680 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
2b690 20 74 68 61 74 20 61 72 65 20 70 61 73 73 65 64   that are passed
2b6a0 20 61 73 20 70 61 72 61 6d 65 74 65 72 73 20 69   as parameters i
2b6b0 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65  nto the.** imple
2b6c0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 61 70  mentation of [ap
2b6d0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2b6e0 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d  d SQL functions]
2b6f0 20 61 72 65 20 70 72 6f 74 65 63 74 65 64 2e 0a   are protected..
2b700 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2b710 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 72 65 74  value object ret
2b720 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c  urned by.** [sql
2b730 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
2b740 65 28 29 5d 20 69 73 20 75 6e 70 72 6f 74 65 63  e()] is unprotec
2b750 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 63  ted..** Unprotec
2b760 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2b770 65 20 6f 62 6a 65 63 74 73 20 6d 61 79 20 6f 6e  e objects may on
2b780 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68 0a  ly be used with.
2b790 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  ** [sqlite3_resu
2b7a0 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20  lt_value()] and 
2b7b0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61  [sqlite3_bind_va
2b7c0 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b  lue()]..** The [
2b7d0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c  sqlite3_value_bl
2b7e0 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 76 61 6c  ob | sqlite3_val
2b7f0 75 65 5f 74 79 70 65 28 29 5d 20 66 61 6d 69 6c  ue_type()] famil
2b800 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63  y of.** interfac
2b810 65 73 20 72 65 71 75 69 72 65 20 70 72 6f 74 65  es require prote
2b820 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2b830 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74  ue objects..*/.t
2b840 79 70 65 64 65 66 20 73 74 72 75 63 74 20 4d 65  ypedef struct Me
2b850 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 3b  m sqlite3_value;
2b860 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2b870 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43  : SQL Function C
2b880 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74 0a 2a 2a  ontext Object.**
2b890 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78 74 20  .** The context 
2b8a0 69 6e 20 77 68 69 63 68 20 61 6e 20 53 51 4c 20  in which an SQL 
2b8b0 66 75 6e 63 74 69 6f 6e 20 65 78 65 63 75 74 65  function execute
2b8c0 73 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61  s is stored in a
2b8d0 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e  n.** sqlite3_con
2b8e0 74 65 78 74 20 6f 62 6a 65 63 74 2e 20 20 5e 41  text object.  ^A
2b8f0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 73   pointer to an s
2b900 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f  qlite3_context o
2b910 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61 6c 77 61  bject.** is alwa
2b920 79 73 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  ys first paramet
2b930 65 72 20 74 6f 20 5b 61 70 70 6c 69 63 61 74 69  er to [applicati
2b940 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
2b950 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68  unctions]..** Th
2b960 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
2b970 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
2b980 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  on implementatio
2b990 6e 20 77 69 6c 6c 20 70 61 73 73 20 74 68 69 73  n will pass this
2b9a0 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 68 72 6f  .** pointer thro
2b9b0 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c 73 20 74  ugh into calls t
2b9c0 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  o [sqlite3_resul
2b9d0 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f  t_int | sqlite3_
2b9e0 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73  result()],.** [s
2b9f0 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
2ba00 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20 5b 73 71  _context()], [sq
2ba10 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28  lite3_user_data(
2ba20 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
2ba30 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c  context_db_handl
2ba40 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 67  e()], [sqlite3_g
2ba50 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2c 0a 2a  et_auxdata()],.*
2ba60 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c 69 74 65  * and/or [sqlite
2ba70 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 5d  3_set_auxdata()]
2ba80 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
2ba90 75 63 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  uct sqlite3_cont
2baa0 65 78 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ext sqlite3_cont
2bab0 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ext;../*.** CAPI
2bac0 33 52 45 46 3a 20 42 69 6e 64 69 6e 67 20 56 61  3REF: Binding Va
2bad0 6c 75 65 73 20 54 6f 20 50 72 65 70 61 72 65 64  lues To Prepared
2bae0 20 53 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b   Statements.** K
2baf0 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73 74 20 70  EYWORDS: {host p
2bb00 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f 73 74 20  arameter} {host 
2bb10 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 68 6f 73  parameters} {hos
2bb20 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65  t parameter name
2bb30 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  }.** KEYWORDS: {
2bb40 53 51 4c 20 70 61 72 61 6d 65 74 65 72 7d 20 7b  SQL parameter} {
2bb50 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 7d 20  SQL parameters} 
2bb60 7b 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69  {parameter bindi
2bb70 6e 67 7d 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74  ng}.**.** ^(In t
2bb80 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
2bb90 20 74 65 78 74 20 69 6e 70 75 74 20 74 6f 20 5b   text input to [
2bba0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2bbb0 76 32 28 29 5d 20 61 6e 64 20 69 74 73 20 76 61  v2()] and its va
2bbc0 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 72  riants,.** liter
2bbd0 61 6c 73 20 6d 61 79 20 62 65 20 72 65 70 6c 61  als may be repla
2bbe0 63 65 64 20 62 79 20 61 20 5b 70 61 72 61 6d 65  ced by a [parame
2bbf0 74 65 72 5d 20 74 68 61 74 20 6d 61 74 63 68 65  ter] that matche
2bc00 73 20 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f 77 69  s one of followi
2bc10 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61 74 65 73 3a  ng.** templates:
2bc20 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
2bc30 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20  li>  ?.** <li>  
2bc40 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56  ?NNN.** <li>  :V
2bc50 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56  VV.** <li>  @VVV
2bc60 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a  .** <li>  $VVV.*
2bc70 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e  * </ul>.**.** In
2bc80 20 74 68 65 20 74 65 6d 70 6c 61 74 65 73 20 61   the templates a
2bc90 62 6f 76 65 2c 20 4e 4e 4e 20 72 65 70 72 65 73  bove, NNN repres
2bca0 65 6e 74 73 20 61 6e 20 69 6e 74 65 67 65 72 20  ents an integer 
2bcb0 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20  literal,.** and 
2bcc0 56 56 56 20 72 65 70 72 65 73 65 6e 74 73 20 61  VVV represents a
2bcd0 6e 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 69  n alphanumeric i
2bce0 64 65 6e 74 69 66 69 65 72 2e 29 5e 20 20 5e 54  dentifier.)^  ^T
2bcf0 68 65 20 76 61 6c 75 65 73 20 6f 66 20 74 68 65  he values of the
2bd00 73 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73  se.** parameters
2bd10 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68   (also called "h
2bd20 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61  ost parameter na
2bd30 6d 65 73 22 20 6f 72 20 22 53 51 4c 20 70 61 72  mes" or "SQL par
2bd40 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e  ameters").** can
2bd50 20 62 65 20 73 65 74 20 75 73 69 6e 67 20 74 68   be set using th
2bd60 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
2bd70 28 29 20 72 6f 75 74 69 6e 65 73 20 64 65 66 69  () routines defi
2bd80 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20  ned here..**.** 
2bd90 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
2bda0 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ent to the sqlit
2bdb0 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74  e3_bind_*() rout
2bdc0 69 6e 65 73 20 69 73 20 61 6c 77 61 79 73 0a 2a  ines is always.*
2bdd0 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  * a pointer to t
2bde0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74  he [sqlite3_stmt
2bdf0 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65  ] object returne
2be00 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74  d from.** [sqlit
2be10 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
2be20 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73   or its variants
2be30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63  ..**.** ^The sec
2be40 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
2be50 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65  the index of the
2be60 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 74   SQL parameter t
2be70 6f 20 62 65 20 73 65 74 2e 0a 2a 2a 20 5e 54 68  o be set..** ^Th
2be80 65 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20 70  e leftmost SQL p
2be90 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20  arameter has an 
2bea0 69 6e 64 65 78 20 6f 66 20 31 2e 20 20 5e 57 68  index of 1.  ^Wh
2beb0 65 6e 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65  en the same name
2bec0 64 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 74  d.** SQL paramet
2bed0 65 72 20 69 73 20 75 73 65 64 20 6d 6f 72 65 20  er is used more 
2bee0 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e  than once, secon
2bef0 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74  d and subsequent
2bf00 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65 73 20  .** occurrences 
2bf10 68 61 76 65 20 74 68 65 20 73 61 6d 65 20 69 6e  have the same in
2bf20 64 65 78 20 61 73 20 74 68 65 20 66 69 72 73 74  dex as the first
2bf30 20 6f 63 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20   occurrence..** 
2bf40 5e 54 68 65 20 69 6e 64 65 78 20 66 6f 72 20 6e  ^The index for n
2bf50 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 73 20  amed parameters 
2bf60 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70  can be looked up
2bf70 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73   using the.** [s
2bf80 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2bf90 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 20 41  meter_index()] A
2bfa0 50 49 20 69 66 20 64 65 73 69 72 65 64 2e 20 20  PI if desired.  
2bfb0 5e 54 68 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f  ^The index.** fo
2bfc0 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74  r "?NNN" paramet
2bfd0 65 72 73 20 69 73 20 74 68 65 20 76 61 6c 75 65  ers is the value
2bfe0 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65   of NNN..** ^The
2bff0 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74 20   NNN value must 
2c000 62 65 20 62 65 74 77 65 65 6e 20 31 20 61 6e 64  be between 1 and
2c010 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69   the [sqlite3_li
2c020 6d 69 74 28 29 5d 0a 2a 2a 20 70 61 72 61 6d 65  mit()].** parame
2c030 74 65 72 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ter [SQLITE_LIMI
2c040 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45  T_VARIABLE_NUMBE
2c050 52 5d 20 28 64 65 66 61 75 6c 74 20 76 61 6c 75  R] (default valu
2c060 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e  e: 999)..**.** ^
2c070 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  The third argume
2c080 6e 74 20 69 73 20 74 68 65 20 76 61 6c 75 65 20  nt is the value 
2c090 74 6f 20 62 69 6e 64 20 74 6f 20 74 68 65 20 70  to bind to the p
2c0a0 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66  arameter..** ^If
2c0b0 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
2c0c0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
2c0d0 62 69 6e 64 5f 74 65 78 74 28 29 20 6f 72 20 73  bind_text() or s
2c0e0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
2c0f0 31 36 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  16().** or sqlit
2c100 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69  e3_bind_blob() i
2c110 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
2c120 20 74 68 65 6e 20 74 68 65 20 66 6f 75 72 74 68   then the fourth
2c130 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 73   parameter.** is
2c140 20 69 67 6e 6f 72 65 64 20 61 6e 64 20 74 68 65   ignored and the
2c150 20 65 6e 64 20 72 65 73 75 6c 74 20 69 73 20 74   end result is t
2c160 68 65 20 73 61 6d 65 20 61 73 20 73 71 6c 69 74  he same as sqlit
2c170 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 29 2e 0a  e3_bind_null()..
2c180 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f 73 65  **.** ^(In those
2c190 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 68   routines that h
2c1a0 61 76 65 20 61 20 66 6f 75 72 74 68 20 61 72 67  ave a fourth arg
2c1b0 75 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 65  ument, its value
2c1c0 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65   is the.** numbe
2c1d0 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
2c1e0 65 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 6f  e parameter.  To
2c1f0 20 62 65 20 63 6c 65 61 72 3a 20 74 68 65 20 76   be clear: the v
2c200 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e  alue is the.** n
2c210 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79 74 65  umber of <u>byte
2c220 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76 61 6c  s</u> in the val
2c230 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62  ue, not the numb
2c240 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73  er of characters
2c250 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  .)^.** ^If the f
2c260 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
2c270 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  to sqlite3_bind_
2c280 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65  text() or sqlite
2c290 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 0a  3_bind_text16().
2c2a0 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  ** is negative, 
2c2b0 74 68 65 6e 20 74 68 65 20 6c 65 6e 67 74 68 20  then the length 
2c2c0 6f 66 20 74 68 65 20 73 74 72 69 6e 67 20 69 73  of the string is
2c2d0 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
2c2e0 66 20 62 79 74 65 73 20 75 70 20 74 6f 20 74 68  f bytes up to th
2c2f0 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72  e first zero ter
2c300 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 20 49 66 20 74  minator..** If t
2c310 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
2c320 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ter to sqlite3_b
2c330 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20 6e 65  ind_blob() is ne
2c340 67 61 74 69 76 65 2c 20 74 68 65 6e 0a 2a 2a 20  gative, then.** 
2c350 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
2c360 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66  undefined..** If
2c370 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20   a non-negative 
2c380 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
2c390 20 69 73 20 70 72 6f 76 69 64 65 64 20 74 6f 20   is provided to 
2c3a0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
2c3b0 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  t().** or sqlite
2c3c0 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20  3_bind_text16() 
2c3d0 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  or sqlite3_bind_
2c3e0 74 65 78 74 36 34 28 29 20 74 68 65 6e 0a 2a 2a  text64() then.**
2c3f0 20 74 68 61 74 20 70 61 72 61 6d 65 74 65 72 20   that parameter 
2c400 6d 75 73 74 20 62 65 20 74 68 65 20 62 79 74 65  must be the byte
2c410 20 6f 66 66 73 65 74 0a 2a 2a 20 77 68 65 72 65   offset.** where
2c420 20 74 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61   the NUL termina
2c430 74 6f 72 20 77 6f 75 6c 64 20 6f 63 63 75 72 20  tor would occur 
2c440 61 73 73 75 6d 69 6e 67 20 74 68 65 20 73 74 72  assuming the str
2c450 69 6e 67 20 77 65 72 65 20 4e 55 4c 0a 2a 2a 20  ing were NUL.** 
2c460 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 49 66 20  terminated.  If 
2c470 61 6e 79 20 4e 55 4c 20 63 68 61 72 61 63 74 65  any NUL characte
2c480 72 73 20 6f 63 63 75 72 20 61 74 20 62 79 74 65  rs occur at byte
2c490 20 6f 66 66 73 65 74 73 20 6c 65 73 73 20 74 68   offsets less th
2c4a0 61 6e 20 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65  an .** the value
2c4b0 20 6f 66 20 74 68 65 20 66 6f 75 72 74 68 20 70   of the fourth p
2c4c0 61 72 61 6d 65 74 65 72 20 74 68 65 6e 20 74 68  arameter then th
2c4d0 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69  e resulting stri
2c4e0 6e 67 20 76 61 6c 75 65 20 77 69 6c 6c 0a 2a 2a  ng value will.**
2c4f0 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64 65   contain embedde
2c500 64 20 4e 55 4c 73 2e 20 20 54 68 65 20 72 65 73  d NULs.  The res
2c510 75 6c 74 20 6f 66 20 65 78 70 72 65 73 73 69 6f  ult of expressio
2c520 6e 73 20 69 6e 76 6f 6c 76 69 6e 67 20 73 74 72  ns involving str
2c530 69 6e 67 73 0a 2a 2a 20 77 69 74 68 20 65 6d 62  ings.** with emb
2c540 65 64 64 65 64 20 4e 55 4c 73 20 69 73 20 75 6e  edded NULs is un
2c550 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  defined..**.** ^
2c560 54 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65  The fifth argume
2c570 6e 74 20 74 6f 20 74 68 65 20 42 4c 4f 42 20 61  nt to the BLOB a
2c580 6e 64 20 73 74 72 69 6e 67 20 62 69 6e 64 69 6e  nd string bindin
2c590 67 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  g interfaces.** 
2c5a0 69 73 20 61 20 64 65 73 74 72 75 63 74 6f 72 20  is a destructor 
2c5b0 75 73 65 64 20 74 6f 20 64 69 73 70 6f 73 65 20  used to dispose 
2c5c0 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a  of the BLOB or.*
2c5d0 2a 20 73 74 72 69 6e 67 20 61 66 74 65 72 20 53  * string after S
2c5e0 51 4c 69 74 65 20 68 61 73 20 66 69 6e 69 73 68  QLite has finish
2c5f0 65 64 20 77 69 74 68 20 69 74 2e 20 20 5e 54 68  ed with it.  ^Th
2c600 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20  e destructor is 
2c610 63 61 6c 6c 65 64 0a 2a 2a 20 74 6f 20 64 69 73  called.** to dis
2c620 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42  pose of the BLOB
2c630 20 6f 72 20 73 74 72 69 6e 67 20 65 76 65 6e 20   or string even 
2c640 69 66 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 62  if the call to b
2c650 69 6e 64 20 41 50 49 20 66 61 69 6c 73 2e 0a 2a  ind API fails..*
2c660 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74 68 20  * ^If the fifth 
2c670 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74  argument is.** t
2c680 68 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65  he special value
2c690 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d   [SQLITE_STATIC]
2c6a0 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 61 73  , then SQLite as
2c6b0 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a  sumes that the.*
2c6c0 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  * information is
2c6d0 20 69 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d 61   in static, unma
2c6e0 6e 61 67 65 64 20 73 70 61 63 65 20 61 6e 64 20  naged space and 
2c6f0 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
2c700 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49   be freed..** ^I
2c710 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75  f the fifth argu
2c720 6d 65 6e 74 20 68 61 73 20 74 68 65 20 76 61 6c  ment has the val
2c730 75 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53  ue [SQLITE_TRANS
2c740 49 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53  IENT], then.** S
2c750 51 4c 69 74 65 20 6d 61 6b 65 73 20 69 74 73 20  QLite makes its 
2c760 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79  own private copy
2c770 20 6f 66 20 74 68 65 20 64 61 74 61 20 69 6d 6d   of the data imm
2c780 65 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65  ediately, before
2c790 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f  .** the sqlite3_
2c7a0 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65  bind_*() routine
2c7b0 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20   returns..**.** 
2c7c0 5e 54 68 65 20 73 69 78 74 68 20 61 72 67 75 6d  ^The sixth argum
2c7d0 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ent to sqlite3_b
2c7e0 69 6e 64 5f 74 65 78 74 36 34 28 29 20 6d 75 73  ind_text64() mus
2c7f0 74 20 62 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 5b  t be one of.** [
2c800 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53  SQLITE_UTF8], [S
2c810 51 4c 49 54 45 5f 55 54 46 31 36 5d 2c 20 5b 53  QLITE_UTF16], [S
2c820 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 20  QLITE_UTF16BE], 
2c830 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  or [SQLITE_UTF16
2c840 4c 45 5d 0a 2a 2a 20 74 6f 20 73 70 65 63 69 66  LE].** to specif
2c850 79 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 6f  y the encoding o
2c860 66 20 74 68 65 20 74 65 78 74 20 69 6e 20 74 68  f the text in th
2c870 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
2c880 72 2e 20 20 49 66 0a 2a 2a 20 74 68 65 20 73 69  r.  If.** the si
2c890 78 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  xth argument to 
2c8a0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
2c8b0 74 36 34 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65  t64() is not one
2c8c0 20 6f 66 20 74 68 65 0a 2a 2a 20 61 6c 6c 6f 77   of the.** allow
2c8d0 65 64 20 76 61 6c 75 65 73 20 73 68 6f 77 6e 20  ed values shown 
2c8e0 61 62 6f 76 65 2c 20 6f 72 20 69 66 20 74 68 65  above, or if the
2c8f0 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 69   text encoding i
2c900 73 20 64 69 66 66 65 72 65 6e 74 0a 2a 2a 20 66  s different.** f
2c910 72 6f 6d 20 74 68 65 20 65 6e 63 6f 64 69 6e 67  rom the encoding
2c920 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68   specified by th
2c930 65 20 73 69 78 74 68 20 70 61 72 61 6d 65 74 65  e sixth paramete
2c940 72 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  r, then the beha
2c950 76 69 6f 72 0a 2a 2a 20 69 73 20 75 6e 64 65 66  vior.** is undef
2c960 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ined..**.** ^The
2c970 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65   sqlite3_bind_ze
2c980 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65  roblob() routine
2c990 20 62 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66   binds a BLOB of
2c9a0 20 6c 65 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a   length N that.*
2c9b0 2a 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68  * is filled with
2c9c0 20 7a 65 72 6f 65 73 2e 20 20 5e 41 20 7a 65 72   zeroes.  ^A zer
2c9d0 6f 62 6c 6f 62 20 75 73 65 73 20 61 20 66 69 78  oblob uses a fix
2c9e0 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d  ed amount of mem
2c9f0 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20  ory.** (just an 
2ca00 69 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 20  integer to hold 
2ca10 69 74 73 20 73 69 7a 65 29 20 77 68 69 6c 65 20  its size) while 
2ca20 69 74 20 69 73 20 62 65 69 6e 67 20 70 72 6f 63  it is being proc
2ca30 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c  essed..** Zerobl
2ca40 6f 62 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64  obs are intended
2ca50 20 74 6f 20 73 65 72 76 65 20 61 73 20 70 6c 61   to serve as pla
2ca60 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c  ceholders for BL
2ca70 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e  OBs whose.** con
2ca80 74 65 6e 74 20 69 73 20 6c 61 74 65 72 20 77 72  tent is later wr
2ca90 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b  itten using.** [
2caa0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65  sqlite3_blob_ope
2cab0 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20  n | incremental 
2cac0 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e  BLOB I/O] routin
2cad0 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 69  es..** ^A negati
2cae0 76 65 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65  ve value for the
2caf0 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74   zeroblob result
2cb00 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67  s in a zero-leng
2cb10 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e  th BLOB..**.** ^
2cb20 49 66 20 61 6e 79 20 6f 66 20 74 68 65 20 73 71  If any of the sq
2cb30 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
2cb40 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c  outines are call
2cb50 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70  ed with a NULL p
2cb60 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f 72 20 74 68  ointer.** for th
2cb70 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
2cb80 65 6d 65 6e 74 5d 20 6f 72 20 77 69 74 68 20 61  ement] or with a
2cb90 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2cba0 65 6e 74 20 66 6f 72 20 77 68 69 63 68 0a 2a 2a  ent for which.**
2cbb0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2cbc0 5d 20 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 65  ] has been calle
2cbd0 64 20 6d 6f 72 65 20 72 65 63 65 6e 74 6c 79 20  d more recently 
2cbe0 74 68 61 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65  than [sqlite3_re
2cbf0 73 65 74 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20  set()],.** then 
2cc00 74 68 65 20 63 61 6c 6c 20 77 69 6c 6c 20 72 65  the call will re
2cc10 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53  turn [SQLITE_MIS
2cc20 55 53 45 5d 2e 20 20 49 66 20 61 6e 79 20 73 71  USE].  If any sq
2cc30 6c 69 74 65 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a  lite3_bind_().**
2cc40 20 72 6f 75 74 69 6e 65 20 69 73 20 70 61 73 73   routine is pass
2cc50 65 64 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  ed a [prepared s
2cc60 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68  tatement] that h
2cc70 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65  as been finalize
2cc80 64 2c 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74  d, the.** result
2cc90 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e   is undefined an
2cca0 64 20 70 72 6f 62 61 62 6c 79 20 68 61 72 6d 66  d probably harmf
2ccb0 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69  ul..**.** ^Bindi
2ccc0 6e 67 73 20 61 72 65 20 6e 6f 74 20 63 6c 65 61  ngs are not clea
2ccd0 72 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69  red by the [sqli
2cce0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 72 6f 75  te3_reset()] rou
2ccf0 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e  tine..** ^Unboun
2cd00 64 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65  d parameters are
2cd10 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
2cd20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  NULL..**.** ^The
2cd30 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20   sqlite3_bind_* 
2cd40 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
2cd50 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73  [SQLITE_OK] on s
2cd60 75 63 63 65 73 73 20 6f 72 20 61 6e 0a 2a 2a 20  uccess or an.** 
2cd70 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20  [error code] if 
2cd80 61 6e 79 74 68 69 6e 67 20 67 6f 65 73 20 77 72  anything goes wr
2cd90 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45  ong..** ^[SQLITE
2cda0 5f 54 4f 4f 42 49 47 5d 20 6d 69 67 68 74 20 62  _TOOBIG] might b
2cdb0 65 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 68  e returned if th
2cdc0 65 20 73 69 7a 65 20 6f 66 20 61 20 73 74 72 69  e size of a stri
2cdd0 6e 67 20 6f 72 20 42 4c 4f 42 0a 2a 2a 20 65 78  ng or BLOB.** ex
2cde0 63 65 65 64 73 20 6c 69 6d 69 74 73 20 69 6d 70  ceeds limits imp
2cdf0 6f 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  osed by [sqlite3
2ce00 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f  _limit]([SQLITE_
2ce10 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 29 20 6f  LIMIT_LENGTH]) o
2ce20 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 41 58  r.** [SQLITE_MAX
2ce30 5f 4c 45 4e 47 54 48 5d 2e 0a 2a 2a 20 5e 5b 53  _LENGTH]..** ^[S
2ce40 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20 69 73 20  QLITE_RANGE] is 
2ce50 72 65 74 75 72 6e 65 64 20 69 66 20 74 68 65 20  returned if the 
2ce60 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64  parameter.** ind
2ce70 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e  ex is out of ran
2ce80 67 65 2e 20 20 5e 5b 53 51 4c 49 54 45 5f 4e 4f  ge.  ^[SQLITE_NO
2ce90 4d 45 4d 5d 20 69 73 20 72 65 74 75 72 6e 65 64  MEM] is returned
2cea0 20 69 66 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69   if malloc() fai
2ceb0 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ls..**.** See al
2cec0 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  so: [sqlite3_bin
2ced0 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e  d_parameter_coun
2cee0 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  t()],.** [sqlite
2cef0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2cf00 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 20 5b 73  _name()], and [s
2cf10 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2cf20 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a  meter_index()]..
2cf30 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
2cf40 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
2cf50 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c   sqlite3_bind_bl
2cf60 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ob(sqlite3_stmt*
2cf70 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69  , int, const voi
2cf80 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28  d*, int n, void(
2cf90 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49  *)(void*));.SQLI
2cfa0 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54  TE_API int SQLIT
2cfb0 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
2cfc0 33 5f 62 69 6e 64 5f 62 6c 6f 62 36 34 28 73 71  3_bind_blob64(sq
2cfd0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2cfe0 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 73  , const void*, s
2cff0 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c 0a 20  qlite3_uint64,. 
2d000 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2d010 20 20 20 20 20 20 20 76 6f 69 64 28 2a 29 28 76         void(*)(v
2d020 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41  oid*));.SQLITE_A
2d030 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54  PI int SQLITE_ST
2d040 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69  DCALL sqlite3_bi
2d050 6e 64 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65  nd_double(sqlite
2d060 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f  3_stmt*, int, do
2d070 75 62 6c 65 29 3b 0a 53 51 4c 49 54 45 5f 41 50  uble);.SQLITE_AP
2d080 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  I int SQLITE_STD
2d090 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e  CALL sqlite3_bin
2d0a0 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  d_int(sqlite3_st
2d0b0 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a  mt*, int, int);.
2d0c0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53  SQLITE_API int S
2d0d0 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
2d0e0 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36 34  lite3_bind_int64
2d0f0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2d100 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  int, sqlite3_int
2d110 36 34 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  64);.SQLITE_API 
2d120 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41  int SQLITE_STDCA
2d130 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  LL sqlite3_bind_
2d140 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d  null(sqlite3_stm
2d150 74 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45  t*, int);.SQLITE
2d160 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f  _API int SQLITE_
2d170 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
2d180 62 69 6e 64 5f 74 65 78 74 28 73 71 6c 69 74 65  bind_text(sqlite
2d190 33 5f 73 74 6d 74 2a 2c 69 6e 74 2c 63 6f 6e 73  3_stmt*,int,cons
2d1a0 74 20 63 68 61 72 2a 2c 69 6e 74 2c 76 6f 69 64  t char*,int,void
2d1b0 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c  (*)(void*));.SQL
2d1c0 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49  ITE_API int SQLI
2d1d0 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
2d1e0 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 73  e3_bind_text16(s
2d1f0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2d200 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  t, const void*, 
2d210 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  int, void(*)(voi
2d220 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  d*));.SQLITE_API
2d230 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43   int SQLITE_STDC
2d240 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  ALL sqlite3_bind
2d250 5f 74 65 78 74 36 34 28 73 71 6c 69 74 65 33 5f  _text64(sqlite3_
2d260 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
2d270 74 20 63 68 61 72 2a 2c 20 73 71 6c 69 74 65 33  t char*, sqlite3
2d280 5f 75 69 6e 74 36 34 2c 0a 20 20 20 20 20 20 20  _uint64,.       
2d290 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2d2a0 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29    void(*)(void*)
2d2b0 2c 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20  , unsigned char 
2d2c0 65 6e 63 6f 64 69 6e 67 29 3b 0a 53 51 4c 49 54  encoding);.SQLIT
2d2d0 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45  E_API int SQLITE
2d2e0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
2d2f0 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69  _bind_value(sqli
2d300 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
2d310 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61  const sqlite3_va
2d320 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  lue*);.SQLITE_AP
2d330 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  I int SQLITE_STD
2d340 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e  CALL sqlite3_bin
2d350 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74  d_zeroblob(sqlit
2d360 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69  e3_stmt*, int, i
2d370 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  nt n);../*.** CA
2d380 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f  PI3REF: Number O
2d390 66 20 53 51 4c 20 50 61 72 61 6d 65 74 65 72 73  f SQL Parameters
2d3a0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
2d3b0 74 69 6e 65 20 63 61 6e 20 62 65 20 75 73 65 64  tine can be used
2d3c0 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d   to find the num
2d3d0 62 65 72 20 6f 66 20 5b 53 51 4c 20 70 61 72 61  ber of [SQL para
2d3e0 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20  meters].** in a 
2d3f0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2d400 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d  ent].  SQL param
2d410 65 74 65 72 73 20 61 72 65 20 74 6f 6b 65 6e 73  eters are tokens
2d420 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20   of the.** form 
2d430 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41  "?", "?NNN", ":A
2d440 41 41 22 2c 20 22 24 41 41 41 22 2c 20 6f 72 20  AA", "$AAA", or 
2d450 22 40 41 41 41 22 20 74 68 61 74 20 73 65 72 76  "@AAA" that serv
2d460 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c  e as.** placehol
2d470 64 65 72 73 20 66 6f 72 20 76 61 6c 75 65 73 20  ders for values 
2d480 74 68 61 74 20 61 72 65 20 5b 73 71 6c 69 74 65  that are [sqlite
2d490 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f  3_bind_blob | bo
2d4a0 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70  und].** to the p
2d4b0 61 72 61 6d 65 74 65 72 73 20 61 74 20 61 20 6c  arameters at a l
2d4c0 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a  ater time..**.**
2d4d0 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20   ^(This routine 
2d4e0 61 63 74 75 61 6c 6c 79 20 72 65 74 75 72 6e 73  actually returns
2d4f0 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68   the index of th
2d500 65 20 6c 61 72 67 65 73 74 20 28 72 69 67 68 74  e largest (right
2d510 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74  most).** paramet
2d520 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d  er. For all form
2d530 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74  s except ?NNN, t
2d540 68 69 73 20 77 69 6c 6c 20 63 6f 72 72 65 73 70  his will corresp
2d550 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75  ond to the.** nu
2d560 6d 62 65 72 20 6f 66 20 75 6e 69 71 75 65 20 70  mber of unique p
2d570 61 72 61 6d 65 74 65 72 73 2e 20 20 49 66 20 70  arameters.  If p
2d580 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65  arameters of the
2d590 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72 65 20 75   ?NNN form are u
2d5a0 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61  sed,.** there ma
2d5b0 79 20 62 65 20 67 61 70 73 20 69 6e 20 74 68 65  y be gaps in the
2d5c0 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53   list.)^.**.** S
2d5d0 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
2d5e0 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69  3_bind_blob|sqli
2d5f0 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20  te3_bind()],.** 
2d600 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
2d610 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c  rameter_name()],
2d620 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
2d630 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2d640 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c  index()]..*/.SQL
2d650 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49  ITE_API int SQLI
2d660 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
2d670 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2d680 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f  r_count(sqlite3_
2d690 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  stmt*);../*.** C
2d6a0 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66  API3REF: Name Of
2d6b0 20 41 20 48 6f 73 74 20 50 61 72 61 6d 65 74 65   A Host Paramete
2d6c0 72 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  r.**.** ^The sql
2d6d0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
2d6e0 74 65 72 5f 6e 61 6d 65 28 50 2c 4e 29 20 69 6e  ter_name(P,N) in
2d6f0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a  terface returns.
2d700 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  ** the name of t
2d710 68 65 20 4e 2d 74 68 20 5b 53 51 4c 20 70 61 72  he N-th [SQL par
2d720 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20 5b  ameter] in the [
2d730 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2d740 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20  nt] P..** ^(SQL 
2d750 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68  parameters of th
2d760 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72  e form "?NNN" or
2d770 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41   ":AAA" or "@AAA
2d780 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 68  " or "$AAA".** h
2d790 61 76 65 20 61 20 6e 61 6d 65 20 77 68 69 63 68  ave a name which
2d7a0 20 69 73 20 74 68 65 20 73 74 72 69 6e 67 20 22   is the string "
2d7b0 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20  ?NNN" or ":AAA" 
2d7c0 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41  or "@AAA" or "$A
2d7d0 41 41 22 0a 2a 2a 20 72 65 73 70 65 63 74 69 76  AA".** respectiv
2d7e0 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72  ely..** In other
2d7f0 20 77 6f 72 64 73 2c 20 74 68 65 20 69 6e 69 74   words, the init
2d800 69 61 6c 20 22 3a 22 20 6f 72 20 22 24 22 20 6f  ial ":" or "$" o
2d810 72 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20  r "@" or "?".** 
2d820 69 73 20 69 6e 63 6c 75 64 65 64 20 61 73 20 70  is included as p
2d830 61 72 74 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e  art of the name.
2d840 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65 74 65 72  )^.** ^Parameter
2d850 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f  s of the form "?
2d860 22 20 77 69 74 68 6f 75 74 20 61 20 66 6f 6c 6c  " without a foll
2d870 6f 77 69 6e 67 20 69 6e 74 65 67 65 72 20 68 61  owing integer ha
2d880 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e  ve no name.** an
2d890 64 20 61 72 65 20 72 65 66 65 72 72 65 64 20 74  d are referred t
2d8a0 6f 20 61 73 20 22 6e 61 6d 65 6c 65 73 73 22 20  o as "nameless" 
2d8b0 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 70 61  or "anonymous pa
2d8c0 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a  rameters"..**.**
2d8d0 20 5e 54 68 65 20 66 69 72 73 74 20 68 6f 73 74   ^The first host
2d8e0 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61   parameter has a
2d8f0 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f  n index of 1, no
2d900 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  t 0..**.** ^If t
2d910 68 65 20 76 61 6c 75 65 20 4e 20 69 73 20 6f 75  he value N is ou
2d920 74 20 6f 66 20 72 61 6e 67 65 20 6f 72 20 69 66  t of range or if
2d930 20 74 68 65 20 4e 2d 74 68 20 70 61 72 61 6d 65   the N-th parame
2d940 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65  ter is.** namele
2d950 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73  ss, then NULL is
2d960 20 72 65 74 75 72 6e 65 64 2e 20 20 5e 54 68 65   returned.  ^The
2d970 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
2d980 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69 6e   is.** always in
2d990 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20   UTF-8 encoding 
2d9a0 65 76 65 6e 20 69 66 20 74 68 65 20 6e 61 6d 65  even if the name
2d9b0 64 20 70 61 72 61 6d 65 74 65 72 20 77 61 73 0a  d parameter was.
2d9c0 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70  ** originally sp
2d9d0 65 63 69 66 69 65 64 20 61 73 20 55 54 46 2d 31  ecified as UTF-1
2d9e0 36 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72  6 in [sqlite3_pr
2d9f0 65 70 61 72 65 31 36 28 29 5d 20 6f 72 0a 2a 2a  epare16()] or.**
2da00 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2da10 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a  e16_v2()]..**.**
2da20 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
2da30 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71  te3_bind_blob|sq
2da40 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a  lite3_bind()],.*
2da50 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
2da60 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
2da70 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
2da80 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
2da90 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a  er_index()]..*/.
2daa0 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
2dab0 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f 53 54   char *SQLITE_ST
2dac0 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69  DCALL sqlite3_bi
2dad0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
2dae0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
2daf0 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   int);../*.** CA
2db00 50 49 33 52 45 46 3a 20 49 6e 64 65 78 20 4f 66  PI3REF: Index Of
2db10 20 41 20 50 61 72 61 6d 65 74 65 72 20 57 69 74   A Parameter Wit
2db20 68 20 41 20 47 69 76 65 6e 20 4e 61 6d 65 0a 2a  h A Given Name.*
2db30 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65  *.** ^Return the
2db40 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c   index of an SQL
2db50 20 70 61 72 61 6d 65 74 65 72 20 67 69 76 65 6e   parameter given
2db60 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54 68 65   its name.  ^The
2db70 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75 65 20  .** index value 
2db80 72 65 74 75 72 6e 65 64 20 69 73 20 73 75 69 74  returned is suit
2db90 61 62 6c 65 20 66 6f 72 20 75 73 65 20 61 73 20  able for use as 
2dba0 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61  the second.** pa
2dbb0 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
2dbc0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71  te3_bind_blob|sq
2dbd0 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20  lite3_bind()].  
2dbe0 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65  ^A zero.** is re
2dbf0 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74  turned if no mat
2dc00 63 68 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20  ching parameter 
2dc10 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68 65 20  is found.  ^The 
2dc20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d  parameter.** nam
2dc30 65 20 6d 75 73 74 20 62 65 20 67 69 76 65 6e 20  e must be given 
2dc40 69 6e 20 55 54 46 2d 38 20 65 76 65 6e 20 69 66  in UTF-8 even if
2dc50 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74   the original st
2dc60 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70  atement.** was p
2dc70 72 65 70 61 72 65 64 20 66 72 6f 6d 20 55 54 46  repared from UTF
2dc80 2d 31 36 20 74 65 78 74 20 75 73 69 6e 67 20 5b  -16 text using [
2dc90 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2dca0 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53  6_v2()]..**.** S
2dcb0 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
2dcc0 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69  3_bind_blob|sqli
2dcd0 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20  te3_bind()],.** 
2dce0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
2dcf0 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d  rameter_count()]
2dd00 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  , and.** [sqlite
2dd10 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2dd20 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51  _index()]..*/.SQ
2dd30 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c  LITE_API int SQL
2dd40 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
2dd50 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
2dd60 65 72 5f 69 6e 64 65 78 28 73 71 6c 69 74 65 33  er_index(sqlite3
2dd70 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68  _stmt*, const ch
2dd80 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a  ar *zName);../*.
2dd90 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73  ** CAPI3REF: Res
2dda0 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20  et All Bindings 
2ddb0 4f 6e 20 41 20 50 72 65 70 61 72 65 64 20 53 74  On A Prepared St
2ddc0 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 43  atement.**.** ^C
2ddd0 6f 6e 74 72 61 72 79 20 74 6f 20 74 68 65 20 69  ontrary to the i
2dde0 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79  ntuition of many
2ddf0 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  , [sqlite3_reset
2de00 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20 72 65 73  ()] does not res
2de10 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74  et.** the [sqlit
2de20 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62  e3_bind_blob | b
2de30 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20 5b 70  indings] on a [p
2de40 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2de50 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74 68 69 73  t]..** ^Use this
2de60 20 72 6f 75 74 69 6e 65 20 74 6f 20 72 65 73 65   routine to rese
2de70 74 20 61 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d  t all host param
2de80 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a  eters to NULL..*
2de90 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
2dea0 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
2deb0 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69  sqlite3_clear_bi
2dec0 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73  ndings(sqlite3_s
2ded0 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt*);../*.** CA
2dee0 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f  PI3REF: Number O
2def0 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52  f Columns In A R
2df00 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20  esult Set.**.** 
2df10 5e 52 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62  ^Return the numb
2df20 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
2df30 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
2df40 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a  returned by the.
2df50 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
2df60 74 65 6d 65 6e 74 5d 2e 20 5e 54 68 69 73 20 72  tement]. ^This r
2df70 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30  outine returns 0
2df80 20 69 66 20 70 53 74 6d 74 20 69 73 20 61 6e 20   if pStmt is an 
2df90 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  SQL.** statement
2dfa0 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 72   that does not r
2dfb0 65 74 75 72 6e 20 64 61 74 61 20 28 66 6f 72 20  eturn data (for 
2dfc0 65 78 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41  example an [UPDA
2dfd0 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  TE])..**.** See 
2dfe0 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 64  also: [sqlite3_d
2dff0 61 74 61 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a  ata_count()].*/.
2e000 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53  SQLITE_API int S
2e010 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
2e020 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75  lite3_column_cou
2e030 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  nt(sqlite3_stmt 
2e040 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
2e050 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e  CAPI3REF: Column
2e060 20 4e 61 6d 65 73 20 49 6e 20 41 20 52 65 73 75   Names In A Resu
2e070 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  lt Set.**.** ^Th
2e080 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ese routines ret
2e090 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 61 73 73  urn the name ass
2e0a0 69 67 6e 65 64 20 74 6f 20 61 20 70 61 72 74 69  igned to a parti
2e0b0 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  cular column.** 
2e0c0 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  in the result se
2e0d0 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20  t of a [SELECT] 
2e0e0 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 54 68 65  statement.  ^The
2e0f0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2e100 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66  name().** interf
2e110 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
2e120 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d  inter to a zero-
2e130 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
2e140 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 73   string.** and s
2e150 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
2e160 6d 65 31 36 28 29 20 72 65 74 75 72 6e 73 20 61  me16() returns a
2e170 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65   pointer to a ze
2e180 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
2e190 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20   UTF-16 string. 
2e1a0 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61   ^The first para
2e1b0 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 70 72  meter is the [pr
2e1c0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2e1d0 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70 6c 65 6d  ].** that implem
2e1e0 65 6e 74 73 20 74 68 65 20 5b 53 45 4c 45 43 54  ents the [SELECT
2e1f0 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 5e 54 68  ] statement. ^Th
2e200 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
2e210 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6c  er is the.** col
2e220 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 5e 54 68  umn number.  ^Th
2e230 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d  e leftmost colum
2e240 6e 20 69 73 20 6e 75 6d 62 65 72 20 30 2e 0a 2a  n is number 0..*
2e250 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e  *.** ^The return
2e260 65 64 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65  ed string pointe
2e270 72 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c  r is valid until
2e280 20 65 69 74 68 65 72 20 74 68 65 20 5b 70 72 65   either the [pre
2e290 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2e2a0 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f 79 65 64  .** is destroyed
2e2b0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   by [sqlite3_fin
2e2c0 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69  alize()] or unti
2e2d0 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  l the statement 
2e2e0 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  is automatically
2e2f0 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20 62  .** reprepared b
2e300 79 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c  y the first call
2e310 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
2e320 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69  p()] for a parti
2e330 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20  cular run.** or 
2e340 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20 63  until the next c
2e350 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  all to.** sqlite
2e360 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20  3_column_name() 
2e370 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  or sqlite3_colum
2e380 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20 74 68  n_name16() on th
2e390 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a  e same column..*
2e3a0 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33  *.** ^If sqlite3
2e3b0 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 20  _malloc() fails 
2e3c0 64 75 72 69 6e 67 20 74 68 65 20 70 72 6f 63 65  during the proce
2e3d0 73 73 69 6e 67 20 6f 66 20 65 69 74 68 65 72 20  ssing of either 
2e3e0 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 20  routine.** (for 
2e3f0 65 78 61 6d 70 6c 65 20 64 75 72 69 6e 67 20 61  example during a
2e400 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d   conversion from
2e410 20 55 54 46 2d 38 20 74 6f 20 55 54 46 2d 31 36   UTF-8 to UTF-16
2e420 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c  ) then a.** NULL
2e430 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75   pointer is retu
2e440 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  rned..**.** ^The
2e450 20 6e 61 6d 65 20 6f 66 20 61 20 72 65 73 75 6c   name of a resul
2e460 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20  t column is the 
2e470 76 61 6c 75 65 20 6f 66 20 74 68 65 20 22 41 53  value of the "AS
2e480 22 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a 2a 20  " clause for.** 
2e490 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 66 20  that column, if 
2e4a0 74 68 65 72 65 20 69 73 20 61 6e 20 41 53 20 63  there is an AS c
2e4b0 6c 61 75 73 65 2e 20 20 49 66 20 74 68 65 72 65  lause.  If there
2e4c0 20 69 73 20 6e 6f 20 41 53 20 63 6c 61 75 73 65   is no AS clause
2e4d0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e 61 6d  .** then the nam
2e4e0 65 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20  e of the column 
2e4f0 69 73 20 75 6e 73 70 65 63 69 66 69 65 64 20 61  is unspecified a
2e500 6e 64 20 6d 61 79 20 63 68 61 6e 67 65 20 66 72  nd may change fr
2e510 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 61 73  om.** one releas
2e520 65 20 6f 66 20 53 51 4c 69 74 65 20 74 6f 20 74  e of SQLite to t
2e530 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a 53 51 4c 49  he next..*/.SQLI
2e540 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61  TE_API const cha
2e550 72 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  r *SQLITE_STDCAL
2e560 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  L sqlite3_column
2e570 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
2e580 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 53 51 4c  mt*, int N);.SQL
2e590 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f  ITE_API const vo
2e5a0 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41  id *SQLITE_STDCA
2e5b0 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  LL sqlite3_colum
2e5c0 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  n_name16(sqlite3
2e5d0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a  _stmt*, int N);.
2e5e0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2e5f0 20 53 6f 75 72 63 65 20 4f 66 20 44 61 74 61 20   Source Of Data 
2e600 49 6e 20 41 20 51 75 65 72 79 20 52 65 73 75 6c  In A Query Resul
2e610 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  t.**.** ^These r
2e620 6f 75 74 69 6e 65 73 20 70 72 6f 76 69 64 65 20  outines provide 
2e630 61 20 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 72  a means to deter
2e640 6d 69 6e 65 20 74 68 65 20 64 61 74 61 62 61 73  mine the databas
2e650 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a  e, table, and.**
2e660 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68   table column th
2e670 61 74 20 69 73 20 74 68 65 20 6f 72 69 67 69 6e  at is the origin
2e680 20 6f 66 20 61 20 70 61 72 74 69 63 75 6c 61 72   of a particular
2e690 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69   result column i
2e6a0 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d 20 73 74  n.** [SELECT] st
2e6b0 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65  atement..** ^The
2e6c0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74   name of the dat
2e6d0 61 62 61 73 65 20 6f 72 20 74 61 62 6c 65 20 6f  abase or table o
2e6e0 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20  r column can be 
2e6f0 72 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65  returned as.** e
2e700 69 74 68 65 72 20 61 20 55 54 46 2d 38 20 6f 72  ither a UTF-8 or
2e710 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20   UTF-16 string. 
2e720 20 5e 54 68 65 20 5f 64 61 74 61 62 61 73 65 5f   ^The _database_
2e730 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
2e740 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
2e750 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c   name, the _tabl
2e760 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  e_ routines retu
2e770 72 6e 20 74 68 65 20 74 61 62 6c 65 20 6e 61 6d  rn the table nam
2e780 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72  e, and.** the or
2e790 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72  igin_ routines r
2e7a0 65 74 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e  eturn the column
2e7b0 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 72   name..** ^The r
2e7c0 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69  eturned string i
2e7d0 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68  s valid until th
2e7e0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
2e7f0 65 6d 65 6e 74 5d 20 69 73 20 64 65 73 74 72 6f  ement] is destro
2e800 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71  yed.** using [sq
2e810 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
2e820 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73  ] or until the s
2e830 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f  tatement is auto
2e840 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70  matically.** rep
2e850 72 65 70 61 72 65 64 20 62 79 20 74 68 65 20 66  repared by the f
2e860 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  irst call to [sq
2e870 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f  lite3_step()] fo
2e880 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72  r a particular r
2e890 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74  un.** or until t
2e8a0 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74  he same informat
2e8b0 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65 64  ion is requested
2e8c0 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 64  .** again in a d
2e8d0 69 66 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e  ifferent encodin
2e8e0 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61  g..**.** ^The na
2e8f0 6d 65 73 20 72 65 74 75 72 6e 65 64 20 61 72 65  mes returned are
2e900 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e   the original un
2e910 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65 73 20 6f  -aliased names o
2e920 66 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  f the.** databas
2e930 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f  e, table, and co
2e940 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  lumn..**.** ^The
2e950 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
2e960 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 61  to these interfa
2e970 63 65 73 20 69 73 20 61 20 5b 70 72 65 70 61 72  ces is a [prepar
2e980 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
2e990 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f  * ^These functio
2e9a0 6e 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d  ns return inform
2e9b0 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20  ation about the 
2e9c0 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  Nth result colum
2e9d0 6e 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  n returned by.**
2e9e0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2c 20   the statement, 
2e9f0 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73  where N is the s
2ea00 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61  econd function a
2ea10 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65  rgument..** ^The
2ea20 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d   left-most colum
2ea30 6e 20 69 73 20 63 6f 6c 75 6d 6e 20 30 20 66 6f  n is column 0 fo
2ea40 72 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  r these routines
2ea50 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
2ea60 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72  Nth column retur
2ea70 6e 65 64 20 62 79 20 74 68 65 20 73 74 61 74 65  ned by the state
2ea80 6d 65 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65  ment is an expre
2ea90 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71  ssion or.** subq
2eaa0 75 65 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20  uery and is not 
2eab0 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20  a column value, 
2eac0 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73  then all of thes
2ead0 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  e functions retu
2eae0 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68  rn.** NULL.  ^Th
2eaf0 65 73 65 20 72 6f 75 74 69 6e 65 20 6d 69 67 68  ese routine migh
2eb00 74 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55  t also return NU
2eb10 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61  LL if a memory a
2eb20 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a  llocation error.
2eb30 2a 2a 20 6f 63 63 75 72 73 2e 20 20 5e 4f 74 68  ** occurs.  ^Oth
2eb40 65 72 77 69 73 65 2c 20 74 68 65 79 20 72 65 74  erwise, they ret
2eb50 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  urn the name of 
2eb60 74 68 65 20 61 74 74 61 63 68 65 64 20 64 61 74  the attached dat
2eb70 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a  abase, table,.**
2eb80 20 6f 72 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20   or column that 
2eb90 71 75 65 72 79 20 72 65 73 75 6c 74 20 63 6f 6c  query result col
2eba0 75 6d 6e 20 77 61 73 20 65 78 74 72 61 63 74 65  umn was extracte
2ebb0 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41  d from..**.** ^A
2ebc0 73 20 77 69 74 68 20 61 6c 6c 20 6f 74 68 65 72  s with all other
2ebd0 20 53 51 4c 69 74 65 20 41 50 49 73 2c 20 74 68   SQLite APIs, th
2ebe0 6f 73 65 20 77 68 6f 73 65 20 6e 61 6d 65 73 20  ose whose names 
2ebf0 65 6e 64 20 77 69 74 68 20 22 31 36 22 20 72 65  end with "16" re
2ec00 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65  turn.** UTF-16 e
2ec10 6e 63 6f 64 65 64 20 73 74 72 69 6e 67 73 20 61  ncoded strings a
2ec20 6e 64 20 74 68 65 20 6f 74 68 65 72 20 66 75 6e  nd the other fun
2ec30 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 55 54  ctions return UT
2ec40 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  F-8..**.** ^Thes
2ec50 65 20 41 50 49 73 20 61 72 65 20 6f 6e 6c 79 20  e APIs are only 
2ec60 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65  available if the
2ec70 20 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d   library was com
2ec80 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  piled with the.*
2ec90 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  * [SQLITE_ENABLE
2eca0 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41  _COLUMN_METADATA
2ecb0 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C-preprocessor
2ecc0 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49   symbol..**.** I
2ecd0 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68  f two or more th
2ece0 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f  reads call one o
2ecf0 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 73 65 20  r more of these 
2ed00 72 6f 75 74 69 6e 65 73 20 61 67 61 69 6e 73 74  routines against
2ed10 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65   the same.** pre
2ed20 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
2ed30 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68  and column at th
2ed40 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e  e same time then
2ed50 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
2ed60 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  .** undefined..*
2ed70 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d  *.** If two or m
2ed80 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c  ore threads call
2ed90 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20   one or more.** 
2eda0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2edb0 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20  database_name | 
2edc0 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 20  column metadata 
2edd0 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 66  interfaces].** f
2ede0 6f 72 20 74 68 65 20 73 61 6d 65 20 5b 70 72 65  or the same [pre
2edf0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2ee00 20 61 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c 75   and result colu
2ee10 6d 6e 0a 2a 2a 20 61 74 20 74 68 65 20 73 61 6d  mn.** at the sam
2ee20 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20  e time then the 
2ee30 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
2ee40 66 69 6e 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45  fined..*/.SQLITE
2ee50 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20  _API const char 
2ee60 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20  *SQLITE_STDCALL 
2ee70 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
2ee80 61 74 61 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c  atabase_name(sql
2ee90 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
2eea0 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
2eeb0 74 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53  t void *SQLITE_S
2eec0 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63  TDCALL sqlite3_c
2eed0 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e  olumn_database_n
2eee0 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
2eef0 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45  mt*,int);.SQLITE
2ef00 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20  _API const char 
2ef10 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20  *SQLITE_STDCALL 
2ef20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2ef30 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65  able_name(sqlite
2ef40 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51  3_stmt*,int);.SQ
2ef50 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76  LITE_API const v
2ef60 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43  oid *SQLITE_STDC
2ef70 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ALL sqlite3_colu
2ef80 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28  mn_table_name16(
2ef90 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
2efa0 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  t);.SQLITE_API c
2efb0 6f 6e 73 74 20 63 68 61 72 20 2a 53 51 4c 49 54  onst char *SQLIT
2efc0 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
2efd0 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f  3_column_origin_
2efe0 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
2eff0 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f  t*,int);.SQLITE_
2f000 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  API const void *
2f010 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
2f020 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72  qlite3_column_or
2f030 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69  igin_name16(sqli
2f040 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
2f050 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2f060 20 44 65 63 6c 61 72 65 64 20 44 61 74 61 74 79   Declared Dataty
2f070 70 65 20 4f 66 20 41 20 51 75 65 72 79 20 52 65  pe Of A Query Re
2f080 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  sult.**.** ^(The
2f090 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
2f0a0 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20   is a [prepared 
2f0b0 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49  statement]..** I
2f0c0 66 20 74 68 69 73 20 73 74 61 74 65 6d 65 6e 74  f this statement
2f0d0 20 69 73 20 61 20 5b 53 45 4c 45 43 54 5d 20 73   is a [SELECT] s
2f0e0 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 68 65  tatement and the
2f0f0 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74   Nth column of t
2f100 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 72  he.** returned r
2f110 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68 61  esult set of tha
2f120 74 20 5b 53 45 4c 45 43 54 5d 20 69 73 20 61 20  t [SELECT] is a 
2f130 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f  table column (no
2f140 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69  t an.** expressi
2f150 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 29 20  on or subquery) 
2f160 74 68 65 6e 20 74 68 65 20 64 65 63 6c 61 72 65  then the declare
2f170 64 20 74 79 70 65 20 6f 66 20 74 68 65 20 74 61  d type of the ta
2f180 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73  ble.** column is
2f190 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 20 5e 49   returned.)^  ^I
2f1a0 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  f the Nth column
2f1b0 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
2f1c0 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72  et is an.** expr
2f1d0 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65  ession or subque
2f1e0 72 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20  ry, then a NULL 
2f1f0 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72  pointer is retur
2f200 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74  ned..** ^The ret
2f210 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20  urned string is 
2f220 61 6c 77 61 79 73 20 55 54 46 2d 38 20 65 6e 63  always UTF-8 enc
2f230 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f  oded..**.** ^(Fo
2f240 72 20 65 78 61 6d 70 6c 65 2c 20 67 69 76 65 6e  r example, given
2f250 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63   the database sc
2f260 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41  hema:.**.** CREA
2f270 54 45 20 54 41 42 4c 45 20 74 31 28 63 31 20 56  TE TABLE t1(c1 V
2f280 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61  ARIANT);.**.** a
2f290 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  nd the following
2f2a0 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65   statement to be
2f2b0 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a   compiled:.**.**
2f2c0 20 53 45 4c 45 43 54 20 63 31 20 2b 20 31 2c 20   SELECT c1 + 1, 
2f2d0 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a  c1 FROM t1;.**.*
2f2e0 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  * this routine w
2f2f0 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20  ould return the 
2f300 73 74 72 69 6e 67 20 22 56 41 52 49 41 4e 54 22  string "VARIANT"
2f310 20 66 6f 72 20 74 68 65 20 73 65 63 6f 6e 64 20   for the second 
2f320 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e  result.** column
2f330 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e   (i==1), and a N
2f340 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20  ULL pointer for 
2f350 74 68 65 20 66 69 72 73 74 20 72 65 73 75 6c 74  the first result
2f360 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e 29   column (i==0).)
2f370 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ^.**.** ^SQLite 
2f380 75 73 65 73 20 64 79 6e 61 6d 69 63 20 72 75 6e  uses dynamic run
2f390 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e 20 20 5e  -time typing.  ^
2f3a0 53 6f 20 6a 75 73 74 20 62 65 63 61 75 73 65 20  So just because 
2f3b0 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64  a column.** is d
2f3c0 65 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74 61  eclared to conta
2f3d0 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  in a particular 
2f3e0 74 79 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65  type does not me
2f3f0 61 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 64  an that the.** d
2f400 61 74 61 20 73 74 6f 72 65 64 20 69 6e 20 74 68  ata stored in th
2f410 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20  at column is of 
2f420 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70  the declared typ
2f430 65 2e 20 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a  e.  SQLite is.**
2f440 20 73 74 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c   strongly typed,
2f450 20 62 75 74 20 74 68 65 20 74 79 70 69 6e 67 20   but the typing 
2f460 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73  is dynamic not s
2f470 74 61 74 69 63 2e 20 20 5e 54 79 70 65 0a 2a 2a  tatic.  ^Type.**
2f480 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 20 77   is associated w
2f490 69 74 68 20 69 6e 64 69 76 69 64 75 61 6c 20 76  ith individual v
2f4a0 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74 68 20  alues, not with 
2f4b0 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a  the containers.*
2f4c0 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 74  * used to hold t
2f4d0 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a  hose values..*/.
2f4e0 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
2f4f0 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f 53 54   char *SQLITE_ST
2f500 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f  DCALL sqlite3_co
2f510 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 71  lumn_decltype(sq
2f520 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
2f530 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  ;.SQLITE_API con
2f540 73 74 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f  st void *SQLITE_
2f550 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
2f560 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31  column_decltype1
2f570 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
2f580 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
2f590 49 33 52 45 46 3a 20 45 76 61 6c 75 61 74 65 20  I3REF: Evaluate 
2f5a0 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
2f5b0 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b  .**.** After a [
2f5c0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2f5d0 6e 74 5d 20 68 61 73 20 62 65 65 6e 20 70 72 65  nt] has been pre
2f5e0 70 61 72 65 64 20 75 73 69 6e 67 20 65 69 74 68  pared using eith
2f5f0 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  er.** [sqlite3_p
2f600 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
2f610 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2f620 31 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20  16_v2()] or one 
2f630 6f 66 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a  of the legacy.**
2f640 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c   interfaces [sql
2f650 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
2f660 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
2f670 61 72 65 31 36 28 29 5d 2c 20 74 68 69 73 20 66  are16()], this f
2f680 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20  unction.** must 
2f690 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72  be called one or
2f6a0 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65   more times to e
2f6b0 76 61 6c 75 61 74 65 20 74 68 65 20 73 74 61 74  valuate the stat
2f6c0 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ement..**.** The
2f6d0 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20   details of the 
2f6e0 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 65 20  behavior of the 
2f6f0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69  sqlite3_step() i
2f700 6e 74 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a  nterface depend.
2f710 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68  ** on whether th
2f720 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20  e statement was 
2f730 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 74  prepared using t
2f740 68 65 20 6e 65 77 65 72 20 22 76 32 22 20 69 6e  he newer "v2" in
2f750 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69  terface.** [sqli
2f760 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
2f770 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70  ] and [sqlite3_p
2f780 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f  repare16_v2()] o
2f790 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61  r the older lega
2f7a0 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  cy.** interface 
2f7b0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2f7c0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
2f7d0 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20 20  _prepare16()].  
2f7e0 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a 2a  The use of the.*
2f7f0 2a 20 6e 65 77 20 22 76 32 22 20 69 6e 74 65 72  * new "v2" inter
2f800 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e  face is recommen
2f810 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70 6c  ded for new appl
2f820 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68 65  ications but the
2f830 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72   legacy.** inter
2f840 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e  face will contin
2f850 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74  ue to be support
2f860 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68  ed..**.** ^In th
2f870 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61  e legacy interfa
2f880 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76  ce, the return v
2f890 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74  alue will be eit
2f8a0 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  her [SQLITE_BUSY
2f8b0 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f  ],.** [SQLITE_DO
2f8c0 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57  NE], [SQLITE_ROW
2f8d0 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ], [SQLITE_ERROR
2f8e0 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49  ], or [SQLITE_MI
2f8f0 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20  SUSE]..** ^With 
2f900 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
2f910 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f  ce, any of the o
2f920 74 68 65 72 20 5b 72 65 73 75 6c 74 20 63 6f 64  ther [result cod
2f930 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e  es] or.** [exten
2f940 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
2f950 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72  ] might be retur
2f960 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a  ned as well..**.
2f970 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53 59  ** ^[SQLITE_BUSY
2f980 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  ] means that the
2f990 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65   database engine
2f9a0 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61   was unable to a
2f9b0 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61  cquire the.** da
2f9c0 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20  tabase locks it 
2f9d0 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20  needs to do its 
2f9e0 6a 6f 62 2e 20 20 5e 49 66 20 74 68 65 20 73 74  job.  ^If the st
2f9f0 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f  atement is a [CO
2fa00 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75  MMIT].** or occu
2fa10 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e  rs outside of an
2fa20 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61   explicit transa
2fa30 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20  ction, then you 
2fa40 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a  can retry the.**
2fa50 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20   statement.  If 
2fa60 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
2fa70 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20   not a [COMMIT] 
2fa80 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68 69  and occurs withi
2fa90 6e 20 61 6e 0a 2a 2a 20 65 78 70 6c 69 63 69 74  n an.** explicit
2faa0 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65   transaction the
2fab0 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c  n you should rol
2fac0 6c 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61  lback the transa
2fad0 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20  ction before.** 
2fae0 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a  continuing..**.*
2faf0 2a 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  * ^[SQLITE_DONE]
2fb00 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
2fb10 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69  statement has fi
2fb20 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67  nished executing
2fb30 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79  .** successfully
2fb40 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  .  sqlite3_step(
2fb50 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20  ) should not be 
2fb60 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20  called again on 
2fb70 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20  this virtual.** 
2fb80 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20  machine without 
2fb90 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73  first calling [s
2fba0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
2fbb0 74 6f 20 72 65 73 65 74 20 74 68 65 20 76 69 72  to reset the vir
2fbc0 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20  tual.** machine 
2fbd0 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74  back to its init
2fbe0 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a  ial state..**.**
2fbf0 20 5e 49 66 20 74 68 65 20 53 51 4c 20 73 74 61   ^If the SQL sta
2fc00 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65  tement being exe
2fc10 63 75 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e  cuted returns an
2fc20 79 20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 51  y data, then [SQ
2fc30 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20  LITE_ROW].** is 
2fc40 72 65 74 75 72 6e 65 64 20 65 61 63 68 20 74 69  returned each ti
2fc50 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20  me a new row of 
2fc60 64 61 74 61 20 69 73 20 72 65 61 64 79 20 66 6f  data is ready fo
2fc70 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20  r processing by 
2fc80 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54  the.** caller. T
2fc90 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65  he values may be
2fca0 20 61 63 63 65 73 73 65 64 20 75 73 69 6e 67 20   accessed using 
2fcb0 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65  the [column acce
2fcc0 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a  ss functions]..*
2fcd0 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  * sqlite3_step()
2fce0 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e   is called again
2fcf0 20 74 6f 20 72 65 74 72 69 65 76 65 20 74 68 65   to retrieve the
2fd00 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74   next row of dat
2fd10 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54  a..**.** ^[SQLIT
2fd20 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74  E_ERROR] means t
2fd30 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65  hat a run-time e
2fd40 72 72 6f 72 20 28 73 75 63 68 20 61 73 20 61 20  rror (such as a 
2fd50 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69  constraint.** vi
2fd60 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63  olation) has occ
2fd70 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f  urred.  sqlite3_
2fd80 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f  step() should no
2fd90 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69  t be called agai
2fda0 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20  n on.** the VM. 
2fdb0 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  More information
2fdc0 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79   may be found by
2fdd0 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
2fde0 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20  3_errmsg()]..** 
2fdf0 5e 57 69 74 68 20 74 68 65 20 6c 65 67 61 63 79  ^With the legacy
2fe00 20 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f   interface, a mo
2fe10 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f  re specific erro
2fe20 72 20 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d  r code (for exam
2fe30 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ple,.** [SQLITE_
2fe40 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c  INTERRUPT], [SQL
2fe50 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51  ITE_SCHEMA], [SQ
2fe60 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61  LITE_CORRUPT], a
2fe70 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20  nd so forth).** 
2fe80 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20  can be obtained 
2fe90 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  by calling [sqli
2fea0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20  te3_reset()] on 
2feb0 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
2fec0 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49   statement].  ^I
2fed0 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  n the "v2" inter
2fee0 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72  face,.** the mor
2fef0 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72  e specific error
2ff00 20 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65   code is returne
2ff10 64 20 64 69 72 65 63 74 6c 79 20 62 79 20 73 71  d directly by sq
2ff20 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a  lite3_step()..**
2ff30 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  .** [SQLITE_MISU
2ff40 53 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74  SE] means that t
2ff50 68 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  he this routine 
2ff60 77 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70  was called inapp
2ff70 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50  ropriately..** P
2ff80 65 72 68 61 70 73 20 69 74 20 77 61 73 20 63 61  erhaps it was ca
2ff90 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61  lled on a [prepa
2ffa0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
2ffb0 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61  hat has.** alrea
2ffc0 64 79 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33  dy been [sqlite3
2ffd0 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61  _finalize | fina
2ffe0 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65  lized] or on one
2fff0 20 74 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 65   that had.** pre
30000 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64  viously returned
30010 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
30020 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  or [SQLITE_DONE]
30030 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a  .  Or it could.*
30040 2a 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68  * be the case th
30050 61 74 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  at the same data
30060 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
30070 69 73 20 62 65 69 6e 67 20 75 73 65 64 20 62 79  is being used by
30080 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20   two or.** more 
30090 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73  threads at the s
300a0 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69  ame moment in ti
300b0 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c  me..**.** For al
300c0 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  l versions of SQ
300d0 4c 69 74 65 20 75 70 20 74 6f 20 61 6e 64 20 69  Lite up to and i
300e0 6e 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e  ncluding 3.6.23.
300f0 31 2c 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  1, a call to.** 
30100 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
30110 5d 20 77 61 73 20 72 65 71 75 69 72 65 64 20 61  ] was required a
30120 66 74 65 72 20 73 71 6c 69 74 65 33 5f 73 74 65  fter sqlite3_ste
30130 70 28 29 20 72 65 74 75 72 6e 65 64 20 61 6e 79  p() returned any
30140 74 68 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 74  thing.** other t
30150 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  han [SQLITE_ROW]
30160 20 62 65 66 6f 72 65 20 61 6e 79 20 73 75 62 73   before any subs
30170 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f  equent invocatio
30180 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  n of.** sqlite3_
30190 73 74 65 70 28 29 2e 20 20 46 61 69 6c 75 72 65  step().  Failure
301a0 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 70 72   to reset the pr
301b0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
301c0 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69   using .** [sqli
301d0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77 6f 75  te3_reset()] wou
301e0 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 6e 20  ld result in an 
301f0 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20  [SQLITE_MISUSE] 
30200 72 65 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73  return from.** s
30210 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20  qlite3_step().  
30220 42 75 74 20 61 66 74 65 72 20 76 65 72 73 69 6f  But after versio
30230 6e 20 33 2e 36 2e 32 33 2e 31 2c 20 73 71 6c 69  n 3.6.23.1, sqli
30240 74 65 33 5f 73 74 65 70 28 29 20 62 65 67 61 6e  te3_step() began
30250 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c  .** calling [sql
30260 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 61 75  ite3_reset()] au
30270 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20 74  tomatically in t
30280 68 69 73 20 63 69 72 63 75 6d 73 74 61 6e 63 65  his circumstance
30290 20 72 61 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20   rather.** than 
302a0 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54  returning [SQLIT
302b0 45 5f 4d 49 53 55 53 45 5d 2e 20 20 54 68 69 73  E_MISUSE].  This
302c0 20 69 73 20 6e 6f 74 20 63 6f 6e 73 69 64 65 72   is not consider
302d0 65 64 20 61 20 63 6f 6d 70 61 74 69 62 69 6c 69  ed a compatibili
302e0 74 79 0a 2a 2a 20 62 72 65 61 6b 20 62 65 63 61  ty.** break beca
302f0 75 73 65 20 61 6e 79 20 61 70 70 6c 69 63 61 74  use any applicat
30300 69 6f 6e 20 74 68 61 74 20 65 76 65 72 20 72 65  ion that ever re
30310 63 65 69 76 65 73 20 61 6e 20 53 51 4c 49 54 45  ceives an SQLITE
30320 5f 4d 49 53 55 53 45 20 65 72 72 6f 72 0a 2a 2a  _MISUSE error.**
30330 20 69 73 20 62 72 6f 6b 65 6e 20 62 79 20 64 65   is broken by de
30340 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 65 20 5b  finition.  The [
30350 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f  SQLITE_OMIT_AUTO
30360 52 45 53 45 54 5d 20 63 6f 6d 70 69 6c 65 2d 74  RESET] compile-t
30370 69 6d 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61  ime option.** ca
30380 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 73  n be used to res
30390 74 6f 72 65 20 74 68 65 20 6c 65 67 61 63 79 20  tore the legacy 
303a0 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20  behavior..**.** 
303b0 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61  <b>Goofy Interfa
303c0 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e  ce Alert:</b> In
303d0 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65   the legacy inte
303e0 72 66 61 63 65 2c 20 74 68 65 20 73 71 6c 69 74  rface, the sqlit
303f0 65 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50 49  e3_step().** API
30400 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20   always returns 
30410 61 20 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20  a generic error 
30420 63 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52  code, [SQLITE_ER
30430 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20  ROR], following 
30440 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68  any.** error oth
30450 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
30460 42 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54  BUSY] and [SQLIT
30470 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20  E_MISUSE].  You 
30480 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71  must call.** [sq
30490 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
304a0 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  r [sqlite3_final
304b0 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20  ize()] in order 
304c0 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74  to find one of t
304d0 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 5b  he.** specific [
304e0 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 74 68 61  error codes] tha
304f0 74 20 62 65 74 74 65 72 20 64 65 73 63 72 69 62  t better describ
30500 65 73 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a  es the error..**
30510 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 20 74   We admit that t
30520 68 69 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64  his is a goofy d
30530 65 73 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62  esign.  The prob
30540 6c 65 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78  lem has been fix
30550 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22  ed.** with the "
30560 76 32 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20  v2" interface.  
30570 49 66 20 79 6f 75 20 70 72 65 70 61 72 65 20 61  If you prepare a
30580 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73  ll of your SQL s
30590 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69  tatements.** usi
305a0 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74  ng either [sqlit
305b0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
305c0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
305d0 70 61 72 65 31 36 5f 76 32 28 29 5d 20 69 6e 73  pare16_v2()] ins
305e0 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c  tead.** of the l
305f0 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70  egacy [sqlite3_p
30600 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73  repare()] and [s
30610 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
30620 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2c 0a  ()] interfaces,.
30630 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f 72 65  ** then the more
30640 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72   specific [error
30650 20 63 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75   codes] are retu
30660 72 6e 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a  rned directly.**
30670 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70   by sqlite3_step
30680 28 29 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20  ().  The use of 
30690 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
306a0 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  ce is recommende
306b0 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  d..*/.SQLITE_API
306c0 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43   int SQLITE_STDC
306d0 41 4c 4c 20 73 71 6c 69 74 65 33 5f 73 74 65 70  ALL sqlite3_step
306e0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
306f0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
30700 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  : Number of colu
30710 6d 6e 73 20 69 6e 20 61 20 72 65 73 75 6c 74 20  mns in a result 
30720 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  set.**.** ^The s
30730 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
30740 74 28 50 29 20 69 6e 74 65 72 66 61 63 65 20 72  t(P) interface r
30750 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
30760 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
30770 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 72  the.** current r
30780 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ow of the result
30790 20 73 65 74 20 6f 66 20 5b 70 72 65 70 61 72 65   set of [prepare
307a0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a  d statement] P..
307b0 2a 2a 20 5e 49 66 20 70 72 65 70 61 72 65 64 20  ** ^If prepared 
307c0 73 74 61 74 65 6d 65 6e 74 20 50 20 64 6f 65 73  statement P does
307d0 20 6e 6f 74 20 68 61 76 65 20 72 65 73 75 6c 74   not have result
307e0 73 20 72 65 61 64 79 20 74 6f 20 72 65 74 75 72  s ready to retur
307f0 6e 0a 2a 2a 20 28 76 69 61 20 63 61 6c 6c 73 20  n.** (via calls 
30800 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
30810 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20 73 71 6c  column_int | sql
30820 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 5d  ite3_column_*()]
30830 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65   of.** interface
30840 73 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  s) then sqlite3_
30850 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 65  data_count(P) re
30860 74 75 72 6e 73 20 30 2e 0a 2a 2a 20 5e 54 68 65  turns 0..** ^The
30870 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
30880 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20 61  unt(P) routine a
30890 6c 73 6f 20 72 65 74 75 72 6e 73 20 30 20 69 66  lso returns 0 if
308a0 20 50 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69   P is a NULL poi
308b0 6e 74 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  nter..** ^The sq
308c0 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
308d0 28 50 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  (P) routine retu
308e0 72 6e 73 20 30 20 69 66 20 74 68 65 20 70 72 65  rns 0 if the pre
308f0 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 0a 2a 2a  vious call to.**
30900 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 28   [sqlite3_step](
30910 50 29 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c  P) returned [SQL
30920 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 5e 54 68 65  ITE_DONE].  ^The
30930 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
30940 75 6e 74 28 50 29 0a 2a 2a 20 77 69 6c 6c 20 72  unt(P).** will r
30950 65 74 75 72 6e 20 6e 6f 6e 2d 7a 65 72 6f 20 69  eturn non-zero i
30960 66 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20  f previous call 
30970 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
30980 5d 28 50 29 20 72 65 74 75 72 6e 65 64 0a 2a 2a  ](P) returned.**
30990 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 65   [SQLITE_ROW], e
309a0 78 63 65 70 74 20 69 6e 20 74 68 65 20 63 61 73  xcept in the cas
309b0 65 20 6f 66 20 74 68 65 20 5b 50 52 41 47 4d 41  e of the [PRAGMA
309c0 20 69 6e 63 72 65 6d 65 6e 74 61 6c 5f 76 61 63   incremental_vac
309d0 75 75 6d 5d 0a 2a 2a 20 77 68 65 72 65 20 69 74  uum].** where it
309e0 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20   always returns 
309f0 7a 65 72 6f 20 73 69 6e 63 65 20 65 61 63 68 20  zero since each 
30a00 73 74 65 70 20 6f 66 20 74 68 61 74 20 6d 75 6c  step of that mul
30a10 74 69 2d 73 74 65 70 0a 2a 2a 20 70 72 61 67 6d  ti-step.** pragm
30a20 61 20 72 65 74 75 72 6e 73 20 30 20 63 6f 6c 75  a returns 0 colu
30a30 6d 6e 73 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a  mns of data..**.
30a40 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
30a50 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75  lite3_column_cou
30a60 6e 74 28 29 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f  nt()].*/.SQLITE_
30a70 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  API int SQLITE_S
30a80 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 64  TDCALL sqlite3_d
30a90 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65  ata_count(sqlite
30aa0 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
30ab0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
30ac0 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74   Fundamental Dat
30ad0 61 74 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52  atypes.** KEYWOR
30ae0 44 53 3a 20 53 51 4c 49 54 45 5f 54 45 58 54 0a  DS: SQLITE_TEXT.
30af0 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72 79 20 76 61  **.** ^(Every va
30b00 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 20 68 61  lue in SQLite ha
30b10 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 20 66 75  s one of five fu
30b20 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 61 74 79  ndamental dataty
30b30 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  pes:.**.** <ul>.
30b40 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73  ** <li> 64-bit s
30b50 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a  igned integer.**
30b60 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49 45 45   <li> 64-bit IEE
30b70 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  E floating point
30b80 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20   number.** <li> 
30b90 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42  string.** <li> B
30ba0 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c  LOB.** <li> NULL
30bb0 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a  .** </ul>)^.**.*
30bc0 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
30bd0 73 20 61 72 65 20 63 6f 64 65 73 20 66 6f 72 20  s are codes for 
30be0 65 61 63 68 20 6f 66 20 74 68 6f 73 65 20 74 79  each of those ty
30bf0 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  pes..**.** Note 
30c00 74 68 61 74 20 74 68 65 20 53 51 4c 49 54 45 5f  that the SQLITE_
30c10 54 45 58 54 20 63 6f 6e 73 74 61 6e 74 20 77 61  TEXT constant wa
30c20 73 20 61 6c 73 6f 20 75 73 65 64 20 69 6e 20 53  s also used in S
30c30 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 0a  QLite version 2.
30c40 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74  ** for a complet
30c50 65 6c 79 20 64 69 66 66 65 72 65 6e 74 20 6d 65  ely different me
30c60 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61 72 65  aning.  Software
30c70 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69   that links agai
30c80 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69  nst both.** SQLi
30c90 74 65 20 76 65 72 73 69 6f 6e 20 32 20 61 6e 64  te version 2 and
30ca0 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
30cb0 33 20 73 68 6f 75 6c 64 20 75 73 65 20 53 51 4c  3 should use SQL
30cc0 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a  ITE3_TEXT, not.*
30cd0 2a 20 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a  * SQLITE_TEXT..*
30ce0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
30cf0 5f 49 4e 54 45 47 45 52 20 20 31 0a 23 64 65 66  _INTEGER  1.#def
30d00 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54  ine SQLITE_FLOAT
30d10 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
30d20 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a  LITE_BLOB     4.
30d30 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
30d40 55 4c 4c 20 20 20 20 20 35 0a 23 69 66 64 65 66  ULL     5.#ifdef
30d50 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 20 75   SQLITE_TEXT.# u
30d60 6e 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54  ndef SQLITE_TEXT
30d70 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20  .#else.# define 
30d80 53 51 4c 49 54 45 5f 54 45 58 54 20 20 20 20 20  SQLITE_TEXT     
30d90 33 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 6e 65  3.#endif.#define
30da0 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20 20 20   SQLITE3_TEXT   
30db0 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33    3../*.** CAPI3
30dc0 52 45 46 3a 20 52 65 73 75 6c 74 20 56 61 6c 75  REF: Result Valu
30dd0 65 73 20 46 72 6f 6d 20 41 20 51 75 65 72 79 0a  es From A Query.
30de0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f  ** KEYWORDS: {co
30df0 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63  lumn access func
30e00 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  tions}.**.** The
30e10 73 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 6d  se routines form
30e20 20 74 68 65 20 22 72 65 73 75 6c 74 20 73 65 74   the "result set
30e30 22 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  " interface..**.
30e40 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
30e50 65 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d  es return inform
30e60 61 74 69 6f 6e 20 61 62 6f 75 74 20 61 20 73 69  ation about a si
30e70 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  ngle column of t
30e80 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65  he current.** re
30e90 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 20 71 75  sult row of a qu
30ea0 65 72 79 2e 20 20 5e 49 6e 20 65 76 65 72 79 20  ery.  ^In every 
30eb0 63 61 73 65 20 74 68 65 20 66 69 72 73 74 20 61  case the first a
30ec0 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
30ed0 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b  nter.** to the [
30ee0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
30ef0 6e 74 5d 20 74 68 61 74 20 69 73 20 62 65 69 6e  nt] that is bein
30f00 67 20 65 76 61 6c 75 61 74 65 64 20 28 74 68 65  g evaluated (the
30f10 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d   [sqlite3_stmt*]
30f20 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 72 65 74  .** that was ret
30f30 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  urned from [sqli
30f40 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
30f50 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 20  ] or one of its 
30f60 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64  variants).** and
30f70 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
30f80 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65  ment is the inde
30f90 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20  x of the column 
30fa0 66 6f 72 20 77 68 69 63 68 20 69 6e 66 6f 72 6d  for which inform
30fb0 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20  ation.** should 
30fc0 62 65 20 72 65 74 75 72 6e 65 64 2e 20 5e 54 68  be returned. ^Th
30fd0 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d  e leftmost colum
30fe0 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  n of the result 
30ff0 73 65 74 20 68 61 73 20 74 68 65 20 69 6e 64 65  set has the inde
31000 78 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d  x 0..** ^The num
31010 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
31020 6e 20 74 68 65 20 72 65 73 75 6c 74 20 63 61 6e  n the result can
31030 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75   be determined u
31040 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
31050 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d  _column_count()]
31060 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53  ..**.** If the S
31070 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65  QL statement doe
31080 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20  s not currently 
31090 70 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c 69 64  point to a valid
310a0 20 72 6f 77 2c 20 6f 72 20 69 66 20 74 68 65 0a   row, or if the.
310b0 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20  ** column index 
310c0 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c  is out of range,
310d0 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 75   the result is u
310e0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65  ndefined..** The
310f0 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79 20  se routines may 
31100 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77  only be called w
31110 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63  hen the most rec
31120 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  ent call to.** [
31130 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
31140 68 61 73 20 72 65 74 75 72 6e 65 64 20 5b 53 51  has returned [SQ
31150 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65  LITE_ROW] and ne
31160 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ither.** [sqlite
31170 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b  3_reset()] nor [
31180 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
31190 28 29 5d 20 68 61 76 65 20 62 65 65 6e 20 63 61  ()] have been ca
311a0 6c 6c 65 64 20 73 75 62 73 65 71 75 65 6e 74 6c  lled subsequentl
311b0 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20  y..** If any of 
311c0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  these routines a
311d0 72 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20  re called after 
311e0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
311f0 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
31200 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20  _finalize()] or 
31210 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73  after [sqlite3_s
31220 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72  tep()] has retur
31230 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67  ned.** something
31240 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
31250 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65  ITE_ROW], the re
31260 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
31270 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69  ned..** If [sqli
31280 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b  te3_step()] or [
31290 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
312a0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   or [sqlite3_fin
312b0 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20  alize()].** are 
312c0 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64 69  called from a di
312d0 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 20 77  fferent thread w
312e0 68 69 6c 65 20 61 6e 79 20 6f 66 20 74 68 65 73  hile any of thes
312f0 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72  e routines.** ar
31300 65 20 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20  e pending, then 
31310 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
31320 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
31330 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f   ^The sqlite3_co
31340 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75 74  lumn_type() rout
31350 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a  ine returns the.
31360 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47  ** [SQLITE_INTEG
31370 45 52 20 7c 20 64 61 74 61 74 79 70 65 20 63 6f  ER | datatype co
31380 64 65 5d 20 66 6f 72 20 74 68 65 20 69 6e 69 74  de] for the init
31390 69 61 6c 20 64 61 74 61 20 74 79 70 65 0a 2a 2a  ial data type.**
313a0 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 63   of the result c
313b0 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65 20 72 65 74  olumn.  ^The ret
313c0 75 72 6e 65 64 20 76 61 6c 75 65 20 69 73 20 6f  urned value is o
313d0 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e  ne of [SQLITE_IN
313e0 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  TEGER],.** [SQLI
313f0 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49  TE_FLOAT], [SQLI
31400 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54  TE_TEXT], [SQLIT
31410 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c  E_BLOB], or [SQL
31420 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20  ITE_NULL].  The 
31430 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65  value.** returne
31440 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
31450 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 6f 6e  umn_type() is on
31460 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66  ly meaningful if
31470 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76   no type.** conv
31480 65 72 73 69 6f 6e 73 20 68 61 76 65 20 6f 63 63  ersions have occ
31490 75 72 72 65 64 20 61 73 20 64 65 73 63 72 69 62  urred as describ
314a0 65 64 20 62 65 6c 6f 77 2e 20 20 41 66 74 65 72  ed below.  After
314b0 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69   a type conversi
314c0 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65  on,.** the value
314d0 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
314e0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
314f0 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  () is undefined.
31500 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 65 72 73    Future.** vers
31510 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d  ions of SQLite m
31520 61 79 20 63 68 61 6e 67 65 20 74 68 65 20 62 65  ay change the be
31530 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65  havior of sqlite
31540 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a  3_column_type().
31550 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74  ** following a t
31560 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a  ype conversion..
31570 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  **.** ^If the re
31580 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f  sult is a BLOB o
31590 72 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 74  r UTF-8 string t
315a0 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hen the sqlite3_
315b0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a  column_bytes().*
315c0 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  * routine return
315d0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
315e0 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c  bytes in that BL
315f0 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a  OB or string..**
31600 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
31610 69 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69  is a UTF-16 stri
31620 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ng, then sqlite3
31630 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
31640 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20  converts.** the 
31650 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 38 20  string to UTF-8 
31660 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73  and then returns
31670 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
31680 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ytes..** ^If the
31690 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d   result is a num
316a0 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20  eric value then 
316b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
316c0 79 74 65 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b  ytes() uses.** [
316d0 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
316e0 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74  ()] to convert t
316f0 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55  hat value to a U
31700 54 46 2d 38 20 73 74 72 69 6e 67 20 61 6e 64 20  TF-8 string and 
31710 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e  returns.** the n
31720 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
31730 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a  n that string..*
31740 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
31750 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73   is NULL, then s
31760 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
31770 74 65 73 28 29 20 72 65 74 75 72 6e 73 20 7a 65  tes() returns ze
31780 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ro..**.** ^If th
31790 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c  e result is a BL
317a0 4f 42 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72  OB or UTF-16 str
317b0 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c  ing then the sql
317c0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
317d0 73 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  s16().** routine
317e0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
317f0 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
31800 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72  that BLOB or str
31810 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ing..** ^If the 
31820 72 65 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d  result is a UTF-
31830 38 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73  8 string, then s
31840 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
31850 74 65 73 31 36 28 29 20 63 6f 6e 76 65 72 74 73  tes16() converts
31860 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74  .** the string t
31870 6f 20 55 54 46 2d 31 36 20 61 6e 64 20 74 68 65  o UTF-16 and the
31880 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
31890 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a  mber of bytes..*
318a0 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
318b0 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61   is a numeric va
318c0 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33  lue then sqlite3
318d0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
318e0 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74  ) uses.** [sqlit
318f0 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74  e3_snprintf()] t
31900 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76  o convert that v
31910 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 31 36  alue to a UTF-16
31920 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75   string and retu
31930 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65  rns.** the numbe
31940 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
31950 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49  at string..** ^I
31960 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
31970 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74  NULL, then sqlit
31980 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
31990 36 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  6() returns zero
319a0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 76 61 6c  ..**.** ^The val
319b0 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ues returned by 
319c0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
319d0 62 79 74 65 73 28 29 5d 20 61 6e 64 20 0a 2a 2a  bytes()] and .**
319e0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
319f0 5f 62 79 74 65 73 31 36 28 29 5d 20 64 6f 20 6e  _bytes16()] do n
31a00 6f 74 20 69 6e 63 6c 75 64 65 20 74 68 65 20 7a  ot include the z
31a10 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 73 20  ero terminators 
31a20 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66  at the end.** of
31a30 20 74 68 65 20 73 74 72 69 6e 67 2e 20 20 5e 46   the string.  ^F
31a40 6f 72 20 63 6c 61 72 69 74 79 3a 20 74 68 65 20  or clarity: the 
31a50 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20  values returned 
31a60 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  by.** [sqlite3_c
31a70 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61  olumn_bytes()] a
31a80 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  nd [sqlite3_colu
31a90 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 61 72  mn_bytes16()] ar
31aa0 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  e the number of.
31ab0 2a 2a 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  ** bytes in the 
31ac0 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20  string, not the 
31ad0 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63  number of charac
31ae0 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72  ters..**.** ^Str
31af0 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79  ings returned by
31b00 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
31b10 74 65 78 74 28 29 20 61 6e 64 20 73 71 6c 69 74  text() and sqlit
31b20 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
31b30 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d 70 74  (),.** even empt
31b40 79 20 73 74 72 69 6e 67 73 2c 20 61 72 65 20 61  y strings, are a
31b50 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69  lways zero-termi
31b60 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 72 65 74  nated.  ^The ret
31b70 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f  urn.** value fro
31b80 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  m sqlite3_column
31b90 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a 65  _blob() for a ze
31ba0 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 20 69  ro-length BLOB i
31bb0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
31bc0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f 62 6a  ..**.** ^The obj
31bd0 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 20  ect returned by 
31be0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
31bf0 76 61 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a  value()] is an.*
31c00 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  * [unprotected s
31c10 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
31c20 6a 65 63 74 2e 20 20 41 6e 20 75 6e 70 72 6f 74  ject.  An unprot
31c30 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
31c40 6c 75 65 20 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61  lue object.** ma
31c50 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77  y only be used w
31c60 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  ith [sqlite3_bin
31c70 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b  d_value()] and [
31c80 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
31c90 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74  alue()]..** If t
31ca0 68 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  he [unprotected 
31cb0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
31cc0 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62  bject returned b
31cd0 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  y.** [sqlite3_co
31ce0 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73  lumn_value()] is
31cf0 20 75 73 65 64 20 69 6e 20 61 6e 79 20 6f 74 68   used in any oth
31d00 65 72 20 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e  er way, includin
31d10 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f  g calls.** to ro
31d20 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c  utines like [sql
31d30 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29  ite3_value_int()
31d40 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ], [sqlite3_valu
31d50 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72  e_text()],.** or
31d60 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
31d70 62 79 74 65 73 28 29 5d 2c 20 74 68 65 6e 20 74  bytes()], then t
31d80 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75  he behavior is u
31d90 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
31da0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
31db0 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72  ttempt to conver
31dc0 74 20 74 68 65 20 76 61 6c 75 65 20 77 68 65 72  t the value wher
31dd0 65 20 61 70 70 72 6f 70 72 69 61 74 65 2e 20 20  e appropriate.  
31de0 5e 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c  ^For.** example,
31df0 20 69 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c   if the internal
31e00 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20   representation 
31e10 69 73 20 46 4c 4f 41 54 20 61 6e 64 20 61 20 74  is FLOAT and a t
31e20 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73  ext result.** is
31e30 20 72 65 71 75 65 73 74 65 64 2c 20 5b 73 71 6c   requested, [sql
31e40 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d  ite3_snprintf()]
31e50 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61   is used interna
31e60 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d 20 74  lly to perform t
31e70 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e  he.** conversion
31e80 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20   automatically. 
31e90 20 5e 28 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67   ^(The following
31ea0 20 74 61 62 6c 65 20 64 65 74 61 69 6c 73 20 74   table details t
31eb0 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a  he conversions.*
31ec0 2a 20 74 68 61 74 20 61 72 65 20 61 70 70 6c 69  * that are appli
31ed0 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ed:.**.** <block
31ee0 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65  quote>.** <table
31ef0 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20   border="1">.** 
31f00 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61  <tr><th> Interna
31f10 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 52  l<br>Type <th> R
31f20 65 71 75 65 73 74 65 64 3c 62 72 3e 54 79 70 65  equested<br>Type
31f30 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f   <th>  Conversio
31f40 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  n.**.** <tr><td>
31f50 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49    NULL    <td> I
31f60 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 52 65  NTEGER   <td> Re
31f70 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72  sult is 0.** <tr
31f80 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
31f90 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
31fa0 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 2e 30  d> Result is 0.0
31fb0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
31fc0 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58  LL    <td>   TEX
31fd0 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  T    <td> Result
31fe0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
31ff0 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  er.** <tr><td>  
32000 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 42  NULL    <td>   B
32010 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52 65 73 75  LOB    <td> Resu
32020 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  lt is a NULL poi
32030 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  nter.** <tr><td>
32040 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20   INTEGER  <td>  
32050 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f  FLOAT    <td> Co
32060 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e 74 65 67  nvert from integ
32070 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c  er to float.** <
32080 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20  tr><td> INTEGER 
32090 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
320a0 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65  <td> ASCII rende
320b0 72 69 6e 67 20 6f 66 20 74 68 65 20 69 6e 74 65  ring of the inte
320c0 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ger.** <tr><td> 
320d0 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20  INTEGER  <td>   
320e0 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d  BLOB    <td> Sam
320f0 65 20 61 73 20 49 4e 54 45 47 45 52 2d 3e 54 45  e as INTEGER->TE
32100 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  XT.** <tr><td>  
32110 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e 54  FLOAT   <td> INT
32120 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53  EGER   <td> [CAS
32130 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a  T] to INTEGER.**
32140 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54   <tr><td>  FLOAT
32150 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20     <td>   TEXT  
32160 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e    <td> ASCII ren
32170 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6c  dering of the fl
32180 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  oat.** <tr><td> 
32190 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20   FLOAT   <td>   
321a0 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 5b 43 41  BLOB    <td> [CA
321b0 53 54 5d 20 74 6f 20 42 4c 4f 42 0a 2a 2a 20 3c  ST] to BLOB.** <
321c0 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20  tr><td>  TEXT   
321d0 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20   <td> INTEGER   
321e0 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49  <td> [CAST] to I
321f0 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74  NTEGER.** <tr><t
32200 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  d>  TEXT    <td>
32210 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
32220 5b 43 41 53 54 5d 20 74 6f 20 52 45 41 4c 0a 2a  [CAST] to REAL.*
32230 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54  * <tr><td>  TEXT
32240 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20      <td>   BLOB 
32250 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67     <td> No chang
32260 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42  e.** <tr><td>  B
32270 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 45  LOB    <td> INTE
32280 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54  GER   <td> [CAST
32290 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20  ] to INTEGER.** 
322a0 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20  <tr><td>  BLOB  
322b0 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
322c0 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20   <td> [CAST] to 
322d0 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  REAL.** <tr><td>
322e0 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20    BLOB    <td>  
322f0 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 64   TEXT    <td> Ad
32300 64 20 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  d a zero termina
32310 74 6f 72 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a  tor if needed.**
32320 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62   </table>.** </b
32330 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a  lockquote>)^.**.
32340 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 61 62 6f  ** The table abo
32350 76 65 20 6d 61 6b 65 73 20 72 65 66 65 72 65 6e  ve makes referen
32360 63 65 20 74 6f 20 73 74 61 6e 64 61 72 64 20 43  ce to standard C
32370 20 6c 69 62 72 61 72 79 20 66 75 6e 63 74 69 6f   library functio
32380 6e 73 20 61 74 6f 69 28 29 0a 2a 2a 20 61 6e 64  ns atoi().** and
32390 20 61 74 6f 66 28 29 2e 20 20 53 51 4c 69 74 65   atof().  SQLite
323a0 20 64 6f 65 73 20 6e 6f 74 20 72 65 61 6c 6c 79   does not really
323b0 20 75 73 65 20 74 68 65 73 65 20 66 75 6e 63 74   use these funct
323c0 69 6f 6e 73 2e 20 20 49 74 20 68 61 73 20 69 74  ions.  It has it
323d0 73 0a 2a 2a 20 6f 77 6e 20 65 71 75 69 76 61 6c  s.** own equival
323e0 65 6e 74 20 69 6e 74 65 72 6e 61 6c 20 72 6f 75  ent internal rou
323f0 74 69 6e 65 73 2e 20 20 54 68 65 20 61 74 6f 69  tines.  The atoi
32400 28 29 20 61 6e 64 20 61 74 6f 66 28 29 20 6e 61  () and atof() na
32410 6d 65 73 20 61 72 65 0a 2a 2a 20 75 73 65 64 20  mes are.** used 
32420 69 6e 20 74 68 65 20 74 61 62 6c 65 20 66 6f 72  in the table for
32430 20 62 72 65 76 69 74 79 20 61 6e 64 20 62 65 63   brevity and bec
32440 61 75 73 65 20 74 68 65 79 20 61 72 65 20 66 61  ause they are fa
32450 6d 69 6c 69 61 72 20 74 6f 20 6d 6f 73 74 0a 2a  miliar to most.*
32460 2a 20 43 20 70 72 6f 67 72 61 6d 6d 65 72 73 2e  * C programmers.
32470 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
32480 20 77 68 65 6e 20 74 79 70 65 20 63 6f 6e 76 65   when type conve
32490 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f  rsions occur, po
324a0 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20  inters returned 
324b0 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c  by prior.** call
324c0 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  s to sqlite3_col
324d0 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69  umn_blob(), sqli
324e0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
324f0 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c  ), and/or.** sql
32500 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
32510 31 36 28 29 20 6d 61 79 20 62 65 20 69 6e 76 61  16() may be inva
32520 6c 69 64 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65  lidated..** Type
32530 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64   conversions and
32540 20 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69 64   pointer invalid
32550 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63  ations might occ
32560 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c  ur.** in the fol
32570 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a  lowing cases:.**
32580 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
32590 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e   The initial con
325a0 74 65 6e 74 20 69 73 20 61 20 42 4c 4f 42 20 61  tent is a BLOB a
325b0 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
325c0 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20  n_text() or.**  
325d0 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75      sqlite3_colu
325e0 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63  mn_text16() is c
325f0 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74  alled.  A zero-t
32600 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a  erminator might.
32610 2a 2a 20 20 20 20 20 20 6e 65 65 64 20 74 6f 20  **      need to 
32620 62 65 20 61 64 64 65 64 20 74 6f 20 74 68 65 20  be added to the 
32630 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20  string.</li>.** 
32640 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c  <li> The initial
32650 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d   content is UTF-
32660 38 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74  8 text and sqlit
32670 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
32680 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73  6() or.**      s
32690 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
326a0 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64  xt16() is called
326b0 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d  .  The content m
326c0 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64  ust be converted
326d0 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d  .**      to UTF-
326e0 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e  16.</li>.** <li>
326f0 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e   The initial con
32700 74 65 6e 74 20 69 73 20 55 54 46 2d 31 36 20 74  tent is UTF-16 t
32710 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  ext and sqlite3_
32720 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f  column_bytes() o
32730 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65  r.**      sqlite
32740 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
32750 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20  is called.  The 
32760 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20  content must be 
32770 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20  converted.**    
32780 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e    to UTF-8.</li>
32790 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
327a0 5e 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65 74  ^Conversions bet
327b0 77 65 65 6e 20 55 54 46 2d 31 36 62 65 20 61 6e  ween UTF-16be an
327c0 64 20 55 54 46 2d 31 36 6c 65 20 61 72 65 20 61  d UTF-16le are a
327d0 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c  lways done in pl
327e0 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f  ace and do.** no
327f0 74 20 69 6e 76 61 6c 69 64 61 74 65 20 61 20 70  t invalidate a p
32800 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74 68  rior pointer, th
32810 6f 75 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74  ough of course t
32820 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
32830 65 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74  e buffer.** that
32840 20 74 68 65 20 70 72 69 6f 72 20 70 6f 69 6e 74   the prior point
32850 65 72 20 72 65 66 65 72 65 6e 63 65 73 20 77 69  er references wi
32860 6c 6c 20 68 61 76 65 20 62 65 65 6e 20 6d 6f 64  ll have been mod
32870 69 66 69 65 64 2e 20 20 4f 74 68 65 72 20 6b 69  ified.  Other ki
32880 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72  nds.** of conver
32890 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e  sion are done in
328a0 20 70 6c 61 63 65 20 77 68 65 6e 20 69 74 20 69   place when it i
328b0 73 20 70 6f 73 73 69 62 6c 65 2c 20 62 75 74 20  s possible, but 
328c0 73 6f 6d 65 74 69 6d 65 73 20 74 68 65 79 0a 2a  sometimes they.*
328d0 2a 20 61 72 65 20 6e 6f 74 20 70 6f 73 73 69 62  * are not possib
328e0 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f 73 65 20  le and in those 
328f0 63 61 73 65 73 20 70 72 69 6f 72 20 70 6f 69 6e  cases prior poin
32900 74 65 72 73 20 61 72 65 20 69 6e 76 61 6c 69 64  ters are invalid
32910 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ated..**.** The 
32920 73 61 66 65 73 74 20 61 6e 64 20 65 61 73 69 65  safest and easie
32930 73 74 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 70  st to remember p
32940 6f 6c 69 63 79 20 69 73 20 74 6f 20 69 6e 76 6f  olicy is to invo
32950 6b 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  ke these routine
32960 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74  s.** in one of t
32970 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79  he following way
32980 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
32990 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f    <li>sqlite3_co
329a0 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c  lumn_text() foll
329b0 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  owed by sqlite3_
329c0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f  column_bytes()</
329d0 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69  li>.**  <li>sqli
329e0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
329f0 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71  ) followed by sq
32a00 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
32a10 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c  es()</li>.**  <l
32a20 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  i>sqlite3_column
32a30 5f 74 65 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77  _text16() follow
32a40 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
32a50 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f  lumn_bytes16()</
32a60 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  li>.** </ul>.**.
32a70 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  ** In other word
32a80 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20 63 61  s, you should ca
32a90 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ll sqlite3_colum
32aa0 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a 20 73 71 6c  n_text(),.** sql
32ab0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
32ac0 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  (), or sqlite3_c
32ad0 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66  olumn_text16() f
32ae0 69 72 73 74 20 74 6f 20 66 6f 72 63 65 20 74 68  irst to force th
32af0 65 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f  e result.** into
32b00 20 74 68 65 20 64 65 73 69 72 65 64 20 66 6f 72   the desired for
32b10 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65  mat, then invoke
32b20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
32b30 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 73 71  bytes() or.** sq
32b40 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
32b50 65 73 31 36 28 29 20 74 6f 20 66 69 6e 64 20 74  es16() to find t
32b60 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 72  he size of the r
32b70 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d  esult.  Do not m
32b80 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73  ix calls.** to s
32b90 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
32ba0 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  xt() or sqlite3_
32bb0 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69  column_blob() wi
32bc0 74 68 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73  th calls to.** s
32bd0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
32be0 74 65 73 31 36 28 29 2c 20 61 6e 64 20 64 6f 20  tes16(), and do 
32bf0 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f  not mix calls to
32c00 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
32c10 74 65 78 74 31 36 28 29 0a 2a 2a 20 77 69 74 68  text16().** with
32c20 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
32c30 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
32c40 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f 69  ..**.** ^The poi
32c50 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 61  nters returned a
32c60 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 61  re valid until a
32c70 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   type conversion
32c80 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20 64 65   occurs as.** de
32c90 73 63 72 69 62 65 64 20 61 62 6f 76 65 2c 20 6f  scribed above, o
32ca0 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33  r until [sqlite3
32cb0 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c  _step()] or [sql
32cc0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
32cd0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  .** [sqlite3_fin
32ce0 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c  alize()] is call
32cf0 65 64 2e 20 20 5e 54 68 65 20 6d 65 6d 6f 72 79  ed.  ^The memory
32d00 20 73 70 61 63 65 20 75 73 65 64 20 74 6f 20 68   space used to h
32d10 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61  old strings.** a
32d20 6e 64 20 42 4c 4f 42 73 20 69 73 20 66 72 65 65  nd BLOBs is free
32d30 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e  d automatically.
32d40 20 20 44 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20    Do <b>not</b> 
32d50 70 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65 72  pass the pointer
32d60 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72  s returned.** fr
32d70 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  om [sqlite3_colu
32d80 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c  mn_blob()], [sql
32d90 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
32da0 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 0a 2a  ()], etc. into.*
32db0 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  * [sqlite3_free(
32dc0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61  )]..**.** ^(If a
32dd0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
32de0 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  on error occurs 
32df0 64 75 72 69 6e 67 20 74 68 65 20 65 76 61 6c 75  during the evalu
32e00 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20  ation of any.** 
32e10 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
32e20 73 2c 20 61 20 64 65 66 61 75 6c 74 20 76 61 6c  s, a default val
32e30 75 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  ue is returned. 
32e40 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c   The default val
32e50 75 65 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20  ue.** is either 
32e60 74 68 65 20 69 6e 74 65 67 65 72 20 30 2c 20 74  the integer 0, t
32e70 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  he floating poin
32e80 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72  t number 0.0, or
32e90 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74   a NULL.** point
32ea0 65 72 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20  er.  Subsequent 
32eb0 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
32ec0 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 77 69 6c  3_errcode()] wil
32ed0 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c  l return.** [SQL
32ee0 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f  ITE_NOMEM].)^.*/
32ef0 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
32f00 74 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53  t void *SQLITE_S
32f10 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63  TDCALL sqlite3_c
32f20 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74  olumn_blob(sqlit
32f30 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
32f40 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  ol);.SQLITE_API 
32f50 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41  int SQLITE_STDCA
32f60 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  LL sqlite3_colum
32f70 6e 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f  n_bytes(sqlite3_
32f80 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
32f90 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
32fa0 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
32fb0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
32fc0 79 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f 73  ytes16(sqlite3_s
32fd0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
32fe0 0a 53 51 4c 49 54 45 5f 41 50 49 20 64 6f 75 62  .SQLITE_API doub
32ff0 6c 65 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  le SQLITE_STDCAL
33000 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  L sqlite3_column
33010 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f  _double(sqlite3_
33020 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
33030 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
33040 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
33050 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69  sqlite3_column_i
33060 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  nt(sqlite3_stmt*
33070 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c  , int iCol);.SQL
33080 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f  ITE_API sqlite3_
33090 69 6e 74 36 34 20 53 51 4c 49 54 45 5f 53 54 44  int64 SQLITE_STD
330a0 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c  CALL sqlite3_col
330b0 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74 65  umn_int64(sqlite
330c0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
330d0 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  l);.SQLITE_API c
330e0 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68  onst unsigned ch
330f0 61 72 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41  ar *SQLITE_STDCA
33100 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  LL sqlite3_colum
33110 6e 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73  n_text(sqlite3_s
33120 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
33130 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
33140 74 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53  t void *SQLITE_S
33150 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63  TDCALL sqlite3_c
33160 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 73 71 6c  olumn_text16(sql
33170 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
33180 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50  iCol);.SQLITE_AP
33190 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  I int SQLITE_STD
331a0 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c  CALL sqlite3_col
331b0 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74 65 33  umn_type(sqlite3
331c0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
331d0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71  );.SQLITE_API sq
331e0 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 53 51 4c  lite3_value *SQL
331f0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
33200 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
33210 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
33220 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a  int iCol);../*.*
33230 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 73 74  * CAPI3REF: Dest
33240 72 6f 79 20 41 20 50 72 65 70 61 72 65 64 20 53  roy A Prepared S
33250 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a  tatement Object.
33260 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
33270 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66 75  e3_finalize() fu
33280 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64  nction is called
33290 20 74 6f 20 64 65 6c 65 74 65 20 61 20 5b 70 72   to delete a [pr
332a0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
332b0 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f  ]..** ^If the mo
332c0 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61  st recent evalua
332d0 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 74 61 74  tion of the stat
332e0 65 6d 65 6e 74 20 65 6e 63 6f 75 6e 74 65 72 65  ement encountere
332f0 64 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f  d no errors.** o
33300 72 20 69 66 20 74 68 65 20 73 74 61 74 65 6d 65  r if the stateme
33310 6e 74 20 69 73 20 6e 65 76 65 72 20 62 65 65 6e  nt is never been
33320 20 65 76 61 6c 75 61 74 65 64 2c 20 74 68 65 6e   evaluated, then
33330 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
33340 65 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 53  e() returns.** S
33350 51 4c 49 54 45 5f 4f 4b 2e 20 20 5e 49 66 20 74  QLITE_OK.  ^If t
33360 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65  he most recent e
33370 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 73 74 61  valuation of sta
33380 74 65 6d 65 6e 74 20 53 20 66 61 69 6c 65 64 2c  tement S failed,
33390 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33   then.** sqlite3
333a0 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 65 74  _finalize(S) ret
333b0 75 72 6e 73 20 74 68 65 20 61 70 70 72 6f 70 72  urns the appropr
333c0 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65  iate [error code
333d0 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65  ] or.** [extende
333e0 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a  d error code]..*
333f0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
33400 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 6f  3_finalize(S) ro
33410 75 74 69 6e 65 20 63 61 6e 20 62 65 20 63 61 6c  utine can be cal
33420 6c 65 64 20 61 74 20 61 6e 79 20 70 6f 69 6e 74  led at any point
33430 20 64 75 72 69 6e 67 0a 2a 2a 20 74 68 65 20 6c   during.** the l
33440 69 66 65 20 63 79 63 6c 65 20 6f 66 20 5b 70 72  ife cycle of [pr
33450 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
33460 5d 20 53 3a 0a 2a 2a 20 62 65 66 6f 72 65 20 73  ] S:.** before s
33470 74 61 74 65 6d 65 6e 74 20 53 20 69 73 20 65 76  tatement S is ev
33480 65 72 20 65 76 61 6c 75 61 74 65 64 2c 20 61 66  er evaluated, af
33490 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f  ter.** one or mo
334a0 72 65 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  re calls to [sql
334b0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 20 6f  ite3_reset()], o
334c0 72 20 61 66 74 65 72 20 61 6e 79 20 63 61 6c 6c  r after any call
334d0 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  .** to [sqlite3_
334e0 73 74 65 70 28 29 5d 20 72 65 67 61 72 64 6c 65  step()] regardle
334f0 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ss of whether or
33500 20 6e 6f 74 20 74 68 65 20 73 74 61 74 65 6d 65   not the stateme
33510 6e 74 20 68 61 73 0a 2a 2a 20 63 6f 6d 70 6c 65  nt has.** comple
33520 74 65 64 20 65 78 65 63 75 74 69 6f 6e 2e 0a 2a  ted execution..*
33530 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b 69 6e 67 20 73  *.** ^Invoking s
33540 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
33550 29 20 6f 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  ) on a NULL poin
33560 74 65 72 20 69 73 20 61 20 68 61 72 6d 6c 65 73  ter is a harmles
33570 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54  s no-op..**.** T
33580 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
33590 75 73 74 20 66 69 6e 61 6c 69 7a 65 20 65 76 65  ust finalize eve
335a0 72 79 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ry [prepared sta
335b0 74 65 6d 65 6e 74 5d 20 69 6e 20 6f 72 64 65 72  tement] in order
335c0 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 72 65 73   to avoid.** res
335d0 6f 75 72 63 65 20 6c 65 61 6b 73 2e 20 20 49 74  ource leaks.  It
335e0 20 69 73 20 61 20 67 72 69 65 76 6f 75 73 20 65   is a grievous e
335f0 72 72 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70  rror for the app
33600 6c 69 63 61 74 69 6f 6e 20 74 6f 20 74 72 79 20  lication to try 
33610 74 6f 20 75 73 65 0a 2a 2a 20 61 20 70 72 65 70  to use.** a prep
33620 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61  ared statement a
33630 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e  fter it has been
33640 20 66 69 6e 61 6c 69 7a 65 64 2e 20 20 41 6e 79   finalized.  Any
33650 20 75 73 65 20 6f 66 20 61 20 70 72 65 70 61 72   use of a prepar
33660 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  ed.** statement 
33670 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65  after it has bee
33680 6e 20 66 69 6e 61 6c 69 7a 65 64 20 63 61 6e 20  n finalized can 
33690 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69  result in undefi
336a0 6e 65 64 20 61 6e 64 0a 2a 2a 20 75 6e 64 65 73  ned and.** undes
336b0 69 72 61 62 6c 65 20 62 65 68 61 76 69 6f 72 20  irable behavior 
336c0 73 75 63 68 20 61 73 20 73 65 67 66 61 75 6c 74  such as segfault
336d0 73 20 61 6e 64 20 68 65 61 70 20 63 6f 72 72 75  s and heap corru
336e0 70 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45  ption..*/.SQLITE
336f0 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f  _API int SQLITE_
33700 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
33710 66 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65 33  finalize(sqlite3
33720 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
33730 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
33740 52 65 73 65 74 20 41 20 50 72 65 70 61 72 65 64  Reset A Prepared
33750 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63   Statement Objec
33760 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  t.**.** The sqli
33770 74 65 33 5f 72 65 73 65 74 28 29 20 66 75 6e 63  te3_reset() func
33780 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74  tion is called t
33790 6f 20 72 65 73 65 74 20 61 20 5b 70 72 65 70 61  o reset a [prepa
337a0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a  red statement].*
337b0 2a 20 6f 62 6a 65 63 74 20 62 61 63 6b 20 74 6f  * object back to
337c0 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61   its initial sta
337d0 74 65 2c 20 72 65 61 64 79 20 74 6f 20 62 65 20  te, ready to be 
337e0 72 65 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a 20  re-executed..** 
337f0 5e 41 6e 79 20 53 51 4c 20 73 74 61 74 65 6d 65  ^Any SQL stateme
33800 6e 74 20 76 61 72 69 61 62 6c 65 73 20 74 68 61  nt variables tha
33810 74 20 68 61 64 20 76 61 6c 75 65 73 20 62 6f 75  t had values bou
33820 6e 64 20 74 6f 20 74 68 65 6d 20 75 73 69 6e 67  nd to them using
33830 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33  .** the [sqlite3
33840 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c  _bind_blob | sql
33850 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 41 50  ite3_bind_*() AP
33860 49 5d 20 72 65 74 61 69 6e 20 74 68 65 69 72 20  I] retain their 
33870 76 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 65 20 5b  values..** Use [
33880 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69  sqlite3_clear_bi
33890 6e 64 69 6e 67 73 28 29 5d 20 74 6f 20 72 65 73  ndings()] to res
338a0 65 74 20 74 68 65 20 62 69 6e 64 69 6e 67 73 2e  et the bindings.
338b0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c  .**.** ^The [sql
338c0 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69  ite3_reset(S)] i
338d0 6e 74 65 72 66 61 63 65 20 72 65 73 65 74 73 20  nterface resets 
338e0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
338f0 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 62 61  atement] S.** ba
33900 63 6b 20 74 6f 20 74 68 65 20 62 65 67 69 6e 6e  ck to the beginn
33910 69 6e 67 20 6f 66 20 69 74 73 20 70 72 6f 67 72  ing of its progr
33920 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  am..**.** ^If th
33930 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61  e most recent ca
33940 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
33950 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a  tep(S)] for the.
33960 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
33970 74 65 6d 65 6e 74 5d 20 53 20 72 65 74 75 72 6e  tement] S return
33980 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20  ed [SQLITE_ROW] 
33990 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  or [SQLITE_DONE]
339a0 2c 0a 2a 2a 20 6f 72 20 69 66 20 5b 73 71 6c 69  ,.** or if [sqli
339b0 74 65 33 5f 73 74 65 70 28 53 29 5d 20 68 61 73  te3_step(S)] has
339c0 20 6e 65 76 65 72 20 62 65 66 6f 72 65 20 62 65   never before be
339d0 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a  en called on S,.
339e0 2a 2a 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33  ** then [sqlite3
339f0 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72  _reset(S)] retur
33a00 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a  ns [SQLITE_OK]..
33a10 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f  **.** ^If the mo
33a20 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74  st recent call t
33a30 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  o [sqlite3_step(
33a40 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b  S)] for the.** [
33a50 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
33a60 6e 74 5d 20 53 20 69 6e 64 69 63 61 74 65 64 20  nt] S indicated 
33a70 61 6e 20 65 72 72 6f 72 2c 20 74 68 65 6e 0a 2a  an error, then.*
33a80 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  * [sqlite3_reset
33a90 28 53 29 5d 20 72 65 74 75 72 6e 73 20 61 6e 20  (S)] returns an 
33aa0 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72  appropriate [err
33ab0 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20  or code]..**.** 
33ac0 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65  ^The [sqlite3_re
33ad0 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63  set(S)] interfac
33ae0 65 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67  e does not chang
33af0 65 20 74 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20  e the values.** 
33b00 6f 66 20 61 6e 79 20 5b 73 71 6c 69 74 65 33 5f  of any [sqlite3_
33b10 62 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e  bind_blob|bindin
33b20 67 73 5d 20 6f 6e 20 74 68 65 20 5b 70 72 65 70  gs] on the [prep
33b30 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
33b40 53 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  S..*/.SQLITE_API
33b50 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43   int SQLITE_STDC
33b60 41 4c 4c 20 73 71 6c 69 74 65 33 5f 72 65 73 65  ALL sqlite3_rese
33b70 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  t(sqlite3_stmt *
33b80 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
33b90 41 50 49 33 52 45 46 3a 20 43 72 65 61 74 65 20  API3REF: Create 
33ba0 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51 4c 20  Or Redefine SQL 
33bb0 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59  Functions.** KEY
33bc0 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e  WORDS: {function
33bd0 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e   creation routin
33be0 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  es}.** KEYWORDS:
33bf0 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   {application-de
33c00 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
33c10 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  on}.** KEYWORDS:
33c20 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   {application-de
33c30 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
33c40 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  ons}.**.** ^Thes
33c50 65 20 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c  e functions (col
33c60 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20  lectively known 
33c70 61 73 20 22 66 75 6e 63 74 69 6f 6e 20 63 72 65  as "function cre
33c80 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29  ation routines")
33c90 0a 2a 2a 20 61 72 65 20 75 73 65 64 20 74 6f 20  .** are used to 
33ca0 61 64 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  add SQL function
33cb0 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 20  s or aggregates 
33cc0 6f 72 20 74 6f 20 72 65 64 65 66 69 6e 65 20 74  or to redefine t
33cd0 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f  he behavior.** o
33ce0 66 20 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66  f existing SQL f
33cf0 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72  unctions or aggr
33d00 65 67 61 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c  egates.  The onl
33d10 79 20 64 69 66 66 65 72 65 6e 63 65 73 20 62 65  y differences be
33d20 74 77 65 65 6e 0a 2a 2a 20 74 68 65 73 65 20 72  tween.** these r
33d30 6f 75 74 69 6e 65 73 20 61 72 65 20 74 68 65 20  outines are the 
33d40 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 65 78  text encoding ex
33d50 70 65 63 74 65 64 20 66 6f 72 0a 2a 2a 20 74 68  pected for.** th
33d60 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
33d70 65 72 20 28 74 68 65 20 6e 61 6d 65 20 6f 66 20  er (the name of 
33d80 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 62 65 69  the function bei
33d90 6e 67 20 63 72 65 61 74 65 64 29 0a 2a 2a 20 61  ng created).** a
33da0 6e 64 20 74 68 65 20 70 72 65 73 65 6e 63 65 20  nd the presence 
33db0 6f 72 20 61 62 73 65 6e 63 65 20 6f 66 20 61 20  or absence of a 
33dc0 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62  destructor callb
33dd0 61 63 6b 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61  ack for.** the a
33de0 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20  pplication data 
33df0 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  pointer..**.** ^
33e00 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
33e10 74 65 72 20 69 73 20 74 68 65 20 5b 64 61 74 61  ter is the [data
33e20 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
33e30 20 74 6f 20 77 68 69 63 68 20 74 68 65 20 53 51   to which the SQ
33e40 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73  L.** function is
33e50 20 74 6f 20 62 65 20 61 64 64 65 64 2e 20 20 5e   to be added.  ^
33e60 49 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  If an applicatio
33e70 6e 20 75 73 65 73 20 6d 6f 72 65 20 74 68 61 6e  n uses more than
33e80 20 6f 6e 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   one database.**
33e90 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 65 6e   connection then
33ea0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
33eb0 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
33ec0 6e 73 20 6d 75 73 74 20 62 65 20 61 64 64 65 64  ns must be added
33ed0 0a 2a 2a 20 74 6f 20 65 61 63 68 20 64 61 74 61  .** to each data
33ee0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
33ef0 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a  separately..**.*
33f00 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61  * ^The second pa
33f10 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e  rameter is the n
33f20 61 6d 65 20 6f 66 20 74 68 65 20 53 51 4c 20 66  ame of the SQL f
33f30 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 63 72  unction to be cr
33f40 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64 65  eated or.** rede
33f50 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 6c 65 6e  fined.  ^The len
33f60 67 74 68 20 6f 66 20 74 68 65 20 6e 61 6d 65 20  gth of the name 
33f70 69 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 32 35  is limited to 25
33f80 35 20 62 79 74 65 73 20 69 6e 20 61 20 55 54 46  5 bytes in a UTF
33f90 2d 38 0a 2a 2a 20 72 65 70 72 65 73 65 6e 74 61  -8.** representa
33fa0 74 69 6f 6e 2c 20 65 78 63 6c 75 73 69 76 65 20  tion, exclusive 
33fb0 6f 66 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d  of the zero-term
33fc0 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f 74 65 20 74  inator.  ^Note t
33fd0 68 61 74 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20  hat the name.** 
33fe0 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20 69 73 20  length limit is 
33ff0 69 6e 20 55 54 46 2d 38 20 62 79 74 65 73 2c 20  in UTF-8 bytes, 
34000 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 20 6e  not characters n
34010 6f 72 20 55 54 46 2d 31 36 20 62 79 74 65 73 2e  or UTF-16 bytes.
34020 20 20 0a 2a 2a 20 5e 41 6e 79 20 61 74 74 65 6d    .** ^Any attem
34030 70 74 20 74 6f 20 63 72 65 61 74 65 20 61 20 66  pt to create a f
34040 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 6c  unction with a l
34050 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69  onger name.** wi
34060 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b 53 51  ll result in [SQ
34070 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 62 65 69  LITE_MISUSE] bei
34080 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  ng returned..**.
34090 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 70 61  ** ^The third pa
340a0 72 61 6d 65 74 65 72 20 28 6e 41 72 67 29 0a 2a  rameter (nArg).*
340b0 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  * is the number 
340c0 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61  of arguments tha
340d0 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  t the SQL functi
340e0 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61  on or.** aggrega
340f0 74 65 20 74 61 6b 65 73 2e 20 5e 49 66 20 74 68  te takes. ^If th
34100 69 73 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  is parameter is 
34110 2d 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c  -1, then the SQL
34120 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20   function or.** 
34130 61 67 67 72 65 67 61 74 65 20 6d 61 79 20 74 61  aggregate may ta
34140 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66  ke any number of
34150 20 61 72 67 75 6d 65 6e 74 73 20 62 65 74 77 65   arguments betwe
34160 65 6e 20 30 20 61 6e 64 20 74 68 65 20 6c 69 6d  en 0 and the lim
34170 69 74 0a 2a 2a 20 73 65 74 20 62 79 20 5b 73 71  it.** set by [sq
34180 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51  lite3_limit]([SQ
34190 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54  LITE_LIMIT_FUNCT
341a0 49 4f 4e 5f 41 52 47 5d 29 2e 20 20 49 66 20 74  ION_ARG]).  If t
341b0 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61  he third.** para
341c0 6d 65 74 65 72 20 69 73 20 6c 65 73 73 20 74 68  meter is less th
341d0 61 6e 20 2d 31 20 6f 72 20 67 72 65 61 74 65 72  an -1 or greater
341e0 20 74 68 61 6e 20 31 32 37 20 74 68 65 6e 20 74   than 127 then t
341f0 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 0a 2a  he behavior is.*
34200 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  * undefined..**.
34210 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70  ** ^The fourth p
34220 61 72 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52  arameter, eTextR
34230 65 70 2c 20 73 70 65 63 69 66 69 65 73 20 77 68  ep, specifies wh
34240 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54  at.** [SQLITE_UT
34250 46 38 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69  F8 | text encodi
34260 6e 67 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e  ng] this SQL fun
34270 63 74 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f  ction prefers fo
34280 72 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74  r.** its paramet
34290 65 72 73 2e 20 20 54 68 65 20 61 70 70 6c 69 63  ers.  The applic
342a0 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 73 65 74  ation should set
342b0 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 20   this parameter 
342c0 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54  to.** [SQLITE_UT
342d0 46 31 36 4c 45 5d 20 69 66 20 74 68 65 20 66 75  F16LE] if the fu
342e0 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
342f0 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 0a 2a  ation invokes .*
34300 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  * [sqlite3_value
34310 5f 74 65 78 74 31 36 6c 65 28 29 5d 20 6f 6e 20  _text16le()] on 
34320 61 6e 20 69 6e 70 75 74 2c 20 6f 72 20 5b 53 51  an input, or [SQ
34330 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 20 69 66  LITE_UTF16BE] if
34340 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e   the.** implemen
34350 74 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 5b  tation invokes [
34360 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
34370 78 74 31 36 62 65 28 29 5d 20 6f 6e 20 61 6e 20  xt16be()] on an 
34380 69 6e 70 75 74 2c 20 6f 72 0a 2a 2a 20 5b 53 51  input, or.** [SQ
34390 4c 49 54 45 5f 55 54 46 31 36 5d 20 69 66 20 5b  LITE_UTF16] if [
343a0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
343b0 78 74 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c  xt16()] is used,
343c0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 38   or [SQLITE_UTF8
343d0 5d 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 2e 20  ].** otherwise. 
343e0 20 5e 54 68 65 20 73 61 6d 65 20 53 51 4c 20 66   ^The same SQL f
343f0 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72  unction may be r
34400 65 67 69 73 74 65 72 65 64 20 6d 75 6c 74 69 70  egistered multip
34410 6c 65 20 74 69 6d 65 73 20 75 73 69 6e 67 0a 2a  le times using.*
34420 2a 20 64 69 66 66 65 72 65 6e 74 20 70 72 65 66  * different pref
34430 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64  erred text encod
34440 69 6e 67 73 2c 20 77 69 74 68 20 64 69 66 66 65  ings, with diffe
34450 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74  rent implementat
34460 69 6f 6e 73 20 66 6f 72 0a 2a 2a 20 65 61 63 68  ions for.** each
34470 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 20 5e 57   encoding..** ^W
34480 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70  hen multiple imp
34490 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20  lementations of 
344a0 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f  the same functio
344b0 6e 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65 2c  n are available,
344c0 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20   SQLite.** will 
344d0 70 69 63 6b 20 74 68 65 20 6f 6e 65 20 74 68 61  pick the one tha
344e0 74 20 69 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c  t involves the l
344f0 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64  east amount of d
34500 61 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a  ata conversion..
34510 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74  **.** ^The fourt
34520 68 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  h parameter may 
34530 6f 70 74 69 6f 6e 61 6c 6c 79 20 62 65 20 4f 52  optionally be OR
34540 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f  ed with [SQLITE_
34550 44 45 54 45 52 4d 49 4e 49 53 54 49 43 5d 0a 2a  DETERMINISTIC].*
34560 2a 20 74 6f 20 73 69 67 6e 61 6c 20 74 68 61 74  * to signal that
34570 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 77 69   the function wi
34580 6c 6c 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  ll always return
34590 20 74 68 65 20 73 61 6d 65 20 72 65 73 75 6c 74   the same result
345a0 20 67 69 76 65 6e 0a 2a 2a 20 74 68 65 20 73 61   given.** the sa
345b0 6d 65 20 69 6e 70 75 74 73 20 77 69 74 68 69 6e  me inputs within
345c0 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74   a single SQL st
345d0 61 74 65 6d 65 6e 74 2e 20 20 4d 6f 73 74 20 53  atement.  Most S
345e0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65  QL functions are
345f0 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 69 73 74 69  .** deterministi
34600 63 2e 20 20 54 68 65 20 62 75 69 6c 74 2d 69 6e  c.  The built-in
34610 20 5b 72 61 6e 64 6f 6d 28 29 5d 20 53 51 4c 20   [random()] SQL 
34620 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 6e 20 65  function is an e
34630 78 61 6d 70 6c 65 20 6f 66 20 61 0a 2a 2a 20 66  xample of a.** f
34640 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 69 73 20  unction that is 
34650 6e 6f 74 20 64 65 74 65 72 6d 69 6e 69 73 74 69  not deterministi
34660 63 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 71  c.  The SQLite q
34670 75 65 72 79 20 70 6c 61 6e 6e 65 72 20 69 73 20  uery planner is 
34680 61 62 6c 65 20 74 6f 0a 2a 2a 20 70 65 72 66 6f  able to.** perfo
34690 72 6d 20 61 64 64 69 74 69 6f 6e 61 6c 20 6f 70  rm additional op
346a0 74 69 6d 69 7a 61 74 69 6f 6e 73 20 6f 6e 20 64  timizations on d
346b0 65 74 65 72 6d 69 6e 69 73 74 69 63 20 66 75 6e  eterministic fun
346c0 63 74 69 6f 6e 73 2c 20 73 6f 20 75 73 65 0a 2a  ctions, so use.*
346d0 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45  * of the [SQLITE
346e0 5f 44 45 54 45 52 4d 49 4e 49 53 54 49 43 5d 20  _DETERMINISTIC] 
346f0 66 6c 61 67 20 69 73 20 72 65 63 6f 6d 6d 65 6e  flag is recommen
34700 64 65 64 20 77 68 65 72 65 20 70 6f 73 73 69 62  ded where possib
34710 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  le..**.** ^(The 
34720 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20  fifth parameter 
34730 69 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 20  is an arbitrary 
34740 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 69 6d  pointer.  The im
34750 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
34760 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  the.** function 
34770 63 61 6e 20 67 61 69 6e 20 61 63 63 65 73 73 20  can gain access 
34780 74 6f 20 74 68 69 73 20 70 6f 69 6e 74 65 72 20  to this pointer 
34790 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75  using [sqlite3_u
347a0 73 65 72 5f 64 61 74 61 28 29 5d 2e 29 5e 0a 2a  ser_data()].)^.*
347b0 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74 68 2c  *.** ^The sixth,
347c0 20 73 65 76 65 6e 74 68 20 61 6e 64 20 65 69 67   seventh and eig
347d0 68 74 68 20 70 61 72 61 6d 65 74 65 72 73 2c 20  hth parameters, 
347e0 78 46 75 6e 63 2c 20 78 53 74 65 70 20 61 6e 64  xFunc, xStep and
347f0 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20   xFinal, are.** 
34800 70 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61  pointers to C-la
34810 6e 67 75 61 67 65 20 66 75 6e 63 74 69 6f 6e 73  nguage functions
34820 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20   that implement 
34830 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
34840 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65   or.** aggregate
34850 2e 20 5e 41 20 73 63 61 6c 61 72 20 53 51 4c 20  . ^A scalar SQL 
34860 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65  function require
34870 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  s an implementat
34880 69 6f 6e 20 6f 66 20 74 68 65 20 78 46 75 6e 63  ion of the xFunc
34890 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c  .** callback onl
348a0 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73  y; NULL pointers
348b0 20 6d 75 73 74 20 62 65 20 70 61 73 73 65 64 20   must be passed 
348c0 61 73 20 74 68 65 20 78 53 74 65 70 20 61 6e 64  as the xStep and
348d0 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d   xFinal.** param
348e0 65 74 65 72 73 2e 20 5e 41 6e 20 61 67 67 72 65  eters. ^An aggre
348f0 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  gate SQL functio
34900 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d  n requires an im
34910 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
34920 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69  xStep.** and xFi
34930 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 70 6f 69  nal and NULL poi
34940 6e 74 65 72 20 6d 75 73 74 20 62 65 20 70 61 73  nter must be pas
34950 73 65 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 5e  sed for xFunc. ^
34960 54 6f 20 64 65 6c 65 74 65 20 61 6e 20 65 78 69  To delete an exi
34970 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e  sting.** SQL fun
34980 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61  ction or aggrega
34990 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20 70 6f  te, pass NULL po
349a0 69 6e 74 65 72 73 20 66 6f 72 20 61 6c 6c 20 74  inters for all t
349b0 68 72 65 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  hree function.**
349c0 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a   callbacks..**.*
349d0 2a 20 5e 28 49 66 20 74 68 65 20 6e 69 6e 74 68  * ^(If the ninth
349e0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
349f0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
34a00 63 74 69 6f 6e 5f 76 32 28 29 20 69 73 20 6e 6f  ction_v2() is no
34a10 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e 20  t NULL,.** then 
34a20 69 74 20 69 73 20 64 65 73 74 72 75 63 74 6f 72  it is destructor
34a30 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61   for the applica
34a40 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65  tion data pointe
34a50 72 2e 20 0a 2a 2a 20 54 68 65 20 64 65 73 74 72  r. .** The destr
34a60 75 63 74 6f 72 20 69 73 20 69 6e 76 6f 6b 65 64  uctor is invoked
34a70 20 77 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69   when the functi
34a80 6f 6e 20 69 73 20 64 65 6c 65 74 65 64 2c 20 65  on is deleted, e
34a90 69 74 68 65 72 20 62 79 20 62 65 69 6e 67 0a 2a  ither by being.*
34aa0 2a 20 6f 76 65 72 6c 6f 61 64 65 64 20 6f 72 20  * overloaded or 
34ab0 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  when the databas
34ac0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f  e connection clo
34ad0 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 64  ses.)^.** ^The d
34ae0 65 73 74 72 75 63 74 6f 72 20 69 73 20 61 6c 73  estructor is als
34af0 6f 20 69 6e 76 6f 6b 65 64 20 69 66 20 74 68 65  o invoked if the
34b00 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69   call to.** sqli
34b10 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
34b20 69 6f 6e 5f 76 32 28 29 20 66 61 69 6c 73 2e 0a  ion_v2() fails..
34b30 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 64 65 73  ** ^When the des
34b40 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b  tructor callback
34b50 20 6f 66 20 74 68 65 20 74 65 6e 74 68 20 70 61   of the tenth pa
34b60 72 61 6d 65 74 65 72 20 69 73 20 69 6e 76 6f 6b  rameter is invok
34b70 65 64 2c 20 69 74 0a 2a 2a 20 69 73 20 70 61 73  ed, it.** is pas
34b80 73 65 64 20 61 20 73 69 6e 67 6c 65 20 61 72 67  sed a single arg
34b90 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
34ba0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 61 70 70   copy of the app
34bb0 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 0a 2a  lication data .*
34bc0 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 20  * pointer which 
34bd0 77 61 73 20 74 68 65 20 66 69 66 74 68 20 70 61  was the fifth pa
34be0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
34bf0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
34c00 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  on_v2()..**.** ^
34c10 49 74 20 69 73 20 70 65 72 6d 69 74 74 65 64 20  It is permitted 
34c20 74 6f 20 72 65 67 69 73 74 65 72 20 6d 75 6c 74  to register mult
34c30 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  iple implementat
34c40 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
34c50 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77 69  .** functions wi
34c60 74 68 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65  th the same name
34c70 20 62 75 74 20 77 69 74 68 20 65 69 74 68 65 72   but with either
34c80 20 64 69 66 66 65 72 69 6e 67 20 6e 75 6d 62 65   differing numbe
34c90 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e  rs of.** argumen
34ca0 74 73 20 6f 72 20 64 69 66 66 65 72 69 6e 67 20  ts or differing 
34cb0 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65  preferred text e
34cc0 6e 63 6f 64 69 6e 67 73 2e 20 20 5e 53 51 4c 69  ncodings.  ^SQLi
34cd0 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74  te will use.** t
34ce0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
34cf0 6e 20 74 68 61 74 20 6d 6f 73 74 20 63 6c 6f 73  n that most clos
34d00 65 6c 79 20 6d 61 74 63 68 65 73 20 74 68 65 20  ely matches the 
34d10 77 61 79 20 69 6e 20 77 68 69 63 68 20 74 68 65  way in which the
34d20 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  .** SQL function
34d30 20 69 73 20 75 73 65 64 2e 20 20 5e 41 20 66 75   is used.  ^A fu
34d40 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
34d50 61 74 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e  ation with a non
34d60 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20 6e 41 72  -negative.** nAr
34d70 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  g parameter is a
34d80 20 62 65 74 74 65 72 20 6d 61 74 63 68 20 74 68   better match th
34d90 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 69 6d  an a function im
34da0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74  plementation wit
34db0 68 0a 2a 2a 20 61 20 6e 65 67 61 74 69 76 65 20  h.** a negative 
34dc0 6e 41 72 67 2e 20 20 5e 41 20 66 75 6e 63 74 69  nArg.  ^A functi
34dd0 6f 6e 20 77 68 65 72 65 20 74 68 65 20 70 72 65  on where the pre
34de0 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f  ferred text enco
34df0 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73 20  ding.** matches 
34e00 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 63  the database enc
34e10 6f 64 69 6e 67 20 69 73 20 61 20 62 65 74 74 65  oding is a bette
34e20 72 0a 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e 20  r.** match than 
34e30 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65  a function where
34e40 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 69 73   the encoding is
34e50 20 64 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a 2a   different.  .**
34e60 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65   ^A function whe
34e70 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  re the encoding 
34e80 64 69 66 66 65 72 65 6e 63 65 20 69 73 20 62 65  difference is be
34e90 74 77 65 65 6e 20 55 54 46 31 36 6c 65 20 61 6e  tween UTF16le an
34ea0 64 20 55 54 46 31 36 62 65 0a 2a 2a 20 69 73 20  d UTF16be.** is 
34eb0 61 20 63 6c 6f 73 65 72 20 6d 61 74 63 68 20 74  a closer match t
34ec0 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77  han a function w
34ed0 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e  here the encodin
34ee0 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 0a  g difference is.
34ef0 2a 2a 20 62 65 74 77 65 65 6e 20 55 54 46 38 20  ** between UTF8 
34f00 61 6e 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a  and UTF16..**.**
34f10 20 5e 42 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74   ^Built-in funct
34f20 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f 76 65 72  ions may be over
34f30 6c 6f 61 64 65 64 20 62 79 20 6e 65 77 20 61 70  loaded by new ap
34f40 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
34f50 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a  d functions..**.
34f60 2a 2a 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69  ** ^An applicati
34f70 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
34f80 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64  ion is permitted
34f90 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65 72 0a 2a   to call other.*
34fa0 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  * SQLite interfa
34fb0 63 65 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 73  ces.  However, s
34fc0 75 63 68 20 63 61 6c 6c 73 20 6d 75 73 74 20 6e  uch calls must n
34fd0 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 65 20  ot.** close the 
34fe0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
34ff0 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 7a 65  ion nor finalize
35000 20 6f 72 20 72 65 73 65 74 20 74 68 65 20 70 72   or reset the pr
35010 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d  epared.** statem
35020 65 6e 74 20 69 6e 20 77 68 69 63 68 20 74 68 65  ent in which the
35030 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
35040 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  ning..*/.SQLITE_
35050 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  API int SQLITE_S
35060 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63  TDCALL sqlite3_c
35070 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 0a  reate_function(.
35080 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20    sqlite3 *db,. 
35090 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75   const char *zFu
350a0 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e  nctionName,.  in
350b0 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54  t nArg,.  int eT
350c0 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a  extRep,.  void *
350d0 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78  pApp,.  void (*x
350e0 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f  Func)(sqlite3_co
350f0 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
35100 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
35110 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c  oid (*xStep)(sql
35120 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
35130 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
35140 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69  *),.  void (*xFi
35150 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  nal)(sqlite3_con
35160 74 65 78 74 2a 29 0a 29 3b 0a 53 51 4c 49 54 45  text*).);.SQLITE
35170 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f  _API int SQLITE_
35180 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
35190 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
351a0 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  6(.  sqlite3 *db
351b0 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  ,.  const void *
351c0 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20  zFunctionName,. 
351d0 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74   int nArg,.  int
351e0 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69   eTextRep,.  voi
351f0 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20  d *pApp,.  void 
35200 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33  (*xFunc)(sqlite3
35210 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
35220 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
35230 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28    void (*xStep)(
35240 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
35250 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
35260 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
35270 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f  xFinal)(sqlite3_
35280 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 53 51 4c  context*).);.SQL
35290 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49  ITE_API int SQLI
352a0 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
352b0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
352c0 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  on_v2(.  sqlite3
352d0 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68   *db,.  const ch
352e0 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d  ar *zFunctionNam
352f0 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20  e,.  int nArg,. 
35300 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20   int eTextRep,. 
35310 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76   void *pApp,.  v
35320 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c  oid (*xFunc)(sql
35330 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
35340 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
35350 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74  *),.  void (*xSt
35360 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ep)(sqlite3_cont
35370 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
35380 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
35390 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69  d (*xFinal)(sqli
353a0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 2c 0a 20  te3_context*),. 
353b0 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29   void(*xDestroy)
353c0 28 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a  (void*).);../*.*
353d0 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 78 74  * CAPI3REF: Text
353e0 20 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a   Encodings.**.**
353f0 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 20   These constant 
35400 64 65 66 69 6e 65 20 69 6e 74 65 67 65 72 20 63  define integer c
35410 6f 64 65 73 20 74 68 61 74 20 72 65 70 72 65 73  odes that repres
35420 65 6e 74 20 74 68 65 20 76 61 72 69 6f 75 73 0a  ent the various.
35430 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  ** text encoding
35440 73 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53  s supported by S
35450 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e  QLite..*/.#defin
35460 65 20 53 51 4c 49 54 45 5f 55 54 46 38 20 20 20  e SQLITE_UTF8   
35470 20 20 20 20 20 20 20 20 31 20 20 20 20 2f 2a 20          1    /* 
35480 49 4d 50 3a 20 52 2d 33 37 35 31 34 2d 33 35 35  IMP: R-37514-355
35490 36 36 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  66 */.#define SQ
354a0 4c 49 54 45 5f 55 54 46 31 36 4c 45 20 20 20 20  LITE_UTF16LE    
354b0 20 20 20 20 32 20 20 20 20 2f 2a 20 49 4d 50 3a      2    /* IMP:
354c0 20 52 2d 30 33 33 37 31 2d 33 37 36 33 37 20 2a   R-03371-37637 *
354d0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
354e0 5f 55 54 46 31 36 42 45 20 20 20 20 20 20 20 20  _UTF16BE        
354f0 33 20 20 20 20 2f 2a 20 49 4d 50 3a 20 52 2d 35  3    /* IMP: R-5
35500 31 39 37 31 2d 33 34 31 35 34 20 2a 2f 0a 23 64  1971-34154 */.#d
35510 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46  efine SQLITE_UTF
35520 31 36 20 20 20 20 20 20 20 20 20 20 34 20 20 20  16          4   
35530 20 2f 2a 20 55 73 65 20 6e 61 74 69 76 65 20 62   /* Use native b
35540 79 74 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65  yte order */.#de
35550 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59 20  fine SQLITE_ANY 
35560 20 20 20 20 20 20 20 20 20 20 20 35 20 20 20 20             5    
35570 2f 2a 20 44 65 70 72 65 63 61 74 65 64 20 2a 2f  /* Deprecated */
35580 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
35590 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 20 20 38  UTF16_ALIGNED  8
355a0 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63      /* sqlite3_c
355b0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20  reate_collation 
355c0 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  only */../*.** C
355d0 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f  API3REF: Functio
355e0 6e 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 54 68  n Flags.**.** Th
355f0 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 6d 61  ese constants ma
35600 79 20 62 65 20 4f 52 65 64 20 74 6f 67 65 74 68  y be ORed togeth
35610 65 72 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20  er with the .** 
35620 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 70  [SQLITE_UTF8 | p
35630 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e  referred text en
35640 63 6f 64 69 6e 67 5d 20 61 73 20 74 68 65 20 66  coding] as the f
35650 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a  ourth argument.*
35660 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72  * to [sqlite3_cr
35670 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
35680 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  , [sqlite3_creat
35690 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 2c  e_function16()],
356a0 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
356b0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f  create_function_
356c0 76 32 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e  v2()]..*/.#defin
356d0 65 20 53 51 4c 49 54 45 5f 44 45 54 45 52 4d 49  e SQLITE_DETERMI
356e0 4e 49 53 54 49 43 20 20 20 20 30 78 38 30 30 0a  NISTIC    0x800.
356f0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
35700 20 44 65 70 72 65 63 61 74 65 64 20 46 75 6e 63   Deprecated Func
35710 74 69 6f 6e 73 0a 2a 2a 20 44 45 50 52 45 43 41  tions.** DEPRECA
35720 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  TED.**.** These 
35730 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 5b 64  functions are [d
35740 65 70 72 65 63 61 74 65 64 5d 2e 20 20 49 6e 20  eprecated].  In 
35750 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e 74 61 69  order to maintai
35760 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63  n.** backwards c
35770 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 77 69 74  ompatibility wit
35780 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20 74 68  h older code, th
35790 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 63 6f  ese functions co
357a0 6e 74 69 6e 75 65 20 0a 2a 2a 20 74 6f 20 62 65  ntinue .** to be
357b0 20 73 75 70 70 6f 72 74 65 64 2e 20 20 48 6f 77   supported.  How
357c0 65 76 65 72 2c 20 6e 65 77 20 61 70 70 6c 69 63  ever, new applic
357d0 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 61 76  ations should av
357e0 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f  oid.** the use o
357f0 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  f these function
35800 73 2e 20 20 54 6f 20 65 6e 63 6f 75 72 61 67 65  s.  To encourage
35810 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 74 6f 20   programmers to 
35820 61 76 6f 69 64 0a 2a 2a 20 74 68 65 73 65 20 66  avoid.** these f
35830 75 6e 63 74 69 6f 6e 73 2c 20 77 65 20 77 69 6c  unctions, we wil
35840 6c 20 6e 6f 74 20 65 78 70 6c 61 69 6e 20 77 68  l not explain wh
35850 61 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a 23  at they do..*/.#
35860 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d  ifndef SQLITE_OM
35870 49 54 5f 44 45 50 52 45 43 41 54 45 44 0a 53 51  IT_DEPRECATED.SQ
35880 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f  LITE_API SQLITE_
35890 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 53  DEPRECATED int S
358a0 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
358b0 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
358c0 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f  count(sqlite3_co
358d0 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f  ntext*);.SQLITE_
358e0 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45  API SQLITE_DEPRE
358f0 43 41 54 45 44 20 69 6e 74 20 53 51 4c 49 54 45  CATED int SQLITE
35900 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
35910 5f 65 78 70 69 72 65 64 28 73 71 6c 69 74 65 33  _expired(sqlite3
35920 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f  _stmt*);.SQLITE_
35930 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45  API SQLITE_DEPRE
35940 43 41 54 45 44 20 69 6e 74 20 53 51 4c 49 54 45  CATED int SQLITE
35950 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
35960 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e 64 69 6e  _transfer_bindin
35970 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  gs(sqlite3_stmt*
35980 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  , sqlite3_stmt*)
35990 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c  ;.SQLITE_API SQL
359a0 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69  ITE_DEPRECATED i
359b0 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  nt SQLITE_STDCAL
359c0 4c 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c  L sqlite3_global
359d0 5f 72 65 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a  _recover(void);.
359e0 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54  SQLITE_API SQLIT
359f0 45 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f 69  E_DEPRECATED voi
35a00 64 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  d SQLITE_STDCALL
35a10 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 5f   sqlite3_thread_
35a20 63 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a 53  cleanup(void);.S
35a30 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45  QLITE_API SQLITE
35a40 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20  _DEPRECATED int 
35a50 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
35a60 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c  qlite3_memory_al
35a70 61 72 6d 28 76 6f 69 64 28 2a 29 28 76 6f 69 64  arm(void(*)(void
35a80 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c  *,sqlite3_int64,
35a90 69 6e 74 29 2c 0a 20 20 20 20 20 20 20 20 20 20  int),.          
35aa0 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64              void
35ab0 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29  *,sqlite3_int64)
35ac0 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20  ;.#endif../*.** 
35ad0 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e  CAPI3REF: Obtain
35ae0 69 6e 67 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e  ing SQL Function
35af0 20 50 61 72 61 6d 65 74 65 72 20 56 61 6c 75 65   Parameter Value
35b00 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c 61  s.**.** The C-la
35b10 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e 74  nguage implement
35b20 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75 6e  ation of SQL fun
35b30 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65  ctions and aggre
35b40 67 61 74 65 73 20 75 73 65 73 0a 2a 2a 20 74 68  gates uses.** th
35b50 69 73 20 73 65 74 20 6f 66 20 69 6e 74 65 72 66  is set of interf
35b60 61 63 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  ace routines to 
35b70 61 63 63 65 73 73 20 74 68 65 20 70 61 72 61 6d  access the param
35b80 65 74 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a 2a  eter values on.*
35b90 2a 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 6f  * the function o
35ba0 72 20 61 67 67 72 65 67 61 74 65 2e 0a 2a 2a 0a  r aggregate..**.
35bb0 2a 2a 20 54 68 65 20 78 46 75 6e 63 20 28 66 6f  ** The xFunc (fo
35bc0 72 20 73 63 61 6c 61 72 20 66 75 6e 63 74 69 6f  r scalar functio
35bd0 6e 73 29 20 6f 72 20 78 53 74 65 70 20 28 66 6f  ns) or xStep (fo
35be0 72 20 61 67 67 72 65 67 61 74 65 73 29 20 70 61  r aggregates) pa
35bf0 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 5b  rameters.** to [
35c00 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
35c10 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b  unction()] and [
35c20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
35c30 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20  unction16()].** 
35c40 64 65 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b 73  define callbacks
35c50 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20   that implement 
35c60 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
35c70 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73  s and aggregates
35c80 2e 0a 2a 2a 20 54 68 65 20 33 72 64 20 70 61 72  ..** The 3rd par
35c90 61 6d 65 74 65 72 20 74 6f 20 74 68 65 73 65 20  ameter to these 
35ca0 63 61 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e 20  callbacks is an 
35cb0 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72  array of pointer
35cc0 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63 74  s to.** [protect
35cd0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
35ce0 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54 68 65 72  ] objects.  Ther
35cf0 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74 65  e is one [sqlite
35d00 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
35d10 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61 72 61  for.** each para
35d20 6d 65 74 65 72 20 74 6f 20 74 68 65 20 53 51 4c  meter to the SQL
35d30 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65 73   function.  Thes
35d40 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75  e routines are u
35d50 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61 63  sed to.** extrac
35d60 74 20 76 61 6c 75 65 73 20 66 72 6f 6d 20 74 68  t values from th
35d70 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
35d80 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a  ] objects..**.**
35d90 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
35da0 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 68 20 5b  work only with [
35db0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
35dc0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73  3_value] objects
35dd0 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74  ..** Any attempt
35de0 20 74 6f 20 75 73 65 20 74 68 65 73 65 20 72 6f   to use these ro
35df0 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20 5b 75 6e  utines on an [un
35e00 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
35e10 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65  3_value].** obje
35e20 63 74 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e  ct results in un
35e30 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72  defined behavior
35e40 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  ..**.** ^These r
35e50 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75 73  outines work jus
35e60 74 20 6c 69 6b 65 20 74 68 65 20 63 6f 72 72 65  t like the corre
35e70 73 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e  sponding [column
35e80 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e   access function
35e90 73 5d 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61  s].** except tha
35ea0 74 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  t these routines
35eb0 20 74 61 6b 65 20 61 20 73 69 6e 67 6c 65 20 5b   take a single [
35ec0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
35ed0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a  3_value] object.
35ee0 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 73 74 65  ** pointer inste
35ef0 61 64 20 6f 66 20 61 20 5b 73 71 6c 69 74 65 33  ad of a [sqlite3
35f00 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 20  _stmt*] pointer 
35f10 61 6e 64 20 61 6e 20 69 6e 74 65 67 65 72 20 63  and an integer c
35f20 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a  olumn number..**
35f30 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
35f40 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 20  _value_text16() 
35f50 69 6e 74 65 72 66 61 63 65 20 65 78 74 72 61 63  interface extrac
35f60 74 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69  ts a UTF-16 stri
35f70 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74  ng.** in the nat
35f80 69 76 65 20 62 79 74 65 2d 6f 72 64 65 72 20 6f  ive byte-order o
35f90 66 20 74 68 65 20 68 6f 73 74 20 6d 61 63 68 69  f the host machi
35fa0 6e 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c  ne.  ^The.** sql
35fb0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
35fc0 36 62 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  6be() and sqlite
35fd0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65  3_value_text16le
35fe0 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  () interfaces.**
35ff0 20 65 78 74 72 61 63 74 20 55 54 46 2d 31 36 20   extract UTF-16 
36000 73 74 72 69 6e 67 73 20 61 73 20 62 69 67 2d 65  strings as big-e
36010 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74 74 6c 65  ndian and little
36020 2d 65 6e 64 69 61 6e 20 72 65 73 70 65 63 74 69  -endian respecti
36030 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  vely..**.** ^(Th
36040 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  e sqlite3_value_
36050 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 29 20 69  numeric_type() i
36060 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74  nterface attempt
36070 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75  s to apply.** nu
36080 6d 65 72 69 63 20 61 66 66 69 6e 69 74 79 20 74  meric affinity t
36090 6f 20 74 68 65 20 76 61 6c 75 65 2e 20 20 54 68  o the value.  Th
360a0 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6e  is means that an
360b0 20 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d   attempt is.** m
360c0 61 64 65 20 74 6f 20 63 6f 6e 76 65 72 74 20 74  ade to convert t
360d0 68 65 20 76 61 6c 75 65 20 74 6f 20 61 6e 20 69  he value to an i
360e0 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f 61 74 69  nteger or floati
360f0 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a  ng point.  If.**
36100 20 73 75 63 68 20 61 20 63 6f 6e 76 65 72 73 69   such a conversi
36110 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c 65 20 77  on is possible w
36120 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69  ithout loss of i
36130 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f  nformation (in o
36140 74 68 65 72 0a 2a 2a 20 77 6f 72 64 73 2c 20 69  ther.** words, i
36150 66 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 61  f the value is a
36160 20 73 74 72 69 6e 67 20 74 68 61 74 20 6c 6f 6f   string that loo
36170 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62 65 72  ks like a number
36180 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 6f  ).** then the co
36190 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 65 72 66  nversion is perf
361a0 6f 72 6d 65 64 2e 20 20 4f 74 68 65 72 77 69 73  ormed.  Otherwis
361b0 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f 6e 20  e no conversion 
361c0 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 68 65 20 5b  occurs..** The [
361d0 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c  SQLITE_INTEGER |
361e0 20 64 61 74 61 74 79 70 65 5d 20 61 66 74 65 72   datatype] after
361f0 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 72   conversion is r
36200 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a  eturned.)^.**.**
36210 20 50 6c 65 61 73 65 20 70 61 79 20 70 61 72 74   Please pay part
36220 69 63 75 6c 61 72 20 61 74 74 65 6e 74 69 6f 6e  icular attention
36230 20 74 6f 20 74 68 65 20 66 61 63 74 20 74 68 61   to the fact tha
36240 74 20 74 68 65 20 70 6f 69 6e 74 65 72 20 72 65  t the pointer re
36250 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  turned.** from [
36260 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c  sqlite3_value_bl
36270 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  ob()], [sqlite3_
36280 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f  value_text()], o
36290 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61  r.** [sqlite3_va
362a0 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 20 63 61  lue_text16()] ca
362b0 6e 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64  n be invalidated
362c0 20 62 79 20 61 20 73 75 62 73 65 71 75 65 6e 74   by a subsequent
362d0 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
362e0 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
362f0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61  ()], [sqlite3_va
36300 6c 75 65 5f 62 79 74 65 73 31 36 28 29 5d 2c 20  lue_bytes16()], 
36310 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
36320 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73  ext()],.** or [s
36330 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
36340 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  t16()]..**.** Th
36350 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73  ese routines mus
36360 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  t be called from
36370 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
36380 20 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66   as.** the SQL f
36390 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 73 75 70  unction that sup
363a0 70 6c 69 65 64 20 74 68 65 20 5b 73 71 6c 69 74  plied the [sqlit
363b0 65 33 5f 76 61 6c 75 65 2a 5d 20 70 61 72 61 6d  e3_value*] param
363c0 65 74 65 72 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45  eters..*/.SQLITE
363d0 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20  _API const void 
363e0 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20  *SQLITE_STDCALL 
363f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c  sqlite3_value_bl
36400 6f 62 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ob(sqlite3_value
36410 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  *);.SQLITE_API i
36420 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  nt SQLITE_STDCAL
36430 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  L sqlite3_value_
36440 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 76 61  bytes(sqlite3_va
36450 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  lue*);.SQLITE_AP
36460 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  I int SQLITE_STD
36470 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c  CALL sqlite3_val
36480 75 65 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74  ue_bytes16(sqlit
36490 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49  e3_value*);.SQLI
364a0 54 45 5f 41 50 49 20 64 6f 75 62 6c 65 20 53 51  TE_API double SQ
364b0 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
364c0 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c  ite3_value_doubl
364d0 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
364e0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
364f0 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
36500 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69   sqlite3_value_i
36510 6e 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt(sqlite3_value
36520 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73  *);.SQLITE_API s
36530 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 53 51 4c  qlite3_int64 SQL
36540 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
36550 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28  te3_value_int64(
36560 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
36570 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
36580 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20  t unsigned char 
36590 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20  *SQLITE_STDCALL 
365a0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
365b0 78 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  xt(sqlite3_value
365c0 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  *);.SQLITE_API c
365d0 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51 4c 49 54  onst void *SQLIT
365e0 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
365f0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 73  3_value_text16(s
36600 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
36610 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
36620 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54   void *SQLITE_ST
36630 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61  DCALL sqlite3_va
36640 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 73 71 6c  lue_text16le(sql
36650 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51  ite3_value*);.SQ
36660 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76  LITE_API const v
36670 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43  oid *SQLITE_STDC
36680 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ALL sqlite3_valu
36690 65 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 74  e_text16be(sqlit
366a0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49  e3_value*);.SQLI
366b0 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54  TE_API int SQLIT
366c0 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
366d0 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 73 71 6c  3_value_type(sql
366e0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51  ite3_value*);.SQ
366f0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c  LITE_API int SQL
36700 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
36710 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69  te3_value_numeri
36720 63 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76  c_type(sqlite3_v
36730 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  alue*);../*.** C
36740 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20  API3REF: Obtain 
36750 41 67 67 72 65 67 61 74 65 20 46 75 6e 63 74 69  Aggregate Functi
36760 6f 6e 20 43 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a  on Context.**.**
36770 20 49 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   Implementations
36780 20 6f 66 20 61 67 67 72 65 67 61 74 65 20 53 51   of aggregate SQ
36790 4c 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 20  L functions use 
367a0 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  this.** routine 
367b0 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f  to allocate memo
367c0 72 79 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 74  ry for storing t
367d0 68 65 69 72 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a  heir state..**.*
367e0 2a 20 5e 54 68 65 20 66 69 72 73 74 20 74 69 6d  * ^The first tim
367f0 65 20 74 68 65 20 73 71 6c 69 74 65 33 5f 61 67  e the sqlite3_ag
36800 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
36810 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20 69 73 20  C,N) routine is 
36820 63 61 6c 6c 65 64 20 0a 2a 2a 20 66 6f 72 20 61  called .** for a
36830 20 70 61 72 74 69 63 75 6c 61 72 20 61 67 67 72   particular aggr
36840 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 2c 20  egate function, 
36850 53 51 4c 69 74 65 0a 2a 2a 20 61 6c 6c 6f 63 61  SQLite.** alloca
36860 74 65 73 20 4e 20 6f 66 20 6d 65 6d 6f 72 79 2c  tes N of memory,
36870 20 7a 65 72 6f 65 73 20 6f 75 74 20 74 68 61 74   zeroes out that
36880 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74   memory, and ret
36890 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a  urns a pointer.*
368a0 2a 20 74 6f 20 74 68 65 20 6e 65 77 20 6d 65 6d  * to the new mem
368b0 6f 72 79 2e 20 5e 4f 6e 20 73 65 63 6f 6e 64 20  ory. ^On second 
368c0 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20 63  and subsequent c
368d0 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  alls to.** sqlit
368e0 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
368f0 74 65 78 74 28 29 20 66 6f 72 20 74 68 65 20 73  text() for the s
36900 61 6d 65 20 61 67 67 72 65 67 61 74 65 20 66 75  ame aggregate fu
36910 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 2c  nction instance,
36920 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 62 75 66  .** the same buf
36930 66 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  fer is returned.
36940 20 20 53 71 6c 69 74 65 33 5f 61 67 67 72 65 67    Sqlite3_aggreg
36950 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 69 73  ate_context() is
36960 20 6e 6f 72 6d 61 6c 6c 79 0a 2a 2a 20 63 61 6c   normally.** cal
36970 6c 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 63  led once for eac
36980 68 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20  h invocation of 
36990 74 68 65 20 78 53 74 65 70 20 63 61 6c 6c 62 61  the xStep callba
369a0 63 6b 20 61 6e 64 20 74 68 65 6e 20 6f 6e 65 0a  ck and then one.
369b0 2a 2a 20 6c 61 73 74 20 74 69 6d 65 20 77 68 65  ** last time whe
369c0 6e 20 74 68 65 20 78 46 69 6e 61 6c 20 63 61 6c  n the xFinal cal
369d0 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
369e0 2e 20 20 5e 28 57 68 65 6e 20 6e 6f 20 72 6f 77  .  ^(When no row
369f0 73 20 6d 61 74 63 68 0a 2a 2a 20 61 6e 20 61 67  s match.** an ag
36a00 67 72 65 67 61 74 65 20 71 75 65 72 79 2c 20 74  gregate query, t
36a10 68 65 20 78 53 74 65 70 28 29 20 63 61 6c 6c 62  he xStep() callb
36a20 61 63 6b 20 6f 66 20 74 68 65 20 61 67 67 72 65  ack of the aggre
36a30 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  gate function.**
36a40 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
36a50 69 73 20 6e 65 76 65 72 20 63 61 6c 6c 65 64 20  is never called 
36a60 61 6e 64 20 78 46 69 6e 61 6c 28 29 20 69 73 20  and xFinal() is 
36a70 63 61 6c 6c 65 64 20 65 78 61 63 74 6c 79 20 6f  called exactly o
36a80 6e 63 65 2e 0a 2a 2a 20 49 6e 20 74 68 6f 73 65  nce..** In those
36a90 20 63 61 73 65 73 2c 20 73 71 6c 69 74 65 33 5f   cases, sqlite3_
36aa0 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
36ab0 74 28 29 20 6d 69 67 68 74 20 62 65 20 63 61 6c  t() might be cal
36ac0 6c 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 66  led for the.** f
36ad0 69 72 73 74 20 74 69 6d 65 20 66 72 6f 6d 20 77  irst time from w
36ae0 69 74 68 69 6e 20 78 46 69 6e 61 6c 28 29 2e 29  ithin xFinal().)
36af0 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ^.**.** ^The sql
36b00 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
36b10 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74  ontext(C,N) rout
36b20 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 4e 55  ine returns a NU
36b30 4c 4c 20 70 6f 69 6e 74 65 72 20 0a 2a 2a 20 77  LL pointer .** w
36b40 68 65 6e 20 66 69 72 73 74 20 63 61 6c 6c 65 64  hen first called
36b50 20 69 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68   if N is less th
36b60 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a  an or equal to z
36b70 65 72 6f 20 6f 72 20 69 66 20 61 20 6d 65 6d 6f  ero or if a memo
36b80 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 65  ry.** allocate e
36b90 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a  rror occurs..**.
36ba0 2a 2a 20 5e 28 54 68 65 20 61 6d 6f 75 6e 74 20  ** ^(The amount 
36bb0 6f 66 20 73 70 61 63 65 20 61 6c 6c 6f 63 61 74  of space allocat
36bc0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 61 67  ed by sqlite3_ag
36bd0 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
36be0 43 2c 4e 29 20 69 73 0a 2a 2a 20 64 65 74 65 72  C,N) is.** deter
36bf0 6d 69 6e 65 64 20 62 79 20 74 68 65 20 4e 20 70  mined by the N p
36c00 61 72 61 6d 65 74 65 72 20 6f 6e 20 66 69 72 73  arameter on firs
36c10 74 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  t successful cal
36c20 6c 2e 20 20 43 68 61 6e 67 69 6e 67 20 74 68 65  l.  Changing the
36c30 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 4e 20 69  .** value of N i
36c40 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  n subsequent cal
36c50 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 61 67 67  l to sqlite3_agg
36c60 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
36c70 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 73   within.** the s
36c80 61 6d 65 20 61 67 67 72 65 67 61 74 65 20 66 75  ame aggregate fu
36c90 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 20  nction instance 
36ca0 77 69 6c 6c 20 6e 6f 74 20 72 65 73 69 7a 65 20  will not resize 
36cb0 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c  the memory.** al
36cc0 6c 6f 63 61 74 69 6f 6e 2e 29 5e 20 20 57 69 74  location.)^  Wit
36cd0 68 69 6e 20 74 68 65 20 78 46 69 6e 61 6c 20 63  hin the xFinal c
36ce0 61 6c 6c 62 61 63 6b 2c 20 69 74 20 69 73 20 63  allback, it is c
36cf0 75 73 74 6f 6d 61 72 79 20 74 6f 20 73 65 74 0a  ustomary to set.
36d00 2a 2a 20 4e 3d 30 20 69 6e 20 63 61 6c 6c 73 20  ** N=0 in calls 
36d10 74 6f 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  to sqlite3_aggre
36d20 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e  gate_context(C,N
36d30 29 20 73 6f 20 74 68 61 74 20 6e 6f 20 0a 2a 2a  ) so that no .**
36d40 20 70 6f 69 6e 74 6c 65 73 73 20 6d 65 6d 6f 72   pointless memor
36d50 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 6f 63  y allocations oc
36d60 63 75 72 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69  cur..**.** ^SQLi
36d70 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  te automatically
36d80 20 66 72 65 65 73 20 74 68 65 20 6d 65 6d 6f 72   frees the memor
36d90 79 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 0a  y allocated by .
36da0 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  ** sqlite3_aggre
36db0 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77  gate_context() w
36dc0 68 65 6e 20 74 68 65 20 61 67 67 72 65 67 61 74  hen the aggregat
36dd0 65 20 71 75 65 72 79 20 63 6f 6e 63 6c 75 64 65  e query conclude
36de0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  s..**.** The fir
36df0 73 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73  st parameter mus
36e00 74 20 62 65 20 61 20 63 6f 70 79 20 6f 66 20 74  t be a copy of t
36e10 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  he.** [sqlite3_c
36e20 6f 6e 74 65 78 74 20 7c 20 53 51 4c 20 66 75 6e  ontext | SQL fun
36e30 63 74 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74  ction context] t
36e40 68 61 74 20 69 73 20 74 68 65 20 66 69 72 73 74  hat is the first
36e50 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f   parameter.** to
36e60 20 74 68 65 20 78 53 74 65 70 20 6f 72 20 78 46   the xStep or xF
36e70 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 72 6f  inal callback ro
36e80 75 74 69 6e 65 20 74 68 61 74 20 69 6d 70 6c 65  utine that imple
36e90 6d 65 6e 74 73 20 74 68 65 20 61 67 67 72 65 67  ments the aggreg
36ea0 61 74 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e  ate.** function.
36eb0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
36ec0 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  ine must be call
36ed0 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65  ed from the same
36ee0 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68   thread in which
36ef0 0a 2a 2a 20 74 68 65 20 61 67 67 72 65 67 61 74  .** the aggregat
36f00 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  e SQL function i
36f10 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51  s running..*/.SQ
36f20 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 53  LITE_API void *S
36f30 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
36f40 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
36f50 63 6f 6e 74 65 78 74 28 73 71 6c 69 74 65 33 5f  context(sqlite3_
36f60 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42  context*, int nB
36f70 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ytes);../*.** CA
36f80 50 49 33 52 45 46 3a 20 55 73 65 72 20 44 61 74  PI3REF: User Dat
36f90 61 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a  a For Functions.
36fa0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
36fb0 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 20 69  e3_user_data() i
36fc0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
36fd0 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68   a copy of.** th
36fe0 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 77  e pointer that w
36ff0 61 73 20 74 68 65 20 70 55 73 65 72 44 61 74 61  as the pUserData
37000 20 70 61 72 61 6d 65 74 65 72 20 28 74 68 65 20   parameter (the 
37010 35 74 68 20 70 61 72 61 6d 65 74 65 72 29 0a 2a  5th parameter).*
37020 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * of the [sqlite
37030 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
37040 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c  n()].** and [sql
37050 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
37060 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e  tion16()] routin
37070 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c  es that original
37080 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64  ly.** registered
37090 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
370a0 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f   defined functio
370b0 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  n..**.** This ro
370c0 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61  utine must be ca
370d0 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61  lled from the sa
370e0 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69  me thread in whi
370f0 63 68 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  ch.** the applic
37100 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
37110 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e  nction is runnin
37120 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  g..*/.SQLITE_API
37130 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54   void *SQLITE_ST
37140 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 75 73  DCALL sqlite3_us
37150 65 72 5f 64 61 74 61 28 73 71 6c 69 74 65 33 5f  er_data(sqlite3_
37160 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a  context*);../*.*
37170 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61  * CAPI3REF: Data
37180 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20  base Connection 
37190 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  For Functions.**
371a0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
371b0 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64  _context_db_hand
371c0 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  le() interface r
371d0 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66  eturns a copy of
371e0 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20  .** the pointer 
371f0 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  to the [database
37200 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 68   connection] (th
37210 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 29  e 1st parameter)
37220 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  .** of the [sqli
37230 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
37240 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73  ion()].** and [s
37250 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
37260 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74  nction16()] rout
37270 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e  ines that origin
37280 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72  ally.** register
37290 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ed the applicati
372a0 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on defined funct
372b0 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ion..*/.SQLITE_A
372c0 50 49 20 73 71 6c 69 74 65 33 20 2a 53 51 4c 49  PI sqlite3 *SQLI
372d0 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
372e0 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61  e3_context_db_ha
372f0 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  ndle(sqlite3_con
37300 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  text*);../*.** C
37310 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f  API3REF: Functio
37320 6e 20 41 75 78 69 6c 69 61 72 79 20 44 61 74 61  n Auxiliary Data
37330 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e  .**.** These fun
37340 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 75 73  ctions may be us
37350 65 64 20 62 79 20 28 6e 6f 6e 2d 61 67 67 72 65  ed by (non-aggre
37360 67 61 74 65 29 20 53 51 4c 20 66 75 6e 63 74 69  gate) SQL functi
37370 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69  ons to.** associ
37380 61 74 65 20 6d 65 74 61 64 61 74 61 20 77 69 74  ate metadata wit
37390 68 20 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 65  h argument value
373a0 73 2e 20 49 66 20 74 68 65 20 73 61 6d 65 20 76  s. If the same v
373b0 61 6c 75 65 20 69 73 20 70 61 73 73 65 64 20 74  alue is passed t
373c0 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e  o.** multiple in
373d0 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  vocations of the
373e0 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69   same SQL functi
373f0 6f 6e 20 64 75 72 69 6e 67 20 71 75 65 72 79 20  on during query 
37400 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72  execution, under
37410 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d 73  .** some circums
37420 74 61 6e 63 65 73 20 74 68 65 20 61 73 73 6f 63  tances the assoc
37430 69 61 74 65 64 20 6d 65 74 61 64 61 74 61 20 6d  iated metadata m
37440 61 79 20 62 65 20 70 72 65 73 65 72 76 65 64 2e  ay be preserved.
37450 20 20 41 6e 20 65 78 61 6d 70 6c 65 0a 2a 2a 20    An example.** 
37460 6f 66 20 77 68 65 72 65 20 74 68 69 73 20 6d 69  of where this mi
37470 67 68 74 20 62 65 20 75 73 65 66 75 6c 20 69 73  ght be useful is
37480 20 69 6e 20 61 20 72 65 67 75 6c 61 72 2d 65 78   in a regular-ex
37490 70 72 65 73 73 69 6f 6e 20 6d 61 74 63 68 69 6e  pression matchin
374a0 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54  g.** function. T
374b0 68 65 20 63 6f 6d 70 69 6c 65 64 20 76 65 72 73  he compiled vers
374c0 69 6f 6e 20 6f 66 20 74 68 65 20 72 65 67 75 6c  ion of the regul
374d0 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61  ar expression ca
374e0 6e 20 62 65 20 73 74 6f 72 65 64 20 61 73 0a 2a  n be stored as.*
374f0 2a 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63  * metadata assoc
37500 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 70  iated with the p
37510 61 74 74 65 72 6e 20 73 74 72 69 6e 67 2e 20 20  attern string.  
37520 0a 2a 2a 20 54 68 65 6e 20 61 73 20 6c 6f 6e 67  .** Then as long
37530 20 61 73 20 74 68 65 20 70 61 74 74 65 72 6e 20   as the pattern 
37540 73 74 72 69 6e 67 20 72 65 6d 61 69 6e 73 20 74  string remains t
37550 68 65 20 73 61 6d 65 2c 0a 2a 2a 20 74 68 65 20  he same,.** the 
37560 63 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c 61 72  compiled regular
37570 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61 6e 20   expression can 
37580 62 65 20 72 65 75 73 65 64 20 6f 6e 20 6d 75 6c  be reused on mul
37590 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61 74  tiple.** invocat
375a0 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
375b0 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   function..**.**
375c0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65   ^The sqlite3_ge
375d0 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65  t_auxdata() inte
375e0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
375f0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d  pointer to the m
37600 65 74 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63  etadata.** assoc
37610 69 61 74 65 64 20 62 79 20 74 68 65 20 73 71 6c  iated by the sql
37620 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
37630 28 29 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68  () function with
37640 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e   the Nth argumen
37650 74 0a 2a 2a 20 76 61 6c 75 65 20 74 6f 20 74 68  t.** value to th
37660 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
37670 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20  fined function. 
37680 5e 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20  ^If there is no 
37690 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f  metadata.** asso
376a0 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
376b0 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e  function argumen
376c0 74 2c 20 74 68 69 73 20 73 71 6c 69 74 65 33 5f  t, this sqlite3_
376d0 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e  get_auxdata() in
376e0 74 65 72 66 61 63 65 0a 2a 2a 20 72 65 74 75 72  terface.** retur
376f0 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ns a NULL pointe
37700 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  r..**.** ^The sq
37710 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
37720 61 28 43 2c 4e 2c 50 2c 58 29 20 69 6e 74 65 72  a(C,N,P,X) inter
37730 66 61 63 65 20 73 61 76 65 73 20 50 20 61 73 20  face saves P as 
37740 6d 65 74 61 64 61 74 61 20 66 6f 72 20 74 68 65  metadata for the
37750 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e   N-th.** argumen
37760 74 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  t of the applica
37770 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
37780 63 74 69 6f 6e 2e 20 20 5e 53 75 62 73 65 71 75  ction.  ^Subsequ
37790 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20  ent.** calls to 
377a0 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
377b0 61 74 61 28 43 2c 4e 29 20 72 65 74 75 72 6e 20  ata(C,N) return 
377c0 50 20 66 72 6f 6d 20 74 68 65 20 6d 6f 73 74 20  P from the most 
377d0 72 65 63 65 6e 74 0a 2a 2a 20 73 71 6c 69 74 65  recent.** sqlite
377e0 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c  3_set_auxdata(C,
377f0 4e 2c 50 2c 58 29 20 63 61 6c 6c 20 69 66 20 74  N,P,X) call if t
37800 68 65 20 6d 65 74 61 64 61 74 61 20 69 73 20 73  he metadata is s
37810 74 69 6c 6c 20 76 61 6c 69 64 20 6f 72 0a 2a 2a  till valid or.**
37820 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 6d 65 74   NULL if the met
37830 61 64 61 74 61 20 68 61 73 20 62 65 65 6e 20 64  adata has been d
37840 69 73 63 61 72 64 65 64 2e 0a 2a 2a 20 5e 41 66  iscarded..** ^Af
37850 74 65 72 20 65 61 63 68 20 63 61 6c 6c 20 74 6f  ter each call to
37860 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
37870 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20 77 68  data(C,N,P,X) wh
37880 65 72 65 20 58 20 69 73 20 6e 6f 74 20 4e 55 4c  ere X is not NUL
37890 4c 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c  L,.** SQLite wil
378a0 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73  l invoke the des
378b0 74 72 75 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e  tructor function
378c0 20 58 20 77 69 74 68 20 70 61 72 61 6d 65 74 65   X with paramete
378d0 72 20 50 20 65 78 61 63 74 6c 79 0a 2a 2a 20 6f  r P exactly.** o
378e0 6e 63 65 2c 20 77 68 65 6e 20 74 68 65 20 6d 65  nce, when the me
378f0 74 61 64 61 74 61 20 69 73 20 64 69 73 63 61 72  tadata is discar
37900 64 65 64 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 69  ded..** SQLite i
37910 73 20 66 72 65 65 20 74 6f 20 64 69 73 63 61 72  s free to discar
37920 64 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 61  d the metadata a
37930 74 20 61 6e 79 20 74 69 6d 65 2c 20 69 6e 63 6c  t any time, incl
37940 75 64 69 6e 67 3a 20 3c 75 6c 3e 0a 2a 2a 20 3c  uding: <ul>.** <
37950 6c 69 3e 20 77 68 65 6e 20 74 68 65 20 63 6f 72  li> when the cor
37960 72 65 73 70 6f 6e 64 69 6e 67 20 66 75 6e 63 74  responding funct
37970 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 63 68  ion parameter ch
37980 61 6e 67 65 73 2c 20 6f 72 0a 2a 2a 20 3c 6c 69  anges, or.** <li
37990 3e 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f  > when [sqlite3_
379a0 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c  reset()] or [sql
379b0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
379c0 20 69 73 20 63 61 6c 6c 65 64 20 66 6f 72 20 74   is called for t
379d0 68 65 0a 2a 2a 20 20 20 20 20 20 53 51 4c 20 73  he.**      SQL s
379e0 74 61 74 65 6d 65 6e 74 2c 20 6f 72 0a 2a 2a 20  tatement, or.** 
379f0 3c 6c 69 3e 20 77 68 65 6e 20 73 71 6c 69 74 65  <li> when sqlite
37a00 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_set_auxdata() 
37a10 69 73 20 69 6e 76 6f 6b 65 64 20 61 67 61 69 6e  is invoked again
37a20 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 70 61 72   on the same par
37a30 61 6d 65 74 65 72 2c 20 6f 72 0a 2a 2a 20 3c 6c  ameter, or.** <l
37a40 69 3e 20 64 75 72 69 6e 67 20 74 68 65 20 6f 72  i> during the or
37a50 69 67 69 6e 61 6c 20 73 71 6c 69 74 65 33 5f 73  iginal sqlite3_s
37a60 65 74 5f 61 75 78 64 61 74 61 28 29 20 63 61 6c  et_auxdata() cal
37a70 6c 20 77 68 65 6e 20 61 20 6d 65 6d 6f 72 79 20  l when a memory 
37a80 0a 2a 2a 20 20 20 20 20 20 61 6c 6c 6f 63 61 74  .**      allocat
37a90 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73  ion error occurs
37aa0 2e 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20  . </ul>)^.**.** 
37ab0 4e 6f 74 65 20 74 68 65 20 6c 61 73 74 20 62 75  Note the last bu
37ac0 6c 6c 65 74 20 69 6e 20 70 61 72 74 69 63 75 6c  llet in particul
37ad0 61 72 2e 20 20 54 68 65 20 64 65 73 74 72 75 63  ar.  The destruc
37ae0 74 6f 72 20 58 20 69 6e 20 0a 2a 2a 20 73 71 6c  tor X in .** sql
37af0 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
37b00 28 43 2c 4e 2c 50 2c 58 29 20 6d 69 67 68 74 20  (C,N,P,X) might 
37b10 62 65 20 63 61 6c 6c 65 64 20 69 6d 6d 65 64 69  be called immedi
37b20 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 20 74 68  ately, before th
37b30 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65 74  e.** sqlite3_set
37b40 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72  _auxdata() inter
37b50 66 61 63 65 20 65 76 65 6e 20 72 65 74 75 72 6e  face even return
37b60 73 2e 20 20 48 65 6e 63 65 20 73 71 6c 69 74 65  s.  Hence sqlite
37b70 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 0a  3_set_auxdata().
37b80 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 63 61 6c  ** should be cal
37b90 6c 65 64 20 6e 65 61 72 20 74 68 65 20 65 6e 64  led near the end
37ba0 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e   of the function
37bb0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
37bc0 61 6e 64 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74  and the.** funct
37bd0 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ion implementati
37be0 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74 20 6d 61  on should not ma
37bf0 6b 65 20 61 6e 79 20 75 73 65 20 6f 66 20 50 20  ke any use of P 
37c00 61 66 74 65 72 0a 2a 2a 20 73 71 6c 69 74 65 33  after.** sqlite3
37c10 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 68  _set_auxdata() h
37c20 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 2e 0a  as been called..
37c30 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 70 72 61 63 74  **.** ^(In pract
37c40 69 63 65 2c 20 6d 65 74 61 64 61 74 61 20 69 73  ice, metadata is
37c50 20 70 72 65 73 65 72 76 65 64 20 62 65 74 77 65   preserved betwe
37c60 65 6e 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c  en function call
37c70 73 20 66 6f 72 0a 2a 2a 20 66 75 6e 63 74 69 6f  s for.** functio
37c80 6e 20 70 61 72 61 6d 65 74 65 72 73 20 74 68 61  n parameters tha
37c90 74 20 61 72 65 20 63 6f 6d 70 69 6c 65 2d 74 69  t are compile-ti
37ca0 6d 65 20 63 6f 6e 73 74 61 6e 74 73 2c 20 69 6e  me constants, in
37cb0 63 6c 75 64 69 6e 67 20 6c 69 74 65 72 61 6c 0a  cluding literal.
37cc0 2a 2a 20 76 61 6c 75 65 73 20 61 6e 64 20 5b 70  ** values and [p
37cd0 61 72 61 6d 65 74 65 72 73 5d 20 61 6e 64 20 65  arameters] and e
37ce0 78 70 72 65 73 73 69 6f 6e 73 20 63 6f 6d 70 6f  xpressions compo
37cf0 73 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d  sed from the sam
37d00 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  e.)^.**.** These
37d10 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62   routines must b
37d20 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  e called from th
37d30 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e  e same thread in
37d40 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 53 51   which.** the SQ
37d50 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  L function is ru
37d60 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45  nning..*/.SQLITE
37d70 5f 41 50 49 20 76 6f 69 64 20 2a 53 51 4c 49 54  _API void *SQLIT
37d80 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
37d90 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 73 71  3_get_auxdata(sq
37da0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
37db0 69 6e 74 20 4e 29 3b 0a 53 51 4c 49 54 45 5f 41  int N);.SQLITE_A
37dc0 50 49 20 76 6f 69 64 20 53 51 4c 49 54 45 5f 53  PI void SQLITE_S
37dd0 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 73  TDCALL sqlite3_s
37de0 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74  et_auxdata(sqlit
37df0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
37e00 20 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f 69 64 20   N, void*, void 
37e10 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f  (*)(void*));.../
37e20 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
37e30 6f 6e 73 74 61 6e 74 73 20 44 65 66 69 6e 69 6e  onstants Definin
37e40 67 20 53 70 65 63 69 61 6c 20 44 65 73 74 72 75  g Special Destru
37e50 63 74 6f 72 20 42 65 68 61 76 69 6f 72 0a 2a 2a  ctor Behavior.**
37e60 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 73 70  .** These are sp
37e70 65 63 69 61 6c 20 76 61 6c 75 65 73 20 66 6f 72  ecial values for
37e80 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   the destructor 
37e90 74 68 61 74 20 69 73 20 70 61 73 73 65 64 20 69  that is passed i
37ea0 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66 69 6e 61  n as the.** fina
37eb0 6c 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 72 6f  l argument to ro
37ec0 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c  utines like [sql
37ed0 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
37ee0 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 20 64 65  ()].  ^If the de
37ef0 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67 75  structor.** argu
37f00 6d 65 6e 74 20 69 73 20 53 51 4c 49 54 45 5f 53  ment is SQLITE_S
37f10 54 41 54 49 43 2c 20 69 74 20 6d 65 61 6e 73 20  TATIC, it means 
37f20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74  that the content
37f30 20 70 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e 73   pointer is cons
37f40 74 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c  tant.** and will
37f50 20 6e 65 76 65 72 20 63 68 61 6e 67 65 2e 20 20   never change.  
37f60 49 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  It does not need
37f70 20 74 6f 20 62 65 20 64 65 73 74 72 6f 79 65 64   to be destroyed
37f80 2e 20 20 5e 54 68 65 0a 2a 2a 20 53 51 4c 49 54  .  ^The.** SQLIT
37f90 45 5f 54 52 41 4e 53 49 45 4e 54 20 76 61 6c 75  E_TRANSIENT valu
37fa0 65 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  e means that the
37fb0 20 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 6c 69   content will li
37fc0 6b 65 6c 79 20 63 68 61 6e 67 65 20 69 6e 0a 2a  kely change in.*
37fd0 2a 20 74 68 65 20 6e 65 61 72 20 66 75 74 75 72  * the near futur
37fe0 65 20 61 6e 64 20 74 68 61 74 20 53 51 4c 69 74  e and that SQLit
37ff0 65 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20 69 74  e should make it
38000 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f  s own private co
38010 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e  py of.** the con
38020 74 65 6e 74 20 62 65 66 6f 72 65 20 72 65 74 75  tent before retu
38030 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rning..**.** The
38040 20 74 79 70 65 64 65 66 20 69 73 20 6e 65 63 65   typedef is nece
38050 73 73 61 72 79 20 74 6f 20 77 6f 72 6b 20 61 72  ssary to work ar
38060 6f 75 6e 64 20 70 72 6f 62 6c 65 6d 73 20 69 6e  ound problems in
38070 20 63 65 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20   certain.** C++ 
38080 63 6f 6d 70 69 6c 65 72 73 2e 0a 2a 2f 0a 74 79  compilers..*/.ty
38090 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c  pedef void (*sql
380a0 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f  ite3_destructor_
380b0 74 79 70 65 29 28 76 6f 69 64 2a 29 3b 0a 23 64  type)(void*);.#d
380c0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41  efine SQLITE_STA
380d0 54 49 43 20 20 20 20 20 20 28 28 73 71 6c 69 74  TIC      ((sqlit
380e0 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79  e3_destructor_ty
380f0 70 65 29 30 29 0a 23 64 65 66 69 6e 65 20 53 51  pe)0).#define SQ
38100 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 20  LITE_TRANSIENT  
38110 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72   ((sqlite3_destr
38120 75 63 74 6f 72 5f 74 79 70 65 29 2d 31 29 0a 0a  uctor_type)-1)..
38130 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
38140 53 65 74 74 69 6e 67 20 54 68 65 20 52 65 73 75  Setting The Resu
38150 6c 74 20 4f 66 20 41 6e 20 53 51 4c 20 46 75 6e  lt Of An SQL Fun
38160 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ction.**.** Thes
38170 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75  e routines are u
38180 73 65 64 20 62 79 20 74 68 65 20 78 46 75 6e 63  sed by the xFunc
38190 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62   or xFinal callb
381a0 61 63 6b 73 20 74 68 61 74 0a 2a 2a 20 69 6d 70  acks that.** imp
381b0 6c 65 6d 65 6e 74 20 53 51 4c 20 66 75 6e 63 74  lement SQL funct
381c0 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61  ions and aggrega
381d0 74 65 73 2e 20 20 53 65 65 0a 2a 2a 20 5b 73 71  tes.  See.** [sq
381e0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
381f0 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  ction()] and [sq
38200 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
38210 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f  ction16()].** fo
38220 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66  r additional inf
38230 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
38240 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
38250 77 6f 72 6b 20 76 65 72 79 20 6d 75 63 68 20 6c  work very much l
38260 69 6b 65 20 74 68 65 20 5b 70 61 72 61 6d 65 74  ike the [paramet
38270 65 72 20 62 69 6e 64 69 6e 67 5d 20 66 61 6d 69  er binding] fami
38280 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e 63 74 69 6f  ly of.** functio
38290 6e 73 20 75 73 65 64 20 74 6f 20 62 69 6e 64 20  ns used to bind 
382a0 76 61 6c 75 65 73 20 74 6f 20 68 6f 73 74 20 70  values to host p
382b0 61 72 61 6d 65 74 65 72 73 20 69 6e 20 70 72 65  arameters in pre
382c0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
382d0 2e 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 74 68  ..** Refer to th
382e0 65 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  e [SQL parameter
382f0 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20  ] documentation 
38300 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69  for additional i
38310 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
38320 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
38330 65 73 75 6c 74 5f 62 6c 6f 62 28 29 20 69 6e 74  esult_blob() int
38340 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
38350 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61  result from.** a
38360 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
38370 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
38380 6f 20 62 65 20 74 68 65 20 42 4c 4f 42 20 77 68  o be the BLOB wh
38390 6f 73 65 20 63 6f 6e 74 65 6e 74 20 69 73 20 70  ose content is p
383a0 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f 20 62 79 20  ointed.** to by 
383b0 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
383c0 65 74 65 72 20 61 6e 64 20 77 68 69 63 68 20 69  eter and which i
383d0 73 20 4e 20 62 79 74 65 73 20 6c 6f 6e 67 20 77  s N bytes long w
383e0 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a  here N is the.**
383f0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
38400 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
38410 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f  ite3_result_zero
38420 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65  blob() interface
38430 73 20 73 65 74 20 74 68 65 20 72 65 73 75 6c 74  s set the result
38440 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69   of.** the appli
38450 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
38460 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20  unction to be a 
38470 42 4c 4f 42 20 63 6f 6e 74 61 69 6e 69 6e 67 20  BLOB containing 
38480 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62 79 74 65  all zero.** byte
38490 73 20 61 6e 64 20 4e 20 62 79 74 65 73 20 69 6e  s and N bytes in
384a0 20 73 69 7a 65 2c 20 77 68 65 72 65 20 4e 20 69   size, where N i
384b0 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  s the value of t
384c0 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
384d0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
384e0 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62  ite3_result_doub
384f0 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  le() interface s
38500 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 66  ets the result f
38510 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63  rom.** an applic
38520 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
38530 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 66  nction to be a f
38540 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61  loating point va
38550 6c 75 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a  lue specified.**
38560 20 62 79 20 69 74 73 20 32 6e 64 20 61 72 67 75   by its 2nd argu
38570 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ment..**.** ^The
38580 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
38590 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69  error() and sqli
385a0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
385b0 31 36 28 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a  16() functions.*
385c0 2a 20 63 61 75 73 65 20 74 68 65 20 69 6d 70 6c  * cause the impl
385d0 65 6d 65 6e 74 65 64 20 53 51 4c 20 66 75 6e 63  emented SQL func
385e0 74 69 6f 6e 20 74 6f 20 74 68 72 6f 77 20 61 6e  tion to throw an
385f0 20 65 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20 5e   exception..** ^
38600 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20  SQLite uses the 
38610 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 64 20 74  string pointed t
38620 6f 20 62 79 20 74 68 65 0a 2a 2a 20 32 6e 64 20  o by the.** 2nd 
38630 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73 71 6c  parameter of sql
38640 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
38650 72 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  r() or sqlite3_r
38660 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a  esult_error16().
38670 2a 2a 20 61 73 20 74 68 65 20 74 65 78 74 20 6f  ** as the text o
38680 66 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61  f an error messa
38690 67 65 2e 20 20 5e 53 51 4c 69 74 65 20 69 6e 74  ge.  ^SQLite int
386a0 65 72 70 72 65 74 73 20 74 68 65 20 65 72 72 6f  erprets the erro
386b0 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 73 74 72  r.** message str
386c0 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ing from sqlite3
386d0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20  _result_error() 
386e0 61 73 20 55 54 46 2d 38 2e 20 5e 53 51 4c 69 74  as UTF-8. ^SQLit
386f0 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 73 20  e.** interprets 
38700 74 68 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20  the string from 
38710 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
38720 72 72 6f 72 31 36 28 29 20 61 73 20 55 54 46 2d  rror16() as UTF-
38730 31 36 20 69 6e 20 6e 61 74 69 76 65 0a 2a 2a 20  16 in native.** 
38740 62 79 74 65 20 6f 72 64 65 72 2e 20 20 5e 49 66  byte order.  ^If
38750 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
38760 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
38770 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a  result_error().*
38780 2a 20 6f 72 20