System.Data.SQLite
Hex Artifact Content
Not logged in

Artifact c03e47e152ddb9c342b84ffb39448bf4a2bd4288:


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 39 2e 30 2e 20 20 42  ersion 3.9.0.  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 33 30 29 0a 23 70 72 61  ble : 4130).#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 35 32 29 0a 23 70 72 61  ble : 4152).#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 31 38 39 29 0a 23 70 72 61  ble : 4189).#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 30 36 29 0a 23 70 72 61  ble : 4206).#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 31 30 29 0a 23 70 72 61  ble : 4210).#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 33 32 29 0a 23 70 72 61  ble : 4232).#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 32 34 34 29 0a 23 70 72 61  ble : 4244).#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 35 29 0a 23 70 72 61  ble : 4305).#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 33 30 36 29 0a 23 70 72 61  ble : 4306).#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 32 29 0a 23 70 72 61  ble : 4702).#pra
0cd0: 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73 61  gma warning(disa
0ce0: 62 6c 65 20 3a 20 34 37 30 36 29 0a 23 65 6e 64  ble : 4706).#end
0cf0: 69 66 20 2f 2a 20 64 65 66 69 6e 65 64 28 5f 4d  if /* defined(_M
0d00: 53 43 5f 56 45 52 29 20 2a 2f 0a 0a 23 65 6e 64  SC_VER) */..#end
0d10: 69 66 20 2f 2a 20 5f 4d 53 56 43 5f 48 5f 20 2a  if /* _MSVC_H_ *
0d20: 2f 0a 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  /../************
0d30: 2a 2a 20 45 6e 64 20 6f 66 20 6d 73 76 63 2e 68  ** End of msvc.h
0d40: 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a   ***************
0d50: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0d60: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0d70: 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  */./************
0d80: 2a 2a 20 43 6f 6e 74 69 6e 75 69 6e 67 20 77 68  ** Continuing wh
0d90: 65 72 65 20 77 65 20 6c 65 66 74 20 6f 66 66 20  ere we left off 
0da0: 69 6e 20 73 71 6c 69 74 65 49 6e 74 2e 68 20 2a  in sqliteInt.h *
0db0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0dc0: 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 61  */../*.** Specia
0dd0: 6c 20 73 65 74 75 70 20 66 6f 72 20 56 78 57 6f  l setup for VxWo
0de0: 72 6b 73 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a  rks.*/./********
0df0: 2a 2a 2a 2a 2a 2a 20 49 6e 63 6c 75 64 65 20 76  ****** Include v
0e00: 78 77 6f 72 6b 73 2e 68 20 69 6e 20 74 68 65 20  xworks.h in the 
0e10: 6d 69 64 64 6c 65 20 6f 66 20 73 71 6c 69 74 65  middle of sqlite
0e20: 49 6e 74 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  Int.h **********
0e30: 2a 2a 2a 2a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a  *****/./********
0e40: 2a 2a 2a 2a 2a 2a 20 42 65 67 69 6e 20 66 69 6c  ****** Begin fil
0e50: 65 20 76 78 77 6f 72 6b 73 2e 68 20 2a 2a 2a 2a  e vxworks.h ****
0e60: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0e70: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0e80: 2a 2a 2a 2a 2a 2f 0a 2f 2a 0a 2a 2a 20 32 30 31  *****/./*.** 201
0e90: 35 2d 30 33 2d 30 32 0a 2a 2a 0a 2a 2a 20 54 68  5-03-02.**.** Th
0ea0: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0eb0: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0ec0: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0ed0: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0ee0: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0ef0: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0f00: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0f10: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
0f20: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
0f30: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
0f40: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
0f50: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
0f60: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
0f70: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0f80: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0f90: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0fa0: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
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 2a 2a 2a 2a 2a  ****************
0fe0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0ff0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a 2a 0a 2a  ***********.**.*
1000: 2a 20 54 68 69 73 20 66 69 6c 65 20 63 6f 6e 74  * This file cont
1010: 61 69 6e 73 20 63 6f 64 65 20 74 68 61 74 20 69  ains code that i
1020: 73 20 73 70 65 63 69 66 69 63 20 74 6f 20 57 69  s specific to Wi
1030: 6e 64 20 52 69 76 65 72 27 73 20 56 78 57 6f 72  nd River's VxWor
1040: 6b 73 0a 2a 2f 0a 23 69 66 20 64 65 66 69 6e 65  ks.*/.#if define
1050: 64 28 5f 5f 52 54 50 5f 5f 29 20 7c 7c 20 64 65  d(__RTP__) || de
1060: 66 69 6e 65 64 28 5f 57 52 53 5f 4b 45 52 4e 45  fined(_WRS_KERNE
1070: 4c 29 0a 2f 2a 20 54 68 69 73 20 69 73 20 56 78  L)./* This is Vx
1080: 57 6f 72 6b 73 2e 20 20 53 65 74 20 75 70 20 74  Works.  Set up t
1090: 68 69 6e 67 73 20 73 70 65 63 69 61 6c 6c 79 20  hings specially 
10a0: 66 6f 72 20 74 68 61 74 20 4f 53 0a 2a 2f 0a 23  for that OS.*/.#
10b0: 69 6e 63 6c 75 64 65 20 3c 76 78 57 6f 72 6b 73  include <vxWorks
10c0: 2e 68 3e 0a 23 69 6e 63 6c 75 64 65 20 3c 70 74  .h>.#include <pt
10d0: 68 72 65 61 64 2e 68 3e 20 20 2f 2a 20 61 6d 61  hread.h>  /* ama
10e0: 6c 67 61 6d 61 74 6f 72 3a 20 64 6f 6e 74 63 61  lgamator: dontca
10f0: 63 68 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 4f  che */.#define O
1100: 53 5f 56 58 57 4f 52 4b 53 20 31 0a 23 64 65 66  S_VXWORKS 1.#def
1110: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 53 5f 4f 54  ine SQLITE_OS_OT
1120: 48 45 52 20 30 0a 23 64 65 66 69 6e 65 20 53 51  HER 0.#define SQ
1130: 4c 49 54 45 5f 48 4f 4d 45 47 52 4f 57 4e 5f 52  LITE_HOMEGROWN_R
1140: 45 43 55 52 53 49 56 45 5f 4d 55 54 45 58 20 31  ECURSIVE_MUTEX 1
1150: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1160: 4f 4d 49 54 5f 4c 4f 41 44 5f 45 58 54 45 4e 53  OMIT_LOAD_EXTENS
1170: 49 4f 4e 20 31 0a 23 64 65 66 69 6e 65 20 53 51  ION 1.#define SQ
1180: 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4c 4f 43 4b  LITE_ENABLE_LOCK
1190: 49 4e 47 5f 53 54 59 4c 45 20 30 0a 23 64 65 66  ING_STYLE 0.#def
11a0: 69 6e 65 20 48 41 56 45 5f 55 54 49 4d 45 20 31  ine HAVE_UTIME 1
11b0: 0a 23 65 6c 73 65 0a 2f 2a 20 54 68 69 73 20 69  .#else./* This i
11c0: 73 20 6e 6f 74 20 56 78 57 6f 72 6b 73 2e 20 2a  s not VxWorks. *
11d0: 2f 0a 23 64 65 66 69 6e 65 20 4f 53 5f 56 58 57  /.#define OS_VXW
11e0: 4f 52 4b 53 20 30 0a 23 65 6e 64 69 66 20 2f 2a  ORKS 0.#endif /*
11f0: 20 64 65 66 69 6e 65 64 28 5f 57 52 53 5f 4b 45   defined(_WRS_KE
1200: 52 4e 45 4c 29 20 2a 2f 0a 0a 2f 2a 2a 2a 2a 2a  RNEL) */../*****
1210: 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 45 6e 64 20 6f 66  ********* End of
1220: 20 76 78 77 6f 72 6b 73 2e 68 20 2a 2a 2a 2a 2a   vxworks.h *****
1230: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1240: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1250: 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 2a 2a 2a 2a  ********/./*****
1260: 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 43 6f 6e 74 69 6e  ********* Contin
1270: 75 69 6e 67 20 77 68 65 72 65 20 77 65 20 6c 65  uing where we le
1280: 66 74 20 6f 66 66 20 69 6e 20 73 71 6c 69 74 65  ft off in sqlite
1290: 49 6e 74 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  Int.h **********
12a0: 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 0a 2f 2a 0a 2a 2a  ********/../*.**
12b0: 20 54 68 65 73 65 20 23 64 65 66 69 6e 65 73 20   These #defines 
12c0: 73 68 6f 75 6c 64 20 65 6e 61 62 6c 65 20 3e 32  should enable >2
12d0: 47 42 20 66 69 6c 65 20 73 75 70 70 6f 72 74 20  GB file support 
12e0: 6f 6e 20 50 4f 53 49 58 20 69 66 20 74 68 65 0a  on POSIX if the.
12f0: 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70  ** underlying op
1300: 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 73  erating system s
1310: 75 70 70 6f 72 74 73 20 69 74 2e 20 20 49 66 20  upports it.  If 
1320: 74 68 65 20 4f 53 20 6c 61 63 6b 73 0a 2a 2a 20  the OS lacks.** 
1330: 6c 61 72 67 65 20 66 69 6c 65 20 73 75 70 70 6f  large file suppo
1340: 72 74 2c 20 6f 72 20 69 66 20 74 68 65 20 4f 53  rt, or if the OS
1350: 20 69 73 20 77 69 6e 64 6f 77 73 2c 20 74 68 65   is windows, the
1360: 73 65 20 73 68 6f 75 6c 64 20 62 65 20 6e 6f 2d  se should be no-
1370: 6f 70 73 2e 0a 2a 2a 0a 2a 2a 20 54 69 63 6b 65  ops..**.** Ticke
1380: 74 20 23 32 37 33 39 3a 20 20 54 68 65 20 5f 4c  t #2739:  The _L
1390: 41 52 47 45 46 49 4c 45 5f 53 4f 55 52 43 45 20  ARGEFILE_SOURCE 
13a0: 6d 61 63 72 6f 20 6d 75 73 74 20 61 70 70 65 61  macro must appea
13b0: 72 20 62 65 66 6f 72 65 20 61 6e 79 0a 2a 2a 20  r before any.** 
13c0: 73 79 73 74 65 6d 20 23 69 6e 63 6c 75 64 65 73  system #includes
13d0: 2e 20 20 48 65 6e 63 65 2c 20 74 68 69 73 20 62  .  Hence, this b
13e0: 6c 6f 63 6b 20 6f 66 20 63 6f 64 65 20 6d 75 73  lock of code mus
13f0: 74 20 62 65 20 74 68 65 20 76 65 72 79 20 66 69  t be the very fi
1400: 72 73 74 0a 2a 2a 20 63 6f 64 65 20 69 6e 20 61  rst.** code in a
1410: 6c 6c 20 73 6f 75 72 63 65 20 66 69 6c 65 73 2e  ll source files.
1420: 0a 2a 2a 0a 2a 2a 20 4c 61 72 67 65 20 66 69 6c  .**.** Large fil
1430: 65 20 73 75 70 70 6f 72 74 20 63 61 6e 20 62 65  e support can be
1440: 20 64 69 73 61 62 6c 65 64 20 75 73 69 6e 67 20   disabled using 
1450: 74 68 65 20 2d 44 53 51 4c 49 54 45 5f 44 49 53  the -DSQLITE_DIS
1460: 41 42 4c 45 5f 4c 46 53 20 73 77 69 74 63 68 0a  ABLE_LFS switch.
1470: 2a 2a 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69 6c  ** on the compil
1480: 65 72 20 63 6f 6d 6d 61 6e 64 20 6c 69 6e 65 2e  er command line.
1490: 20 20 54 68 69 73 20 69 73 20 6e 65 63 65 73 73    This is necess
14a0: 61 72 79 20 69 66 20 79 6f 75 20 61 72 65 20 63  ary if you are c
14b0: 6f 6d 70 69 6c 69 6e 67 0a 2a 2a 20 6f 6e 20 61  ompiling.** on a
14c0: 20 72 65 63 65 6e 74 20 6d 61 63 68 69 6e 65 20   recent machine 
14d0: 28 65 78 3a 20 52 65 64 20 48 61 74 20 37 2e 32  (ex: Red Hat 7.2
14e0: 29 20 62 75 74 20 79 6f 75 20 77 61 6e 74 20 79  ) but you want y
14f0: 6f 75 72 20 63 6f 64 65 20 74 6f 20 77 6f 72 6b  our code to work
1500: 0a 2a 2a 20 6f 6e 20 61 6e 20 6f 6c 64 65 72 20  .** on an older 
1510: 6d 61 63 68 69 6e 65 20 28 65 78 3a 20 52 65 64  machine (ex: Red
1520: 20 48 61 74 20 36 2e 30 29 2e 20 20 49 66 20 79   Hat 6.0).  If y
1530: 6f 75 20 63 6f 6d 70 69 6c 65 20 6f 6e 20 52 65  ou compile on Re
1540: 64 20 48 61 74 20 37 2e 32 0a 2a 2a 20 77 69 74  d Hat 7.2.** wit
1550: 68 6f 75 74 20 74 68 69 73 20 6f 70 74 69 6f 6e  hout this option
1560: 2c 20 4c 46 53 20 69 73 20 65 6e 61 62 6c 65 2e  , LFS is enable.
1570: 20 20 42 75 74 20 4c 46 53 20 64 6f 65 73 20 6e    But LFS does n
1580: 6f 74 20 65 78 69 73 74 20 69 6e 20 74 68 65 20  ot exist in the 
1590: 6b 65 72 6e 65 6c 0a 2a 2a 20 69 6e 20 52 65 64  kernel.** in Red
15a0: 20 48 61 74 20 36 2e 30 2c 20 73 6f 20 74 68 65   Hat 6.0, so the
15b0: 20 63 6f 64 65 20 77 6f 6e 27 74 20 77 6f 72 6b   code won't work
15c0: 2e 20 20 48 65 6e 63 65 2c 20 66 6f 72 20 6d 61  .  Hence, for ma
15d0: 78 69 6d 75 6d 20 62 69 6e 61 72 79 0a 2a 2a 20  ximum binary.** 
15e0: 70 6f 72 74 61 62 69 6c 69 74 79 20 79 6f 75 20  portability you 
15f0: 73 68 6f 75 6c 64 20 6f 6d 69 74 20 4c 46 53 2e  should omit LFS.
1600: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 76 69  .**.** The previ
1610: 6f 75 73 20 70 61 72 61 67 72 61 70 68 20 77 61  ous paragraph wa
1620: 73 20 77 72 69 74 74 65 6e 20 69 6e 20 32 30 30  s written in 200
1630: 35 2e 20 20 28 54 68 69 73 20 70 61 72 61 67 72  5.  (This paragr
1640: 61 70 68 20 69 73 20 77 72 69 74 74 65 6e 0a 2a  aph is written.*
1650: 2a 20 6f 6e 20 32 30 30 38 2d 31 31 2d 32 38 2e  * on 2008-11-28.
1660: 29 20 54 68 65 73 65 20 64 61 79 73 2c 20 61 6c  ) These days, al
1670: 6c 20 4c 69 6e 75 78 20 6b 65 72 6e 65 6c 73 20  l Linux kernels 
1680: 73 75 70 70 6f 72 74 20 6c 61 72 67 65 20 66 69  support large fi
1690: 6c 65 73 2c 20 73 6f 0a 2a 2a 20 79 6f 75 20 73  les, so.** you s
16a0: 68 6f 75 6c 64 20 70 72 6f 62 61 62 6c 79 20 6c  hould probably l
16b0: 65 61 76 65 20 4c 46 53 20 65 6e 61 62 6c 65 64  eave LFS enabled
16c0: 2e 20 20 42 75 74 20 73 6f 6d 65 20 65 6d 62 65  .  But some embe
16d0: 64 64 65 64 20 70 6c 61 74 66 6f 72 6d 73 20 6d  dded platforms m
16e0: 69 67 68 74 0a 2a 2a 20 6c 61 63 6b 20 4c 46 53  ight.** lack LFS
16f0: 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 74   in which case t
1700: 68 65 20 53 51 4c 49 54 45 5f 44 49 53 41 42 4c  he SQLITE_DISABL
1710: 45 5f 4c 46 53 20 6d 61 63 72 6f 20 6d 69 67 68  E_LFS macro migh
1720: 74 20 73 74 69 6c 6c 20 62 65 20 75 73 65 66 75  t still be usefu
1730: 6c 2e 0a 2a 2a 0a 2a 2a 20 53 69 6d 69 6c 61 72  l..**.** Similar
1740: 20 69 73 20 74 72 75 65 20 66 6f 72 20 4d 61 63   is true for Mac
1750: 20 4f 53 20 58 2e 20 20 4c 46 53 20 69 73 20 6f   OS X.  LFS is o
1760: 6e 6c 79 20 73 75 70 70 6f 72 74 65 64 20 6f 6e  nly supported on
1770: 20 4d 61 63 20 4f 53 20 58 20 39 20 61 6e 64 20   Mac OS X 9 and 
1780: 6c 61 74 65 72 2e 0a 2a 2f 0a 23 69 66 6e 64 65  later..*/.#ifnde
1790: 66 20 53 51 4c 49 54 45 5f 44 49 53 41 42 4c 45  f SQLITE_DISABLE
17a0: 5f 4c 46 53 0a 23 20 64 65 66 69 6e 65 20 5f 4c  _LFS.# define _L
17b0: 41 52 47 45 5f 46 49 4c 45 20 20 20 20 20 20 20  ARGE_FILE       
17c0: 31 0a 23 20 69 66 6e 64 65 66 20 5f 46 49 4c 45  1.# ifndef _FILE
17d0: 5f 4f 46 46 53 45 54 5f 42 49 54 53 0a 23 20 20  _OFFSET_BITS.#  
17e0: 20 64 65 66 69 6e 65 20 5f 46 49 4c 45 5f 4f 46   define _FILE_OF
17f0: 46 53 45 54 5f 42 49 54 53 20 36 34 0a 23 20 65  FSET_BITS 64.# e
1800: 6e 64 69 66 0a 23 20 64 65 66 69 6e 65 20 5f 4c  ndif.# define _L
1810: 41 52 47 45 46 49 4c 45 5f 53 4f 55 52 43 45 20  ARGEFILE_SOURCE 
1820: 31 0a 23 65 6e 64 69 66 0a 0a 2f 2a 20 57 68 61  1.#endif../* Wha
1830: 74 20 76 65 72 73 69 6f 6e 20 6f 66 20 47 43 43  t version of GCC
1840: 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 2e 20   is being used. 
1850: 20 30 20 6d 65 61 6e 73 20 47 43 43 20 69 73 20   0 means GCC is 
1860: 6e 6f 74 20 62 65 69 6e 67 20 75 73 65 64 20 2a  not being used *
1870: 2f 0a 23 69 66 64 65 66 20 5f 5f 47 4e 55 43 5f  /.#ifdef __GNUC_
1880: 5f 0a 23 20 64 65 66 69 6e 65 20 47 43 43 5f 56  _.# define GCC_V
1890: 45 52 53 49 4f 4e 20 28 5f 5f 47 4e 55 43 5f 5f  ERSION (__GNUC__
18a0: 2a 31 30 30 30 30 30 30 2b 5f 5f 47 4e 55 43 5f  *1000000+__GNUC_
18b0: 4d 49 4e 4f 52 5f 5f 2a 31 30 30 30 2b 5f 5f 47  MINOR__*1000+__G
18c0: 4e 55 43 5f 50 41 54 43 48 4c 45 56 45 4c 5f 5f  NUC_PATCHLEVEL__
18d0: 29 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65  ).#else.# define
18e0: 20 47 43 43 5f 56 45 52 53 49 4f 4e 20 30 0a 23   GCC_VERSION 0.#
18f0: 65 6e 64 69 66 0a 0a 2f 2a 20 4e 65 65 64 65 64  endif../* Needed
1900: 20 66 6f 72 20 76 61 72 69 6f 75 73 20 64 65 66   for various def
1910: 69 6e 69 74 69 6f 6e 73 2e 2e 2e 20 2a 2f 0a 23  initions... */.#
1920: 69 66 20 64 65 66 69 6e 65 64 28 5f 5f 47 4e 55  if defined(__GNU
1930: 43 5f 5f 29 20 26 26 20 21 64 65 66 69 6e 65 64  C__) && !defined
1940: 28 5f 47 4e 55 5f 53 4f 55 52 43 45 29 0a 23 20  (_GNU_SOURCE).# 
1950: 64 65 66 69 6e 65 20 5f 47 4e 55 5f 53 4f 55 52  define _GNU_SOUR
1960: 43 45 0a 23 65 6e 64 69 66 0a 0a 23 69 66 20 64  CE.#endif..#if d
1970: 65 66 69 6e 65 64 28 5f 5f 4f 70 65 6e 42 53 44  efined(__OpenBSD
1980: 5f 5f 29 20 26 26 20 21 64 65 66 69 6e 65 64 28  __) && !defined(
1990: 5f 42 53 44 5f 53 4f 55 52 43 45 29 0a 23 20 64  _BSD_SOURCE).# d
19a0: 65 66 69 6e 65 20 5f 42 53 44 5f 53 4f 55 52 43  efine _BSD_SOURC
19b0: 45 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20  E.#endif../*.** 
19c0: 46 6f 72 20 4d 69 6e 47 57 2c 20 63 68 65 63 6b  For MinGW, check
19d0: 20 74 6f 20 73 65 65 20 69 66 20 77 65 20 63 61   to see if we ca
19e0: 6e 20 69 6e 63 6c 75 64 65 20 74 68 65 20 68 65  n include the he
19f0: 61 64 65 72 20 66 69 6c 65 20 63 6f 6e 74 61 69  ader file contai
1a00: 6e 69 6e 67 20 69 74 73 0a 2a 2a 20 76 65 72 73  ning its.** vers
1a10: 69 6f 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2c  ion information,
1a20: 20 61 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69   among other thi
1a30: 6e 67 73 2e 20 20 4e 6f 72 6d 61 6c 6c 79 2c 20  ngs.  Normally, 
1a40: 74 68 69 73 20 69 6e 74 65 72 6e 61 6c 20 4d 69  this internal Mi
1a50: 6e 47 57 0a 2a 2a 20 68 65 61 64 65 72 20 66 69  nGW.** header fi
1a60: 6c 65 20 77 6f 75 6c 64 20 5b 6f 6e 6c 79 5d 20  le would [only] 
1a70: 62 65 20 69 6e 63 6c 75 64 65 64 20 61 75 74 6f  be included auto
1a80: 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 6f 74 68  matically by oth
1a90: 65 72 20 4d 69 6e 47 57 20 68 65 61 64 65 72 0a  er MinGW header.
1aa0: 2a 2a 20 66 69 6c 65 73 3b 20 68 6f 77 65 76 65  ** files; howeve
1ab0: 72 2c 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 64  r, the contained
1ac0: 20 76 65 72 73 69 6f 6e 20 69 6e 66 6f 72 6d 61   version informa
1ad0: 74 69 6f 6e 20 69 73 20 6e 6f 77 20 72 65 71 75  tion is now requ
1ae0: 69 72 65 64 20 62 79 20 74 68 69 73 0a 2a 2a 20  ired by this.** 
1af0: 68 65 61 64 65 72 20 66 69 6c 65 20 74 6f 20 77  header file to w
1b00: 6f 72 6b 20 61 72 6f 75 6e 64 20 62 69 6e 61 72  ork around binar
1b10: 79 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20  y compatibility 
1b20: 69 73 73 75 65 73 20 28 73 65 65 20 62 65 6c 6f  issues (see belo
1b30: 77 29 20 61 6e 64 0a 2a 2a 20 74 68 69 73 20 69  w) and.** this i
1b40: 73 20 74 68 65 20 6f 6e 6c 79 20 6b 6e 6f 77 6e  s the only known
1b50: 20 77 61 79 20 74 6f 20 72 65 6c 69 61 62 6c 79   way to reliably
1b60: 20 6f 62 74 61 69 6e 20 69 74 2e 20 20 54 68 69   obtain it.  Thi
1b70: 73 20 65 6e 74 69 72 65 20 23 69 66 20 62 6c 6f  s entire #if blo
1b80: 63 6b 0a 2a 2a 20 77 6f 75 6c 64 20 62 65 20 63  ck.** would be c
1b90: 6f 6d 70 6c 65 74 65 6c 79 20 75 6e 6e 65 63 65  ompletely unnece
1ba0: 73 73 61 72 79 20 69 66 20 74 68 65 72 65 20 77  ssary if there w
1bb0: 61 73 20 61 6e 79 20 6f 74 68 65 72 20 77 61 79  as any other way
1bc0: 20 6f 66 20 64 65 74 65 63 74 69 6e 67 0a 2a 2a   of detecting.**
1bd0: 20 4d 69 6e 47 57 20 76 69 61 20 74 68 65 69 72   MinGW via their
1be0: 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 28 65   preprocessor (e
1bf0: 2e 67 2e 20 69 66 20 74 68 65 79 20 63 75 73 74  .g. if they cust
1c00: 6f 6d 69 7a 65 64 20 74 68 65 69 72 20 47 43 43  omized their GCC
1c10: 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 73 6f   to define.** so
1c20: 6d 65 20 4d 69 6e 47 57 2d 73 70 65 63 69 66 69  me MinGW-specifi
1c30: 63 20 6d 61 63 72 6f 73 29 2e 20 20 57 68 65 6e  c macros).  When
1c40: 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20 4d   compiling for M
1c50: 69 6e 47 57 2c 20 65 69 74 68 65 72 20 74 68 65  inGW, either the
1c60: 0a 2a 2a 20 5f 48 41 56 45 5f 4d 49 4e 47 57 5f  .** _HAVE_MINGW_
1c70: 48 20 6f 72 20 5f 48 41 56 45 5f 5f 4d 49 4e 47  H or _HAVE__MING
1c80: 57 5f 48 20 28 6e 6f 74 65 20 74 68 65 20 65 78  W_H (note the ex
1c90: 74 72 61 20 75 6e 64 65 72 73 63 6f 72 65 29 20  tra underscore) 
1ca0: 6d 61 63 72 6f 20 6d 75 73 74 20 62 65 0a 2a 2a  macro must be.**
1cb0: 20 64 65 66 69 6e 65 64 3b 20 6f 74 68 65 72 77   defined; otherw
1cc0: 69 73 65 2c 20 64 65 74 65 63 74 69 6f 6e 20 6f  ise, detection o
1cd0: 66 20 63 6f 6e 64 69 74 69 6f 6e 73 20 73 70 65  f conditions spe
1ce0: 63 69 66 69 63 20 74 6f 20 4d 69 6e 47 57 20 77  cific to MinGW w
1cf0: 69 6c 6c 20 62 65 0a 2a 2a 20 64 69 73 61 62 6c  ill be.** disabl
1d00: 65 64 2e 0a 2a 2f 0a 23 69 66 20 64 65 66 69 6e  ed..*/.#if defin
1d10: 65 64 28 5f 48 41 56 45 5f 4d 49 4e 47 57 5f 48  ed(_HAVE_MINGW_H
1d20: 29 0a 23 20 69 6e 63 6c 75 64 65 20 22 6d 69 6e  ).# include "min
1d30: 67 77 2e 68 22 0a 23 65 6c 69 66 20 64 65 66 69  gw.h".#elif defi
1d40: 6e 65 64 28 5f 48 41 56 45 5f 5f 4d 49 4e 47 57  ned(_HAVE__MINGW
1d50: 5f 48 29 0a 23 20 69 6e 63 6c 75 64 65 20 22 5f  _H).# include "_
1d60: 6d 69 6e 67 77 2e 68 22 0a 23 65 6e 64 69 66 0a  mingw.h".#endif.
1d70: 0a 2f 2a 0a 2a 2a 20 46 6f 72 20 4d 69 6e 47 57  ./*.** For MinGW
1d80: 20 76 65 72 73 69 6f 6e 20 34 2e 78 20 28 61 6e   version 4.x (an
1d90: 64 20 68 69 67 68 65 72 29 2c 20 63 68 65 63 6b  d higher), check
1da0: 20 74 6f 20 73 65 65 20 69 66 20 74 68 65 20 5f   to see if the _
1db0: 55 53 45 5f 33 32 42 49 54 5f 54 49 4d 45 5f 54  USE_32BIT_TIME_T
1dc0: 0a 2a 2a 20 64 65 66 69 6e 65 20 69 73 20 72 65  .** define is re
1dd0: 71 75 69 72 65 64 20 74 6f 20 6d 61 69 6e 74 61  quired to mainta
1de0: 69 6e 20 62 69 6e 61 72 79 20 63 6f 6d 70 61 74  in binary compat
1df0: 69 62 69 6c 69 74 79 20 77 69 74 68 20 74 68 65  ibility with the
1e00: 20 4d 53 56 43 20 72 75 6e 74 69 6d 65 0a 2a 2a   MSVC runtime.**
1e10: 20 6c 69 62 72 61 72 79 20 69 6e 20 75 73 65 20   library in use 
1e20: 28 65 2e 67 2e 20 66 6f 72 20 57 69 6e 64 6f 77  (e.g. for Window
1e30: 73 20 58 50 29 2e 0a 2a 2f 0a 23 69 66 20 21 64  s XP)..*/.#if !d
1e40: 65 66 69 6e 65 64 28 5f 55 53 45 5f 33 32 42 49  efined(_USE_32BI
1e50: 54 5f 54 49 4d 45 5f 54 29 20 26 26 20 21 64 65  T_TIME_T) && !de
1e60: 66 69 6e 65 64 28 5f 55 53 45 5f 36 34 42 49 54  fined(_USE_64BIT
1e70: 5f 54 49 4d 45 5f 54 29 20 26 26 20 5c 0a 20 20  _TIME_T) && \.  
1e80: 20 20 64 65 66 69 6e 65 64 28 5f 57 49 4e 33 32    defined(_WIN32
1e90: 29 20 26 26 20 21 64 65 66 69 6e 65 64 28 5f 57  ) && !defined(_W
1ea0: 49 4e 36 34 29 20 26 26 20 5c 0a 20 20 20 20 64  IN64) && \.    d
1eb0: 65 66 69 6e 65 64 28 5f 5f 4d 49 4e 47 57 5f 4d  efined(__MINGW_M
1ec0: 41 4a 4f 52 5f 56 45 52 53 49 4f 4e 29 20 26 26  AJOR_VERSION) &&
1ed0: 20 5f 5f 4d 49 4e 47 57 5f 4d 41 4a 4f 52 5f 56   __MINGW_MAJOR_V
1ee0: 45 52 53 49 4f 4e 20 3e 3d 20 34 20 26 26 20 5c  ERSION >= 4 && \
1ef0: 0a 20 20 20 20 64 65 66 69 6e 65 64 28 5f 5f 4d  .    defined(__M
1f00: 53 56 43 52 54 5f 5f 29 0a 23 20 64 65 66 69 6e  SVCRT__).# defin
1f10: 65 20 5f 55 53 45 5f 33 32 42 49 54 5f 54 49 4d  e _USE_32BIT_TIM
1f20: 45 5f 54 0a 23 65 6e 64 69 66 0a 0a 2f 2a 20 54  E_T.#endif../* T
1f30: 68 65 20 70 75 62 6c 69 63 20 53 51 4c 69 74 65  he public SQLite
1f40: 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68 65   interface.  The
1f50: 20 5f 46 49 4c 45 5f 4f 46 46 53 45 54 5f 42 49   _FILE_OFFSET_BI
1f60: 54 53 20 6d 61 63 72 6f 20 6d 75 73 74 20 61 70  TS macro must ap
1f70: 70 65 61 72 0a 2a 2a 20 66 69 72 73 74 20 69 6e  pear.** first in
1f80: 20 51 4e 58 2e 20 20 41 6c 73 6f 2c 20 74 68 65   QNX.  Also, the
1f90: 20 5f 55 53 45 5f 33 32 42 49 54 5f 54 49 4d 45   _USE_32BIT_TIME
1fa0: 5f 54 20 6d 61 63 72 6f 20 6d 75 73 74 20 61 70  _T macro must ap
1fb0: 70 65 61 72 20 66 69 72 73 74 20 66 6f 72 0a 2a  pear first for.*
1fc0: 2a 20 4d 69 6e 47 57 2e 0a 2a 2f 0a 2f 2a 2a 2a  * MinGW..*/./***
1fd0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 49 6e 63 6c  *********** Incl
1fe0: 75 64 65 20 73 71 6c 69 74 65 33 2e 68 20 69 6e  ude sqlite3.h in
1ff0: 20 74 68 65 20 6d 69 64 64 6c 65 20 6f 66 20 73   the middle of s
2000: 71 6c 69 74 65 49 6e 74 2e 68 20 2a 2a 2a 2a 2a  qliteInt.h *****
2010: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 2a 2a  **********/./***
2020: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 42 65 67 69  *********** Begi
2030: 6e 20 66 69 6c 65 20 73 71 6c 69 74 65 33 2e 68  n file sqlite3.h
2040: 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a   ***************
2050: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
2060: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 0a 2a  **********/./*.*
2070: 2a 20 32 30 30 31 20 53 65 70 74 65 6d 62 65 72  * 2001 September
2080: 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75   15.**.** The au
2090: 74 68 6f 72 20 64 69 73 63 6c 61 69 6d 73 20 63  thor disclaims c
20a0: 6f 70 79 72 69 67 68 74 20 74 6f 20 74 68 69 73  opyright to this
20b0: 20 73 6f 75 72 63 65 20 63 6f 64 65 2e 20 20 49   source code.  I
20c0: 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 61 20  n place of.** a 
20d0: 6c 65 67 61 6c 20 6e 6f 74 69 63 65 2c 20 68 65  legal notice, he
20e0: 72 65 20 69 73 20 61 20 62 6c 65 73 73 69 6e 67  re is a blessing
20f0: 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d 61 79 20 79  :.**.**    May y
2100: 6f 75 20 64 6f 20 67 6f 6f 64 20 61 6e 64 20 6e  ou do good and n
2110: 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20 20 20 20 4d  ot evil..**    M
2120: 61 79 20 79 6f 75 20 66 69 6e 64 20 66 6f 72 67  ay you find forg
2130: 69 76 65 6e 65 73 73 20 66 6f 72 20 79 6f 75 72  iveness for your
2140: 73 65 6c 66 20 61 6e 64 20 66 6f 72 67 69 76 65  self and forgive
2150: 20 6f 74 68 65 72 73 2e 0a 2a 2a 20 20 20 20 4d   others..**    M
2160: 61 79 20 79 6f 75 20 73 68 61 72 65 20 66 72 65  ay you share fre
2170: 65 6c 79 2c 20 6e 65 76 65 72 20 74 61 6b 69 6e  ely, never takin
2180: 67 20 6d 6f 72 65 20 74 68 61 6e 20 79 6f 75 20  g more than you 
2190: 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a  give..**.*******
21a0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
21b0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
21c0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
21d0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
21e0: 2a 2a 0a 2a 2a 20 54 68 69 73 20 68 65 61 64 65  **.** This heade
21f0: 72 20 66 69 6c 65 20 64 65 66 69 6e 65 73 20 74  r file defines t
2200: 68 65 20 69 6e 74 65 72 66 61 63 65 20 74 68 61  he interface tha
2210: 74 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62  t the SQLite lib
2220: 72 61 72 79 0a 2a 2a 20 70 72 65 73 65 6e 74 73  rary.** presents
2230: 20 74 6f 20 63 6c 69 65 6e 74 20 70 72 6f 67 72   to client progr
2240: 61 6d 73 2e 20 20 49 66 20 61 20 43 2d 66 75 6e  ams.  If a C-fun
2250: 63 74 69 6f 6e 2c 20 73 74 72 75 63 74 75 72 65  ction, structure
2260: 2c 20 64 61 74 61 74 79 70 65 2c 0a 2a 2a 20 6f  , datatype,.** o
2270: 72 20 63 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e  r constant defin
2280: 69 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 61  ition does not a
2290: 70 70 65 61 72 20 69 6e 20 74 68 69 73 20 66 69  ppear in this fi
22a0: 6c 65 2c 20 74 68 65 6e 20 69 74 20 69 73 0a 2a  le, then it is.*
22b0: 2a 20 6e 6f 74 20 61 20 70 75 62 6c 69 73 68 65  * not a publishe
22c0: 64 20 41 50 49 20 6f 66 20 53 51 4c 69 74 65 2c  d API of SQLite,
22d0: 20 69 73 20 73 75 62 6a 65 63 74 20 74 6f 20 63   is subject to c
22e0: 68 61 6e 67 65 20 77 69 74 68 6f 75 74 0a 2a 2a  hange without.**
22f0: 20 6e 6f 74 69 63 65 2c 20 61 6e 64 20 73 68 6f   notice, and sho
2300: 75 6c 64 20 6e 6f 74 20 62 65 20 72 65 66 65 72  uld not be refer
2310: 65 6e 63 65 64 20 62 79 20 70 72 6f 67 72 61 6d  enced by program
2320: 73 20 74 68 61 74 20 75 73 65 20 53 51 4c 69 74  s that use SQLit
2330: 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66  e..**.** Some of
2340: 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e 73   the definitions
2350: 20 74 68 61 74 20 61 72 65 20 69 6e 20 74 68 69   that are in thi
2360: 73 20 66 69 6c 65 20 61 72 65 20 6d 61 72 6b 65  s file are marke
2370: 64 20 61 73 0a 2a 2a 20 22 65 78 70 65 72 69 6d  d as.** "experim
2380: 65 6e 74 61 6c 22 2e 20 20 45 78 70 65 72 69 6d  ental".  Experim
2390: 65 6e 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73  ental interfaces
23a0: 20 61 72 65 20 6e 6f 72 6d 61 6c 6c 79 20 6e 65   are normally ne
23b0: 77 0a 2a 2a 20 66 65 61 74 75 72 65 73 20 72 65  w.** features re
23c0: 63 65 6e 74 6c 79 20 61 64 64 65 64 20 74 6f 20  cently added to 
23d0: 53 51 4c 69 74 65 2e 20 20 57 65 20 64 6f 20 6e  SQLite.  We do n
23e0: 6f 74 20 61 6e 74 69 63 69 70 61 74 65 20 63 68  ot anticipate ch
23f0: 61 6e 67 65 73 0a 2a 2a 20 74 6f 20 65 78 70 65  anges.** to expe
2400: 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66 61  rimental interfa
2410: 63 65 73 20 62 75 74 20 72 65 73 65 72 76 65 20  ces but reserve 
2420: 74 68 65 20 72 69 67 68 74 20 74 6f 20 6d 61 6b  the right to mak
2430: 65 20 6d 69 6e 6f 72 20 63 68 61 6e 67 65 73 0a  e minor changes.
2440: 2a 2a 20 69 66 20 65 78 70 65 72 69 65 6e 63 65  ** if experience
2450: 20 66 72 6f 6d 20 75 73 65 20 22 69 6e 20 74 68   from use "in th
2460: 65 20 77 69 6c 64 22 20 73 75 67 67 65 73 74 20  e wild" suggest 
2470: 73 75 63 68 20 63 68 61 6e 67 65 73 20 61 72 65  such changes are
2480: 20 70 72 75 64 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20   prudent..**.** 
2490: 54 68 65 20 6f 66 66 69 63 69 61 6c 20 43 2d 6c  The official C-l
24a0: 61 6e 67 75 61 67 65 20 41 50 49 20 64 6f 63 75  anguage API docu
24b0: 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 53 51  mentation for SQ
24c0: 4c 69 74 65 20 69 73 20 64 65 72 69 76 65 64 0a  Lite is derived.
24d0: 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d 65 6e 74 73  ** from comments
24e0: 20 69 6e 20 74 68 69 73 20 66 69 6c 65 2e 20 20   in this file.  
24f0: 54 68 69 73 20 66 69 6c 65 20 69 73 20 74 68 65  This file is the
2500: 20 61 75 74 68 6f 72 69 74 61 74 69 76 65 20 73   authoritative s
2510: 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20 68 6f 77 20  ource.** on how 
2520: 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
2530: 73 20 61 72 65 20 73 75 70 70 6f 73 65 64 20 74  s are supposed t
2540: 6f 20 6f 70 65 72 61 74 65 2e 0a 2a 2a 0a 2a 2a  o operate..**.**
2550: 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 69   The name of thi
2560: 73 20 66 69 6c 65 20 75 6e 64 65 72 20 63 6f 6e  s file under con
2570: 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67  figuration manag
2580: 65 6d 65 6e 74 20 69 73 20 22 73 71 6c 69 74 65  ement is "sqlite
2590: 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54 68 65 20 6d  .h.in"..** The m
25a0: 61 6b 65 66 69 6c 65 20 6d 61 6b 65 73 20 73 6f  akefile makes so
25b0: 6d 65 20 6d 69 6e 6f 72 20 63 68 61 6e 67 65 73  me minor changes
25c0: 20 74 6f 20 74 68 69 73 20 66 69 6c 65 20 28 73   to this file (s
25d0: 75 63 68 20 61 73 20 69 6e 73 65 72 74 69 6e 67  uch as inserting
25e0: 0a 2a 2a 20 74 68 65 20 76 65 72 73 69 6f 6e 20  .** the version 
25f0: 6e 75 6d 62 65 72 29 20 61 6e 64 20 63 68 61 6e  number) and chan
2600: 67 65 73 20 69 74 73 20 6e 61 6d 65 20 74 6f 20  ges its name to 
2610: 22 73 71 6c 69 74 65 33 2e 68 22 20 61 73 0a 2a  "sqlite3.h" as.*
2620: 2a 20 70 61 72 74 20 6f 66 20 74 68 65 20 62 75  * part of the bu
2630: 69 6c 64 20 70 72 6f 63 65 73 73 2e 0a 2a 2f 0a  ild process..*/.
2640: 23 69 66 6e 64 65 66 20 5f 53 51 4c 49 54 45 33  #ifndef _SQLITE3
2650: 5f 48 5f 0a 23 64 65 66 69 6e 65 20 5f 53 51 4c  _H_.#define _SQL
2660: 49 54 45 33 5f 48 5f 0a 23 69 6e 63 6c 75 64 65  ITE3_H_.#include
2670: 20 3c 73 74 64 61 72 67 2e 68 3e 20 20 20 20 20   <stdarg.h>     
2680: 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72 20 74 68  /* Needed for th
2690: 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 66 20  e definition of 
26a0: 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a  va_list */../*.*
26b0: 2a 20 4d 61 6b 65 20 73 75 72 65 20 77 65 20 63  * Make sure we c
26c0: 61 6e 20 63 61 6c 6c 20 74 68 69 73 20 73 74 75  an call this stu
26d0: 66 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a 2a 2f 0a  ff from C++..*/.
26e0: 23 69 66 20 30 0a 65 78 74 65 72 6e 20 22 43 22  #if 0.extern "C"
26f0: 20 7b 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a   {.#endif.../*.*
2700: 2a 20 50 72 6f 76 69 64 65 20 74 68 65 20 61 62  * Provide the ab
2710: 69 6c 69 74 79 20 74 6f 20 6f 76 65 72 72 69 64  ility to overrid
2720: 65 20 6c 69 6e 6b 61 67 65 20 66 65 61 74 75 72  e linkage featur
2730: 65 73 20 6f 66 20 74 68 65 20 69 6e 74 65 72 66  es of the interf
2740: 61 63 65 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20  ace..*/.#ifndef 
2750: 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a 23 20  SQLITE_EXTERN.# 
2760: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 58  define SQLITE_EX
2770: 54 45 52 4e 20 65 78 74 65 72 6e 0a 23 65 6e 64  TERN extern.#end
2780: 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54  if.#ifndef SQLIT
2790: 45 5f 41 50 49 0a 23 20 64 65 66 69 6e 65 20 53  E_API.# define S
27a0: 51 4c 49 54 45 5f 41 50 49 0a 23 65 6e 64 69 66  QLITE_API.#endif
27b0: 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f  .#ifndef SQLITE_
27c0: 43 44 45 43 4c 0a 23 20 64 65 66 69 6e 65 20 53  CDECL.# define S
27d0: 51 4c 49 54 45 5f 43 44 45 43 4c 0a 23 65 6e 64  QLITE_CDECL.#end
27e0: 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54  if.#ifndef SQLIT
27f0: 45 5f 53 54 44 43 41 4c 4c 0a 23 20 64 65 66 69  E_STDCALL.# defi
2800: 6e 65 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  ne SQLITE_STDCAL
2810: 4c 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20  L.#endif../*.** 
2820: 54 68 65 73 65 20 6e 6f 2d 6f 70 20 6d 61 63 72  These no-op macr
2830: 6f 73 20 61 72 65 20 75 73 65 64 20 69 6e 20 66  os are used in f
2840: 72 6f 6e 74 20 6f 66 20 69 6e 74 65 72 66 61 63  ront of interfac
2850: 65 73 20 74 6f 20 6d 61 72 6b 20 74 68 6f 73 65  es to mark those
2860: 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61  .** interfaces a
2870: 73 20 65 69 74 68 65 72 20 64 65 70 72 65 63 61  s either depreca
2880: 74 65 64 20 6f 72 20 65 78 70 65 72 69 6d 65 6e  ted or experimen
2890: 74 61 6c 2e 20 20 4e 65 77 20 61 70 70 6c 69 63  tal.  New applic
28a0: 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64  ations.** should
28b0: 20 6e 6f 74 20 75 73 65 20 64 65 70 72 65 63 61   not use depreca
28c0: 74 65 64 20 69 6e 74 65 72 66 61 63 65 73 20 2d  ted interfaces -
28d0: 20 74 68 65 79 20 61 72 65 20 73 75 70 70 6f 72   they are suppor
28e0: 74 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64  ted for backward
28f0: 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69  s.** compatibili
2900: 74 79 20 6f 6e 6c 79 2e 20 20 41 70 70 6c 69 63  ty only.  Applic
2910: 61 74 69 6f 6e 20 77 72 69 74 65 72 73 20 73 68  ation writers sh
2920: 6f 75 6c 64 20 62 65 20 61 77 61 72 65 20 74 68  ould be aware th
2930: 61 74 0a 2a 2a 20 65 78 70 65 72 69 6d 65 6e 74  at.** experiment
2940: 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  al interfaces ar
2950: 65 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61  e subject to cha
2960: 6e 67 65 20 69 6e 20 70 6f 69 6e 74 20 72 65 6c  nge in point rel
2970: 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  eases..**.** The
2980: 73 65 20 6d 61 63 72 6f 73 20 75 73 65 64 20 74  se macros used t
2990: 6f 20 72 65 73 6f 6c 76 65 20 74 6f 20 76 61 72  o resolve to var
29a0: 69 6f 75 73 20 6b 69 6e 64 73 20 6f 66 20 63 6f  ious kinds of co
29b0: 6d 70 69 6c 65 72 20 6d 61 67 69 63 20 74 68 61  mpiler magic tha
29c0: 74 0a 2a 2a 20 77 6f 75 6c 64 20 67 65 6e 65 72  t.** would gener
29d0: 61 74 65 20 77 61 72 6e 69 6e 67 20 6d 65 73 73  ate warning mess
29e0: 61 67 65 73 20 77 68 65 6e 20 74 68 65 79 20 77  ages when they w
29f0: 65 72 65 20 75 73 65 64 2e 20 20 42 75 74 20 74  ere used.  But t
2a00: 68 61 74 0a 2a 2a 20 63 6f 6d 70 69 6c 65 72 20  hat.** compiler 
2a10: 6d 61 67 69 63 20 65 6e 64 65 64 20 75 70 20 67  magic ended up g
2a20: 65 6e 65 72 61 74 69 6e 67 20 73 75 63 68 20 61  enerating such a
2a30: 20 66 6c 75 72 72 79 20 6f 66 20 62 75 67 20 72   flurry of bug r
2a40: 65 70 6f 72 74 73 0a 2a 2a 20 74 68 61 74 20 77  eports.** that w
2a50: 65 20 68 61 76 65 20 74 61 6b 65 6e 20 69 74 20  e have taken it 
2a60: 61 6c 6c 20 6f 75 74 20 61 6e 64 20 67 6f 6e 65  all out and gone
2a70: 20 62 61 63 6b 20 74 6f 20 75 73 69 6e 67 20 73   back to using s
2a80: 69 6d 70 6c 65 0a 2a 2a 20 6e 6f 6f 70 20 6d 61  imple.** noop ma
2a90: 63 72 6f 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  cros..*/.#define
2aa0: 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54   SQLITE_DEPRECAT
2ab0: 45 44 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  ED.#define SQLIT
2ac0: 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 0a  E_EXPERIMENTAL..
2ad0: 2f 2a 0a 2a 2a 20 45 6e 73 75 72 65 20 74 68 65  /*.** Ensure the
2ae0: 73 65 20 73 79 6d 62 6f 6c 73 20 77 65 72 65 20  se symbols were 
2af0: 6e 6f 74 20 64 65 66 69 6e 65 64 20 62 79 20 73  not defined by s
2b00: 6f 6d 65 20 70 72 65 76 69 6f 75 73 20 68 65 61  ome previous hea
2b10: 64 65 72 20 66 69 6c 65 2e 0a 2a 2f 0a 23 69 66  der file..*/.#if
2b20: 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49  def SQLITE_VERSI
2b30: 4f 4e 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54  ON.# undef SQLIT
2b40: 45 5f 56 45 52 53 49 4f 4e 0a 23 65 6e 64 69 66  E_VERSION.#endif
2b50: 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 56  .#ifdef SQLITE_V
2b60: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23 20  ERSION_NUMBER.# 
2b70: 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52  undef SQLITE_VER
2b80: 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23 65 6e 64  SION_NUMBER.#end
2b90: 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  if../*.** CAPI3R
2ba0: 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65  EF: Compile-Time
2bb0: 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f 6e   Library Version
2bc0: 20 4e 75 6d 62 65 72 73 0a 2a 2a 0a 2a 2a 20 5e   Numbers.**.** ^
2bd0: 28 54 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52  (The [SQLITE_VER
2be0: 53 49 4f 4e 5d 20 43 20 70 72 65 70 72 6f 63 65  SION] C preproce
2bf0: 73 73 6f 72 20 6d 61 63 72 6f 20 69 6e 20 74 68  ssor macro in th
2c00: 65 20 73 71 6c 69 74 65 33 2e 68 20 68 65 61 64  e sqlite3.h head
2c10: 65 72 0a 2a 2a 20 65 76 61 6c 75 61 74 65 73 20  er.** evaluates 
2c20: 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65  to a string lite
2c30: 72 61 6c 20 74 68 61 74 20 69 73 20 74 68 65 20  ral that is the 
2c40: 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 69  SQLite version i
2c50: 6e 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 61 74 20  n the.** format 
2c60: 22 58 2e 59 2e 5a 22 20 77 68 65 72 65 20 58 20  "X.Y.Z" where X 
2c70: 69 73 20 74 68 65 20 6d 61 6a 6f 72 20 76 65 72  is the major ver
2c80: 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 61 6c 77  sion number (alw
2c90: 61 79 73 20 33 20 66 6f 72 0a 2a 2a 20 53 51 4c  ays 3 for.** SQL
2ca0: 69 74 65 33 29 20 61 6e 64 20 59 20 69 73 20 74  ite3) and Y is t
2cb0: 68 65 20 6d 69 6e 6f 72 20 76 65 72 73 69 6f 6e  he minor version
2cc0: 20 6e 75 6d 62 65 72 20 61 6e 64 20 5a 20 69 73   number and Z is
2cd0: 20 74 68 65 20 72 65 6c 65 61 73 65 20 6e 75 6d   the release num
2ce0: 62 65 72 2e 29 5e 0a 2a 2a 20 5e 28 54 68 65 20  ber.)^.** ^(The 
2cf0: 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f  [SQLITE_VERSION_
2d00: 4e 55 4d 42 45 52 5d 20 43 20 70 72 65 70 72 6f  NUMBER] C prepro
2d10: 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 72 65 73  cessor macro res
2d20: 6f 6c 76 65 73 20 74 6f 20 61 6e 20 69 6e 74 65  olves to an inte
2d30: 67 65 72 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ger.** with the 
2d40: 76 61 6c 75 65 20 28 58 2a 31 30 30 30 30 30 30  value (X*1000000
2d50: 20 2b 20 59 2a 31 30 30 30 20 2b 20 5a 29 20 77   + Y*1000 + Z) w
2d60: 68 65 72 65 20 58 2c 20 59 2c 20 61 6e 64 20 5a  here X, Y, and Z
2d70: 20 61 72 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a   are the same.**
2d80: 20 6e 75 6d 62 65 72 73 20 75 73 65 64 20 69 6e   numbers used in
2d90: 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e   [SQLITE_VERSION
2da0: 5d 2e 29 5e 0a 2a 2a 20 54 68 65 20 53 51 4c 49  ].)^.** The SQLI
2db0: 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45  TE_VERSION_NUMBE
2dc0: 52 20 66 6f 72 20 61 6e 79 20 67 69 76 65 6e 20  R for any given 
2dd0: 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74  release of SQLit
2de0: 65 20 77 69 6c 6c 20 61 6c 73 6f 0a 2a 2a 20 62  e will also.** b
2df0: 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20 74 68  e larger than th
2e00: 65 20 72 65 6c 65 61 73 65 20 66 72 6f 6d 20 77  e release from w
2e10: 68 69 63 68 20 69 74 20 69 73 20 64 65 72 69 76  hich it is deriv
2e20: 65 64 2e 20 20 45 69 74 68 65 72 20 59 20 77 69  ed.  Either Y wi
2e30: 6c 6c 0a 2a 2a 20 62 65 20 68 65 6c 64 20 63 6f  ll.** be held co
2e40: 6e 73 74 61 6e 74 20 61 6e 64 20 5a 20 77 69 6c  nstant and Z wil
2e50: 6c 20 62 65 20 69 6e 63 72 65 6d 65 6e 74 65 64  l be incremented
2e60: 20 6f 72 20 65 6c 73 65 20 59 20 77 69 6c 6c 20   or else Y will 
2e70: 62 65 20 69 6e 63 72 65 6d 65 6e 74 65 64 0a 2a  be incremented.*
2e80: 2a 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65 20  * and Z will be 
2e90: 72 65 73 65 74 20 74 6f 20 7a 65 72 6f 2e 0a 2a  reset to zero..*
2ea0: 2a 0a 2a 2a 20 53 69 6e 63 65 20 76 65 72 73 69  *.** Since versi
2eb0: 6f 6e 20 33 2e 36 2e 31 38 2c 20 53 51 4c 69 74  on 3.6.18, SQLit
2ec0: 65 20 73 6f 75 72 63 65 20 63 6f 64 65 20 68 61  e source code ha
2ed0: 73 20 62 65 65 6e 20 73 74 6f 72 65 64 20 69 6e  s been stored in
2ee0: 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d   the.** <a href=
2ef0: 22 68 74 74 70 3a 2f 2f 77 77 77 2e 66 6f 73 73  "http://www.foss
2f00: 69 6c 2d 73 63 6d 2e 6f 72 67 2f 22 3e 46 6f 73  il-scm.org/">Fos
2f10: 73 69 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  sil configuratio
2f20: 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 0a 2a 2a 20  n management.** 
2f30: 73 79 73 74 65 6d 3c 2f 61 3e 2e 20 20 5e 54 68  system</a>.  ^Th
2f40: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  e SQLITE_SOURCE_
2f50: 49 44 20 6d 61 63 72 6f 20 65 76 61 6c 75 61 74  ID macro evaluat
2f60: 65 73 20 74 6f 0a 2a 2a 20 61 20 73 74 72 69 6e  es to.** a strin
2f70: 67 20 77 68 69 63 68 20 69 64 65 6e 74 69 66 69  g which identifi
2f80: 65 73 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  es a particular 
2f90: 63 68 65 63 6b 2d 69 6e 20 6f 66 20 53 51 4c 69  check-in of SQLi
2fa0: 74 65 0a 2a 2a 20 77 69 74 68 69 6e 20 69 74 73  te.** within its
2fb0: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d   configuration m
2fc0: 61 6e 61 67 65 6d 65 6e 74 20 73 79 73 74 65 6d  anagement system
2fd0: 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 53  .  ^The SQLITE_S
2fe0: 4f 55 52 43 45 5f 49 44 0a 2a 2a 20 73 74 72 69  OURCE_ID.** stri
2ff0: 6e 67 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20  ng contains the 
3000: 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 6f 66  date and time of
3010: 20 74 68 65 20 63 68 65 63 6b 2d 69 6e 20 28 55   the check-in (U
3020: 54 43 29 20 61 6e 64 20 61 6e 20 53 48 41 31 0a  TC) and an SHA1.
3030: 2a 2a 20 68 61 73 68 20 6f 66 20 74 68 65 20 65  ** hash of the e
3040: 6e 74 69 72 65 20 73 6f 75 72 63 65 20 74 72 65  ntire source tre
3050: 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  e..**.** See als
3060: 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76  o: [sqlite3_libv
3070: 65 72 73 69 6f 6e 28 29 5d 2c 0a 2a 2a 20 5b 73  ersion()],.** [s
3080: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
3090: 6e 5f 6e 75 6d 62 65 72 28 29 5d 2c 20 5b 73 71  n_number()], [sq
30a0: 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29  lite3_sourceid()
30b0: 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 76 65  ],.** [sqlite_ve
30c0: 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  rsion()] and [sq
30d0: 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29  lite_source_id()
30e0: 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ]..*/.#define SQ
30f0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 20 20 20  LITE_VERSION    
3100: 20 20 20 20 22 33 2e 39 2e 30 22 0a 23 64 65 66      "3.9.0".#def
3110: 69 6e 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49  ine SQLITE_VERSI
3120: 4f 4e 5f 4e 55 4d 42 45 52 20 33 30 30 39 30 30  ON_NUMBER 300900
3130: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
3140: 5f 53 4f 55 52 43 45 5f 49 44 20 20 20 20 20 20  _SOURCE_ID      
3150: 22 32 30 31 35 2d 31 30 2d 31 34 20 31 32 3a 32  "2015-10-14 12:2
3160: 39 3a 35 33 20 61 37 32 31 66 63 30 64 38 39 34  9:53 a721fc0d894
3170: 39 35 35 31 38 66 65 35 36 31 32 65 32 65 33 62  95518fe5612e2e3b
3180: 62 63 36 30 62 65 66 64 32 65 39 30 64 22 0a 0a  bc60befd2e90d"..
3190: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
31a0: 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 79  Run-Time Library
31b0: 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73   Version Numbers
31c0: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71  .** KEYWORDS: sq
31d0: 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 2c 20 73  lite3_version, s
31e0: 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 0a  qlite3_sourceid.
31f0: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65  **.** These inte
3200: 72 66 61 63 65 73 20 70 72 6f 76 69 64 65 20 74  rfaces provide t
3210: 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74  he same informat
3220: 69 6f 6e 20 61 73 20 74 68 65 20 5b 53 51 4c 49  ion as the [SQLI
3230: 54 45 5f 56 45 52 53 49 4f 4e 5d 2c 0a 2a 2a 20  TE_VERSION],.** 
3240: 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f  [SQLITE_VERSION_
3250: 4e 55 4d 42 45 52 5d 2c 20 61 6e 64 20 5b 53 51  NUMBER], and [SQ
3260: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20  LITE_SOURCE_ID] 
3270: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
3280: 61 63 72 6f 73 0a 2a 2a 20 62 75 74 20 61 72 65  acros.** but are
3290: 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
32a0: 20 74 68 65 20 6c 69 62 72 61 72 79 20 69 6e 73   the library ins
32b0: 74 65 61 64 20 6f 66 20 74 68 65 20 68 65 61 64  tead of the head
32c0: 65 72 20 66 69 6c 65 2e 20 20 5e 28 43 61 75 74  er file.  ^(Caut
32d0: 69 6f 75 73 0a 2a 2a 20 70 72 6f 67 72 61 6d 6d  ious.** programm
32e0: 65 72 73 20 6d 69 67 68 74 20 69 6e 63 6c 75 64  ers might includ
32f0: 65 20 61 73 73 65 72 74 28 29 20 73 74 61 74 65  e assert() state
3300: 6d 65 6e 74 73 20 69 6e 20 74 68 65 69 72 20 61  ments in their a
3310: 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 0a 2a 2a  pplication to.**
3320: 20 76 65 72 69 66 79 20 74 68 61 74 20 76 61 6c   verify that val
3330: 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ues returned by 
3340: 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73  these interfaces
3350: 20 6d 61 74 63 68 20 74 68 65 20 6d 61 63 72 6f   match the macro
3360: 73 20 69 6e 0a 2a 2a 20 74 68 65 20 68 65 61 64  s in.** the head
3370: 65 72 2c 20 61 6e 64 20 74 68 75 73 20 65 6e 73  er, and thus ens
3380: 75 72 65 20 74 68 61 74 20 74 68 65 20 61 70 70  ure that the app
3390: 6c 69 63 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 63  lication is.** c
33a0: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6d 61 74  ompiled with mat
33b0: 63 68 69 6e 67 20 6c 69 62 72 61 72 79 20 61 6e  ching library an
33c0: 64 20 68 65 61 64 65 72 20 66 69 6c 65 73 2e 0a  d header files..
33d0: 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
33e0: 65 3e 3c 70 72 65 3e 0a 2a 2a 20 61 73 73 65 72  e><pre>.** asser
33f0: 74 28 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  t( sqlite3_libve
3400: 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 3d 3d  rsion_number()==
3410: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
3420: 55 4d 42 45 52 20 29 3b 0a 2a 2a 20 61 73 73 65  UMBER );.** asse
3430: 72 74 28 20 73 74 72 63 6d 70 28 73 71 6c 69 74  rt( strcmp(sqlit
3440: 65 33 5f 73 6f 75 72 63 65 69 64 28 29 2c 53 51  e3_sourceid(),SQ
3450: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 29 3d  LITE_SOURCE_ID)=
3460: 3d 30 20 29 3b 0a 2a 2a 20 61 73 73 65 72 74 28  =0 );.** assert(
3470: 20 73 74 72 63 6d 70 28 73 71 6c 69 74 65 33 5f   strcmp(sqlite3_
3480: 6c 69 62 76 65 72 73 69 6f 6e 28 29 2c 53 51 4c  libversion(),SQL
3490: 49 54 45 5f 56 45 52 53 49 4f 4e 29 3d 3d 30 20  ITE_VERSION)==0 
34a0: 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  );.** </pre></bl
34b0: 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a  ockquote>)^.**.*
34c0: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76  * ^The sqlite3_v
34d0: 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e 67 20  ersion[] string 
34e0: 63 6f 6e 73 74 61 6e 74 20 63 6f 6e 74 61 69 6e  constant contain
34f0: 73 20 74 68 65 20 74 65 78 74 20 6f 66 20 5b 53  s the text of [S
3500: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 0a 2a  QLITE_VERSION].*
3510: 2a 20 6d 61 63 72 6f 2e 20 20 5e 54 68 65 20 73  * macro.  ^The s
3520: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
3530: 6e 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  n() function ret
3540: 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
3550: 6f 20 74 68 65 0a 2a 2a 20 74 6f 20 74 68 65 20  o the.** to the 
3560: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b  sqlite3_version[
3570: 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e  ] string constan
3580: 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  t.  The sqlite3_
3590: 6c 69 62 76 65 72 73 69 6f 6e 28 29 0a 2a 2a 20  libversion().** 
35a0: 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 72 6f 76  function is prov
35b0: 69 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20  ided for use in 
35c0: 44 4c 4c 73 20 73 69 6e 63 65 20 44 4c 4c 20 75  DLLs since DLL u
35d0: 73 65 72 73 20 75 73 75 61 6c 6c 79 20 64 6f 20  sers usually do 
35e0: 6e 6f 74 20 68 61 76 65 0a 2a 2a 20 64 69 72 65  not have.** dire
35f0: 63 74 20 61 63 63 65 73 73 20 74 6f 20 73 74 72  ct access to str
3600: 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 20 77 69  ing constants wi
3610: 74 68 69 6e 20 74 68 65 20 44 4c 4c 2e 20 20 5e  thin the DLL.  ^
3620: 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6c  The.** sqlite3_l
3630: 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72  ibversion_number
3640: 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  () function retu
3650: 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 65  rns an integer e
3660: 71 75 61 6c 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49  qual to.** [SQLI
3670: 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45  TE_VERSION_NUMBE
3680: 52 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  R].  ^The sqlite
3690: 33 5f 73 6f 75 72 63 65 69 64 28 29 20 66 75 6e  3_sourceid() fun
36a0: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 0a 2a  ction returns .*
36b0: 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  * a pointer to a
36c0: 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74   string constant
36d0: 20 77 68 6f 73 65 20 76 61 6c 75 65 20 69 73 20   whose value is 
36e0: 74 68 65 20 73 61 6d 65 20 61 73 20 74 68 65 20  the same as the 
36f0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 4f 55 52  .** [SQLITE_SOUR
3700: 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72 6f 63  CE_ID] C preproc
3710: 65 73 73 6f 72 20 6d 61 63 72 6f 2e 0a 2a 2a 0a  essor macro..**.
3720: 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
3730: 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28 29 5d 20  lite_version()] 
3740: 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73 6f 75 72  and [sqlite_sour
3750: 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a 53 51 4c  ce_id()]..*/.SQL
3760: 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68  ITE_API const ch
3770: 61 72 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69  ar sqlite3_versi
3780: 6f 6e 5b 5d 20 3d 20 53 51 4c 49 54 45 5f 56 45  on[] = SQLITE_VE
3790: 52 53 49 4f 4e 3b 0a 53 51 4c 49 54 45 5f 41 50  RSION;.SQLITE_AP
37a0: 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51  I const char *SQ
37b0: 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
37c0: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28  ite3_libversion(
37d0: 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50  void);.SQLITE_AP
37e0: 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51  I const char *SQ
37f0: 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
3800: 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 76 6f  ite3_sourceid(vo
3810: 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  id);.SQLITE_API 
3820: 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41  int SQLITE_STDCA
3830: 4c 4c 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  LL sqlite3_libve
3840: 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69  rsion_number(voi
3850: 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  d);../*.** CAPI3
3860: 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69  REF: Run-Time Li
3870: 62 72 61 72 79 20 43 6f 6d 70 69 6c 61 74 69 6f  brary Compilatio
3880: 6e 20 4f 70 74 69 6f 6e 73 20 44 69 61 67 6e 6f  n Options Diagno
3890: 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  stics.**.** ^The
38a0: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
38b0: 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 20 66 75  option_used() fu
38c0: 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 30  nction returns 0
38d0: 20 6f 72 20 31 20 0a 2a 2a 20 69 6e 64 69 63 61   or 1 .** indica
38e0: 74 69 6e 67 20 77 68 65 74 68 65 72 20 74 68 65  ting whether the
38f0: 20 73 70 65 63 69 66 69 65 64 20 6f 70 74 69 6f   specified optio
3900: 6e 20 77 61 73 20 64 65 66 69 6e 65 64 20 61 74  n was defined at
3910: 20 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 69 6d   .** compile tim
3920: 65 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f  e.  ^The SQLITE_
3930: 20 70 72 65 66 69 78 20 6d 61 79 20 62 65 20 6f   prefix may be o
3940: 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20  mitted from the 
3950: 0a 2a 2a 20 6f 70 74 69 6f 6e 20 6e 61 6d 65 20  .** option name 
3960: 70 61 73 73 65 64 20 74 6f 20 73 71 6c 69 74 65  passed to sqlite
3970: 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  3_compileoption_
3980: 75 73 65 64 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20  used().  .**.** 
3990: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d  ^The sqlite3_com
39a0: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29  pileoption_get()
39b0: 20 66 75 6e 63 74 69 6f 6e 20 61 6c 6c 6f 77 73   function allows
39c0: 20 69 74 65 72 61 74 69 6e 67 0a 2a 2a 20 6f 76   iterating.** ov
39d0: 65 72 20 74 68 65 20 6c 69 73 74 20 6f 66 20 6f  er the list of o
39e0: 70 74 69 6f 6e 73 20 74 68 61 74 20 77 65 72 65  ptions that were
39f0: 20 64 65 66 69 6e 65 64 20 61 74 20 63 6f 6d 70   defined at comp
3a00: 69 6c 65 20 74 69 6d 65 20 62 79 0a 2a 2a 20 72  ile time by.** r
3a10: 65 74 75 72 6e 69 6e 67 20 74 68 65 20 4e 2d 74  eturning the N-t
3a20: 68 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 20 6f  h compile time o
3a30: 70 74 69 6f 6e 20 73 74 72 69 6e 67 2e 20 20 5e  ption string.  ^
3a40: 49 66 20 4e 20 69 73 20 6f 75 74 20 6f 66 20 72  If N is out of r
3a50: 61 6e 67 65 2c 0a 2a 2a 20 73 71 6c 69 74 65 33  ange,.** sqlite3
3a60: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67  _compileoption_g
3a70: 65 74 28 29 20 72 65 74 75 72 6e 73 20 61 20 4e  et() returns a N
3a80: 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54  ULL pointer.  ^T
3a90: 68 65 20 53 51 4c 49 54 45 5f 20 0a 2a 2a 20 70  he SQLITE_ .** p
3aa0: 72 65 66 69 78 20 69 73 20 6f 6d 69 74 74 65 64  refix is omitted
3ab0: 20 66 72 6f 6d 20 61 6e 79 20 73 74 72 69 6e 67   from any string
3ac0: 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 0a 2a  s returned by .*
3ad0: 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c  * sqlite3_compil
3ae0: 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a  eoption_get()..*
3af0: 2a 0a 2a 2a 20 5e 53 75 70 70 6f 72 74 20 66 6f  *.** ^Support fo
3b00: 72 20 74 68 65 20 64 69 61 67 6e 6f 73 74 69 63  r the diagnostic
3b10: 20 66 75 6e 63 74 69 6f 6e 73 20 73 71 6c 69 74   functions sqlit
3b20: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e  e3_compileoption
3b30: 5f 75 73 65 64 28 29 0a 2a 2a 20 61 6e 64 20 73  _used().** and s
3b40: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
3b50: 74 69 6f 6e 5f 67 65 74 28 29 20 6d 61 79 20 62  tion_get() may b
3b60: 65 20 6f 6d 69 74 74 65 64 20 62 79 20 73 70 65  e omitted by spe
3b70: 63 69 66 79 69 6e 67 20 74 68 65 20 0a 2a 2a 20  cifying the .** 
3b80: 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d  [SQLITE_OMIT_COM
3b90: 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53  PILEOPTION_DIAGS
3ba0: 5d 20 6f 70 74 69 6f 6e 20 61 74 20 63 6f 6d 70  ] option at comp
3bb0: 69 6c 65 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20  ile time..**.** 
3bc0: 53 65 65 20 61 6c 73 6f 3a 20 53 51 4c 20 66 75  See also: SQL fu
3bd0: 6e 63 74 69 6f 6e 73 20 5b 73 71 6c 69 74 65 5f  nctions [sqlite_
3be0: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
3bf0: 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71  ed()] and.** [sq
3c00: 6c 69 74 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  lite_compileopti
3c10: 6f 6e 5f 67 65 74 28 29 5d 20 61 6e 64 20 74 68  on_get()] and th
3c20: 65 20 5b 63 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f  e [compile_optio
3c30: 6e 73 20 70 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23  ns pragma]..*/.#
3c40: 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d  ifndef SQLITE_OM
3c50: 49 54 5f 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e  IT_COMPILEOPTION
3c60: 5f 44 49 41 47 53 0a 53 51 4c 49 54 45 5f 41 50  _DIAGS.SQLITE_AP
3c70: 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  I int SQLITE_STD
3c80: 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6d  CALL sqlite3_com
3c90: 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28  pileoption_used(
3ca0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4f 70 74  const char *zOpt
3cb0: 4e 61 6d 65 29 3b 0a 53 51 4c 49 54 45 5f 41 50  Name);.SQLITE_AP
3cc0: 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51  I const char *SQ
3cd0: 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
3ce0: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
3cf0: 6f 6e 5f 67 65 74 28 69 6e 74 20 4e 29 3b 0a 23  on_get(int N);.#
3d00: 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  endif../*.** CAP
3d10: 49 33 52 45 46 3a 20 54 65 73 74 20 54 6f 20 53  I3REF: Test To S
3d20: 65 65 20 49 66 20 54 68 65 20 4c 69 62 72 61 72  ee If The Librar
3d30: 79 20 49 73 20 54 68 72 65 61 64 73 61 66 65 0a  y Is Threadsafe.
3d40: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
3d50: 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 20  e3_threadsafe() 
3d60: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
3d70: 20 7a 65 72 6f 20 69 66 20 61 6e 64 20 6f 6e 6c   zero if and onl
3d80: 79 20 69 66 0a 2a 2a 20 53 51 4c 69 74 65 20 77  y if.** SQLite w
3d90: 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  as compiled with
3da0: 20 6d 75 74 65 78 69 6e 67 20 63 6f 64 65 20 6f   mutexing code o
3db0: 6d 69 74 74 65 64 20 64 75 65 20 74 6f 20 74 68  mitted due to th
3dc0: 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52  e.** [SQLITE_THR
3dd0: 45 41 44 53 41 46 45 5d 20 63 6f 6d 70 69 6c 65  EADSAFE] compile
3de0: 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 62 65 69  -time option bei
3df0: 6e 67 20 73 65 74 20 74 6f 20 30 2e 0a 2a 2a 0a  ng set to 0..**.
3e00: 2a 2a 20 53 51 4c 69 74 65 20 63 61 6e 20 62 65  ** SQLite can be
3e10: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6f   compiled with o
3e20: 72 20 77 69 74 68 6f 75 74 20 6d 75 74 65 78 65  r without mutexe
3e30: 73 2e 20 20 57 68 65 6e 0a 2a 2a 20 74 68 65 20  s.  When.** the 
3e40: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
3e50: 46 45 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73  FE] C preprocess
3e60: 6f 72 20 6d 61 63 72 6f 20 69 73 20 31 20 6f 72  or macro is 1 or
3e70: 20 32 2c 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61   2, mutexes.** a
3e80: 72 65 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 53  re enabled and S
3e90: 51 4c 69 74 65 20 69 73 20 74 68 72 65 61 64 73  QLite is threads
3ea0: 61 66 65 2e 20 20 57 68 65 6e 20 74 68 65 0a 2a  afe.  When the.*
3eb0: 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  * [SQLITE_THREAD
3ec0: 53 41 46 45 5d 20 6d 61 63 72 6f 20 69 73 20 30  SAFE] macro is 0
3ed0: 2c 20 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65  , .** the mutexe
3ee0: 73 20 61 72 65 20 6f 6d 69 74 74 65 64 2e 20 20  s are omitted.  
3ef0: 57 69 74 68 6f 75 74 20 74 68 65 20 6d 75 74 65  Without the mute
3f00: 78 65 73 2c 20 69 74 20 69 73 20 6e 6f 74 20 73  xes, it is not s
3f10: 61 66 65 0a 2a 2a 20 74 6f 20 75 73 65 20 53 51  afe.** to use SQ
3f20: 4c 69 74 65 20 63 6f 6e 63 75 72 72 65 6e 74 6c  Lite concurrentl
3f30: 79 20 66 72 6f 6d 20 6d 6f 72 65 20 74 68 61 6e  y from more than
3f40: 20 6f 6e 65 20 74 68 72 65 61 64 2e 0a 2a 2a 0a   one thread..**.
3f50: 2a 2a 20 45 6e 61 62 6c 69 6e 67 20 6d 75 74 65  ** Enabling mute
3f60: 78 65 73 20 69 6e 63 75 72 73 20 61 20 6d 65 61  xes incurs a mea
3f70: 73 75 72 61 62 6c 65 20 70 65 72 66 6f 72 6d 61  surable performa
3f80: 6e 63 65 20 70 65 6e 61 6c 74 79 2e 0a 2a 2a 20  nce penalty..** 
3f90: 53 6f 20 69 66 20 73 70 65 65 64 20 69 73 20 6f  So if speed is o
3fa0: 66 20 75 74 6d 6f 73 74 20 69 6d 70 6f 72 74 61  f utmost importa
3fb0: 6e 63 65 2c 20 69 74 20 6d 61 6b 65 73 20 73 65  nce, it makes se
3fc0: 6e 73 65 20 74 6f 20 64 69 73 61 62 6c 65 0a 2a  nse to disable.*
3fd0: 2a 20 74 68 65 20 6d 75 74 65 78 65 73 2e 20 20  * the mutexes.  
3fe0: 42 75 74 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20  But for maximum 
3ff0: 73 61 66 65 74 79 2c 20 6d 75 74 65 78 65 73 20  safety, mutexes 
4000: 73 68 6f 75 6c 64 20 62 65 20 65 6e 61 62 6c 65  should be enable
4010: 64 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75  d..** ^The defau
4020: 6c 74 20 62 65 68 61 76 69 6f 72 20 69 73 20 66  lt behavior is f
4030: 6f 72 20 6d 75 74 65 78 65 73 20 74 6f 20 62 65  or mutexes to be
4040: 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20   enabled..**.** 
4050: 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63  This interface c
4060: 61 6e 20 62 65 20 75 73 65 64 20 62 79 20 61 6e  an be used by an
4070: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20   application to 
4080: 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 20 74  make sure that t
4090: 68 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66  he.** version of
40a0: 20 53 51 4c 69 74 65 20 74 68 61 74 20 69 74 20   SQLite that it 
40b0: 69 73 20 6c 69 6e 6b 69 6e 67 20 61 67 61 69 6e  is linking again
40c0: 73 74 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20  st was compiled 
40d0: 77 69 74 68 0a 2a 2a 20 74 68 65 20 64 65 73 69  with.** the desi
40e0: 72 65 64 20 73 65 74 74 69 6e 67 20 6f 66 20 74  red setting of t
40f0: 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
4100: 44 53 41 46 45 5d 20 6d 61 63 72 6f 2e 0a 2a 2a  DSAFE] macro..**
4110: 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61  .** This interfa
4120: 63 65 20 6f 6e 6c 79 20 72 65 70 6f 72 74 73 20  ce only reports 
4130: 6f 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74  on the compile-t
4140: 69 6d 65 20 6d 75 74 65 78 20 73 65 74 74 69 6e  ime mutex settin
4150: 67 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c  g.** of the [SQL
4160: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20  ITE_THREADSAFE] 
4170: 66 6c 61 67 2e 20 20 49 66 20 53 51 4c 69 74 65  flag.  If SQLite
4180: 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
4190: 68 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 48 52 45  h.** SQLITE_THRE
41a0: 41 44 53 41 46 45 3d 31 20 6f 72 20 3d 32 20 74  ADSAFE=1 or =2 t
41b0: 68 65 6e 20 6d 75 74 65 78 65 73 20 61 72 65 20  hen mutexes are 
41c0: 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  enabled by defau
41d0: 6c 74 20 62 75 74 0a 2a 2a 20 63 61 6e 20 62 65  lt but.** can be
41e0: 20 66 75 6c 6c 79 20 6f 72 20 70 61 72 74 69 61   fully or partia
41f0: 6c 6c 79 20 64 69 73 61 62 6c 65 64 20 75 73 69  lly disabled usi
4200: 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71  ng a call to [sq
4210: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 0a  lite3_config()].
4220: 2a 2a 20 77 69 74 68 20 74 68 65 20 76 65 72 62  ** with the verb
4230: 73 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  s [SQLITE_CONFIG
4240: 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 2c 20  _SINGLETHREAD], 
4250: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
4260: 55 4c 54 49 54 48 52 45 41 44 5d 2c 0a 2a 2a 20  ULTITHREAD],.** 
4270: 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  or [SQLITE_CONFI
4280: 47 5f 53 45 52 49 41 4c 49 5a 45 44 5d 2e 20 20  G_SERIALIZED].  
4290: 5e 28 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c  ^(The return val
42a0: 75 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 71 6c  ue of the.** sql
42b0: 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28  ite3_threadsafe(
42c0: 29 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 77 73  ) function shows
42d0: 20 6f 6e 6c 79 20 74 68 65 20 63 6f 6d 70 69 6c   only the compil
42e0: 65 2d 74 69 6d 65 20 73 65 74 74 69 6e 67 20 6f  e-time setting o
42f0: 66 0a 2a 2a 20 74 68 72 65 61 64 20 73 61 66 65  f.** thread safe
4300: 74 79 2c 20 6e 6f 74 20 61 6e 79 20 72 75 6e 2d  ty, not any run-
4310: 74 69 6d 65 20 63 68 61 6e 67 65 73 20 74 6f 20  time changes to 
4320: 74 68 61 74 20 73 65 74 74 69 6e 67 20 6d 61 64  that setting mad
4330: 65 20 62 79 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  e by.** sqlite3_
4340: 63 6f 6e 66 69 67 28 29 2e 20 49 6e 20 6f 74 68  config(). In oth
4350: 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 72 65  er words, the re
4360: 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20  turn value from 
4370: 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61  sqlite3_threadsa
4380: 66 65 28 29 0a 2a 2a 20 69 73 20 75 6e 63 68 61  fe().** is uncha
4390: 6e 67 65 64 20 62 79 20 63 61 6c 6c 73 20 74 6f  nged by calls to
43a0: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
43b0: 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 74  ).)^.**.** See t
43c0: 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  he [threading mo
43d0: 64 65 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f  de] documentatio
43e0: 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  n for additional
43f0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f   information..*/
4400: 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
4410: 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
4420: 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66  qlite3_threadsaf
4430: 65 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20  e(void);../*.** 
4440: 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61  CAPI3REF: Databa
4450: 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 48 61  se Connection Ha
4460: 6e 64 6c 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ndle.** KEYWORDS
4470: 3a 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  : {database conn
4480: 65 63 74 69 6f 6e 7d 20 7b 64 61 74 61 62 61 73  ection} {databas
4490: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 7d 0a 2a  e connections}.*
44a0: 2a 0a 2a 2a 20 45 61 63 68 20 6f 70 65 6e 20 53  *.** Each open S
44b0: 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 69  QLite database i
44c0: 73 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79  s represented by
44d0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
44e0: 20 69 6e 73 74 61 6e 63 65 20 6f 66 0a 2a 2a 20   instance of.** 
44f0: 74 68 65 20 6f 70 61 71 75 65 20 73 74 72 75 63  the opaque struc
4500: 74 75 72 65 20 6e 61 6d 65 64 20 22 73 71 6c 69  ture named "sqli
4510: 74 65 33 22 2e 20 20 49 74 20 69 73 20 75 73 65  te3".  It is use
4520: 66 75 6c 20 74 6f 20 74 68 69 6e 6b 20 6f 66 20  ful to think of 
4530: 61 6e 20 73 71 6c 69 74 65 33 0a 2a 2a 20 70 6f  an sqlite3.** po
4540: 69 6e 74 65 72 20 61 73 20 61 6e 20 6f 62 6a 65  inter as an obje
4550: 63 74 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65  ct.  The [sqlite
4560: 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69  3_open()], [sqli
4570: 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61  te3_open16()], a
4580: 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f  nd.** [sqlite3_o
4590: 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66  pen_v2()] interf
45a0: 61 63 65 73 20 61 72 65 20 69 74 73 20 63 6f 6e  aces are its con
45b0: 73 74 72 75 63 74 6f 72 73 2c 20 61 6e 64 20 5b  structors, and [
45c0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d  sqlite3_close()]
45d0: 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
45e0: 5f 63 6c 6f 73 65 5f 76 32 28 29 5d 20 61 72 65  _close_v2()] are
45f0: 20 69 74 73 20 64 65 73 74 72 75 63 74 6f 72 73   its destructors
4600: 2e 20 20 54 68 65 72 65 20 61 72 65 20 6d 61 6e  .  There are man
4610: 79 20 6f 74 68 65 72 0a 2a 2a 20 69 6e 74 65 72  y other.** inter
4620: 66 61 63 65 73 20 28 73 75 63 68 20 61 73 0a 2a  faces (such as.*
4630: 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
4640: 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74  re_v2()], [sqlit
4650: 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
4660: 6f 6e 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73  on()], and.** [s
4670: 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65  qlite3_busy_time
4680: 6f 75 74 28 29 5d 20 74 6f 20 6e 61 6d 65 20 62  out()] to name b
4690: 75 74 20 74 68 72 65 65 29 20 74 68 61 74 20 61  ut three) that a
46a0: 72 65 20 6d 65 74 68 6f 64 73 20 6f 6e 20 61 6e  re methods on an
46b0: 0a 2a 2a 20 73 71 6c 69 74 65 33 20 6f 62 6a 65  .** sqlite3 obje
46c0: 63 74 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  ct..*/.typedef s
46d0: 74 72 75 63 74 20 73 71 6c 69 74 65 33 20 73 71  truct sqlite3 sq
46e0: 6c 69 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  lite3;../*.** CA
46f0: 50 49 33 52 45 46 3a 20 36 34 2d 42 69 74 20 49  PI3REF: 64-Bit I
4700: 6e 74 65 67 65 72 20 54 79 70 65 73 0a 2a 2a 20  nteger Types.** 
4710: 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65  KEYWORDS: sqlite
4720: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69  _int64 sqlite_ui
4730: 6e 74 36 34 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75  nt64.**.** Becau
4740: 73 65 20 74 68 65 72 65 20 69 73 20 6e 6f 20 63  se there is no c
4750: 72 6f 73 73 2d 70 6c 61 74 66 6f 72 6d 20 77 61  ross-platform wa
4760: 79 20 74 6f 20 73 70 65 63 69 66 79 20 36 34 2d  y to specify 64-
4770: 62 69 74 20 69 6e 74 65 67 65 72 20 74 79 70 65  bit integer type
4780: 73 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 63 6c  s.** SQLite incl
4790: 75 64 65 73 20 74 79 70 65 64 65 66 73 20 66 6f  udes typedefs fo
47a0: 72 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20  r 64-bit signed 
47b0: 61 6e 64 20 75 6e 73 69 67 6e 65 64 20 69 6e 74  and unsigned int
47c0: 65 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  egers..**.** The
47d0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 61   sqlite3_int64 a
47e0: 6e 64 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  nd sqlite3_uint6
47f0: 34 20 61 72 65 20 74 68 65 20 70 72 65 66 65 72  4 are the prefer
4800: 72 65 64 20 74 79 70 65 20 64 65 66 69 6e 69 74  red type definit
4810: 69 6f 6e 73 2e 0a 2a 2a 20 54 68 65 20 73 71 6c  ions..** The sql
4820: 69 74 65 5f 69 6e 74 36 34 20 61 6e 64 20 73 71  ite_int64 and sq
4830: 6c 69 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65  lite_uint64 type
4840: 73 20 61 72 65 20 73 75 70 70 6f 72 74 65 64 20  s are supported 
4850: 66 6f 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a  for backwards.**
4860: 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f   compatibility o
4870: 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  nly..**.** ^The 
4880: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e  sqlite3_int64 an
4890: 64 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 74  d sqlite_int64 t
48a0: 79 70 65 73 20 63 61 6e 20 73 74 6f 72 65 20 69  ypes can store i
48b0: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 0a 2a 2a  nteger values.**
48c0: 20 62 65 74 77 65 65 6e 20 2d 39 32 32 33 33 37   between -922337
48d0: 32 30 33 36 38 35 34 37 37 35 38 30 38 20 61 6e  2036854775808 an
48e0: 64 20 2b 39 32 32 33 33 37 32 30 33 36 38 35 34  d +9223372036854
48f0: 37 37 35 38 30 37 20 69 6e 63 6c 75 73 69 76 65  775807 inclusive
4900: 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74  .  ^The.** sqlit
4910: 65 33 5f 75 69 6e 74 36 34 20 61 6e 64 20 73 71  e3_uint64 and sq
4920: 6c 69 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65  lite_uint64 type
4930: 73 20 63 61 6e 20 73 74 6f 72 65 20 69 6e 74 65  s can store inte
4940: 67 65 72 20 76 61 6c 75 65 73 20 0a 2a 2a 20 62  ger values .** b
4950: 65 74 77 65 65 6e 20 30 20 61 6e 64 20 2b 31 38  etween 0 and +18
4960: 34 34 36 37 34 34 30 37 33 37 30 39 35 35 31 36  4467440737095516
4970: 31 35 20 69 6e 63 6c 75 73 69 76 65 2e 0a 2a 2f  15 inclusive..*/
4980: 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 49  .#ifdef SQLITE_I
4990: 4e 54 36 34 5f 54 59 50 45 0a 20 20 74 79 70 65  NT64_TYPE.  type
49a0: 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34  def SQLITE_INT64
49b0: 5f 54 59 50 45 20 73 71 6c 69 74 65 5f 69 6e 74  _TYPE sqlite_int
49c0: 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e  64;.  typedef un
49d0: 73 69 67 6e 65 64 20 53 51 4c 49 54 45 5f 49 4e  signed SQLITE_IN
49e0: 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74 65 5f  T64_TYPE sqlite_
49f0: 75 69 6e 74 36 34 3b 0a 23 65 6c 69 66 20 64 65  uint64;.#elif de
4a00: 66 69 6e 65 64 28 5f 4d 53 43 5f 56 45 52 29 20  fined(_MSC_VER) 
4a10: 7c 7c 20 64 65 66 69 6e 65 64 28 5f 5f 42 4f 52  || defined(__BOR
4a20: 4c 41 4e 44 43 5f 5f 29 0a 20 20 74 79 70 65 64  LANDC__).  typed
4a30: 65 66 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74  ef __int64 sqlit
4a40: 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64  e_int64;.  typed
4a50: 65 66 20 75 6e 73 69 67 6e 65 64 20 5f 5f 69 6e  ef unsigned __in
4a60: 74 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74 36  t64 sqlite_uint6
4a70: 34 3b 0a 23 65 6c 73 65 0a 20 20 74 79 70 65 64  4;.#else.  typed
4a80: 65 66 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74  ef long long int
4a90: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20   sqlite_int64;. 
4aa0: 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65   typedef unsigne
4ab0: 64 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20  d long long int 
4ac0: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23  sqlite_uint64;.#
4ad0: 65 6e 64 69 66 0a 74 79 70 65 64 65 66 20 73 71  endif.typedef sq
4ae0: 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69 74  lite_int64 sqlit
4af0: 65 33 5f 69 6e 74 36 34 3b 0a 74 79 70 65 64 65  e3_int64;.typede
4b00: 66 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 20  f sqlite_uint64 
4b10: 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 3b 0a  sqlite3_uint64;.
4b20: 0a 2f 2a 0a 2a 2a 20 49 66 20 63 6f 6d 70 69 6c  ./*.** If compil
4b30: 69 6e 67 20 66 6f 72 20 61 20 70 72 6f 63 65 73  ing for a proces
4b40: 73 6f 72 20 74 68 61 74 20 6c 61 63 6b 73 20 66  sor that lacks f
4b50: 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 73 75  loating point su
4b60: 70 70 6f 72 74 2c 0a 2a 2a 20 73 75 62 73 74 69  pport,.** substi
4b70: 74 75 74 65 20 69 6e 74 65 67 65 72 20 66 6f 72  tute integer for
4b80: 20 66 6c 6f 61 74 69 6e 67 2d 70 6f 69 6e 74 2e   floating-point.
4b90: 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54  .*/.#ifdef SQLIT
4ba0: 45 5f 4f 4d 49 54 5f 46 4c 4f 41 54 49 4e 47 5f  E_OMIT_FLOATING_
4bb0: 50 4f 49 4e 54 0a 23 20 64 65 66 69 6e 65 20 64  POINT.# define d
4bc0: 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 69 6e  ouble sqlite3_in
4bd0: 74 36 34 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a  t64.#endif../*.*
4be0: 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6c 6f 73  * CAPI3REF: Clos
4bf0: 69 6e 67 20 41 20 44 61 74 61 62 61 73 65 20 43  ing A Database C
4c00: 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 44 45 53  onnection.** DES
4c10: 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 65 33  TRUCTOR: sqlite3
4c20: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
4c30: 74 65 33 5f 63 6c 6f 73 65 28 29 20 61 6e 64 20  te3_close() and 
4c40: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32  sqlite3_close_v2
4c50: 28 29 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  () routines are 
4c60: 64 65 73 74 72 75 63 74 6f 72 73 0a 2a 2a 20 66  destructors.** f
4c70: 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d  or the [sqlite3]
4c80: 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 43 61 6c   object..** ^Cal
4c90: 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6c  ls to sqlite3_cl
4ca0: 6f 73 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ose() and sqlite
4cb0: 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72 65 74  3_close_v2() ret
4cc0: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  urn [SQLITE_OK] 
4cd0: 69 66 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74  if.** the [sqlit
4ce0: 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 73 75  e3] object is su
4cf0: 63 63 65 73 73 66 75 6c 6c 79 20 64 65 73 74 72  ccessfully destr
4d00: 6f 79 65 64 20 61 6e 64 20 61 6c 6c 20 61 73 73  oyed and all ass
4d10: 6f 63 69 61 74 65 64 0a 2a 2a 20 72 65 73 6f 75  ociated.** resou
4d20: 72 63 65 73 20 61 72 65 20 64 65 61 6c 6c 6f 63  rces are dealloc
4d30: 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ated..**.** ^If 
4d40: 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
4d50: 6e 65 63 74 69 6f 6e 20 69 73 20 61 73 73 6f 63  nection is assoc
4d60: 69 61 74 65 64 20 77 69 74 68 20 75 6e 66 69 6e  iated with unfin
4d70: 61 6c 69 7a 65 64 20 70 72 65 70 61 72 65 64 0a  alized prepared.
4d80: 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 72  ** statements or
4d90: 20 75 6e 66 69 6e 69 73 68 65 64 20 73 71 6c 69   unfinished sqli
4da0: 74 65 33 5f 62 61 63 6b 75 70 20 6f 62 6a 65 63  te3_backup objec
4db0: 74 73 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  ts then sqlite3_
4dc0: 63 6c 6f 73 65 28 29 0a 2a 2a 20 77 69 6c 6c 20  close().** will 
4dd0: 6c 65 61 76 65 20 74 68 65 20 64 61 74 61 62 61  leave the databa
4de0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70  se connection op
4df0: 65 6e 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53  en and return [S
4e00: 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 20  QLITE_BUSY]..** 
4e10: 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  ^If sqlite3_clos
4e20: 65 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64  e_v2() is called
4e30: 20 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a 65   with unfinalize
4e40: 64 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  d prepared state
4e50: 6d 65 6e 74 73 0a 2a 2a 20 61 6e 64 2f 6f 72 20  ments.** and/or 
4e60: 75 6e 66 69 6e 69 73 68 65 64 20 73 71 6c 69 74  unfinished sqlit
4e70: 65 33 5f 62 61 63 6b 75 70 73 2c 20 74 68 65 6e  e3_backups, then
4e80: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
4e90: 6e 6e 65 63 74 69 6f 6e 20 62 65 63 6f 6d 65 73  nnection becomes
4ea0: 0a 2a 2a 20 61 6e 20 75 6e 75 73 61 62 6c 65 20  .** an unusable 
4eb0: 22 7a 6f 6d 62 69 65 22 20 77 68 69 63 68 20 77  "zombie" which w
4ec0: 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ill automaticall
4ed0: 79 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64  y be deallocated
4ee0: 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 73   when the.** las
4ef0: 74 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  t prepared state
4f00: 6d 65 6e 74 20 69 73 20 66 69 6e 61 6c 69 7a 65  ment is finalize
4f10: 64 20 6f 72 20 74 68 65 20 6c 61 73 74 20 73 71  d or the last sq
4f20: 6c 69 74 65 33 5f 62 61 63 6b 75 70 20 69 73 0a  lite3_backup is.
4f30: 2a 2a 20 66 69 6e 69 73 68 65 64 2e 20 20 54 68  ** finished.  Th
4f40: 65 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f  e sqlite3_close_
4f50: 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  v2() interface i
4f60: 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75  s intended for u
4f70: 73 65 20 77 69 74 68 0a 2a 2a 20 68 6f 73 74 20  se with.** host 
4f80: 6c 61 6e 67 75 61 67 65 73 20 74 68 61 74 20 61  languages that a
4f90: 72 65 20 67 61 72 62 61 67 65 20 63 6f 6c 6c 65  re garbage colle
4fa0: 63 74 65 64 2c 20 61 6e 64 20 77 68 65 72 65 20  cted, and where 
4fb0: 74 68 65 20 6f 72 64 65 72 20 69 6e 20 77 68 69  the order in whi
4fc0: 63 68 0a 2a 2a 20 64 65 73 74 72 75 63 74 6f 72  ch.** destructor
4fd0: 73 20 61 72 65 20 63 61 6c 6c 65 64 20 69 73 20  s are called is 
4fe0: 61 72 62 69 74 72 61 72 79 2e 0a 2a 2a 0a 2a 2a  arbitrary..**.**
4ff0: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68   Applications sh
5000: 6f 75 6c 64 20 5b 73 71 6c 69 74 65 33 5f 66 69  ould [sqlite3_fi
5010: 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a  nalize | finaliz
5020: 65 5d 20 61 6c 6c 20 5b 70 72 65 70 61 72 65 64  e] all [prepared
5030: 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c 0a 2a 2a   statements],.**
5040: 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63   [sqlite3_blob_c
5050: 6c 6f 73 65 20 7c 20 63 6c 6f 73 65 5d 20 61 6c  lose | close] al
5060: 6c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d  l [BLOB handles]
5070: 2c 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74  , and .** [sqlit
5080: 65 33 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73 68  e3_backup_finish
5090: 20 7c 20 66 69 6e 69 73 68 5d 20 61 6c 6c 20 5b   | finish] all [
50a0: 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20  sqlite3_backup] 
50b0: 6f 62 6a 65 63 74 73 20 61 73 73 6f 63 69 61 74  objects associat
50c0: 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b  ed.** with the [
50d0: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20  sqlite3] object 
50e0: 70 72 69 6f 72 20 74 6f 20 61 74 74 65 6d 70 74  prior to attempt
50f0: 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65  ing to close the
5100: 20 6f 62 6a 65 63 74 2e 20 20 5e 49 66 0a 2a 2a   object.  ^If.**
5110: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76   sqlite3_close_v
5120: 32 28 29 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e  2() is called on
5130: 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   a [database con
5140: 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 20 73 74  nection] that st
5150: 69 6c 6c 20 68 61 73 0a 2a 2a 20 6f 75 74 73 74  ill has.** outst
5160: 61 6e 64 69 6e 67 20 5b 70 72 65 70 61 72 65 64  anding [prepared
5170: 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c 20 5b 42   statements], [B
5180: 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e  LOB handles], an
5190: 64 2f 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  d/or.** [sqlite3
51a0: 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73  _backup] objects
51b0: 20 74 68 65 6e 20 69 74 20 72 65 74 75 72 6e 73   then it returns
51c0: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 61 6e 64   [SQLITE_OK] and
51d0: 20 74 68 65 20 64 65 61 6c 6c 6f 63 61 74 69 6f   the deallocatio
51e0: 6e 0a 2a 2a 20 6f 66 20 72 65 73 6f 75 72 63 65  n.** of resource
51f0: 73 20 69 73 20 64 65 66 65 72 72 65 64 20 75 6e  s is deferred un
5200: 74 69 6c 20 61 6c 6c 20 5b 70 72 65 70 61 72 65  til all [prepare
5210: 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c 20 5b  d statements], [
5220: 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 0a 2a  BLOB handles],.*
5230: 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62  * and [sqlite3_b
5240: 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20 61  ackup] objects a
5250: 72 65 20 61 6c 73 6f 20 64 65 73 74 72 6f 79 65  re also destroye
5260: 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20  d..**.** ^If an 
5270: 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74  [sqlite3] object
5280: 20 69 73 20 64 65 73 74 72 6f 79 65 64 20 77 68   is destroyed wh
5290: 69 6c 65 20 61 20 74 72 61 6e 73 61 63 74 69 6f  ile a transactio
52a0: 6e 20 69 73 20 6f 70 65 6e 2c 0a 2a 2a 20 74 68  n is open,.** th
52b0: 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73  e transaction is
52c0: 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72   automatically r
52d0: 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a  olled back..**.*
52e0: 2a 20 54 68 65 20 43 20 70 61 72 61 6d 65 74 65  * The C paramete
52f0: 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c  r to [sqlite3_cl
5300: 6f 73 65 28 43 29 5d 20 61 6e 64 20 5b 73 71 6c  ose(C)] and [sql
5310: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 43 29  ite3_close_v2(C)
5320: 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74  ].** must be eit
5330: 68 65 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f  her a NULL.** po
5340: 69 6e 74 65 72 20 6f 72 20 61 6e 20 5b 73 71 6c  inter or an [sql
5350: 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 6f 69  ite3] object poi
5360: 6e 74 65 72 20 6f 62 74 61 69 6e 65 64 0a 2a 2a  nter obtained.**
5370: 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6f   from [sqlite3_o
5380: 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  pen()], [sqlite3
5390: 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a  _open16()], or.*
53a0: 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  * [sqlite3_open_
53b0: 76 32 28 29 5d 2c 20 61 6e 64 20 6e 6f 74 20 70  v2()], and not p
53c0: 72 65 76 69 6f 75 73 6c 79 20 63 6c 6f 73 65 64  reviously closed
53d0: 2e 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71  ..** ^Calling sq
53e0: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 6f 72  lite3_close() or
53f0: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76   sqlite3_close_v
5400: 32 28 29 20 77 69 74 68 20 61 20 4e 55 4c 4c 20  2() with a NULL 
5410: 70 6f 69 6e 74 65 72 0a 2a 2a 20 61 72 67 75 6d  pointer.** argum
5420: 65 6e 74 20 69 73 20 61 20 68 61 72 6d 6c 65 73  ent is a harmles
5430: 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a 53 51 4c 49  s no-op..*/.SQLI
5440: 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54  TE_API int SQLIT
5450: 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
5460: 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 2a  3_close(sqlite3*
5470: 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
5480: 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
5490: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76   sqlite3_close_v
54a0: 32 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  2(sqlite3*);../*
54b0: 0a 2a 2a 20 54 68 65 20 74 79 70 65 20 66 6f 72  .** The type for
54c0: 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63   a callback func
54d0: 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69 73  tion..** This is
54e0: 20 6c 65 67 61 63 79 20 61 6e 64 20 64 65 70 72   legacy and depr
54f0: 65 63 61 74 65 64 2e 20 20 49 74 20 69 73 20 69  ecated.  It is i
5500: 6e 63 6c 75 64 65 64 20 66 6f 72 20 68 69 73 74  ncluded for hist
5510: 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74  orical.** compat
5520: 69 62 69 6c 69 74 79 20 61 6e 64 20 69 73 20 6e  ibility and is n
5530: 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a 2a  ot documented..*
5540: 2f 0a 74 79 70 65 64 65 66 20 69 6e 74 20 28 2a  /.typedef int (*
5550: 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63 6b  sqlite3_callback
5560: 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72  )(void*,int,char
5570: 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f 2a  **, char**);../*
5580: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 6e  .** CAPI3REF: On
5590: 65 2d 53 74 65 70 20 51 75 65 72 79 20 45 78 65  e-Step Query Exe
55a0: 63 75 74 69 6f 6e 20 49 6e 74 65 72 66 61 63 65  cution Interface
55b0: 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
55c0: 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  te3.**.** The sq
55d0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74  lite3_exec() int
55e0: 65 72 66 61 63 65 20 69 73 20 61 20 63 6f 6e 76  erface is a conv
55f0: 65 6e 69 65 6e 63 65 20 77 72 61 70 70 65 72 20  enience wrapper 
5600: 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  around.** [sqlit
5610: 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
5620: 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  , [sqlite3_step(
5630: 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  )], and [sqlite3
5640: 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2c 0a 2a 2a  _finalize()],.**
5650: 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 61 6e 20   that allows an 
5660: 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 72  application to r
5670: 75 6e 20 6d 75 6c 74 69 70 6c 65 20 73 74 61 74  un multiple stat
5680: 65 6d 65 6e 74 73 20 6f 66 20 53 51 4c 0a 2a 2a  ements of SQL.**
5690: 20 77 69 74 68 6f 75 74 20 68 61 76 69 6e 67 20   without having 
56a0: 74 6f 20 75 73 65 20 61 20 6c 6f 74 20 6f 66 20  to use a lot of 
56b0: 43 20 63 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a 20 5e  C code. .**.** ^
56c0: 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  The sqlite3_exec
56d0: 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 75 6e  () interface run
56e0: 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 55  s zero or more U
56f0: 54 46 2d 38 20 65 6e 63 6f 64 65 64 2c 0a 2a 2a  TF-8 encoded,.**
5700: 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72   semicolon-separ
5710: 61 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ate SQL statemen
5720: 74 73 20 70 61 73 73 65 64 20 69 6e 74 6f 20 69  ts passed into i
5730: 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2c  ts 2nd argument,
5740: 0a 2a 2a 20 69 6e 20 74 68 65 20 63 6f 6e 74 65  .** in the conte
5750: 78 74 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62  xt of the [datab
5760: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
5770: 70 61 73 73 65 64 20 69 6e 20 61 73 20 69 74 73  passed in as its
5780: 20 31 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74   1st.** argument
5790: 2e 20 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62  .  ^If the callb
57a0: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20  ack function of 
57b0: 74 68 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74  the 3rd argument
57c0: 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65   to.** sqlite3_e
57d0: 78 65 63 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c  xec() is not NUL
57e0: 4c 2c 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e  L, then it is in
57f0: 76 6f 6b 65 64 20 66 6f 72 20 65 61 63 68 20 72  voked for each r
5800: 65 73 75 6c 74 20 72 6f 77 0a 2a 2a 20 63 6f 6d  esult row.** com
5810: 69 6e 67 20 6f 75 74 20 6f 66 20 74 68 65 20 65  ing out of the e
5820: 76 61 6c 75 61 74 65 64 20 53 51 4c 20 73 74 61  valuated SQL sta
5830: 74 65 6d 65 6e 74 73 2e 20 20 5e 54 68 65 20 34  tements.  ^The 4
5840: 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  th argument to.*
5850: 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  * sqlite3_exec()
5860: 20 69 73 20 72 65 6c 61 79 65 64 20 74 68 72 6f   is relayed thro
5870: 75 67 68 20 74 6f 20 74 68 65 20 31 73 74 20 61  ugh to the 1st a
5880: 72 67 75 6d 65 6e 74 20 6f 66 20 65 61 63 68 0a  rgument of each.
5890: 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 6e 76 6f  ** callback invo
58a0: 63 61 74 69 6f 6e 2e 20 20 5e 49 66 20 74 68 65  cation.  ^If the
58b0: 20 63 61 6c 6c 62 61 63 6b 20 70 6f 69 6e 74 65   callback pointe
58c0: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65  r to sqlite3_exe
58d0: 63 28 29 0a 2a 2a 20 69 73 20 4e 55 4c 4c 2c 20  c().** is NULL, 
58e0: 74 68 65 6e 20 6e 6f 20 63 61 6c 6c 62 61 63 6b  then no callback
58f0: 20 69 73 20 65 76 65 72 20 69 6e 76 6f 6b 65 64   is ever invoked
5900: 20 61 6e 64 20 72 65 73 75 6c 74 20 72 6f 77 73   and result rows
5910: 20 61 72 65 0a 2a 2a 20 69 67 6e 6f 72 65 64 2e   are.** ignored.
5920: 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 65 72  .**.** ^If an er
5930: 72 6f 72 20 6f 63 63 75 72 73 20 77 68 69 6c 65  ror occurs while
5940: 20 65 76 61 6c 75 61 74 69 6e 67 20 74 68 65 20   evaluating the 
5950: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 70  SQL statements p
5960: 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 73 71  assed into.** sq
5970: 6c 69 74 65 33 5f 65 78 65 63 28 29 2c 20 74 68  lite3_exec(), th
5980: 65 6e 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20  en execution of 
5990: 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61 74  the current stat
59a0: 65 6d 65 6e 74 20 73 74 6f 70 73 20 61 6e 64 0a  ement stops and.
59b0: 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 73 74  ** subsequent st
59c0: 61 74 65 6d 65 6e 74 73 20 61 72 65 20 73 6b 69  atements are ski
59d0: 70 70 65 64 2e 20 20 5e 49 66 20 74 68 65 20 35  pped.  ^If the 5
59e0: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
59f0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a  sqlite3_exec().*
5a00: 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68  * is not NULL th
5a10: 65 6e 20 61 6e 79 20 65 72 72 6f 72 20 6d 65 73  en any error mes
5a20: 73 61 67 65 20 69 73 20 77 72 69 74 74 65 6e 20  sage is written 
5a30: 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61  into memory obta
5a40: 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71  ined.** from [sq
5a50: 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
5a60: 61 6e 64 20 70 61 73 73 65 64 20 62 61 63 6b 20  and passed back 
5a70: 74 68 72 6f 75 67 68 20 74 68 65 20 35 74 68 20  through the 5th 
5a80: 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 54 6f  parameter..** To
5a90: 20 61 76 6f 69 64 20 6d 65 6d 6f 72 79 20 6c 65   avoid memory le
5aa0: 61 6b 73 2c 20 74 68 65 20 61 70 70 6c 69 63 61  aks, the applica
5ab0: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 69 6e 76 6f  tion should invo
5ac0: 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ke [sqlite3_free
5ad0: 28 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72 6f 72 20  ()].** on error 
5ae0: 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 73 20  message strings 
5af0: 72 65 74 75 72 6e 65 64 20 74 68 72 6f 75 67 68  returned through
5b00: 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74   the 5th paramet
5b10: 65 72 20 6f 66 0a 2a 2a 20 6f 66 20 73 71 6c 69  er of.** of sqli
5b20: 74 65 33 5f 65 78 65 63 28 29 20 61 66 74 65 72  te3_exec() after
5b30: 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
5b40: 67 65 20 73 74 72 69 6e 67 20 69 73 20 6e 6f 20  ge string is no 
5b50: 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e 0a 2a  longer needed..*
5b60: 2a 20 5e 49 66 20 74 68 65 20 35 74 68 20 70 61  * ^If the 5th pa
5b70: 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
5b80: 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74  e3_exec() is not
5b90: 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20 65 72 72   NULL and no err
5ba0: 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c 20 74 68  ors.** occur, th
5bb0: 65 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  en sqlite3_exec(
5bc0: 29 20 73 65 74 73 20 74 68 65 20 70 6f 69 6e 74  ) sets the point
5bd0: 65 72 20 69 6e 20 69 74 73 20 35 74 68 20 70 61  er in its 5th pa
5be0: 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 4e 55  rameter to.** NU
5bf0: 4c 4c 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e  LL before return
5c00: 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61  ing..**.** ^If a
5c10: 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  n sqlite3_exec()
5c20: 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
5c30: 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20  s non-zero, the 
5c40: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a  sqlite3_exec().*
5c50: 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  * routine return
5c60: 73 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 77  s SQLITE_ABORT w
5c70: 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69 6e 67 20  ithout invoking 
5c80: 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 67 61  the callback aga
5c90: 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74 68 6f 75  in and.** withou
5ca0: 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79 20 73 75  t running any su
5cb0: 62 73 65 71 75 65 6e 74 20 53 51 4c 20 73 74 61  bsequent SQL sta
5cc0: 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e  tements..**.** ^
5cd0: 54 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74  The 2nd argument
5ce0: 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
5cf0: 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20  exec() callback 
5d00: 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 68 65 0a  function is the.
5d10: 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  ** number of col
5d20: 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75  umns in the resu
5d30: 6c 74 2e 20 20 5e 54 68 65 20 33 72 64 20 61 72  lt.  ^The 3rd ar
5d40: 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71  gument to the sq
5d50: 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20  lite3_exec().** 
5d60: 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 61  callback is an a
5d70: 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73  rray of pointers
5d80: 20 74 6f 20 73 74 72 69 6e 67 73 20 6f 62 74 61   to strings obta
5d90: 69 6e 65 64 20 61 73 20 69 66 20 66 72 6f 6d 0a  ined as if from.
5da0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
5db0: 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f 6e 65 20  mn_text()], one 
5dc0: 66 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e 2e  for each column.
5dd0: 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d 65 6e 74    ^If an element
5de0: 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75 6c 74 20   of a.** result 
5df0: 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e  row is NULL then
5e00: 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
5e10: 6e 67 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65  ng string pointe
5e20: 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20 73 71 6c  r for the.** sql
5e30: 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c  ite3_exec() call
5e40: 62 61 63 6b 20 69 73 20 61 20 4e 55 4c 4c 20 70  back is a NULL p
5e50: 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 34 74  ointer.  ^The 4t
5e60: 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  h argument to th
5e70: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65  e.** sqlite3_exe
5e80: 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  c() callback is 
5e90: 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e  an array of poin
5ea0: 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20  ters to strings 
5eb0: 77 68 65 72 65 20 65 61 63 68 0a 2a 2a 20 65 6e  where each.** en
5ec0: 74 72 79 20 72 65 70 72 65 73 65 6e 74 73 20 74  try represents t
5ed0: 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f 72 72 65  he name of corre
5ee0: 73 70 6f 6e 64 69 6e 67 20 72 65 73 75 6c 74 20  sponding result 
5ef0: 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74 61 69 6e  column as obtain
5f00: 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69  ed.** from [sqli
5f10: 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
5f20: 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  )]..**.** ^If th
5f30: 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  e 2nd parameter 
5f40: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
5f50: 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  ) is a NULL poin
5f60: 74 65 72 2c 20 61 20 70 6f 69 6e 74 65 72 0a 2a  ter, a pointer.*
5f70: 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74  * to an empty st
5f80: 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f 69 6e 74  ring, or a point
5f90: 65 72 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 73  er that contains
5fa0: 20 6f 6e 6c 79 20 77 68 69 74 65 73 70 61 63 65   only whitespace
5fb0: 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53 51 4c 20   and/or .** SQL 
5fc0: 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 6e 20 6e  comments, then n
5fd0: 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  o SQL statements
5fe0: 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 61   are evaluated a
5ff0: 6e 64 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  nd the database.
6000: 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65  ** is not change
6010: 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74 72 69 63  d..**.** Restric
6020: 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  tions:.**.** <ul
6030: 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70  >.** <li> The ap
6040: 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 65  plication must e
6050: 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20 31  nsure that the 1
6060: 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
6070: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a  sqlite3_exec().*
6080: 2a 20 20 20 20 20 20 69 73 20 61 20 76 61 6c 69  *      is a vali
6090: 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64 61 74 61  d and open [data
60a0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
60b0: 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70  ..** <li> The ap
60c0: 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e  plication must n
60d0: 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 5b 64 61  ot close the [da
60e0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
60f0: 6e 5d 20 73 70 65 63 69 66 69 65 64 20 62 79 0a  n] specified by.
6100: 2a 2a 20 20 20 20 20 20 74 68 65 20 31 73 74 20  **      the 1st 
6110: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
6120: 69 74 65 33 5f 65 78 65 63 28 29 20 77 68 69 6c  ite3_exec() whil
6130: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
6140: 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20   is running..** 
6150: 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61  <li> The applica
6160: 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 6d 6f  tion must not mo
6170: 64 69 66 79 20 74 68 65 20 53 51 4c 20 73 74 61  dify the SQL sta
6180: 74 65 6d 65 6e 74 20 74 65 78 74 20 70 61 73 73  tement text pass
6190: 65 64 20 69 6e 74 6f 0a 2a 2a 20 20 20 20 20 20  ed into.**      
61a0: 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
61b0: 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 65 78 65  r of sqlite3_exe
61c0: 63 28 29 20 77 68 69 6c 65 20 73 71 6c 69 74 65  c() while sqlite
61d0: 33 5f 65 78 65 63 28 29 20 69 73 20 72 75 6e 6e  3_exec() is runn
61e0: 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f  ing..** </ul>.*/
61f0: 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
6200: 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
6210: 71 6c 69 74 65 33 5f 65 78 65 63 28 0a 20 20 73  qlite3_exec(.  s
6220: 71 6c 69 74 65 33 2a 2c 20 20 20 20 20 20 20 20  qlite3*,        
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 2f 2a 20 41 6e 20            /* An 
6250: 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f  open database */
6260: 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  .  const char *s
6270: 71 6c 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  ql,             
6280: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
6290: 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75   SQL to be evalu
62a0: 61 74 65 64 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  ated */.  int (*
62b0: 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c  callback)(void*,
62c0: 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68 61 72 2a  int,char**,char*
62d0: 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b  *),  /* Callback
62e0: 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76   function */.  v
62f0: 6f 69 64 20 2a 2c 20 20 20 20 20 20 20 20 20 20  oid *,          
6300: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6310: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 31 73 74            /* 1st
6320: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c   argument to cal
6330: 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 68 61 72 20  lback */.  char 
6340: 2a 2a 65 72 72 6d 73 67 20 20 20 20 20 20 20 20  **errmsg        
6350: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6360: 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d        /* Error m
6370: 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65 20  sg written here 
6380: 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.);../*.** CAP
6390: 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 43 6f  I3REF: Result Co
63a0: 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  des.** KEYWORDS:
63b0: 20 7b 72 65 73 75 6c 74 20 63 6f 64 65 20 64 65   {result code de
63c0: 66 69 6e 69 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a  finitions}.**.**
63d0: 20 4d 61 6e 79 20 53 51 4c 69 74 65 20 66 75 6e   Many SQLite fun
63e0: 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 61 6e  ctions return an
63f0: 20 69 6e 74 65 67 65 72 20 72 65 73 75 6c 74 20   integer result 
6400: 63 6f 64 65 20 66 72 6f 6d 20 74 68 65 20 73 65  code from the se
6410: 74 20 73 68 6f 77 6e 0a 2a 2a 20 68 65 72 65 20  t shown.** here 
6420: 69 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 64 69  in order to indi
6430: 63 61 74 65 20 73 75 63 63 65 73 73 20 6f 72 20  cate success or 
6440: 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 4e  failure..**.** N
6450: 65 77 20 65 72 72 6f 72 20 63 6f 64 65 73 20 6d  ew error codes m
6460: 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
6470: 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
6480: 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20  f SQLite..**.** 
6490: 53 65 65 20 61 6c 73 6f 3a 20 5b 65 78 74 65 6e  See also: [exten
64a0: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 20  ded result code 
64b0: 64 65 66 69 6e 69 74 69 6f 6e 73 5d 0a 2a 2f 0a  definitions].*/.
64c0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
64d0: 4b 20 20 20 20 20 20 20 20 20 20 20 30 20 20 20  K           0   
64e0: 2f 2a 20 53 75 63 63 65 73 73 66 75 6c 20 72 65  /* Successful re
64f0: 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67 69 6e  sult */./* begin
6500: 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f  ning-of-error-co
6510: 64 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  des */.#define S
6520: 51 4c 49 54 45 5f 45 52 52 4f 52 20 20 20 20 20  QLITE_ERROR     
6530: 20 20 20 31 20 20 20 2f 2a 20 53 51 4c 20 65 72     1   /* SQL er
6540: 72 6f 72 20 6f 72 20 6d 69 73 73 69 6e 67 20 64  ror or missing d
6550: 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 69  atabase */.#defi
6560: 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 4e  ne SQLITE_INTERN
6570: 41 4c 20 20 20 20 20 32 20 20 20 2f 2a 20 49 6e  AL     2   /* In
6580: 74 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65 72 72  ternal logic err
6590: 6f 72 20 69 6e 20 53 51 4c 69 74 65 20 2a 2f 0a  or in SQLite */.
65a0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50  #define SQLITE_P
65b0: 45 52 4d 20 20 20 20 20 20 20 20 20 33 20 20 20  ERM         3   
65c0: 2f 2a 20 41 63 63 65 73 73 20 70 65 72 6d 69 73  /* Access permis
65d0: 73 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23  sion denied */.#
65e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 42  define SQLITE_AB
65f0: 4f 52 54 20 20 20 20 20 20 20 20 34 20 20 20 2f  ORT        4   /
6600: 2a 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69  * Callback routi
6610: 6e 65 20 72 65 71 75 65 73 74 65 64 20 61 6e 20  ne requested an 
6620: 61 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69 6e 65  abort */.#define
6630: 20 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20 20   SQLITE_BUSY    
6640: 20 20 20 20 20 35 20 20 20 2f 2a 20 54 68 65 20       5   /* The 
6650: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 73  database file is
6660: 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69   locked */.#defi
6670: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44  ne SQLITE_LOCKED
6680: 20 20 20 20 20 20 20 36 20 20 20 2f 2a 20 41 20         6   /* A 
6690: 74 61 62 6c 65 20 69 6e 20 74 68 65 20 64 61 74  table in the dat
66a0: 61 62 61 73 65 20 69 73 20 6c 6f 63 6b 65 64 20  abase is locked 
66b0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
66c0: 45 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 37  E_NOMEM        7
66d0: 20 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63 28 29     /* A malloc()
66e0: 20 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65 66 69   failed */.#defi
66f0: 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e  ne SQLITE_READON
6700: 4c 59 20 20 20 20 20 38 20 20 20 2f 2a 20 41 74  LY     8   /* At
6710: 74 65 6d 70 74 20 74 6f 20 77 72 69 74 65 20 61  tempt to write a
6720: 20 72 65 61 64 6f 6e 6c 79 20 64 61 74 61 62 61   readonly databa
6730: 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  se */.#define SQ
6740: 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 20 20  LITE_INTERRUPT  
6750: 20 20 39 20 20 20 2f 2a 20 4f 70 65 72 61 74 69    9   /* Operati
6760: 6f 6e 20 74 65 72 6d 69 6e 61 74 65 64 20 62 79  on terminated by
6770: 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
6780: 70 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65 20 53  pt()*/.#define S
6790: 51 4c 49 54 45 5f 49 4f 45 52 52 20 20 20 20 20  QLITE_IOERR     
67a0: 20 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65 20 6b    10   /* Some k
67b0: 69 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f 4f 20  ind of disk I/O 
67c0: 65 72 72 6f 72 20 6f 63 63 75 72 72 65 64 20 2a  error occurred *
67d0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
67e0: 5f 43 4f 52 52 55 50 54 20 20 20 20 20 31 31 20  _CORRUPT     11 
67f0: 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73    /* The databas
6800: 65 20 64 69 73 6b 20 69 6d 61 67 65 20 69 73 20  e disk image is 
6810: 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23 64 65  malformed */.#de
6820: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 46  fine SQLITE_NOTF
6830: 4f 55 4e 44 20 20 20 20 31 32 20 20 20 2f 2a 20  OUND    12   /* 
6840: 55 6e 6b 6e 6f 77 6e 20 6f 70 63 6f 64 65 20 69  Unknown opcode i
6850: 6e 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63  n sqlite3_file_c
6860: 6f 6e 74 72 6f 6c 28 29 20 2a 2f 0a 23 64 65 66  ontrol() */.#def
6870: 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4c 4c 20  ine SQLITE_FULL 
6880: 20 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20 49         13   /* I
6890: 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 65 64 20  nsertion failed 
68a0: 62 65 63 61 75 73 65 20 64 61 74 61 62 61 73 65  because database
68b0: 20 69 73 20 66 75 6c 6c 20 2a 2f 0a 23 64 65 66   is full */.#def
68c0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f  ine SQLITE_CANTO
68d0: 50 45 4e 20 20 20 20 31 34 20 20 20 2f 2a 20 55  PEN    14   /* U
68e0: 6e 61 62 6c 65 20 74 6f 20 6f 70 65 6e 20 74 68  nable to open th
68f0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
6900: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6910: 45 5f 50 52 4f 54 4f 43 4f 4c 20 20 20 20 31 35  E_PROTOCOL    15
6920: 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 6c     /* Database l
6930: 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c 20 65 72 72  ock protocol err
6940: 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  or */.#define SQ
6950: 4c 49 54 45 5f 45 4d 50 54 59 20 20 20 20 20 20  LITE_EMPTY      
6960: 20 31 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73   16   /* Databas
6970: 65 20 69 73 20 65 6d 70 74 79 20 2a 2f 0a 23 64  e is empty */.#d
6980: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 43 48  efine SQLITE_SCH
6990: 45 4d 41 20 20 20 20 20 20 31 37 20 20 20 2f 2a  EMA      17   /*
69a0: 20 54 68 65 20 64 61 74 61 62 61 73 65 20 73 63   The database sc
69b0: 68 65 6d 61 20 63 68 61 6e 67 65 64 20 2a 2f 0a  hema changed */.
69c0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
69d0: 4f 4f 42 49 47 20 20 20 20 20 20 31 38 20 20 20  OOBIG      18   
69e0: 2f 2a 20 53 74 72 69 6e 67 20 6f 72 20 42 4c 4f  /* String or BLO
69f0: 42 20 65 78 63 65 65 64 73 20 73 69 7a 65 20 6c  B exceeds size l
6a00: 69 6d 69 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20  imit */.#define 
6a10: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
6a20: 54 20 20 31 39 20 20 20 2f 2a 20 41 62 6f 72 74  T  19   /* Abort
6a30: 20 64 75 65 20 74 6f 20 63 6f 6e 73 74 72 61 69   due to constrai
6a40: 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a  nt violation */.
6a50: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d  #define SQLITE_M
6a60: 49 53 4d 41 54 43 48 20 20 20 20 32 30 20 20 20  ISMATCH    20   
6a70: 2f 2a 20 44 61 74 61 20 74 79 70 65 20 6d 69 73  /* Data type mis
6a80: 6d 61 74 63 68 20 2a 2f 0a 23 64 65 66 69 6e 65  match */.#define
6a90: 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 20   SQLITE_MISUSE  
6aa0: 20 20 20 20 32 31 20 20 20 2f 2a 20 4c 69 62 72      21   /* Libr
6ab0: 61 72 79 20 75 73 65 64 20 69 6e 63 6f 72 72 65  ary used incorre
6ac0: 63 74 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ctly */.#define 
6ad0: 53 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 20 20 20  SQLITE_NOLFS    
6ae0: 20 20 20 32 32 20 20 20 2f 2a 20 55 73 65 73 20     22   /* Uses 
6af0: 4f 53 20 66 65 61 74 75 72 65 73 20 6e 6f 74 20  OS features not 
6b00: 73 75 70 70 6f 72 74 65 64 20 6f 6e 20 68 6f 73  supported on hos
6b10: 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
6b20: 49 54 45 5f 41 55 54 48 20 20 20 20 20 20 20 20  ITE_AUTH        
6b30: 32 33 20 20 20 2f 2a 20 41 75 74 68 6f 72 69 7a  23   /* Authoriz
6b40: 61 74 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a  ation denied */.
6b50: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
6b60: 4f 52 4d 41 54 20 20 20 20 20 20 32 34 20 20 20  ORMAT      24   
6b70: 2f 2a 20 41 75 78 69 6c 69 61 72 79 20 64 61 74  /* Auxiliary dat
6b80: 61 62 61 73 65 20 66 6f 72 6d 61 74 20 65 72 72  abase format err
6b90: 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  or */.#define SQ
6ba0: 4c 49 54 45 5f 52 41 4e 47 45 20 20 20 20 20 20  LITE_RANGE      
6bb0: 20 32 35 20 20 20 2f 2a 20 32 6e 64 20 70 61 72   25   /* 2nd par
6bc0: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
6bd0: 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20 72 61  3_bind out of ra
6be0: 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nge */.#define S
6bf0: 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20 20 20  QLITE_NOTADB    
6c00: 20 20 32 36 20 20 20 2f 2a 20 46 69 6c 65 20 6f    26   /* File o
6c10: 70 65 6e 65 64 20 74 68 61 74 20 69 73 20 6e 6f  pened that is no
6c20: 74 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c  t a database fil
6c30: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
6c40: 49 54 45 5f 4e 4f 54 49 43 45 20 20 20 20 20 20  ITE_NOTICE      
6c50: 32 37 20 20 20 2f 2a 20 4e 6f 74 69 66 69 63 61  27   /* Notifica
6c60: 74 69 6f 6e 73 20 66 72 6f 6d 20 73 71 6c 69 74  tions from sqlit
6c70: 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a 23 64 65 66  e3_log() */.#def
6c80: 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52 4e 49  ine SQLITE_WARNI
6c90: 4e 47 20 20 20 20 20 32 38 20 20 20 2f 2a 20 57  NG     28   /* W
6ca0: 61 72 6e 69 6e 67 73 20 66 72 6f 6d 20 73 71 6c  arnings from sql
6cb0: 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a 23 64  ite3_log() */.#d
6cc0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 4f 57  efine SQLITE_ROW
6cd0: 20 20 20 20 20 20 20 20 20 31 30 30 20 20 2f 2a           100  /*
6ce0: 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
6cf0: 68 61 73 20 61 6e 6f 74 68 65 72 20 72 6f 77 20  has another row 
6d00: 72 65 61 64 79 20 2a 2f 0a 23 64 65 66 69 6e 65  ready */.#define
6d10: 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20 20 20 20   SQLITE_DONE    
6d20: 20 20 20 20 31 30 31 20 20 2f 2a 20 73 71 6c 69      101  /* sqli
6d30: 74 65 33 5f 73 74 65 70 28 29 20 68 61 73 20 66  te3_step() has f
6d40: 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e  inished executin
6d50: 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65  g */./* end-of-e
6d60: 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f  rror-codes */../
6d70: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45  *.** CAPI3REF: E
6d80: 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43  xtended Result C
6d90: 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  odes.** KEYWORDS
6da0: 3a 20 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75  : {extended resu
6db0: 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69  lt code definiti
6dc0: 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 69 74  ons}.**.** In it
6dd0: 73 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67  s default config
6de0: 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20  uration, SQLite 
6df0: 41 50 49 20 72 6f 75 74 69 6e 65 73 20 72 65 74  API routines ret
6e00: 75 72 6e 20 6f 6e 65 20 6f 66 20 33 30 20 69 6e  urn one of 30 in
6e10: 74 65 67 65 72 0a 2a 2a 20 5b 72 65 73 75 6c 74  teger.** [result
6e20: 20 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76 65   codes].  Howeve
6e30: 72 2c 20 65 78 70 65 72 69 65 6e 63 65 20 68 61  r, experience ha
6e40: 73 20 73 68 6f 77 6e 20 74 68 61 74 20 6d 61 6e  s shown that man
6e50: 79 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72 65  y of.** these re
6e60: 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 74  sult codes are t
6e70: 6f 6f 20 63 6f 61 72 73 65 2d 67 72 61 69 6e 65  oo coarse-graine
6e80: 64 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f 74 20  d.  They do not 
6e90: 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75  provide as.** mu
6ea0: 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  ch information a
6eb0: 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20 61 73  bout problems as
6ec0: 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67   programmers mig
6ed0: 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20  ht like.  In an 
6ee0: 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64  effort to.** add
6ef0: 72 65 73 73 20 74 68 69 73 2c 20 6e 65 77 65 72  ress this, newer
6f00: 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
6f10: 69 74 65 20 28 76 65 72 73 69 6f 6e 20 33 2e 33  ite (version 3.3
6f20: 2e 38 20 61 6e 64 20 6c 61 74 65 72 29 20 69 6e  .8 and later) in
6f30: 63 6c 75 64 65 0a 2a 2a 20 73 75 70 70 6f 72 74  clude.** support
6f40: 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
6f50: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 74 68 61  result codes tha
6f60: 74 20 70 72 6f 76 69 64 65 20 6d 6f 72 65 20 64  t provide more d
6f70: 65 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61 74  etailed informat
6f80: 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 72 72  ion.** about err
6f90: 6f 72 73 2e 20 54 68 65 73 65 20 5b 65 78 74 65  ors. These [exte
6fa0: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
6fb0: 73 5d 20 61 72 65 20 65 6e 61 62 6c 65 64 20 6f  s] are enabled o
6fc0: 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20 6f 6e  r disabled.** on
6fd0: 20 61 20 70 65 72 20 64 61 74 61 62 61 73 65 20   a per database 
6fe0: 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73  connection basis
6ff0: 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73   using the.** [s
7000: 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
7010: 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 5d 20  result_codes()] 
7020: 41 50 49 2e 20 20 4f 72 2c 20 74 68 65 20 65 78  API.  Or, the ex
7030: 74 65 6e 64 65 64 20 63 6f 64 65 20 66 6f 72 0a  tended code for.
7040: 2a 2a 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  ** the most rece
7050: 6e 74 20 65 72 72 6f 72 20 63 61 6e 20 62 65 20  nt error can be 
7060: 6f 62 74 61 69 6e 65 64 20 75 73 69 6e 67 0a 2a  obtained using.*
7070: 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  * [sqlite3_exten
7080: 64 65 64 5f 65 72 72 63 6f 64 65 28 29 5d 2e 0a  ded_errcode()]..
7090: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
70a0: 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 20 20 20  E_IOERR_READ    
70b0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
70c0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c 38 29  E_IOERR | (1<<8)
70d0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
70e0: 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41  _IOERR_SHORT_REA
70f0: 44 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  D        (SQLITE
7100: 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38 29 29  _IOERR | (2<<8))
7110: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
7120: 49 4f 45 52 52 5f 57 52 49 54 45 20 20 20 20 20  IOERR_WRITE     
7130: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
7140: 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29 29 0a  IOERR | (3<<8)).
7150: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
7160: 4f 45 52 52 5f 46 53 59 4e 43 20 20 20 20 20 20  OERR_FSYNC      
7170: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
7180: 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29 29 0a 23  OERR | (4<<8)).#
7190: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
71a0: 45 52 52 5f 44 49 52 5f 46 53 59 4e 43 20 20 20  ERR_DIR_FSYNC   
71b0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
71c0: 45 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64  ERR | (5<<8)).#d
71d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
71e0: 52 52 5f 54 52 55 4e 43 41 54 45 20 20 20 20 20  RR_TRUNCATE     
71f0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
7200: 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65  RR | (6<<8)).#de
7210: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
7220: 52 5f 46 53 54 41 54 20 20 20 20 20 20 20 20 20  R_FSTAT         
7230: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
7240: 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66  R | (7<<8)).#def
7250: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
7260: 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  _UNLOCK         
7270: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
7280: 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 69   | (8<<8)).#defi
7290: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
72a0: 52 44 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20  RDLOCK          
72b0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
72c0: 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (9<<8)).#defin
72d0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44  e SQLITE_IOERR_D
72e0: 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 20  ELETE           
72f0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
7300: 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e   (10<<8)).#defin
7310: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42  e SQLITE_IOERR_B
7320: 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 20 20 20  LOCKED          
7330: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
7340: 20 28 31 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e   (11<<8)).#defin
7350: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4e  e SQLITE_IOERR_N
7360: 4f 4d 45 4d 20 20 20 20 20 20 20 20 20 20 20 20  OMEM            
7370: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
7380: 20 28 31 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e   (12<<8)).#defin
7390: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 41  e SQLITE_IOERR_A
73a0: 43 43 45 53 53 20 20 20 20 20 20 20 20 20 20 20  CCESS           
73b0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
73c0: 20 28 31 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e   (13<<8)).#defin
73d0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43  e SQLITE_IOERR_C
73e0: 48 45 43 4b 52 45 53 45 52 56 45 44 4c 4f 43 4b  HECKRESERVEDLOCK
73f0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
7400: 20 28 31 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e   (14<<8)).#defin
7410: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4c  e SQLITE_IOERR_L
7420: 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  OCK             
7430: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
7440: 20 28 31 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e   (15<<8)).#defin
7450: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43  e SQLITE_IOERR_C
7460: 4c 4f 53 45 20 20 20 20 20 20 20 20 20 20 20 20  LOSE            
7470: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
7480: 20 28 31 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e   (16<<8)).#defin
7490: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44  e SQLITE_IOERR_D
74a0: 49 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20  IR_CLOSE        
74b0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
74c0: 20 28 31 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e   (17<<8)).#defin
74d0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53  e SQLITE_IOERR_S
74e0: 48 4d 4f 50 45 4e 20 20 20 20 20 20 20 20 20 20  HMOPEN          
74f0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
7500: 20 28 31 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e   (18<<8)).#defin
7510: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53  e SQLITE_IOERR_S
7520: 48 4d 53 49 5a 45 20 20 20 20 20 20 20 20 20 20  HMSIZE          
7530: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
7540: 20 28 31 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e   (19<<8)).#defin
7550: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53  e SQLITE_IOERR_S
7560: 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20  HMLOCK          
7570: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
7580: 20 28 32 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e   (20<<8)).#defin
7590: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53  e SQLITE_IOERR_S
75a0: 48 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20 20  HMMAP           
75b0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
75c0: 20 28 32 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e   (21<<8)).#defin
75d0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53  e SQLITE_IOERR_S
75e0: 45 45 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  EEK             
75f0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
7600: 20 28 32 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e   (22<<8)).#defin
7610: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44  e SQLITE_IOERR_D
7620: 45 4c 45 54 45 5f 4e 4f 45 4e 54 20 20 20 20 20  ELETE_NOENT     
7630: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
7640: 20 28 32 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e   (23<<8)).#defin
7650: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4d  e SQLITE_IOERR_M
7660: 4d 41 50 20 20 20 20 20 20 20 20 20 20 20 20 20  MAP             
7670: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
7680: 20 28 32 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e   (24<<8)).#defin
7690: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 47  e SQLITE_IOERR_G
76a0: 45 54 54 45 4d 50 50 41 54 48 20 20 20 20 20 20  ETTEMPPATH      
76b0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
76c0: 20 28 32 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e   (25<<8)).#defin
76d0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43  e SQLITE_IOERR_C
76e0: 4f 4e 56 50 41 54 48 20 20 20 20 20 20 20 20 20  ONVPATH         
76f0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
7700: 20 28 32 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e   (26<<8)).#defin
7710: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 56  e SQLITE_IOERR_V
7720: 4e 4f 44 45 20 20 20 20 20 20 20 20 20 20 20 20  NODE            
7730: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
7740: 20 28 32 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e   (27<<8)).#defin
7750: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 5f  e SQLITE_LOCKED_
7760: 53 48 41 52 45 44 43 41 43 48 45 20 20 20 20 20  SHAREDCACHE     
7770: 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20   (SQLITE_LOCKED 
7780: 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69  |  (1<<8)).#defi
7790: 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 5f 52  ne SQLITE_BUSY_R
77a0: 45 43 4f 56 45 52 59 20 20 20 20 20 20 20 20 20  ECOVERY         
77b0: 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59 20 20    (SQLITE_BUSY  
77c0: 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 66   |  (1<<8)).#def
77d0: 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 5f  ine SQLITE_BUSY_
77e0: 53 4e 41 50 53 48 4f 54 20 20 20 20 20 20 20 20  SNAPSHOT        
77f0: 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59 20     (SQLITE_BUSY 
7800: 20 20 7c 20 20 28 32 3c 3c 38 29 29 0a 23 64 65    |  (2<<8)).#de
7810: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54  fine SQLITE_CANT
7820: 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52 20 20  OPEN_NOTEMPDIR  
7830: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54      (SQLITE_CANT
7840: 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29 0a 23  OPEN | (1<<8)).#
7850: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41  define SQLITE_CA
7860: 4e 54 4f 50 45 4e 5f 49 53 44 49 52 20 20 20 20  NTOPEN_ISDIR    
7870: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41        (SQLITE_CA
7880: 4e 54 4f 50 45 4e 20 7c 20 28 32 3c 3c 38 29 29  NTOPEN | (2<<8))
7890: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
78a0: 43 41 4e 54 4f 50 45 4e 5f 46 55 4c 4c 50 41 54  CANTOPEN_FULLPAT
78b0: 48 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  H       (SQLITE_
78c0: 43 41 4e 54 4f 50 45 4e 20 7c 20 28 33 3c 3c 38  CANTOPEN | (3<<8
78d0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
78e0: 45 5f 43 41 4e 54 4f 50 45 4e 5f 43 4f 4e 56 50  E_CANTOPEN_CONVP
78f0: 41 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54  ATH       (SQLIT
7900: 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 34 3c  E_CANTOPEN | (4<
7910: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
7920: 49 54 45 5f 43 4f 52 52 55 50 54 5f 56 54 41 42  ITE_CORRUPT_VTAB
7930: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
7940: 49 54 45 5f 43 4f 52 52 55 50 54 20 7c 20 28 31  ITE_CORRUPT | (1
7950: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
7960: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 45  LITE_READONLY_RE
7970: 43 4f 56 45 52 59 20 20 20 20 20 20 20 28 53 51  COVERY       (SQ
7980: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20  LITE_READONLY | 
7990: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
79a0: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f  SQLITE_READONLY_
79b0: 43 41 4e 54 4c 4f 43 4b 20 20 20 20 20 20 20 28  CANTLOCK       (
79c0: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20  SQLITE_READONLY 
79d0: 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (2<<8)).#defin
79e0: 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c  e SQLITE_READONL
79f0: 59 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20 20 20  Y_ROLLBACK      
7a00: 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c   (SQLITE_READONL
7a10: 59 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66  Y | (3<<8)).#def
7a20: 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f  ine SQLITE_READO
7a30: 4e 4c 59 5f 44 42 4d 4f 56 45 44 20 20 20 20 20  NLY_DBMOVED     
7a40: 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f     (SQLITE_READO
7a50: 4e 4c 59 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64  NLY | (4<<8)).#d
7a60: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f  efine SQLITE_ABO
7a70: 52 54 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20 20  RT_ROLLBACK     
7a80: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 41 42 4f       (SQLITE_ABO
7a90: 52 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65  RT | (2<<8)).#de
7aa0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
7ab0: 54 52 41 49 4e 54 5f 43 48 45 43 4b 20 20 20 20  TRAINT_CHECK    
7ac0: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53      (SQLITE_CONS
7ad0: 54 52 41 49 4e 54 20 7c 20 28 31 3c 3c 38 29 29  TRAINT | (1<<8))
7ae0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
7af0: 43 4f 4e 53 54 52 41 49 4e 54 5f 43 4f 4d 4d 49  CONSTRAINT_COMMI
7b00: 54 48 4f 4f 4b 20 20 20 28 53 51 4c 49 54 45 5f  THOOK   (SQLITE_
7b10: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 32 3c  CONSTRAINT | (2<
7b20: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
7b30: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46  ITE_CONSTRAINT_F
7b40: 4f 52 45 49 47 4e 4b 45 59 20 20 20 28 53 51 4c  OREIGNKEY   (SQL
7b50: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
7b60: 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (3<<8)).#define
7b70: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
7b80: 4e 54 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20  NT_FUNCTION     
7b90: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
7ba0: 4e 54 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65  NT | (4<<8)).#de
7bb0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
7bc0: 54 52 41 49 4e 54 5f 4e 4f 54 4e 55 4c 4c 20 20  TRAINT_NOTNULL  
7bd0: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53      (SQLITE_CONS
7be0: 54 52 41 49 4e 54 20 7c 20 28 35 3c 3c 38 29 29  TRAINT | (5<<8))
7bf0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
7c00: 43 4f 4e 53 54 52 41 49 4e 54 5f 50 52 49 4d 41  CONSTRAINT_PRIMA
7c10: 52 59 4b 45 59 20 20 20 28 53 51 4c 49 54 45 5f  RYKEY   (SQLITE_
7c20: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 36 3c  CONSTRAINT | (6<
7c30: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
7c40: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 54  ITE_CONSTRAINT_T
7c50: 52 49 47 47 45 52 20 20 20 20 20 20 28 53 51 4c  RIGGER      (SQL
7c60: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
7c70: 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (7<<8)).#define
7c80: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
7c90: 4e 54 5f 55 4e 49 51 55 45 20 20 20 20 20 20 20  NT_UNIQUE       
7ca0: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
7cb0: 4e 54 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65  NT | (8<<8)).#de
7cc0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
7cd0: 54 52 41 49 4e 54 5f 56 54 41 42 20 20 20 20 20  TRAINT_VTAB     
7ce0: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53      (SQLITE_CONS
7cf0: 54 52 41 49 4e 54 20 7c 20 28 39 3c 3c 38 29 29  TRAINT | (9<<8))
7d00: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
7d10: 43 4f 4e 53 54 52 41 49 4e 54 5f 52 4f 57 49 44  CONSTRAINT_ROWID
7d20: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
7d30: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 28 31 30 3c  CONSTRAINT |(10<
7d40: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
7d50: 49 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43 4f 56  ITE_NOTICE_RECOV
7d60: 45 52 5f 57 41 4c 20 20 20 20 20 20 28 53 51 4c  ER_WAL      (SQL
7d70: 49 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28 31 3c  ITE_NOTICE | (1<
7d80: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
7d90: 49 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43 4f 56  ITE_NOTICE_RECOV
7da0: 45 52 5f 52 4f 4c 4c 42 41 43 4b 20 28 53 51 4c  ER_ROLLBACK (SQL
7db0: 49 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28 32 3c  ITE_NOTICE | (2<
7dc0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
7dd0: 49 54 45 5f 57 41 52 4e 49 4e 47 5f 41 55 54 4f  ITE_WARNING_AUTO
7de0: 49 4e 44 45 58 20 20 20 20 20 20 20 28 53 51 4c  INDEX       (SQL
7df0: 49 54 45 5f 57 41 52 4e 49 4e 47 20 7c 20 28 31  ITE_WARNING | (1
7e00: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
7e10: 4c 49 54 45 5f 41 55 54 48 5f 55 53 45 52 20 20  LITE_AUTH_USER  
7e20: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
7e30: 4c 49 54 45 5f 41 55 54 48 20 7c 20 28 31 3c 3c  LITE_AUTH | (1<<
7e40: 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  8))../*.** CAPI3
7e50: 52 45 46 3a 20 46 6c 61 67 73 20 46 6f 72 20 46  REF: Flags For F
7e60: 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61 74 69  ile Open Operati
7e70: 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ons.**.** These 
7e80: 62 69 74 20 76 61 6c 75 65 73 20 61 72 65 20 69  bit values are i
7e90: 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20  ntended for use 
7ea0: 69 6e 20 74 68 65 0a 2a 2a 20 33 72 64 20 70 61  in the.** 3rd pa
7eb0: 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b  rameter to the [
7ec0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
7ed0: 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61 6e 64  )] interface and
7ee0: 0a 2a 2a 20 69 6e 20 74 68 65 20 34 74 68 20 70  .** in the 4th p
7ef0: 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
7f00: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70  [sqlite3_vfs.xOp
7f10: 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 23  en] method..*/.#
7f20: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
7f30: 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20  EN_READONLY     
7f40: 20 20 20 20 30 78 30 30 30 30 30 30 30 31 20 20      0x00000001  
7f50: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
7f60: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
7f70: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
7f80: 45 4e 5f 52 45 41 44 57 52 49 54 45 20 20 20 20  EN_READWRITE    
7f90: 20 20 20 20 30 78 30 30 30 30 30 30 30 32 20 20      0x00000002  
7fa0: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
7fb0: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
7fc0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
7fd0: 45 4e 5f 43 52 45 41 54 45 20 20 20 20 20 20 20  EN_CREATE       
7fe0: 20 20 20 20 30 78 30 30 30 30 30 30 30 34 20 20      0x00000004  
7ff0: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
8000: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
8010: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
8020: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
8030: 20 20 20 20 30 78 30 30 30 30 30 30 30 38 20 20      0x00000008  
8040: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
8050: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
8060: 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20  EN_EXCLUSIVE    
8070: 20 20 20 20 30 78 30 30 30 30 30 30 31 30 20 20      0x00000010  
8080: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
8090: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
80a0: 45 4e 5f 41 55 54 4f 50 52 4f 58 59 20 20 20 20  EN_AUTOPROXY    
80b0: 20 20 20 20 30 78 30 30 30 30 30 30 32 30 20 20      0x00000020  
80c0: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
80d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
80e0: 45 4e 5f 55 52 49 20 20 20 20 20 20 20 20 20 20  EN_URI          
80f0: 20 20 20 20 30 78 30 30 30 30 30 30 34 30 20 20      0x00000040  
8100: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
8110: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
8120: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
8130: 45 4e 5f 4d 45 4d 4f 52 59 20 20 20 20 20 20 20  EN_MEMORY       
8140: 20 20 20 20 30 78 30 30 30 30 30 30 38 30 20 20      0x00000080  
8150: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
8160: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
8170: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
8180: 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20 20 20  EN_MAIN_DB      
8190: 20 20 20 20 30 78 30 30 30 30 30 31 30 30 20 20      0x00000100  
81a0: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
81b0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
81c0: 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20 20 20  EN_TEMP_DB      
81d0: 20 20 20 20 30 78 30 30 30 30 30 32 30 30 20 20      0x00000200  
81e0: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
81f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
8200: 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 20  EN_TRANSIENT_DB 
8210: 20 20 20 20 30 78 30 30 30 30 30 34 30 30 20 20      0x00000400  
8220: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
8230: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
8240: 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20  EN_MAIN_JOURNAL 
8250: 20 20 20 20 30 78 30 30 30 30 30 38 30 30 20 20      0x00000800  
8260: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
8270: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
8280: 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20  EN_TEMP_JOURNAL 
8290: 20 20 20 20 30 78 30 30 30 30 31 30 30 30 20 20      0x00001000  
82a0: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
82b0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
82c0: 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 20 20 20  EN_SUBJOURNAL   
82d0: 20 20 20 20 30 78 30 30 30 30 32 30 30 30 20 20      0x00002000  
82e0: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
82f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
8300: 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41  EN_MASTER_JOURNA
8310: 4c 20 20 20 30 78 30 30 30 30 34 30 30 30 20 20  L   0x00004000  
8320: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
8330: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
8340: 45 4e 5f 4e 4f 4d 55 54 45 58 20 20 20 20 20 20  EN_NOMUTEX      
8350: 20 20 20 20 30 78 30 30 30 30 38 30 30 30 20 20      0x00008000  
8360: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
8370: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
8380: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
8390: 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 20 20 20 20  EN_FULLMUTEX    
83a0: 20 20 20 20 30 78 30 30 30 31 30 30 30 30 20 20      0x00010000  
83b0: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
83c0: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
83d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
83e0: 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 20  EN_SHAREDCACHE  
83f0: 20 20 20 20 30 78 30 30 30 32 30 30 30 30 20 20      0x00020000  
8400: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
8410: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
8420: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
8430: 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 20  EN_PRIVATECACHE 
8440: 20 20 20 20 30 78 30 30 30 34 30 30 30 30 20 20      0x00040000  
8450: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
8460: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
8470: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
8480: 45 4e 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20  EN_WAL          
8490: 20 20 20 20 30 78 30 30 30 38 30 30 30 30 20 20      0x00080000  
84a0: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 0a  /* VFS only */..
84b0: 2f 2a 20 52 65 73 65 72 76 65 64 3a 20 20 20 20  /* Reserved:    
84c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
84d0: 20 20 20 20 20 30 78 30 30 46 30 30 30 30 30 20       0x00F00000 
84e0: 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
84f0: 45 46 3a 20 44 65 76 69 63 65 20 43 68 61 72 61  EF: Device Chara
8500: 63 74 65 72 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a  cteristics.**.**
8510: 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61 72   The xDeviceChar
8520: 61 63 74 65 72 69 73 74 69 63 73 20 6d 65 74 68  acteristics meth
8530: 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  od of the [sqlit
8540: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a  e3_io_methods].*
8550: 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 73  * object returns
8560: 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63   an integer whic
8570: 68 20 69 73 20 61 20 76 65 63 74 6f 72 20 6f 66  h is a vector of
8580: 20 74 68 65 73 65 0a 2a 2a 20 62 69 74 20 76 61   these.** bit va
8590: 6c 75 65 73 20 65 78 70 72 65 73 73 69 6e 67 20  lues expressing 
85a0: 49 2f 4f 20 63 68 61 72 61 63 74 65 72 69 73 74  I/O characterist
85b0: 69 63 73 20 6f 66 20 74 68 65 20 6d 61 73 73 20  ics of the mass 
85c0: 73 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76 69 63  storage.** devic
85d0: 65 20 74 68 61 74 20 68 6f 6c 64 73 20 74 68 65  e that holds the
85e0: 20 66 69 6c 65 20 74 68 61 74 20 74 68 65 20 5b   file that the [
85f0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
8600: 64 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20 74 6f  ds].** refers to
8610: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49  ..**.** The SQLI
8620: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20  TE_IOCAP_ATOMIC 
8630: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
8640: 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f  hat all writes o
8650: 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72  f.** any size ar
8660: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53  e atomic.  The S
8670: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
8680: 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20  ICnnn values.** 
8690: 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73  mean that writes
86a0: 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20   of blocks that 
86b0: 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e  are nnn bytes in
86c0: 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65   size and.** are
86d0: 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61   aligned to an a
86e0: 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20  ddress which is 
86f0: 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69  an integer multi
8700: 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72  ple of.** nnn ar
8710: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53  e atomic.  The S
8720: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
8730: 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65  _APPEND value me
8740: 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e  ans.** that when
8750: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65   data is appende
8760: 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65  d to a file, the
8770: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65   data is appende
8780: 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20  d.** first then 
8790: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
87a0: 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64  file is extended
87b0: 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65  , never the othe
87c0: 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e  r.** way around.
87d0: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
87e0: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72  AP_SEQUENTIAL pr
87f0: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61  operty means tha
8800: 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  t.** information
8810: 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64   is written to d
8820: 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20  isk in the same 
8830: 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a  order as calls.*
8840: 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 20 20  * to xWrite().  
8850: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
8860: 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57  _POWERSAFE_OVERW
8870: 52 49 54 45 20 70 72 6f 70 65 72 74 79 20 6d 65  RITE property me
8880: 61 6e 73 20 74 68 61 74 0a 2a 2a 20 61 66 74 65  ans that.** afte
8890: 72 20 72 65 62 6f 6f 74 20 66 6f 6c 6c 6f 77 69  r reboot followi
88a0: 6e 67 20 61 20 63 72 61 73 68 20 6f 72 20 70 6f  ng a crash or po
88b0: 77 65 72 20 6c 6f 73 73 2c 20 74 68 65 20 6f 6e  wer loss, the on
88c0: 6c 79 20 62 79 74 65 73 20 69 6e 20 61 0a 2a 2a  ly bytes in a.**
88d0: 20 66 69 6c 65 20 74 68 61 74 20 77 65 72 65 20   file that were 
88e0: 77 72 69 74 74 65 6e 20 61 74 20 74 68 65 20 61  written at the a
88f0: 70 70 6c 69 63 61 74 69 6f 6e 20 6c 65 76 65 6c  pplication level
8900: 20 6d 69 67 68 74 20 68 61 76 65 20 63 68 61 6e   might have chan
8910: 67 65 64 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20  ged.** and that 
8920: 61 64 6a 61 63 65 6e 74 20 62 79 74 65 73 2c 20  adjacent bytes, 
8930: 65 76 65 6e 20 62 79 74 65 73 20 77 69 74 68 69  even bytes withi
8940: 6e 20 74 68 65 20 73 61 6d 65 20 73 65 63 74 6f  n the same secto
8950: 72 20 61 72 65 0a 2a 2a 20 67 75 61 72 61 6e 74  r are.** guarant
8960: 65 65 64 20 74 6f 20 62 65 20 75 6e 63 68 61 6e  eed to be unchan
8970: 67 65 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45  ged.  The SQLITE
8980: 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42  _IOCAP_UNDELETAB
8990: 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 0a 2a 2a 20  LE_WHEN_OPEN.** 
89a0: 66 6c 61 67 20 69 6e 64 69 63 61 74 65 20 74 68  flag indicate th
89b0: 61 74 20 61 20 66 69 6c 65 20 63 61 6e 6e 6f 74  at a file cannot
89c0: 20 62 65 20 64 65 6c 65 74 65 64 20 77 68 65 6e   be deleted when
89d0: 20 6f 70 65 6e 2e 20 20 54 68 65 0a 2a 2a 20 53   open.  The.** S
89e0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55  QLITE_IOCAP_IMMU
89f0: 54 41 42 4c 45 20 66 6c 61 67 20 69 6e 64 69 63  TABLE flag indic
8a00: 61 74 65 73 20 74 68 61 74 20 74 68 65 20 66 69  ates that the fi
8a10: 6c 65 20 69 73 20 6f 6e 0a 2a 2a 20 72 65 61 64  le is on.** read
8a20: 2d 6f 6e 6c 79 20 6d 65 64 69 61 20 61 6e 64 20  -only media and 
8a30: 63 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 65  cannot be change
8a40: 64 20 65 76 65 6e 20 62 79 20 70 72 6f 63 65 73  d even by proces
8a50: 73 65 73 20 77 69 74 68 0a 2a 2a 20 65 6c 65 76  ses with.** elev
8a60: 61 74 65 64 20 70 72 69 76 69 6c 65 67 65 73 2e  ated privileges.
8a70: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
8a80: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20  TE_IOCAP_ATOMIC 
8a90: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
8aa0: 30 78 30 30 30 30 30 30 30 31 0a 23 64 65 66 69  0x00000001.#defi
8ab0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
8ac0: 41 54 4f 4d 49 43 35 31 32 20 20 20 20 20 20 20  ATOMIC512       
8ad0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
8ae0: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
8af0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 20  _IOCAP_ATOMIC1K 
8b00: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
8b10: 30 30 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65  00000004.#define
8b20: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
8b30: 4f 4d 49 43 32 4b 20 20 20 20 20 20 20 20 20 20  OMIC2K          
8b40: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 38 0a       0x00000008.
8b50: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
8b60: 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 20 20 20  OCAP_ATOMIC4K   
8b70: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
8b80: 30 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53  000010.#define S
8b90: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
8ba0: 49 43 38 4b 20 20 20 20 20 20 20 20 20 20 20 20  IC8K            
8bb0: 20 20 20 30 78 30 30 30 30 30 30 32 30 0a 23 64     0x00000020.#d
8bc0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
8bd0: 41 50 5f 41 54 4f 4d 49 43 31 36 4b 20 20 20 20  AP_ATOMIC16K    
8be0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
8bf0: 30 30 34 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0040.#define SQL
8c00: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
8c10: 33 32 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  32K             
8c20: 20 30 78 30 30 30 30 30 30 38 30 0a 23 64 65 66   0x00000080.#def
8c30: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
8c40: 5f 41 54 4f 4d 49 43 36 34 4b 20 20 20 20 20 20  _ATOMIC64K      
8c50: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31          0x000001
8c60: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  00.#define SQLIT
8c70: 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50  E_IOCAP_SAFE_APP
8c80: 45 4e 44 20 20 20 20 20 20 20 20 20 20 20 20 30  END            0
8c90: 78 30 30 30 30 30 32 30 30 0a 23 64 65 66 69 6e  x00000200.#defin
8ca0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
8cb0: 45 51 55 45 4e 54 49 41 4c 20 20 20 20 20 20 20  EQUENTIAL       
8cc0: 20 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30        0x00000400
8cd0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
8ce0: 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c  IOCAP_UNDELETABL
8cf0: 45 5f 57 48 45 4e 5f 4f 50 45 4e 20 20 30 78 30  E_WHEN_OPEN  0x0
8d00: 30 30 30 30 38 30 30 0a 23 64 65 66 69 6e 65 20  0000800.#define 
8d10: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57  SQLITE_IOCAP_POW
8d20: 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45  ERSAFE_OVERWRITE
8d30: 20 20 20 20 30 78 30 30 30 30 31 30 30 30 0a 23      0x00001000.#
8d40: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
8d50: 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 20 20 20  CAP_IMMUTABLE   
8d60: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
8d70: 30 32 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  02000../*.** CAP
8d80: 49 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63 6b  I3REF: File Lock
8d90: 69 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a 2a 2a  ing Levels.**.**
8da0: 20 53 51 4c 69 74 65 20 75 73 65 73 20 6f 6e 65   SQLite uses one
8db0: 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67 65   of these intege
8dc0: 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20  r values as the 
8dd0: 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65  second.** argume
8de0: 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69 74 20 6d  nt to calls it m
8df0: 61 6b 65 73 20 74 6f 20 74 68 65 20 78 4c 6f 63  akes to the xLoc
8e00: 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28  k() and xUnlock(
8e10: 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20  ) methods.** of 
8e20: 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  an [sqlite3_io_m
8e30: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 0a  ethods] object..
8e40: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
8e50: 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20 20  E_LOCK_NONE     
8e60: 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53       0.#define S
8e70: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45  QLITE_LOCK_SHARE
8e80: 44 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69  D        1.#defi
8e90: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52  ne SQLITE_LOCK_R
8ea0: 45 53 45 52 56 45 44 20 20 20 20 20 20 32 0a 23  ESERVED      2.#
8eb0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
8ec0: 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20 20 20  CK_PENDING      
8ed0: 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   3.#define SQLIT
8ee0: 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45  E_LOCK_EXCLUSIVE
8ef0: 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41       4../*.** CA
8f00: 50 49 33 52 45 46 3a 20 53 79 6e 63 68 72 6f 6e  PI3REF: Synchron
8f10: 69 7a 61 74 69 6f 6e 20 54 79 70 65 20 46 6c 61  ization Type Fla
8f20: 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51  gs.**.** When SQ
8f30: 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 65  Lite invokes the
8f40: 20 78 53 79 6e 63 28 29 20 6d 65 74 68 6f 64 20   xSync() method 
8f50: 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65  of an.** [sqlite
8f60: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
8f70: 6a 65 63 74 20 69 74 20 75 73 65 73 20 61 20 63  ject it uses a c
8f80: 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a  ombination of.**
8f90: 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 76   these integer v
8fa0: 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 63  alues as the sec
8fb0: 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  ond argument..**
8fc0: 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 53 51 4c  .** When the SQL
8fd0: 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c  ITE_SYNC_DATAONL
8fe0: 59 20 66 6c 61 67 20 69 73 20 75 73 65 64 2c 20  Y flag is used, 
8ff0: 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  it means that th
9000: 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61 74  e.** sync operat
9010: 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74  ion only needs t
9020: 6f 20 66 6c 75 73 68 20 64 61 74 61 20 74 6f 20  o flush data to 
9030: 6d 61 73 73 20 73 74 6f 72 61 67 65 2e 20 20 49  mass storage.  I
9040: 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  node.** informat
9050: 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65 20  ion need not be 
9060: 66 6c 75 73 68 65 64 2e 20 49 66 20 74 68 65 20  flushed. If the 
9070: 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73 20  lower four bits 
9080: 6f 66 20 74 68 65 20 66 6c 61 67 0a 2a 2a 20 65  of the flag.** e
9090: 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43  qual SQLITE_SYNC
90a0: 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 74 20 6d 65  _NORMAL, that me
90b0: 61 6e 73 20 74 6f 20 75 73 65 20 6e 6f 72 6d 61  ans to use norma
90c0: 6c 20 66 73 79 6e 63 28 29 20 73 65 6d 61 6e 74  l fsync() semant
90d0: 69 63 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6c  ics..** If the l
90e0: 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73 20 65  ower four bits e
90f0: 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43  qual SQLITE_SYNC
9100: 5f 46 55 4c 4c 2c 20 74 68 61 74 20 6d 65 61 6e  _FULL, that mean
9110: 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63 20  s.** to use Mac 
9120: 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73  OS X style fulls
9130: 79 6e 63 20 69 6e 73 74 65 61 64 20 6f 66 20 66  ync instead of f
9140: 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 44 6f  sync()..**.** Do
9150: 20 6e 6f 74 20 63 6f 6e 66 75 73 65 20 74 68 65   not confuse the
9160: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52   SQLITE_SYNC_NOR
9170: 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53  MAL and SQLITE_S
9180: 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73 0a 2a  YNC_FULL flags.*
9190: 2a 20 77 69 74 68 20 74 68 65 20 5b 50 52 41 47  * with the [PRAG
91a0: 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d  MA synchronous]=
91b0: 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b 50 52 41 47  NORMAL and [PRAG
91c0: 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d  MA synchronous]=
91d0: 46 55 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e 67 73  FULL.** settings
91e0: 2e 20 20 54 68 65 20 5b 73 79 6e 63 68 72 6f 6e  .  The [synchron
91f0: 6f 75 73 20 70 72 61 67 6d 61 5d 20 64 65 74 65  ous pragma] dete
9200: 72 6d 69 6e 65 73 20 77 68 65 6e 20 63 61 6c 6c  rmines when call
9210: 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 79 6e  s to the.** xSyn
9220: 63 20 56 46 53 20 6d 65 74 68 6f 64 20 6f 63 63  c VFS method occ
9230: 75 72 20 61 6e 64 20 61 70 70 6c 69 65 73 20 75  ur and applies u
9240: 6e 69 66 6f 72 6d 6c 79 20 61 63 72 6f 73 73 20  niformly across 
9250: 61 6c 6c 20 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a  all platforms..*
9260: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 53 59 4e  * The SQLITE_SYN
9270: 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c  C_NORMAL and SQL
9280: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c  ITE_SYNC_FULL fl
9290: 61 67 73 20 64 65 74 65 72 6d 69 6e 65 20 68 6f  ags determine ho
92a0: 77 0a 2a 2a 20 65 6e 65 72 67 65 74 69 63 20 6f  w.** energetic o
92b0: 72 20 72 69 67 6f 72 6f 75 73 20 6f 72 20 66 6f  r rigorous or fo
92c0: 72 63 65 66 75 6c 20 74 68 65 20 73 79 6e 63 20  rceful the sync 
92d0: 6f 70 65 72 61 74 69 6f 6e 73 20 61 72 65 20 61  operations are a
92e0: 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b 65 20  nd.** only make 
92f0: 61 20 64 69 66 66 65 72 65 6e 63 65 20 6f 6e 20  a difference on 
9300: 4d 61 63 20 4f 53 58 20 66 6f 72 20 74 68 65 20  Mac OSX for the 
9310: 64 65 66 61 75 6c 74 20 53 51 4c 69 74 65 20 63  default SQLite c
9320: 6f 64 65 2e 0a 2a 2a 20 28 54 68 69 72 64 2d 70  ode..** (Third-p
9330: 61 72 74 79 20 56 46 53 20 69 6d 70 6c 65 6d 65  arty VFS impleme
9340: 6e 74 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 61  ntations might a
9350: 6c 73 6f 20 6d 61 6b 65 20 74 68 65 20 64 69 73  lso make the dis
9360: 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74 77  tinction.** betw
9370: 65 65 6e 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  een SQLITE_SYNC_
9380: 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54  NORMAL and SQLIT
9390: 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 62 75 74  E_SYNC_FULL, but
93a0: 20 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20 6f 70   among the.** op
93b0: 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 73 20  erating systems 
93c0: 6e 61 74 69 76 65 6c 79 20 73 75 70 70 6f 72 74  natively support
93d0: 65 64 20 62 79 20 53 51 4c 69 74 65 2c 20 6f 6e  ed by SQLite, on
93e0: 6c 79 20 4d 61 63 20 4f 53 58 0a 2a 2a 20 63 61  ly Mac OSX.** ca
93f0: 72 65 73 20 61 62 6f 75 74 20 74 68 65 20 64 69  res about the di
9400: 66 66 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a 23 64  fference.).*/.#d
9410: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e  efine SQLITE_SYN
9420: 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20 20  C_NORMAL        
9430: 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20  0x00002.#define 
9440: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
9450: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
9460: 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
9470: 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 20  _SYNC_DATAONLY  
9480: 20 20 20 20 30 78 30 30 30 31 30 0a 0a 2f 2a 0a      0x00010../*.
9490: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20  ** CAPI3REF: OS 
94a0: 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e 20 46  Interface Open F
94b0: 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a  ile Handle.**.**
94c0: 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c   An [sqlite3_fil
94d0: 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73  e] object repres
94e0: 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66 69 6c  ents an open fil
94f0: 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b 73 71  e in the .** [sq
9500: 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f 53 20 69  lite3_vfs | OS i
9510: 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72 5d 2e  nterface layer].
9520: 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f 53 20    Individual OS 
9530: 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 6d 70  interface.** imp
9540: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c  lementations wil
9550: 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73 75 62  l.** want to sub
9560: 63 6c 61 73 73 20 74 68 69 73 20 6f 62 6a 65 63  class this objec
9570: 74 20 62 79 20 61 70 70 65 6e 64 69 6e 67 20 61  t by appending a
9580: 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73  dditional fields
9590: 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72 20 6f 77  .** for their ow
95a0: 6e 20 75 73 65 2e 20 20 54 68 65 20 70 4d 65 74  n use.  The pMet
95b0: 68 6f 64 73 20 65 6e 74 72 79 20 69 73 20 61 20  hods entry is a 
95c0: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a  pointer to an.**
95d0: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
95e0: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74 68 61  hods] object tha
95f0: 74 20 64 65 66 69 6e 65 73 20 6d 65 74 68 6f 64  t defines method
9600: 73 20 66 6f 72 20 70 65 72 66 6f 72 6d 69 6e 67  s for performing
9610: 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f  .** I/O operatio
9620: 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e 20 66  ns on the open f
9630: 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ile..*/.typedef 
9640: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66  struct sqlite3_f
9650: 69 6c 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  ile sqlite3_file
9660: 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  ;.struct sqlite3
9670: 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 74 20  _file {.  const 
9680: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69  struct sqlite3_i
9690: 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65 74 68  o_methods *pMeth
96a0: 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f 64 73  ods;  /* Methods
96b0: 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66 69 6c   for an open fil
96c0: 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43  e */.};../*.** C
96d0: 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65  API3REF: OS Inte
96e0: 72 66 61 63 65 20 46 69 6c 65 20 56 69 72 74 75  rface File Virtu
96f0: 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63  al Methods Objec
9700: 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66 69  t.**.** Every fi
9710: 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74 68 65  le opened by the
9720: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f   [sqlite3_vfs.xO
9730: 70 65 6e 5d 20 6d 65 74 68 6f 64 20 70 6f 70 75  pen] method popu
9740: 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73 71 6c  lates an.** [sql
9750: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
9760: 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d 6d  t (or, more comm
9770: 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61 73 73  only, a subclass
9780: 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   of the.** [sqli
9790: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74  te3_file] object
97a0: 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72  ) with a pointer
97b0: 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20   to an instance 
97c0: 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 2e 0a  of this object..
97d0: 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 64  ** This object d
97e0: 65 66 69 6e 65 73 20 74 68 65 20 6d 65 74 68 6f  efines the metho
97f0: 64 73 20 75 73 65 64 20 74 6f 20 70 65 72 66 6f  ds used to perfo
9800: 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65 72 61  rm various opera
9810: 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e 73 74  tions.** against
9820: 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 20 72   the open file r
9830: 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 74 68  epresented by th
9840: 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  e [sqlite3_file]
9850: 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49   object..**.** I
9860: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  f the [sqlite3_v
9870: 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64  fs.xOpen] method
9880: 20 73 65 74 73 20 74 68 65 20 73 71 6c 69 74 65   sets the sqlite
9890: 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20  3_file.pMethods 
98a0: 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f 20 61  element .** to a
98b0: 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65   non-NULL pointe
98c0: 72 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69  r, then the sqli
98d0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 2e 78  te3_io_methods.x
98e0: 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a 2a 2a 20  Close method.** 
98f0: 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 65  may be invoked e
9900: 76 65 6e 20 69 66 20 74 68 65 20 5b 73 71 6c 69  ven if the [sqli
9910: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 72  te3_vfs.xOpen] r
9920: 65 70 6f 72 74 65 64 20 74 68 61 74 20 69 74 20  eported that it 
9930: 66 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a 2a 20  failed.  The.** 
9940: 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70 72 65 76  only way to prev
9950: 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20 78 43  ent a call to xC
9960: 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  lose following a
9970: 20 66 61 69 6c 65 64 20 5b 73 71 6c 69 74 65 33   failed [sqlite3
9980: 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a 20 69  _vfs.xOpen].** i
9990: 73 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74  s for the [sqlit
99a0: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 74 6f  e3_vfs.xOpen] to
99b0: 20 73 65 74 20 74 68 65 20 73 71 6c 69 74 65 33   set the sqlite3
99c0: 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65  _file.pMethods e
99d0: 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e 55 4c  lement.** to NUL
99e0: 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61  L..**.** The fla
99f0: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78  gs argument to x
9a00: 53 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65 20  Sync may be one 
9a10: 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f  of [SQLITE_SYNC_
9a20: 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53  NORMAL] or.** [S
9a30: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d  QLITE_SYNC_FULL]
9a40: 2e 20 20 54 68 65 20 66 69 72 73 74 20 63 68 6f  .  The first cho
9a50: 69 63 65 20 69 73 20 74 68 65 20 6e 6f 72 6d 61  ice is the norma
9a60: 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54 68  l fsync()..** Th
9a70: 65 20 73 65 63 6f 6e 64 20 63 68 6f 69 63 65 20  e second choice 
9a80: 69 73 20 61 20 4d 61 63 20 4f 53 20 58 20 73 74  is a Mac OS X st
9a90: 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20 54  yle fullsync.  T
9aa0: 68 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f  he [SQLITE_SYNC_
9ab0: 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61  DATAONLY].** fla
9ac0: 67 20 6d 61 79 20 62 65 20 4f 52 65 64 20 69 6e  g may be ORed in
9ad0: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61   to indicate tha
9ae0: 74 20 6f 6e 6c 79 20 74 68 65 20 64 61 74 61 20  t only the data 
9af0: 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20 61  of the file.** a
9b00: 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64 65  nd not its inode
9b10: 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 79 6e   needs to be syn
9b20: 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69  ced..**.** The i
9b30: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 74 6f  nteger values to
9b40: 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e   xLock() and xUn
9b50: 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f  lock() are one o
9b60: 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  f.** <ul>.** <li
9b70: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e  > [SQLITE_LOCK_N
9b80: 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  ONE],.** <li> [S
9b90: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45  QLITE_LOCK_SHARE
9ba0: 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  D],.** <li> [SQL
9bb0: 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45  ITE_LOCK_RESERVE
9bc0: 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  D],.** <li> [SQL
9bd0: 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47  ITE_LOCK_PENDING
9be0: 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  ], or.** <li> [S
9bf0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55  QLITE_LOCK_EXCLU
9c00: 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a  SIVE]..** </ul>.
9c10: 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72 65  ** xLock() incre
9c20: 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78  ases the lock. x
9c30: 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65 61 73  Unlock() decreas
9c40: 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20  es the lock..** 
9c50: 54 68 65 20 78 43 68 65 63 6b 52 65 73 65 72 76  The xCheckReserv
9c60: 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 20  edLock() method 
9c70: 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 61  checks whether a
9c80: 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ny database conn
9c90: 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65  ection,.** eithe
9ca0: 72 20 69 6e 20 74 68 69 73 20 70 72 6f 63 65 73  r in this proces
9cb0: 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74 68  s or in some oth
9cc0: 65 72 20 70 72 6f 63 65 73 73 2c 20 69 73 20 68  er process, is h
9cd0: 6f 6c 64 69 6e 67 20 61 20 52 45 53 45 52 56 45  olding a RESERVE
9ce0: 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f  D,.** PENDING, o
9cf0: 72 20 45 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b  r EXCLUSIVE lock
9d00: 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 49   on the file.  I
9d10: 74 20 72 65 74 75 72 6e 73 20 74 72 75 65 0a 2a  t returns true.*
9d20: 2a 20 69 66 20 73 75 63 68 20 61 20 6c 6f 63 6b  * if such a lock
9d30: 20 65 78 69 73 74 73 20 61 6e 64 20 66 61 6c 73   exists and fals
9d40: 65 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a  e otherwise..**.
9d50: 2a 2a 20 54 68 65 20 78 46 69 6c 65 43 6f 6e 74  ** The xFileCont
9d60: 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69 73 20  rol() method is 
9d70: 61 20 67 65 6e 65 72 69 63 20 69 6e 74 65 72 66  a generic interf
9d80: 61 63 65 20 74 68 61 74 20 61 6c 6c 6f 77 73 20  ace that allows 
9d90: 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d  custom.** VFS im
9da0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74 6f  plementations to
9db0: 20 64 69 72 65 63 74 6c 79 20 63 6f 6e 74 72 6f   directly contro
9dc0: 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 75  l an open file u
9dd0: 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  sing the.** [sql
9de0: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
9df0: 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20  l()] interface. 
9e00: 20 54 68 65 20 73 65 63 6f 6e 64 20 22 6f 70 22   The second "op"
9e10: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 0a   argument is an.
9e20: 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70 63 6f 64  ** integer opcod
9e30: 65 2e 20 20 54 68 65 20 74 68 69 72 64 20 61 72  e.  The third ar
9e40: 67 75 6d 65 6e 74 20 69 73 20 61 20 67 65 6e 65  gument is a gene
9e50: 72 69 63 20 70 6f 69 6e 74 65 72 20 69 6e 74 65  ric pointer inte
9e60: 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74  nded to.** point
9e70: 20 74 6f 20 61 20 73 74 72 75 63 74 75 72 65 20   to a structure 
9e80: 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e  that may contain
9e90: 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 73 70   arguments or sp
9ea0: 61 63 65 20 69 6e 20 77 68 69 63 68 20 74 6f 0a  ace in which to.
9eb0: 2a 2a 20 77 72 69 74 65 20 72 65 74 75 72 6e 20  ** write return 
9ec0: 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74 69  values.  Potenti
9ed0: 61 6c 20 75 73 65 73 20 66 6f 72 20 78 46 69 6c  al uses for xFil
9ee0: 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74  eControl() might
9ef0: 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73   be.** functions
9f00: 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b   to enable block
9f10: 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68 20 74  ing locks with t
9f20: 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e  imeouts, to chan
9f30: 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e  ge the.** lockin
9f40: 67 20 73 74 72 61 74 65 67 79 20 28 66 6f 72 20  g strategy (for 
9f50: 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 65 20 64  example to use d
9f60: 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20  ot-file locks), 
9f70: 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62  to inquire.** ab
9f80: 6f 75 74 20 74 68 65 20 73 74 61 74 75 73 20 6f  out the status o
9f90: 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20  f a lock, or to 
9fa0: 62 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b  break stale lock
9fb0: 73 2e 20 20 54 68 65 20 53 51 4c 69 74 65 0a 2a  s.  The SQLite.*
9fc0: 2a 20 63 6f 72 65 20 72 65 73 65 72 76 65 73 20  * core reserves 
9fd0: 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73 73  all opcodes less
9fe0: 20 74 68 61 6e 20 31 30 30 20 66 6f 72 20 69 74   than 100 for it
9ff0: 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41 20  s own use..** A 
a000: 5b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70  [file control op
a010: 63 6f 64 65 73 20 7c 20 6c 69 73 74 20 6f 66 20  codes | list of 
a020: 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73 20 74 68  opcodes] less th
a030: 61 6e 20 31 30 30 20 69 73 20 61 76 61 69 6c 61  an 100 is availa
a040: 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74  ble..** Applicat
a050: 69 6f 6e 73 20 74 68 61 74 20 64 65 66 69 6e 65  ions that define
a060: 20 61 20 63 75 73 74 6f 6d 20 78 46 69 6c 65 43   a custom xFileC
a070: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73 68  ontrol method sh
a080: 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f 64 65 73  ould use opcodes
a090: 0a 2a 2a 20 67 72 65 61 74 65 72 20 74 68 61 6e  .** greater than
a0a0: 20 31 30 30 20 74 6f 20 61 76 6f 69 64 20 63 6f   100 to avoid co
a0b0: 6e 66 6c 69 63 74 73 2e 20 20 56 46 53 20 69 6d  nflicts.  VFS im
a0c0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68  plementations sh
a0d0: 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b  ould.** return [
a0e0: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d  SQLITE_NOTFOUND]
a0f0: 20 66 6f 72 20 66 69 6c 65 20 63 6f 6e 74 72 6f   for file contro
a100: 6c 20 6f 70 63 6f 64 65 73 20 74 68 61 74 20 74  l opcodes that t
a110: 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 72 65  hey do not.** re
a120: 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a 2a 20 54  cognize..**.** T
a130: 68 65 20 78 53 65 63 74 6f 72 53 69 7a 65 28 29  he xSectorSize()
a140: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
a150: 74 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20  the sector size 
a160: 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76 69 63 65  of the.** device
a170: 20 74 68 61 74 20 75 6e 64 65 72 6c 69 65 73 20   that underlies 
a180: 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 73  the file.  The s
a190: 65 63 74 6f 72 20 73 69 7a 65 20 69 73 20 74 68  ector size is th
a1a0: 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72 69  e.** minimum wri
a1b0: 74 65 20 74 68 61 74 20 63 61 6e 20 62 65 20 70  te that can be p
a1c0: 65 72 66 6f 72 6d 65 64 20 77 69 74 68 6f 75 74  erformed without
a1d0: 20 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20 6f   disturbing.** o
a1e0: 74 68 65 72 20 62 79 74 65 73 20 69 6e 20 74 68  ther bytes in th
a1f0: 65 20 66 69 6c 65 2e 20 20 54 68 65 20 78 44 65  e file.  The xDe
a200: 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74  viceCharacterist
a210: 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20  ics().** method 
a220: 72 65 74 75 72 6e 73 20 61 20 62 69 74 20 76 65  returns a bit ve
a230: 63 74 6f 72 20 64 65 73 63 72 69 62 69 6e 67 20  ctor describing 
a240: 62 65 68 61 76 69 6f 72 73 20 6f 66 20 74 68 65  behaviors of the
a250: 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 64  .** underlying d
a260: 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  evice:.**.** <ul
a270: 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  >.** <li> [SQLIT
a280: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d 0a  E_IOCAP_ATOMIC].
a290: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
a2a0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 5d  IOCAP_ATOMIC512]
a2b0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
a2c0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 5d  _IOCAP_ATOMIC1K]
a2d0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
a2e0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 5d  _IOCAP_ATOMIC2K]
a2f0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
a300: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 5d  _IOCAP_ATOMIC4K]
a310: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
a320: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 5d  _IOCAP_ATOMIC8K]
a330: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
a340: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b  _IOCAP_ATOMIC16K
a350: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
a360: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32  E_IOCAP_ATOMIC32
a370: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
a380: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36  TE_IOCAP_ATOMIC6
a390: 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  4K].** <li> [SQL
a3a0: 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41  ITE_IOCAP_SAFE_A
a3b0: 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  PPEND].** <li> [
a3c0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51  SQLITE_IOCAP_SEQ
a3d0: 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c  UENTIAL].** </ul
a3e0: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49  >.**.** The SQLI
a3f0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20  TE_IOCAP_ATOMIC 
a400: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
a410: 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f  hat all writes o
a420: 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72  f.** any size ar
a430: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53  e atomic.  The S
a440: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
a450: 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20  ICnnn values.** 
a460: 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73  mean that writes
a470: 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20   of blocks that 
a480: 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e  are nnn bytes in
a490: 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65   size and.** are
a4a0: 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61   aligned to an a
a4b0: 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20  ddress which is 
a4c0: 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69  an integer multi
a4d0: 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72  ple of.** nnn ar
a4e0: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53  e atomic.  The S
a4f0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
a500: 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65  _APPEND value me
a510: 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e  ans.** that when
a520: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65   data is appende
a530: 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65  d to a file, the
a540: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65   data is appende
a550: 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20  d.** first then 
a560: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
a570: 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64  file is extended
a580: 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65  , never the othe
a590: 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e  r.** way around.
a5a0: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
a5b0: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72  AP_SEQUENTIAL pr
a5c0: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61  operty means tha
a5d0: 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  t.** information
a5e0: 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64   is written to d
a5f0: 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20  isk in the same 
a600: 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a  order as calls.*
a610: 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a  * to xWrite()..*
a620: 2a 0a 2a 2a 20 49 66 20 78 52 65 61 64 28 29 20  *.** If xRead() 
a630: 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 49  returns SQLITE_I
a640: 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20  OERR_SHORT_READ 
a650: 69 74 20 6d 75 73 74 20 61 6c 73 6f 20 66 69 6c  it must also fil
a660: 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e 72 65  l.** in the unre
a670: 61 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66 20 74  ad portions of t
a680: 68 65 20 62 75 66 66 65 72 20 77 69 74 68 20 7a  he buffer with z
a690: 65 72 6f 73 2e 20 20 41 20 56 46 53 20 74 68 61  eros.  A VFS tha
a6a0: 74 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20 7a 65  t.** fails to ze
a6b0: 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65  ro-fill short re
a6c0: 61 64 73 20 6d 69 67 68 74 20 73 65 65 6d 20 74  ads might seem t
a6d0: 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76 65 72  o work.  However
a6e0: 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74 6f 20  ,.** failure to 
a6f0: 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20  zero-fill short 
a700: 72 65 61 64 73 20 77 69 6c 6c 20 65 76 65 6e 74  reads will event
a710: 75 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a 2a 2a  ually lead to.**
a720: 20 64 61 74 61 62 61 73 65 20 63 6f 72 72 75 70   database corrup
a730: 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  tion..*/.typedef
a740: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
a750: 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74  io_methods sqlit
a760: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73  e3_io_methods;.s
a770: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f  truct sqlite3_io
a780: 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74  _methods {.  int
a790: 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74   iVersion;.  int
a7a0: 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74   (*xClose)(sqlit
a7b0: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74  e3_file*);.  int
a7c0: 20 28 2a 78 52 65 61 64 29 28 73 71 6c 69 74 65   (*xRead)(sqlite
a7d0: 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20  3_file*, void*, 
a7e0: 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65  int iAmt, sqlite
a7f0: 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a  3_int64 iOfst);.
a800: 20 20 69 6e 74 20 28 2a 78 57 72 69 74 65 29 28    int (*xWrite)(
a810: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63  sqlite3_file*, c
a820: 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20  onst void*, int 
a830: 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e  iAmt, sqlite3_in
a840: 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e  t64 iOfst);.  in
a850: 74 20 28 2a 78 54 72 75 6e 63 61 74 65 29 28 73  t (*xTruncate)(s
a860: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71  qlite3_file*, sq
a870: 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 69 7a 65  lite3_int64 size
a880: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63  );.  int (*xSync
a890: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
a8a0: 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 69   int flags);.  i
a8b0: 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a 65 29 28  nt (*xFileSize)(
a8c0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73  sqlite3_file*, s
a8d0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 53  qlite3_int64 *pS
a8e0: 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c  ize);.  int (*xL
a8f0: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ock)(sqlite3_fil
a900: 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20  e*, int);.  int 
a910: 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74  (*xUnlock)(sqlit
a920: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a  e3_file*, int);.
a930: 20 20 69 6e 74 20 28 2a 78 43 68 65 63 6b 52 65    int (*xCheckRe
a940: 73 65 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69  servedLock)(sqli
a950: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a  te3_file*, int *
a960: 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20  pResOut);.  int 
a970: 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28  (*xFileControl)(
a980: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
a990: 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72  nt op, void *pAr
a9a0: 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65 63  g);.  int (*xSec
a9b0: 74 6f 72 53 69 7a 65 29 28 73 71 6c 69 74 65 33  torSize)(sqlite3
a9c0: 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28  _file*);.  int (
a9d0: 2a 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65  *xDeviceCharacte
a9e0: 72 69 73 74 69 63 73 29 28 73 71 6c 69 74 65 33  ristics)(sqlite3
a9f0: 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4d 65  _file*);.  /* Me
aa00: 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20  thods above are 
aa10: 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f  valid for versio
aa20: 6e 20 31 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  n 1 */.  int (*x
aa30: 53 68 6d 4d 61 70 29 28 73 71 6c 69 74 65 33 5f  ShmMap)(sqlite3_
aa40: 66 69 6c 65 2a 2c 20 69 6e 74 20 69 50 67 2c 20  file*, int iPg, 
aa50: 69 6e 74 20 70 67 73 7a 2c 20 69 6e 74 2c 20 76  int pgsz, int, v
aa60: 6f 69 64 20 76 6f 6c 61 74 69 6c 65 2a 2a 29 3b  oid volatile**);
aa70: 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4c 6f 63  .  int (*xShmLoc
aa80: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  k)(sqlite3_file*
aa90: 2c 20 69 6e 74 20 6f 66 66 73 65 74 2c 20 69 6e  , int offset, in
aaa0: 74 20 6e 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b  t n, int flags);
aab0: 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 6d 42 61  .  void (*xShmBa
aac0: 72 72 69 65 72 29 28 73 71 6c 69 74 65 33 5f 66  rrier)(sqlite3_f
aad0: 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  ile*);.  int (*x
aae0: 53 68 6d 55 6e 6d 61 70 29 28 73 71 6c 69 74 65  ShmUnmap)(sqlite
aaf0: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 64 65 6c  3_file*, int del
ab00: 65 74 65 46 6c 61 67 29 3b 0a 20 20 2f 2a 20 4d  eteFlag);.  /* M
ab10: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
ab20: 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69   valid for versi
ab30: 6f 6e 20 32 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  on 2 */.  int (*
ab40: 78 46 65 74 63 68 29 28 73 71 6c 69 74 65 33 5f  xFetch)(sqlite3_
ab50: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
ab60: 6e 74 36 34 20 69 4f 66 73 74 2c 20 69 6e 74 20  nt64 iOfst, int 
ab70: 69 41 6d 74 2c 20 76 6f 69 64 20 2a 2a 70 70 29  iAmt, void **pp)
ab80: 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 66 65 74  ;.  int (*xUnfet
ab90: 63 68 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ch)(sqlite3_file
aba0: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
abb0: 20 69 4f 66 73 74 2c 20 76 6f 69 64 20 2a 70 29   iOfst, void *p)
abc0: 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61  ;.  /* Methods a
abd0: 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66  bove are valid f
abe0: 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 2a 2f 0a  or version 3 */.
abf0: 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20    /* Additional 
ac00: 6d 65 74 68 6f 64 73 20 6d 61 79 20 62 65 20 61  methods may be a
ac10: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72  dded in future r
ac20: 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f  eleases */.};../
ac30: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
ac40: 74 61 6e 64 61 72 64 20 46 69 6c 65 20 43 6f 6e  tandard File Con
ac50: 74 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a 20  trol Opcodes.** 
ac60: 4b 45 59 57 4f 52 44 53 3a 20 7b 66 69 6c 65 20  KEYWORDS: {file 
ac70: 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 7d  control opcodes}
ac80: 20 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f   {file control o
ac90: 70 63 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  pcode}.**.** The
aca0: 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74  se integer const
acb0: 61 6e 74 73 20 61 72 65 20 6f 70 63 6f 64 65 73  ants are opcodes
acc0: 20 66 6f 72 20 74 68 65 20 78 46 69 6c 65 43 6f   for the xFileCo
acd0: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20  ntrol method.** 
ace0: 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
acf0: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
ad00: 63 74 20 61 6e 64 20 66 6f 72 20 74 68 65 20 5b  ct and for the [
ad10: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
ad20: 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72  trol()].** inter
ad30: 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  face..**.** <ul>
ad40: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
ad50: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45  _FCNTL_LOCKSTATE
ad60: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
ad70: 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54  E_FCNTL_LOCKSTAT
ad80: 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  E] opcode is use
ad90: 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e  d for debugging.
ada0: 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65    This.** opcode
adb0: 20 63 61 75 73 65 73 20 74 68 65 20 78 46 69 6c   causes the xFil
adc0: 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20  eControl method 
add0: 74 6f 20 77 72 69 74 65 20 74 68 65 20 63 75 72  to write the cur
ade0: 72 65 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a  rent state of.**
adf0: 20 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f   the lock (one o
ae00: 66 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e  f [SQLITE_LOCK_N
ae10: 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f  ONE], [SQLITE_LO
ae20: 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b  CK_SHARED],.** [
ae30: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45  SQLITE_LOCK_RESE
ae40: 52 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c  RVED], [SQLITE_L
ae50: 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72  OCK_PENDING], or
ae60: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58   [SQLITE_LOCK_EX
ae70: 43 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74  CLUSIVE]).** int
ae80: 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 74 68 61  o an integer tha
ae90: 74 20 74 68 65 20 70 41 72 67 20 61 72 67 75 6d  t the pArg argum
aea0: 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54  ent points to. T
aeb0: 68 69 73 20 63 61 70 61 62 69 6c 69 74 79 0a 2a  his capability.*
aec0: 2a 20 69 73 20 75 73 65 64 20 64 75 72 69 6e 67  * is used during
aed0: 20 74 65 73 74 69 6e 67 20 61 6e 64 20 69 73 20   testing and is 
aee0: 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 77  only available w
aef0: 68 65 6e 20 74 68 65 20 53 51 4c 49 54 45 5f 54  hen the SQLITE_T
af00: 45 53 54 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74  EST.** compile-t
af10: 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 73  ime option is us
af20: 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ed..**.** <li>[[
af30: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a  SQLITE_FCNTL_SIZ
af40: 45 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 54 68 65 20  E_HINT]].** The 
af50: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49  [SQLITE_FCNTL_SI
af60: 5a 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65 20  ZE_HINT] opcode 
af70: 69 73 20 75 73 65 64 20 62 79 20 53 51 4c 69 74  is used by SQLit
af80: 65 20 74 6f 20 67 69 76 65 20 74 68 65 20 56 46  e to give the VF
af90: 53 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68 69 6e  S.** layer a hin
afa0: 74 20 6f 66 20 68 6f 77 20 6c 61 72 67 65 20 74  t of how large t
afb0: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
afc0: 20 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62 65   will grow to be
afd0: 20 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20 63   during the.** c
afe0: 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74 69  urrent transacti
aff0: 6f 6e 2e 20 20 54 68 69 73 20 68 69 6e 74 20 69  on.  This hint i
b000: 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 64  s not guaranteed
b010: 20 74 6f 20 62 65 20 61 63 63 75 72 61 74 65 20   to be accurate 
b020: 62 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66 74  but it.** is oft
b030: 65 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65 20 75  en close.  The u
b040: 6e 64 65 72 6c 79 69 6e 67 20 56 46 53 20 6d 69  nderlying VFS mi
b050: 67 68 74 20 63 68 6f 6f 73 65 20 74 6f 20 70 72  ght choose to pr
b060: 65 61 6c 6c 6f 63 61 74 65 20 64 61 74 61 62 61  eallocate databa
b070: 73 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63 65  se.** file space
b080: 20 62 61 73 65 64 20 6f 6e 20 74 68 69 73 20 68   based on this h
b090: 69 6e 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  int in order to 
b0a0: 68 65 6c 70 20 77 72 69 74 65 73 20 74 6f 20 74  help writes to t
b0b0: 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66  he database.** f
b0c0: 69 6c 65 20 72 75 6e 20 66 61 73 74 65 72 2e 0a  ile run faster..
b0d0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
b0e0: 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53  TE_FCNTL_CHUNK_S
b0f0: 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  IZE]].** The [SQ
b100: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b  LITE_FCNTL_CHUNK
b110: 5f 53 49 5a 45 5d 20 6f 70 63 6f 64 65 20 69 73  _SIZE] opcode is
b120: 20 75 73 65 64 20 74 6f 20 72 65 71 75 65 73 74   used to request
b130: 20 74 68 61 74 20 74 68 65 20 56 46 53 0a 2a 2a   that the VFS.**
b140: 20 65 78 74 65 6e 64 73 20 61 6e 64 20 74 72 75   extends and tru
b150: 6e 63 61 74 65 73 20 74 68 65 20 64 61 74 61 62  ncates the datab
b160: 61 73 65 20 66 69 6c 65 20 69 6e 20 63 68 75 6e  ase file in chun
b170: 6b 73 20 6f 66 20 61 20 73 69 7a 65 20 73 70 65  ks of a size spe
b180: 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65  cified.** by the
b190: 20 75 73 65 72 2e 20 54 68 65 20 66 6f 75 72 74   user. The fourt
b1a0: 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73  h argument to [s
b1b0: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
b1c0: 72 6f 6c 28 29 5d 20 73 68 6f 75 6c 64 20 0a 2a  rol()] should .*
b1d0: 2a 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 69 6e  * point to an in
b1e0: 74 65 67 65 72 20 28 74 79 70 65 20 69 6e 74 29  teger (type int)
b1f0: 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
b200: 6e 65 77 20 63 68 75 6e 6b 2d 73 69 7a 65 20 74  new chunk-size t
b210: 6f 20 75 73 65 0a 2a 2a 20 66 6f 72 20 74 68 65  o use.** for the
b220: 20 6e 6f 6d 69 6e 61 74 65 64 20 64 61 74 61 62   nominated datab
b230: 61 73 65 2e 20 41 6c 6c 6f 63 61 74 69 6e 67 20  ase. Allocating 
b240: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 73 70  database file sp
b250: 61 63 65 20 69 6e 20 6c 61 72 67 65 0a 2a 2a 20  ace in large.** 
b260: 63 68 75 6e 6b 73 20 28 73 61 79 20 31 4d 42 20  chunks (say 1MB 
b270: 61 74 20 61 20 74 69 6d 65 29 2c 20 6d 61 79 20  at a time), may 
b280: 72 65 64 75 63 65 20 66 69 6c 65 2d 73 79 73 74  reduce file-syst
b290: 65 6d 20 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e  em fragmentation
b2a0: 20 61 6e 64 0a 2a 2a 20 69 6d 70 72 6f 76 65 20   and.** improve 
b2b0: 70 65 72 66 6f 72 6d 61 6e 63 65 20 6f 6e 20 73  performance on s
b2c0: 6f 6d 65 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 0a  ome systems..**.
b2d0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
b2e0: 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54  FCNTL_FILE_POINT
b2f0: 45 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ER]].** The [SQL
b300: 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50  ITE_FCNTL_FILE_P
b310: 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 69  OINTER] opcode i
b320: 73 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e  s used to obtain
b330: 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f   a pointer.** to
b340: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   the [sqlite3_fi
b350: 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f 63  le] object assoc
b360: 69 61 74 65 64 20 77 69 74 68 20 61 20 70 61 72  iated with a par
b370: 74 69 63 75 6c 61 72 20 64 61 74 61 62 61 73 65  ticular database
b380: 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  .** connection. 
b390: 20 53 65 65 20 74 68 65 20 5b 73 71 6c 69 74 65   See the [sqlite
b3a0: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
b3b0: 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20  ] documentation 
b3c0: 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61  for.** additiona
b3d0: 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  l information..*
b3e0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
b3f0: 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49  E_FCNTL_SYNC_OMI
b400: 54 54 45 44 5d 5d 0a 2a 2a 20 4e 6f 20 6c 6f 6e  TTED]].** No lon
b410: 67 65 72 20 69 6e 20 75 73 65 2e 0a 2a 2a 0a 2a  ger in use..**.*
b420: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
b430: 43 4e 54 4c 5f 53 59 4e 43 5d 5d 0a 2a 2a 20 54  CNTL_SYNC]].** T
b440: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
b450: 5f 53 59 4e 43 5d 20 6f 70 63 6f 64 65 20 69 73  _SYNC] opcode is
b460: 20 67 65 6e 65 72 61 74 65 64 20 69 6e 74 65 72   generated inter
b470: 6e 61 6c 6c 79 20 62 79 20 53 51 4c 69 74 65 20  nally by SQLite 
b480: 61 6e 64 0a 2a 2a 20 73 65 6e 74 20 74 6f 20 74  and.** sent to t
b490: 68 65 20 56 46 53 20 69 6d 6d 65 64 69 61 74 65  he VFS immediate
b4a0: 6c 79 20 62 65 66 6f 72 65 20 74 68 65 20 78 53  ly before the xS
b4b0: 79 6e 63 20 6d 65 74 68 6f 64 20 69 73 20 69 6e  ync method is in
b4c0: 76 6f 6b 65 64 20 6f 6e 20 61 0a 2a 2a 20 64 61  voked on a.** da
b4d0: 74 61 62 61 73 65 20 66 69 6c 65 20 64 65 73 63  tabase file desc
b4e0: 72 69 70 74 6f 72 2e 20 4f 72 2c 20 69 66 20 74  riptor. Or, if t
b4f0: 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 20  he xSync method 
b500: 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 0a  is not invoked .
b510: 2a 2a 20 62 65 63 61 75 73 65 20 74 68 65 20 75  ** because the u
b520: 73 65 72 20 68 61 73 20 63 6f 6e 66 69 67 75 72  ser has configur
b530: 65 64 20 53 51 4c 69 74 65 20 77 69 74 68 20 0a  ed SQLite with .
b540: 2a 2a 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68  ** [PRAGMA synch
b550: 72 6f 6e 6f 75 73 20 7c 20 50 52 41 47 4d 41 20  ronous | PRAGMA 
b560: 73 79 6e 63 68 72 6f 6e 6f 75 73 3d 4f 46 46 5d  synchronous=OFF]
b570: 20 69 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 69   it is invoked i
b580: 6e 20 70 6c 61 63 65 20 0a 2a 2a 20 6f 66 20 74  n place .** of t
b590: 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 2e  he xSync method.
b5a0: 20 49 6e 20 6d 6f 73 74 20 63 61 73 65 73 2c 20   In most cases, 
b5b0: 74 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75  the pointer argu
b5c0: 6d 65 6e 74 20 70 61 73 73 65 64 20 77 69 74 68  ment passed with
b5d0: 0a 2a 2a 20 74 68 69 73 20 66 69 6c 65 2d 63 6f  .** this file-co
b5e0: 6e 74 72 6f 6c 20 69 73 20 4e 55 4c 4c 2e 20 48  ntrol is NULL. H
b5f0: 6f 77 65 76 65 72 2c 20 69 66 20 74 68 65 20 64  owever, if the d
b600: 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 73 20  atabase file is 
b610: 62 65 69 6e 67 20 73 79 6e 63 65 64 0a 2a 2a 20  being synced.** 
b620: 61 73 20 70 61 72 74 20 6f 66 20 61 20 6d 75 6c  as part of a mul
b630: 74 69 2d 64 61 74 61 62 61 73 65 20 63 6f 6d 6d  ti-database comm
b640: 69 74 2c 20 74 68 65 20 61 72 67 75 6d 65 6e 74  it, the argument
b650: 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 6e 75 6c   points to a nul
b660: 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73  -terminated.** s
b670: 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67  tring containing
b680: 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   the transaction
b690: 73 20 6d 61 73 74 65 72 2d 6a 6f 75 72 6e 61 6c  s master-journal
b6a0: 20 66 69 6c 65 20 6e 61 6d 65 2e 20 56 46 53 65   file name. VFSe
b6b0: 73 20 74 68 61 74 20 0a 2a 2a 20 64 6f 20 6e 6f  s that .** do no
b6c0: 74 20 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e  t need this sign
b6d0: 61 6c 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74  al should silent
b6e0: 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 73 20 6f  ly ignore this o
b6f0: 70 63 6f 64 65 2e 20 41 70 70 6c 69 63 61 74 69  pcode. Applicati
b700: 6f 6e 73 20 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e  ons .** should n
b710: 6f 74 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33  ot call [sqlite3
b720: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
b730: 20 77 69 74 68 20 74 68 69 73 20 6f 70 63 6f 64   with this opcod
b740: 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61  e as doing so ma
b750: 79 20 0a 2a 2a 20 64 69 73 72 75 70 74 20 74 68  y .** disrupt th
b760: 65 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20 74  e operation of t
b770: 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20 56  he specialized V
b780: 46 53 65 73 20 74 68 61 74 20 64 6f 20 72 65 71  FSes that do req
b790: 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a  uire it.  .**.**
b7a0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
b7b0: 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45  NTL_COMMIT_PHASE
b7c0: 54 57 4f 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  TWO]].** The [SQ
b7d0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49  LITE_FCNTL_COMMI
b7e0: 54 5f 50 48 41 53 45 54 57 4f 5d 20 6f 70 63 6f  T_PHASETWO] opco
b7f0: 64 65 20 69 73 20 67 65 6e 65 72 61 74 65 64 20  de is generated 
b800: 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 53 51  internally by SQ
b810: 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 73 65 6e 74  Lite.** and sent
b820: 20 74 6f 20 74 68 65 20 56 46 53 20 61 66 74 65   to the VFS afte
b830: 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  r a transaction 
b840: 68 61 73 20 62 65 65 6e 20 63 6f 6d 6d 69 74 74  has been committ
b850: 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 0a 2a  ed immediately.*
b860: 2a 20 62 75 74 20 62 65 66 6f 72 65 20 74 68 65  * but before the
b870: 20 64 61 74 61 62 61 73 65 20 69 73 20 75 6e 6c   database is unl
b880: 6f 63 6b 65 64 2e 20 56 46 53 65 73 20 74 68 61  ocked. VFSes tha
b890: 74 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68  t do not need th
b8a0: 69 73 20 73 69 67 6e 61 6c 0a 2a 2a 20 73 68 6f  is signal.** sho
b8b0: 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e  uld silently ign
b8c0: 6f 72 65 20 74 68 69 73 20 6f 70 63 6f 64 65 2e  ore this opcode.
b8d0: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68   Applications sh
b8e0: 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 0a 2a 2a  ould not call.**
b8f0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
b900: 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74  ontrol()] with t
b910: 68 69 73 20 6f 70 63 6f 64 65 20 61 73 20 64 6f  his opcode as do
b920: 69 6e 67 20 73 6f 20 6d 61 79 20 64 69 73 72 75  ing so may disru
b930: 70 74 20 74 68 65 20 0a 2a 2a 20 6f 70 65 72 61  pt the .** opera
b940: 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63  tion of the spec
b950: 69 61 6c 69 7a 65 64 20 56 46 53 65 73 20 74 68  ialized VFSes th
b960: 61 74 20 64 6f 20 72 65 71 75 69 72 65 20 69 74  at do require it
b970: 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  .  .**.** <li>[[
b980: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
b990: 33 32 5f 41 56 5f 52 45 54 52 59 5d 5d 0a 2a 2a  32_AV_RETRY]].**
b9a0: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43   ^The [SQLITE_FC
b9b0: 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54  NTL_WIN32_AV_RET
b9c0: 52 59 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  RY] opcode is us
b9d0: 65 64 20 74 6f 20 63 6f 6e 66 69 67 75 72 65 20  ed to configure 
b9e0: 61 75 74 6f 6d 61 74 69 63 0a 2a 2a 20 72 65 74  automatic.** ret
b9f0: 72 79 20 63 6f 75 6e 74 73 20 61 6e 64 20 69 6e  ry counts and in
ba00: 74 65 72 76 61 6c 73 20 66 6f 72 20 63 65 72 74  tervals for cert
ba10: 61 69 6e 20 64 69 73 6b 20 49 2f 4f 20 6f 70 65  ain disk I/O ope
ba20: 72 61 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 0a  rations for the.
ba30: 2a 2a 20 77 69 6e 64 6f 77 73 20 5b 56 46 53 5d  ** windows [VFS]
ba40: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 70 72 6f   in order to pro
ba50: 76 69 64 65 20 72 6f 62 75 73 74 6e 65 73 73 20  vide robustness 
ba60: 69 6e 20 74 68 65 20 70 72 65 73 65 6e 63 65 20  in the presence 
ba70: 6f 66 0a 2a 2a 20 61 6e 74 69 2d 76 69 72 75 73  of.** anti-virus
ba80: 20 70 72 6f 67 72 61 6d 73 2e 20 20 42 79 20 64   programs.  By d
ba90: 65 66 61 75 6c 74 2c 20 74 68 65 20 77 69 6e 64  efault, the wind
baa0: 6f 77 73 20 56 46 53 20 77 69 6c 6c 20 72 65 74  ows VFS will ret
bab0: 72 79 20 66 69 6c 65 20 72 65 61 64 2c 0a 2a 2a  ry file read,.**
bac0: 20 66 69 6c 65 20 77 72 69 74 65 2c 20 61 6e 64   file write, and
bad0: 20 66 69 6c 65 20 64 65 6c 65 74 65 20 6f 70 65   file delete ope
bae0: 72 61 74 69 6f 6e 73 20 75 70 20 74 6f 20 31 30  rations up to 10
baf0: 20 74 69 6d 65 73 2c 20 77 69 74 68 20 61 20 64   times, with a d
bb00: 65 6c 61 79 0a 2a 2a 20 6f 66 20 32 35 20 6d 69  elay.** of 25 mi
bb10: 6c 6c 69 73 65 63 6f 6e 64 73 20 62 65 66 6f 72  lliseconds befor
bb20: 65 20 74 68 65 20 66 69 72 73 74 20 72 65 74 72  e the first retr
bb30: 79 20 61 6e 64 20 77 69 74 68 20 74 68 65 20 64  y and with the d
bb40: 65 6c 61 79 20 69 6e 63 72 65 61 73 69 6e 67 0a  elay increasing.
bb50: 2a 2a 20 62 79 20 61 6e 20 61 64 64 69 74 69 6f  ** by an additio
bb60: 6e 61 6c 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f  nal 25 milliseco
bb70: 6e 64 73 20 77 69 74 68 20 65 61 63 68 20 73 75  nds with each su
bb80: 62 73 65 71 75 65 6e 74 20 72 65 74 72 79 2e 20  bsequent retry. 
bb90: 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20   This.** opcode 
bba0: 61 6c 6c 6f 77 73 20 74 68 65 73 65 20 74 77 6f  allows these two
bbb0: 20 76 61 6c 75 65 73 20 28 31 30 20 72 65 74 72   values (10 retr
bbc0: 69 65 73 20 61 6e 64 20 32 35 20 6d 69 6c 6c 69  ies and 25 milli
bbd0: 73 65 63 6f 6e 64 73 20 6f 66 20 64 65 6c 61 79  seconds of delay
bbe0: 29 0a 2a 2a 20 74 6f 20 62 65 20 61 64 6a 75 73  ).** to be adjus
bbf0: 74 65 64 2e 20 20 54 68 65 20 76 61 6c 75 65 73  ted.  The values
bc00: 20 61 72 65 20 63 68 61 6e 67 65 64 20 66 6f 72   are changed for
bc10: 20 61 6c 6c 20 64 61 74 61 62 61 73 65 20 63 6f   all database co
bc20: 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 77 69 74  nnections.** wit
bc30: 68 69 6e 20 74 68 65 20 73 61 6d 65 20 70 72 6f  hin the same pro
bc40: 63 65 73 73 2e 20 20 54 68 65 20 61 72 67 75 6d  cess.  The argum
bc50: 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ent is a pointer
bc60: 20 74 6f 20 61 6e 20 61 72 72 61 79 20 6f 66 20   to an array of 
bc70: 74 77 6f 0a 2a 2a 20 69 6e 74 65 67 65 72 73 20  two.** integers 
bc80: 77 68 65 72 65 20 74 68 65 20 66 69 72 73 74 20  where the first 
bc90: 69 6e 74 65 67 65 72 20 69 20 74 68 65 20 6e 65  integer i the ne
bca0: 77 20 72 65 74 72 79 20 63 6f 75 6e 74 20 61 6e  w retry count an
bcb0: 64 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20  d the second.** 
bcc0: 69 6e 74 65 67 65 72 20 69 73 20 74 68 65 20 64  integer is the d
bcd0: 65 6c 61 79 2e 20 20 49 66 20 65 69 74 68 65 72  elay.  If either
bce0: 20 69 6e 74 65 67 65 72 20 69 73 20 6e 65 67 61   integer is nega
bcf0: 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20 73  tive, then the s
bd00: 65 74 74 69 6e 67 0a 2a 2a 20 69 73 20 6e 6f 74  etting.** is not
bd10: 20 63 68 61 6e 67 65 64 20 62 75 74 20 69 6e 73   changed but ins
bd20: 74 65 61 64 20 74 68 65 20 70 72 69 6f 72 20 76  tead the prior v
bd30: 61 6c 75 65 20 6f 66 20 74 68 61 74 20 73 65 74  alue of that set
bd40: 74 69 6e 67 20 69 73 20 77 72 69 74 74 65 6e 0a  ting is written.
bd50: 2a 2a 20 69 6e 74 6f 20 74 68 65 20 61 72 72 61  ** into the arra
bd60: 79 20 65 6e 74 72 79 2c 20 61 6c 6c 6f 77 69 6e  y entry, allowin
bd70: 67 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 65  g the current re
bd80: 74 72 79 20 73 65 74 74 69 6e 67 73 20 74 6f 20  try settings to 
bd90: 62 65 0a 2a 2a 20 69 6e 74 65 72 72 6f 67 61 74  be.** interrogat
bda0: 65 64 2e 20 20 54 68 65 20 7a 44 62 4e 61 6d 65  ed.  The zDbName
bdb0: 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 69 67   parameter is ig
bdc0: 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  nored..**.** <li
bdd0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
bde0: 50 45 52 53 49 53 54 5f 57 41 4c 5d 5d 0a 2a 2a  PERSIST_WAL]].**
bdf0: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43   ^The [SQLITE_FC
be00: 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d  NTL_PERSIST_WAL]
be10: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
be20: 74 6f 20 73 65 74 20 6f 72 20 71 75 65 72 79 20  to set or query 
be30: 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e  the.** persisten
be40: 74 20 5b 57 41 4c 20 7c 20 57 72 69 74 65 20 41  t [WAL | Write A
be50: 68 65 61 64 20 4c 6f 67 5d 20 73 65 74 74 69 6e  head Log] settin
be60: 67 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c 20  g.  By default, 
be70: 74 68 65 20 61 75 78 69 6c 69 61 72 79 0a 2a 2a  the auxiliary.**
be80: 20 77 72 69 74 65 20 61 68 65 61 64 20 6c 6f 67   write ahead log
be90: 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d 6f   and shared memo
bea0: 72 79 20 66 69 6c 65 73 20 75 73 65 64 20 66 6f  ry files used fo
beb0: 72 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f  r transaction co
bec0: 6e 74 72 6f 6c 0a 2a 2a 20 61 72 65 20 61 75 74  ntrol.** are aut
bed0: 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74  omatically delet
bee0: 65 64 20 77 68 65 6e 20 74 68 65 20 6c 61 74 65  ed when the late
bef0: 73 74 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f  st connection to
bf00: 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
bf10: 20 63 6c 6f 73 65 73 2e 20 20 53 65 74 74 69 6e   closes.  Settin
bf20: 67 20 70 65 72 73 69 73 74 65 6e 74 20 57 41 4c  g persistent WAL
bf30: 20 6d 6f 64 65 20 63 61 75 73 65 73 20 74 68 6f   mode causes tho
bf40: 73 65 20 66 69 6c 65 73 20 74 6f 20 70 65 72 73  se files to pers
bf50: 69 73 74 20 61 66 74 65 72 0a 2a 2a 20 63 6c 6f  ist after.** clo
bf60: 73 65 2e 20 20 50 65 72 73 69 73 74 69 6e 67 20  se.  Persisting 
bf70: 74 68 65 20 66 69 6c 65 73 20 69 73 20 75 73 65  the files is use
bf80: 66 75 6c 20 77 68 65 6e 20 6f 74 68 65 72 20 70  ful when other p
bf90: 72 6f 63 65 73 73 65 73 20 74 68 61 74 20 64 6f  rocesses that do
bfa0: 20 6e 6f 74 0a 2a 2a 20 68 61 76 65 20 77 72 69   not.** have wri
bfb0: 74 65 20 70 65 72 6d 69 73 73 69 6f 6e 20 6f 6e  te permission on
bfc0: 20 74 68 65 20 64 69 72 65 63 74 6f 72 79 20 63   the directory c
bfd0: 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 64 61  ontaining the da
bfe0: 74 61 62 61 73 65 20 66 69 6c 65 20 77 61 6e 74  tabase file want
bff0: 0a 2a 2a 20 74 6f 20 72 65 61 64 20 74 68 65 20  .** to read the 
c000: 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 61  database file, a
c010: 73 20 74 68 65 20 57 41 4c 20 61 6e 64 20 73 68  s the WAL and sh
c020: 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65  ared memory file
c030: 73 20 6d 75 73 74 20 65 78 69 73 74 0a 2a 2a 20  s must exist.** 
c040: 69 6e 20 6f 72 64 65 72 20 66 6f 72 20 74 68 65  in order for the
c050: 20 64 61 74 61 62 61 73 65 20 74 6f 20 62 65 20   database to be 
c060: 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20 66  readable.  The f
c070: 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
c080: 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  to.** [sqlite3_f
c090: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66  ile_control()] f
c0a0: 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73  or this opcode s
c0b0: 68 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74  hould be a point
c0c0: 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  er to an integer
c0d0: 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65  ..** That intege
c0e0: 72 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c  r is 0 to disabl
c0f0: 65 20 70 65 72 73 69 73 74 65 6e 74 20 57 41 4c  e persistent WAL
c100: 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20 65 6e   mode or 1 to en
c110: 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74 0a  able persistent.
c120: 2a 2a 20 57 41 4c 20 6d 6f 64 65 2e 20 20 49 66  ** WAL mode.  If
c130: 20 74 68 65 20 69 6e 74 65 67 65 72 20 69 73 20   the integer is 
c140: 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 73 20 6f  -1, then it is o
c150: 76 65 72 77 72 69 74 74 65 6e 20 77 69 74 68 20  verwritten with 
c160: 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 57  the current.** W
c170: 41 4c 20 70 65 72 73 69 73 74 65 6e 63 65 20 73  AL persistence s
c180: 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  etting..**.** <l
c190: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
c1a0: 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57  _POWERSAFE_OVERW
c1b0: 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b  RITE]].** ^The [
c1c0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57  SQLITE_FCNTL_POW
c1d0: 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45  ERSAFE_OVERWRITE
c1e0: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
c1f0: 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65 72 79   to set or query
c200: 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 74 65   the.** persiste
c210: 6e 74 20 22 70 6f 77 65 72 73 61 66 65 2d 6f 76  nt "powersafe-ov
c220: 65 72 77 72 69 74 65 22 20 6f 72 20 22 50 53 4f  erwrite" or "PSO
c230: 57 22 20 73 65 74 74 69 6e 67 2e 20 20 54 68 65  W" setting.  The
c240: 20 50 53 4f 57 20 73 65 74 74 69 6e 67 0a 2a 2a   PSOW setting.**
c250: 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 65 20   determines the 
c260: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f  [SQLITE_IOCAP_PO
c270: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54  WERSAFE_OVERWRIT
c280: 45 5d 20 62 69 74 20 6f 66 20 74 68 65 0a 2a 2a  E] bit of the.**
c290: 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65   xDeviceCharacte
c2a0: 72 69 73 74 69 63 73 20 6d 65 74 68 6f 64 73 2e  ristics methods.
c2b0: 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   The fourth para
c2c0: 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c  meter to.** [sql
c2d0: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
c2e0: 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20 6f 70  l()] for this op
c2f0: 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65 20 61  code should be a
c300: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
c310: 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20  nteger..** That 
c320: 69 6e 74 65 67 65 72 20 69 73 20 30 20 74 6f 20  integer is 0 to 
c330: 64 69 73 61 62 6c 65 20 7a 65 72 6f 2d 64 61 6d  disable zero-dam
c340: 61 67 65 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f  age mode or 1 to
c350: 20 65 6e 61 62 6c 65 20 7a 65 72 6f 2d 64 61 6d   enable zero-dam
c360: 61 67 65 0a 2a 2a 20 6d 6f 64 65 2e 20 20 49 66  age.** mode.  If
c370: 20 74 68 65 20 69 6e 74 65 67 65 72 20 69 73 20   the integer is 
c380: 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 73 20 6f  -1, then it is o
c390: 76 65 72 77 72 69 74 74 65 6e 20 77 69 74 68 20  verwritten with 
c3a0: 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 7a  the current.** z
c3b0: 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20  ero-damage mode 
c3c0: 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c  setting..**.** <
c3d0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
c3e0: 4c 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a  L_OVERWRITE]].**
c3f0: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43   ^The [SQLITE_FC
c400: 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f  NTL_OVERWRITE] o
c410: 70 63 6f 64 65 20 69 73 20 69 6e 76 6f 6b 65 64  pcode is invoked
c420: 20 62 79 20 53 51 4c 69 74 65 20 61 66 74 65 72   by SQLite after
c430: 20 6f 70 65 6e 69 6e 67 0a 2a 2a 20 61 20 77 72   opening.** a wr
c440: 69 74 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  ite transaction 
c450: 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74  to indicate that
c460: 2c 20 75 6e 6c 65 73 73 20 69 74 20 69 73 20 72  , unless it is r
c470: 6f 6c 6c 65 64 20 62 61 63 6b 20 66 6f 72 20 73  olled back for s
c480: 6f 6d 65 0a 2a 2a 20 72 65 61 73 6f 6e 2c 20 74  ome.** reason, t
c490: 68 65 20 65 6e 74 69 72 65 20 64 61 74 61 62 61  he entire databa
c4a0: 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20  se file will be 
c4b0: 6f 76 65 72 77 72 69 74 74 65 6e 20 62 79 20 74  overwritten by t
c4c0: 68 65 20 63 75 72 72 65 6e 74 20 0a 2a 2a 20 74  he current .** t
c4d0: 72 61 6e 73 61 63 74 69 6f 6e 2e 20 54 68 69 73  ransaction. This
c4e0: 20 69 73 20 75 73 65 64 20 62 79 20 56 41 43 55   is used by VACU
c4f0: 55 4d 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a  UM operations..*
c500: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
c510: 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d  E_FCNTL_VFSNAME]
c520: 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ].** ^The [SQLIT
c530: 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d  E_FCNTL_VFSNAME]
c540: 20 6f 70 63 6f 64 65 20 63 61 6e 20 62 65 20 75   opcode can be u
c550: 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68  sed to obtain th
c560: 65 20 6e 61 6d 65 73 20 6f 66 0a 2a 2a 20 61 6c  e names of.** al
c570: 6c 20 5b 56 46 53 65 73 5d 20 69 6e 20 74 68 65  l [VFSes] in the
c580: 20 56 46 53 20 73 74 61 63 6b 2e 20 20 54 68 65   VFS stack.  The
c590: 20 6e 61 6d 65 73 20 61 72 65 20 6f 66 20 61 6c   names are of al
c5a0: 6c 20 56 46 53 20 73 68 69 6d 73 20 61 6e 64 20  l VFS shims and 
c5b0: 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 62 6f 74  the.** final bot
c5c0: 74 6f 6d 2d 6c 65 76 65 6c 20 56 46 53 20 61 72  tom-level VFS ar
c5d0: 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d  e written into m
c5e0: 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66  emory obtained f
c5f0: 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  rom .** [sqlite3
c600: 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 74  _malloc()] and t
c610: 68 65 20 72 65 73 75 6c 74 20 69 73 20 73 74 6f  he result is sto
c620: 72 65 64 20 69 6e 20 74 68 65 20 63 68 61 72 2a  red in the char*
c630: 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 74 68 61   variable.** tha
c640: 74 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  t the fourth par
c650: 61 6d 65 74 65 72 20 6f 66 20 5b 73 71 6c 69 74  ameter of [sqlit
c660: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
c670: 29 5d 20 70 6f 69 6e 74 73 20 74 6f 2e 0a 2a 2a  )] points to..**
c680: 20 54 68 65 20 63 61 6c 6c 65 72 20 69 73 20 72   The caller is r
c690: 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 66  esponsible for f
c6a0: 72 65 65 69 6e 67 20 74 68 65 20 6d 65 6d 6f 72  reeing the memor
c6b0: 79 20 77 68 65 6e 20 64 6f 6e 65 2e 20 20 41 73  y when done.  As
c6c0: 20 77 69 74 68 0a 2a 2a 20 61 6c 6c 20 66 69 6c   with.** all fil
c6d0: 65 2d 63 6f 6e 74 72 6f 6c 20 61 63 74 69 6f 6e  e-control action
c6e0: 73 2c 20 74 68 65 72 65 20 69 73 20 6e 6f 20 67  s, there is no g
c6f0: 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 74 68  uarantee that th
c700: 69 73 20 77 69 6c 6c 20 61 63 74 75 61 6c 6c 79  is will actually
c710: 0a 2a 2a 20 64 6f 20 61 6e 79 74 68 69 6e 67 2e  .** do anything.
c720: 20 20 43 61 6c 6c 65 72 73 20 73 68 6f 75 6c 64    Callers should
c730: 20 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20   initialize the 
c740: 63 68 61 72 2a 20 76 61 72 69 61 62 6c 65 20 74  char* variable t
c750: 6f 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e  o a NULL.** poin
c760: 74 65 72 20 69 6e 20 63 61 73 65 20 74 68 69 73  ter in case this
c770: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73   file-control is
c780: 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64   not implemented
c790: 2e 20 20 54 68 69 73 20 66 69 6c 65 2d 63 6f 6e  .  This file-con
c7a0: 74 72 6f 6c 0a 2a 2a 20 69 73 20 69 6e 74 65 6e  trol.** is inten
c7b0: 64 65 64 20 66 6f 72 20 64 69 61 67 6e 6f 73 74  ded for diagnost
c7c0: 69 63 20 75 73 65 20 6f 6e 6c 79 2e 0a 2a 2a 0a  ic use only..**.
c7d0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
c7e0: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 5d 0a 2a  FCNTL_PRAGMA]].*
c7f0: 2a 20 5e 57 68 65 6e 65 76 65 72 20 61 20 5b 50  * ^Whenever a [P
c800: 52 41 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e 74  RAGMA] statement
c810: 20 69 73 20 70 61 72 73 65 64 2c 20 61 6e 20 5b   is parsed, an [
c820: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
c830: 47 4d 41 5d 20 0a 2a 2a 20 66 69 6c 65 20 63 6f  GMA] .** file co
c840: 6e 74 72 6f 6c 20 69 73 20 73 65 6e 74 20 74 6f  ntrol is sent to
c850: 20 74 68 65 20 6f 70 65 6e 20 5b 73 71 6c 69 74   the open [sqlit
c860: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20  e3_file] object 
c870: 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a  corresponding.**
c880: 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65   to the database
c890: 20 66 69 6c 65 20 74 6f 20 77 68 69 63 68 20 74   file to which t
c8a0: 68 65 20 70 72 61 67 6d 61 20 73 74 61 74 65 6d  he pragma statem
c8b0: 65 6e 74 20 72 65 66 65 72 73 2e 20 5e 54 68 65  ent refers. ^The
c8c0: 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20   argument.** to 
c8d0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  the [SQLITE_FCNT
c8e0: 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63  L_PRAGMA] file c
c8f0: 6f 6e 74 72 6f 6c 20 69 73 20 61 6e 20 61 72 72  ontrol is an arr
c900: 61 79 20 6f 66 0a 2a 2a 20 70 6f 69 6e 74 65 72  ay of.** pointer
c910: 73 20 74 6f 20 73 74 72 69 6e 67 73 20 28 63 68  s to strings (ch
c920: 61 72 2a 2a 29 20 69 6e 20 77 68 69 63 68 20 74  ar**) in which t
c930: 68 65 20 73 65 63 6f 6e 64 20 65 6c 65 6d 65 6e  he second elemen
c940: 74 20 6f 66 20 74 68 65 20 61 72 72 61 79 0a 2a  t of the array.*
c950: 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  * is the name of
c960: 20 74 68 65 20 70 72 61 67 6d 61 20 61 6e 64 20   the pragma and 
c970: 74 68 65 20 74 68 69 72 64 20 65 6c 65 6d 65 6e  the third elemen
c980: 74 20 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e  t is the argumen
c990: 74 20 74 6f 20 74 68 65 0a 2a 2a 20 70 72 61 67  t to the.** prag
c9a0: 6d 61 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68  ma or NULL if th
c9b0: 65 20 70 72 61 67 6d 61 20 68 61 73 20 6e 6f 20  e pragma has no 
c9c0: 61 72 67 75 6d 65 6e 74 2e 20 20 5e 54 68 65 20  argument.  ^The 
c9d0: 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 6e 0a 2a  handler for an.*
c9e0: 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  * [SQLITE_FCNTL_
c9f0: 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e  PRAGMA] file con
ca00: 74 72 6f 6c 20 63 61 6e 20 6f 70 74 69 6f 6e 61  trol can optiona
ca10: 6c 6c 79 20 6d 61 6b 65 20 74 68 65 20 66 69 72  lly make the fir
ca20: 73 74 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 6f 66  st element.** of
ca30: 20 74 68 65 20 63 68 61 72 2a 2a 20 61 72 67 75   the char** argu
ca40: 6d 65 6e 74 20 70 6f 69 6e 74 20 74 6f 20 61 20  ment point to a 
ca50: 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 20  string obtained 
ca60: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 70  from [sqlite3_mp
ca70: 72 69 6e 74 66 28 29 5d 0a 2a 2a 20 6f 72 20 74  rintf()].** or t
ca80: 68 65 20 65 71 75 69 76 61 6c 65 6e 74 20 61 6e  he equivalent an
ca90: 64 20 74 68 61 74 20 73 74 72 69 6e 67 20 77 69  d that string wi
caa0: 6c 6c 20 62 65 63 6f 6d 65 20 74 68 65 20 72 65  ll become the re
cab0: 73 75 6c 74 20 6f 66 20 74 68 65 20 70 72 61 67  sult of the prag
cac0: 6d 61 20 6f 72 0a 2a 2a 20 74 68 65 20 65 72 72  ma or.** the err
cad0: 6f 72 20 6d 65 73 73 61 67 65 20 69 66 20 74 68  or message if th
cae0: 65 20 70 72 61 67 6d 61 20 66 61 69 6c 73 2e 20  e pragma fails. 
caf0: 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ^If the.** [SQLI
cb00: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
cb10: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65   file control re
cb20: 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4e 4f  turns [SQLITE_NO
cb30: 54 46 4f 55 4e 44 5d 2c 20 74 68 65 6e 20 6e 6f  TFOUND], then no
cb40: 72 6d 61 6c 20 0a 2a 2a 20 5b 50 52 41 47 4d 41  rmal .** [PRAGMA
cb50: 5d 20 70 72 6f 63 65 73 73 69 6e 67 20 63 6f 6e  ] processing con
cb60: 74 69 6e 75 65 73 2e 20 20 5e 49 66 20 74 68 65  tinues.  ^If the
cb70: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
cb80: 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63  RAGMA].** file c
cb90: 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b  ontrol returns [
cba0: 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 65 6e  SQLITE_OK], then
cbb0: 20 74 68 65 20 70 61 72 73 65 72 20 61 73 73 75   the parser assu
cbc0: 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  mes that the.** 
cbd0: 56 46 53 20 68 61 73 20 68 61 6e 64 6c 65 64 20  VFS has handled 
cbe0: 74 68 65 20 50 52 41 47 4d 41 20 69 74 73 65 6c  the PRAGMA itsel
cbf0: 66 20 61 6e 64 20 74 68 65 20 70 61 72 73 65 72  f and the parser
cc00: 20 67 65 6e 65 72 61 74 65 73 20 61 20 6e 6f 2d   generates a no-
cc10: 6f 70 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73  op.** prepared s
cc20: 74 61 74 65 6d 65 6e 74 20 69 66 20 72 65 73 75  tatement if resu
cc30: 6c 74 20 73 74 72 69 6e 67 20 69 73 20 4e 55 4c  lt string is NUL
cc40: 4c 2c 20 6f 72 20 74 68 61 74 20 72 65 74 75 72  L, or that retur
cc50: 6e 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20  ns a copy.** of 
cc60: 74 68 65 20 72 65 73 75 6c 74 20 73 74 72 69 6e  the result strin
cc70: 67 20 69 66 20 74 68 65 20 73 74 72 69 6e 67 20  g if the string 
cc80: 69 73 20 6e 6f 6e 2d 4e 55 4c 4c 2e 0a 2a 2a 20  is non-NULL..** 
cc90: 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ^If the [SQLITE_
cca0: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69  FCNTL_PRAGMA] fi
ccb0: 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72  le control retur
ccc0: 6e 73 0a 2a 2a 20 61 6e 79 20 72 65 73 75 6c 74  ns.** any result
ccd0: 20 63 6f 64 65 20 6f 74 68 65 72 20 74 68 61 6e   code other than
cce0: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20   [SQLITE_OK] or 
ccf0: 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44  [SQLITE_NOTFOUND
cd00: 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a  ], that means.**
cd10: 20 74 68 61 74 20 74 68 65 20 56 46 53 20 65 6e   that the VFS en
cd20: 63 6f 75 6e 74 65 72 65 64 20 61 6e 20 65 72 72  countered an err
cd30: 6f 72 20 77 68 69 6c 65 20 68 61 6e 64 6c 69 6e  or while handlin
cd40: 67 20 74 68 65 20 5b 50 52 41 47 4d 41 5d 20 61  g the [PRAGMA] a
cd50: 6e 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c  nd the.** compil
cd60: 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 50 52 41  ation of the PRA
cd70: 47 4d 41 20 66 61 69 6c 73 20 77 69 74 68 20 61  GMA fails with a
cd80: 6e 20 65 72 72 6f 72 2e 20 20 5e 54 68 65 20 5b  n error.  ^The [
cd90: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
cda0: 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e  GMA].** file con
cdb0: 74 72 6f 6c 20 6f 63 63 75 72 73 20 61 74 20 74  trol occurs at t
cdc0: 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20  he beginning of 
cdd0: 70 72 61 67 6d 61 20 73 74 61 74 65 6d 65 6e 74  pragma statement
cde0: 20 61 6e 61 6c 79 73 69 73 20 61 6e 64 20 73 6f   analysis and so
cdf0: 0a 2a 2a 20 69 74 20 69 73 20 61 62 6c 65 20 74  .** it is able t
ce00: 6f 20 6f 76 65 72 72 69 64 65 20 62 75 69 6c 74  o override built
ce10: 2d 69 6e 20 5b 50 52 41 47 4d 41 5d 20 73 74 61  -in [PRAGMA] sta
ce20: 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 3c  tements..**.** <
ce30: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
ce40: 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d 5d 0a  L_BUSYHANDLER]].
ce50: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
ce60: 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45  FCNTL_BUSYHANDLE
ce70: 52 5d 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72  R].** file-contr
ce80: 6f 6c 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65  ol may be invoke
ce90: 64 20 62 79 20 53 51 4c 69 74 65 20 6f 6e 20 74  d by SQLite on t
cea0: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
ceb0: 20 68 61 6e 64 6c 65 0a 2a 2a 20 73 68 6f 72 74   handle.** short
cec0: 6c 79 20 61 66 74 65 72 20 69 74 20 69 73 20 6f  ly after it is o
ced0: 70 65 6e 65 64 20 69 6e 20 6f 72 64 65 72 20 74  pened in order t
cee0: 6f 20 70 72 6f 76 69 64 65 20 61 20 63 75 73 74  o provide a cust
cef0: 6f 6d 20 56 46 53 20 77 69 74 68 20 61 63 63 65  om VFS with acce
cf00: 73 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6e  ss.** to the con
cf10: 6e 65 63 74 69 6f 6e 73 20 62 75 73 79 2d 68 61  nections busy-ha
cf20: 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20  ndler callback. 
cf30: 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  The argument is 
cf40: 6f 66 20 74 79 70 65 20 28 76 6f 69 64 20 2a 2a  of type (void **
cf50: 29 0a 2a 2a 20 2d 20 61 6e 20 61 72 72 61 79 20  ).** - an array 
cf60: 6f 66 20 74 77 6f 20 28 76 6f 69 64 20 2a 29 20  of two (void *) 
cf70: 76 61 6c 75 65 73 2e 20 54 68 65 20 66 69 72 73  values. The firs
cf80: 74 20 28 76 6f 69 64 20 2a 29 20 61 63 74 75 61  t (void *) actua
cf90: 6c 6c 79 20 70 6f 69 6e 74 73 0a 2a 2a 20 74 6f  lly points.** to
cfa0: 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74   a function of t
cfb0: 79 70 65 20 28 69 6e 74 20 28 2a 29 28 76 6f 69  ype (int (*)(voi
cfc0: 64 20 2a 29 29 2e 20 49 6e 20 6f 72 64 65 72 20  d *)). In order 
cfd0: 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 20 63 6f  to invoke the co
cfe0: 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 62 75 73  nnections.** bus
cff0: 79 2d 68 61 6e 64 6c 65 72 2c 20 74 68 69 73 20  y-handler, this 
d000: 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20  function should 
d010: 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20  be invoked with 
d020: 74 68 65 20 73 65 63 6f 6e 64 20 28 76 6f 69 64  the second (void
d030: 20 2a 29 20 69 6e 0a 2a 2a 20 74 68 65 20 61 72   *) in.** the ar
d040: 72 61 79 20 61 73 20 74 68 65 20 6f 6e 6c 79 20  ray as the only 
d050: 61 72 67 75 6d 65 6e 74 2e 20 49 66 20 69 74 20  argument. If it 
d060: 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f  returns non-zero
d070: 2c 20 74 68 65 6e 20 74 68 65 20 6f 70 65 72 61  , then the opera
d080: 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62  tion.** should b
d090: 65 20 72 65 74 72 69 65 64 2e 20 49 66 20 69 74  e retried. If it
d0a0: 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74   returns zero, t
d0b0: 68 65 20 63 75 73 74 6f 6d 20 56 46 53 20 73 68  he custom VFS sh
d0c0: 6f 75 6c 64 20 61 62 61 6e 64 6f 6e 20 74 68 65  ould abandon the
d0d0: 0a 2a 2a 20 63 75 72 72 65 6e 74 20 6f 70 65 72  .** current oper
d0e0: 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  ation..**.** <li
d0f0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
d100: 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 5d 0a 2a  TEMPFILENAME]].*
d110: 2a 20 5e 41 70 70 6c 69 63 61 74 69 6f 6e 20 63  * ^Application c
d120: 61 6e 20 69 6e 76 6f 6b 65 20 74 68 65 20 5b 53  an invoke the [S
d130: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50  QLITE_FCNTL_TEMP
d140: 46 49 4c 45 4e 41 4d 45 5d 20 66 69 6c 65 2d 63  FILENAME] file-c
d150: 6f 6e 74 72 6f 6c 0a 2a 2a 20 74 6f 20 68 61 76  ontrol.** to hav
d160: 65 20 53 51 4c 69 74 65 20 67 65 6e 65 72 61 74  e SQLite generat
d170: 65 20 61 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79  e a.** temporary
d180: 20 66 69 6c 65 6e 61 6d 65 20 75 73 69 6e 67 20   filename using 
d190: 74 68 65 20 73 61 6d 65 20 61 6c 67 6f 72 69 74  the same algorit
d1a0: 68 6d 20 74 68 61 74 20 69 73 20 66 6f 6c 6c 6f  hm that is follo
d1b0: 77 65 64 20 74 6f 20 67 65 6e 65 72 61 74 65 0a  wed to generate.
d1c0: 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c  ** temporary fil
d1d0: 65 6e 61 6d 65 73 20 66 6f 72 20 54 45 4d 50 20  enames for TEMP 
d1e0: 74 61 62 6c 65 73 20 61 6e 64 20 6f 74 68 65 72  tables and other
d1f0: 20 69 6e 74 65 72 6e 61 6c 20 75 73 65 73 2e 20   internal uses. 
d200: 20 54 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74   The.** argument
d210: 20 73 68 6f 75 6c 64 20 62 65 20 61 20 63 68 61   should be a cha
d220: 72 2a 2a 20 77 68 69 63 68 20 77 69 6c 6c 20 62  r** which will b
d230: 65 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68  e filled with th
d240: 65 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 77 72  e filename.** wr
d250: 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72  itten into memor
d260: 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
d270: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
d280: 29 5d 2e 20 20 54 68 65 20 63 61 6c 6c 65 72 20  )].  The caller 
d290: 73 68 6f 75 6c 64 0a 2a 2a 20 69 6e 76 6f 6b 65  should.** invoke
d2a0: 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
d2b0: 5d 20 6f 6e 20 74 68 65 20 72 65 73 75 6c 74 20  ] on the result 
d2c0: 74 6f 20 61 76 6f 69 64 20 61 20 6d 65 6d 6f 72  to avoid a memor
d2d0: 79 20 6c 65 61 6b 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  y leak..**.** <l
d2e0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
d2f0: 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20  _MMAP_SIZE]].** 
d300: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
d310: 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c  L_MMAP_SIZE] fil
d320: 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65  e control is use
d330: 64 20 74 6f 20 71 75 65 72 79 20 6f 72 20 73 65  d to query or se
d340: 74 20 74 68 65 0a 2a 2a 20 6d 61 78 69 6d 75 6d  t the.** maximum
d350: 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
d360: 20 74 68 61 74 20 77 69 6c 6c 20 62 65 20 75 73   that will be us
d370: 65 64 20 66 6f 72 20 6d 65 6d 6f 72 79 2d 6d 61  ed for memory-ma
d380: 70 70 65 64 20 49 2f 4f 2e 0a 2a 2a 20 54 68 65  pped I/O..** The
d390: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70   argument is a p
d3a0: 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c 75  ointer to a valu
d3b0: 65 20 6f 66 20 74 79 70 65 20 73 71 6c 69 74 65  e of type sqlite
d3c0: 33 5f 69 6e 74 36 34 20 74 68 61 74 0a 2a 2a 20  3_int64 that.** 
d3d0: 69 73 20 61 6e 20 61 64 76 69 73 6f 72 79 20 6d  is an advisory m
d3e0: 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
d3f0: 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 66 69   bytes in the fi
d400: 6c 65 20 74 6f 20 6d 65 6d 6f 72 79 20 6d 61 70  le to memory map
d410: 2e 20 20 54 68 65 0a 2a 2a 20 70 6f 69 6e 74 65  .  The.** pointe
d420: 72 20 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e  r is overwritten
d430: 20 77 69 74 68 20 74 68 65 20 6f 6c 64 20 76 61   with the old va
d440: 6c 75 65 2e 20 20 54 68 65 20 6c 69 6d 69 74 20  lue.  The limit 
d450: 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 20 69  is not changed i
d460: 66 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f  f.** the value o
d470: 72 69 67 69 6e 61 6c 6c 79 20 70 6f 69 6e 74 65  riginally pointe
d480: 64 20 74 6f 20 69 73 20 6e 65 67 61 74 69 76 65  d to is negative
d490: 2c 20 61 6e 64 20 73 6f 20 74 68 65 20 63 75 72  , and so the cur
d4a0: 72 65 6e 74 20 6c 69 6d 69 74 20 0a 2a 2a 20 63  rent limit .** c
d4b0: 61 6e 20 62 65 20 71 75 65 72 69 65 64 20 62 79  an be queried by
d4c0: 20 70 61 73 73 69 6e 67 20 69 6e 20 61 20 70 6f   passing in a po
d4d0: 69 6e 74 65 72 20 74 6f 20 61 20 6e 65 67 61 74  inter to a negat
d4e0: 69 76 65 20 6e 75 6d 62 65 72 2e 20 20 54 68 69  ive number.  Thi
d4f0: 73 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f  s.** file-contro
d500: 6c 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e  l is used intern
d510: 61 6c 6c 79 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  ally to implemen
d520: 74 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73  t [PRAGMA mmap_s
d530: 69 7a 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  ize]..**.** <li>
d540: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54  [[SQLITE_FCNTL_T
d550: 52 41 43 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  RACE]].** The [S
d560: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43  QLITE_FCNTL_TRAC
d570: 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  E] file control 
d580: 70 72 6f 76 69 64 65 73 20 61 64 76 69 73 6f 72  provides advisor
d590: 79 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a  y information.**
d5a0: 20 74 6f 20 74 68 65 20 56 46 53 20 61 62 6f 75   to the VFS abou
d5b0: 74 20 77 68 61 74 20 74 68 65 20 68 69 67 68 65  t what the highe
d5c0: 72 20 6c 61 79 65 72 73 20 6f 66 20 74 68 65 20  r layers of the 
d5d0: 53 51 4c 69 74 65 20 73 74 61 63 6b 20 61 72 65  SQLite stack are
d5e0: 20 64 6f 69 6e 67 2e 0a 2a 2a 20 54 68 69 73 20   doing..** This 
d5f0: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20  file control is 
d600: 75 73 65 64 20 62 79 20 73 6f 6d 65 20 56 46 53  used by some VFS
d610: 20 61 63 74 69 76 69 74 79 20 74 72 61 63 69 6e   activity tracin
d620: 67 20 5b 73 68 69 6d 73 5d 2e 0a 2a 2a 20 54 68  g [shims]..** Th
d630: 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  e argument is a 
d640: 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
d650: 73 74 72 69 6e 67 2e 20 20 48 69 67 68 65 72 20  string.  Higher 
d660: 6c 61 79 65 72 73 20 69 6e 20 74 68 65 0a 2a 2a  layers in the.**
d670: 20 53 51 4c 69 74 65 20 73 74 61 63 6b 20 6d 61   SQLite stack ma
d680: 79 20 67 65 6e 65 72 61 74 65 20 69 6e 73 74 61  y generate insta
d690: 6e 63 65 73 20 6f 66 20 74 68 69 73 20 66 69 6c  nces of this fil
d6a0: 65 20 63 6f 6e 74 72 6f 6c 20 69 66 0a 2a 2a 20  e control if.** 
d6b0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f  the [SQLITE_USE_
d6c0: 46 43 4e 54 4c 5f 54 52 41 43 45 5d 20 63 6f 6d  FCNTL_TRACE] com
d6d0: 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
d6e0: 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a   is enabled..**.
d6f0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
d700: 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d  FCNTL_HAS_MOVED]
d710: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
d720: 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44  _FCNTL_HAS_MOVED
d730: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69  ] file control i
d740: 6e 74 65 72 70 72 65 74 73 20 69 74 73 20 61 72  nterprets its ar
d750: 67 75 6d 65 6e 74 20 61 73 20 61 0a 2a 2a 20 70  gument as a.** p
d760: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
d770: 65 67 65 72 20 61 6e 64 20 69 74 20 77 72 69 74  eger and it writ
d780: 65 73 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e 74  es a boolean int
d790: 6f 20 74 68 61 74 20 69 6e 74 65 67 65 72 20 64  o that integer d
d7a0: 65 70 65 6e 64 69 6e 67 0a 2a 2a 20 6f 6e 20 77  epending.** on w
d7b0: 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
d7c0: 65 20 66 69 6c 65 20 68 61 73 20 62 65 65 6e 20  e file has been 
d7d0: 72 65 6e 61 6d 65 64 2c 20 6d 6f 76 65 64 2c 20  renamed, moved, 
d7e0: 6f 72 20 64 65 6c 65 74 65 64 20 73 69 6e 63 65  or deleted since
d7f0: 20 69 74 0a 2a 2a 20 77 61 73 20 66 69 72 73 74   it.** was first
d800: 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c   opened..**.** <
d810: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
d820: 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44  L_WIN32_SET_HAND
d830: 4c 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  LE]].** The [SQL
d840: 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f  ITE_FCNTL_WIN32_
d850: 53 45 54 5f 48 41 4e 44 4c 45 5d 20 6f 70 63 6f  SET_HANDLE] opco
d860: 64 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64  de is used for d
d870: 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a  ebugging.  This.
d880: 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73  ** opcode causes
d890: 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f   the xFileContro
d8a0: 6c 20 6d 65 74 68 6f 64 20 74 6f 20 73 77 61 70  l method to swap
d8b0: 20 74 68 65 20 66 69 6c 65 20 68 61 6e 64 6c 65   the file handle
d8c0: 20 77 69 74 68 20 74 68 65 20 6f 6e 65 0a 2a 2a   with the one.**
d8d0: 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74   pointed to by t
d8e0: 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74  he pArg argument
d8f0: 2e 20 20 54 68 69 73 20 63 61 70 61 62 69 6c 69  .  This capabili
d900: 74 79 20 69 73 20 75 73 65 64 20 64 75 72 69 6e  ty is used durin
d910: 67 20 74 65 73 74 69 6e 67 0a 2a 2a 20 61 6e 64  g testing.** and
d920: 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 62   only needs to b
d930: 65 20 73 75 70 70 6f 72 74 65 64 20 77 68 65 6e  e supported when
d940: 20 53 51 4c 49 54 45 5f 54 45 53 54 20 69 73 20   SQLITE_TEST is 
d950: 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c  defined..**.** <
d960: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
d970: 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 5d 0a 2a 2a  L_WAL_BLOCK]].**
d980: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
d990: 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 20 69 73  TL_WAL_BLOCK] is
d9a0: 20 61 20 73 69 67 6e 61 6c 20 74 6f 20 74 68 65   a signal to the
d9b0: 20 56 46 53 20 6c 61 79 65 72 20 74 68 61 74 20   VFS layer that 
d9c0: 69 74 20 6d 69 67 68 74 0a 2a 2a 20 62 65 20 61  it might.** be a
d9d0: 64 76 61 6e 74 61 67 65 6f 75 73 20 74 6f 20 62  dvantageous to b
d9e0: 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 6e 65 78 74  lock on the next
d9f0: 20 57 41 4c 20 6c 6f 63 6b 20 69 66 20 74 68 65   WAL lock if the
da00: 20 6c 6f 63 6b 20 69 73 20 6e 6f 74 20 69 6d 6d   lock is not imm
da10: 65 64 69 61 74 65 6c 79 0a 2a 2a 20 61 76 61 69  ediately.** avai
da20: 6c 61 62 6c 65 2e 20 20 54 68 65 20 57 41 4c 20  lable.  The WAL 
da30: 73 75 62 73 79 73 74 65 6d 20 69 73 73 75 65 73  subsystem issues
da40: 20 74 68 69 73 20 73 69 67 6e 61 6c 20 64 75 72   this signal dur
da50: 69 6e 67 20 72 61 72 65 0a 2a 2a 20 63 69 72 63  ing rare.** circ
da60: 75 6d 73 74 61 6e 63 65 73 20 69 6e 20 6f 72 64  umstances in ord
da70: 65 72 20 74 6f 20 66 69 78 20 61 20 70 72 6f 62  er to fix a prob
da80: 6c 65 6d 20 77 69 74 68 20 70 72 69 6f 72 69 74  lem with priorit
da90: 79 20 69 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20  y inversion..** 
daa0: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f  Applications sho
dab0: 75 6c 64 20 3c 65 6d 3e 6e 6f 74 3c 2f 65 6d 3e  uld <em>not</em>
dac0: 20 75 73 65 20 74 68 69 73 20 66 69 6c 65 2d 63   use this file-c
dad0: 6f 6e 74 72 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  ontrol..**.** <l
dae0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
daf0: 5f 5a 49 50 56 46 53 5d 5d 0a 2a 2a 20 54 68 65  _ZIPVFS]].** The
db00: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a   [SQLITE_FCNTL_Z
db10: 49 50 56 46 53 5d 20 6f 70 63 6f 64 65 20 69 73  IPVFS] opcode is
db20: 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79 20   implemented by 
db30: 7a 69 70 76 66 73 20 6f 6e 6c 79 2e 20 41 6c 6c  zipvfs only. All
db40: 20 6f 74 68 65 72 0a 2a 2a 20 56 46 53 20 73 68   other.** VFS sh
db50: 6f 75 6c 64 20 72 65 74 75 72 6e 20 53 51 4c 49  ould return SQLI
db60: 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 66 6f 72 20  TE_NOTFOUND for 
db70: 74 68 69 73 20 6f 70 63 6f 64 65 2e 0a 2a 2a 0a  this opcode..**.
db80: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
db90: 46 43 4e 54 4c 5f 52 42 55 5d 5d 0a 2a 2a 20 54  FCNTL_RBU]].** T
dba0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
dbb0: 5f 52 42 55 5d 20 6f 70 63 6f 64 65 20 69 73 20  _RBU] opcode is 
dbc0: 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79 20 74  implemented by t
dbd0: 68 65 20 73 70 65 63 69 61 6c 20 56 46 53 20 75  he special VFS u
dbe0: 73 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 52 42  sed by.** the RB
dbf0: 55 20 65 78 74 65 6e 73 69 6f 6e 20 6f 6e 6c 79  U extension only
dc00: 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 56 46 53  .  All other VFS
dc10: 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 53   should return S
dc20: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 66  QLITE_NOTFOUND f
dc30: 6f 72 0a 2a 2a 20 74 68 69 73 20 6f 70 63 6f 64  or.** this opcod
dc40: 65 2e 20 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f  e.  .** </ul>.*/
dc50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
dc60: 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20  FCNTL_LOCKSTATE 
dc70: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 0a                1.
dc80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
dc90: 43 4e 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f  CNTL_GET_LOCKPRO
dca0: 58 59 46 49 4c 45 20 20 20 20 20 20 20 32 0a 23  XYFILE       2.#
dcb0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
dcc0: 4e 54 4c 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58  NTL_SET_LOCKPROX
dcd0: 59 46 49 4c 45 20 20 20 20 20 20 20 33 0a 23 64  YFILE       3.#d
dce0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
dcf0: 54 4c 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20  TL_LAST_ERRNO   
dd00: 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65             4.#de
dd10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
dd20: 4c 5f 53 49 5a 45 5f 48 49 4e 54 20 20 20 20 20  L_SIZE_HINT     
dd30: 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66            5.#def
dd40: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
dd50: 5f 43 48 55 4e 4b 5f 53 49 5a 45 20 20 20 20 20  _CHUNK_SIZE     
dd60: 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69           6.#defi
dd70: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
dd80: 46 49 4c 45 5f 50 4f 49 4e 54 45 52 20 20 20 20  FILE_POINTER    
dd90: 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e          7.#defin
dda0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53  e SQLITE_FCNTL_S
ddb0: 59 4e 43 5f 4f 4d 49 54 54 45 44 20 20 20 20 20  YNC_OMITTED     
ddc0: 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65         8.#define
ddd0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49   SQLITE_FCNTL_WI
dde0: 4e 33 32 5f 41 56 5f 52 45 54 52 59 20 20 20 20  N32_AV_RETRY    
ddf0: 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20        9.#define 
de00: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52  SQLITE_FCNTL_PER
de10: 53 49 53 54 5f 57 41 4c 20 20 20 20 20 20 20 20  SIST_WAL        
de20: 20 20 20 20 31 30 0a 23 64 65 66 69 6e 65 20 53      10.#define S
de30: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52  QLITE_FCNTL_OVER
de40: 57 52 49 54 45 20 20 20 20 20 20 20 20 20 20 20  WRITE           
de50: 20 20 20 31 31 0a 23 64 65 66 69 6e 65 20 53 51     11.#define SQ
de60: 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41  LITE_FCNTL_VFSNA
de70: 4d 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ME              
de80: 20 20 31 32 0a 23 64 65 66 69 6e 65 20 53 51 4c    12.#define SQL
de90: 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53  ITE_FCNTL_POWERS
dea0: 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20  AFE_OVERWRITE   
deb0: 20 31 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   13.#define SQLI
dec0: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 20  TE_FCNTL_PRAGMA 
ded0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
dee0: 31 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  14.#define SQLIT
def0: 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44  E_FCNTL_BUSYHAND
df00: 4c 45 52 20 20 20 20 20 20 20 20 20 20 20 20 31  LER            1
df10: 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  5.#define SQLITE
df20: 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e  _FCNTL_TEMPFILEN
df30: 41 4d 45 20 20 20 20 20 20 20 20 20 20 20 31 36  AME           16
df40: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
df50: 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 20  FCNTL_MMAP_SIZE 
df60: 20 20 20 20 20 20 20 20 20 20 20 20 20 31 38 0a               18.
df70: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
df80: 43 4e 54 4c 5f 54 52 41 43 45 20 20 20 20 20 20  CNTL_TRACE      
df90: 20 20 20 20 20 20 20 20 20 20 20 20 31 39 0a 23              19.#
dfa0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
dfb0: 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 20 20 20  NTL_HAS_MOVED   
dfc0: 20 20 20 20 20 20 20 20 20 20 20 32 30 0a 23 64             20.#d
dfd0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
dfe0: 54 4c 5f 53 59 4e 43 20 20 20 20 20 20 20 20 20  TL_SYNC         
dff0: 20 20 20 20 20 20 20 20 20 20 32 31 0a 23 64 65            21.#de
e000: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
e010: 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57  L_COMMIT_PHASETW
e020: 4f 20 20 20 20 20 20 20 20 32 32 0a 23 64 65 66  O        22.#def
e030: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
e040: 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c  _WIN32_SET_HANDL
e050: 45 20 20 20 20 20 20 20 32 33 0a 23 64 65 66 69  E       23.#defi
e060: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
e070: 57 41 4c 5f 42 4c 4f 43 4b 20 20 20 20 20 20 20  WAL_BLOCK       
e080: 20 20 20 20 20 20 20 32 34 0a 23 64 65 66 69 6e         24.#defin
e090: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a  e SQLITE_FCNTL_Z
e0a0: 49 50 56 46 53 20 20 20 20 20 20 20 20 20 20 20  IPVFS           
e0b0: 20 20 20 20 20 20 32 35 0a 23 64 65 66 69 6e 65        25.#define
e0c0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 42   SQLITE_FCNTL_RB
e0d0: 55 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  U               
e0e0: 20 20 20 20 20 32 36 0a 0a 2f 2a 20 64 65 70 72       26../* depr
e0f0: 65 63 61 74 65 64 20 6e 61 6d 65 73 20 2a 2f 0a  ecated names */.
e100: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 47  #define SQLITE_G
e110: 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45  ET_LOCKPROXYFILE
e120: 20 20 20 20 20 20 53 51 4c 49 54 45 5f 46 43 4e        SQLITE_FCN
e130: 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59  TL_GET_LOCKPROXY
e140: 46 49 4c 45 0a 23 64 65 66 69 6e 65 20 53 51 4c  FILE.#define SQL
e150: 49 54 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58  ITE_SET_LOCKPROX
e160: 59 46 49 4c 45 20 20 20 20 20 20 53 51 4c 49 54  YFILE      SQLIT
e170: 45 5f 46 43 4e 54 4c 5f 53 45 54 5f 4c 4f 43 4b  E_FCNTL_SET_LOCK
e180: 50 52 4f 58 59 46 49 4c 45 0a 23 64 65 66 69 6e  PROXYFILE.#defin
e190: 65 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f 45 52  e SQLITE_LAST_ER
e1a0: 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20 20  RNO             
e1b0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 41 53  SQLITE_FCNTL_LAS
e1c0: 54 5f 45 52 52 4e 4f 0a 0a 0a 2f 2a 0a 2a 2a 20  T_ERRNO.../*.** 
e1d0: 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20  CAPI3REF: Mutex 
e1e0: 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65  Handle.**.** The
e1f0: 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 69   mutex module wi
e200: 74 68 69 6e 20 53 51 4c 69 74 65 20 64 65 66 69  thin SQLite defi
e210: 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  nes [sqlite3_mut
e220: 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20  ex] to be an.** 
e230: 61 62 73 74 72 61 63 74 20 74 79 70 65 20 66 6f  abstract type fo
e240: 72 20 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 74  r a mutex object
e250: 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f  .  The SQLite co
e260: 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a  re never looks.*
e270: 2a 20 61 74 20 74 68 65 20 69 6e 74 65 72 6e 61  * at the interna
e280: 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e  l representation
e290: 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   of an [sqlite3_
e2a0: 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79  mutex].  It only
e2b0: 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74 68 20 70  .** deals with p
e2c0: 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20 5b  ointers to the [
e2d0: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f  sqlite3_mutex] o
e2e0: 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74  bject..**.** Mut
e2f0: 65 78 65 73 20 61 72 65 20 63 72 65 61 74 65 64  exes are created
e300: 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
e310: 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a  mutex_alloc()]..
e320: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
e330: 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20  t sqlite3_mutex 
e340: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a  sqlite3_mutex;..
e350: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
e360: 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 62 6a  OS Interface Obj
e370: 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  ect.**.** An ins
e380: 74 61 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c  tance of the sql
e390: 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20  ite3_vfs object 
e3a0: 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65  defines the inte
e3b0: 72 66 61 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a  rface between.**
e3c0: 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   the SQLite core
e3d0: 20 61 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79   and the underly
e3e0: 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79  ing operating sy
e3f0: 73 74 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22  stem.  The "vfs"
e400: 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20  .** in the name 
e410: 6f 66 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74  of the object st
e420: 61 6e 64 73 20 66 6f 72 20 22 76 69 72 74 75 61  ands for "virtua
e430: 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 20  l file system". 
e440: 20 53 65 65 0a 2a 2a 20 74 68 65 20 5b 56 46 53   See.** the [VFS
e450: 20 7c 20 56 46 53 20 64 6f 63 75 6d 65 6e 74 61   | VFS documenta
e460: 74 69 6f 6e 5d 20 66 6f 72 20 66 75 72 74 68 65  tion] for furthe
e470: 72 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  r information..*
e480: 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 6f  *.** The value o
e490: 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66  f the iVersion f
e4a0: 69 65 6c 64 20 69 73 20 69 6e 69 74 69 61 6c 6c  ield is initiall
e4b0: 79 20 31 20 62 75 74 20 6d 61 79 20 62 65 20 6c  y 1 but may be l
e4c0: 61 72 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74 75  arger in.** futu
e4d0: 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
e4e0: 51 4c 69 74 65 2e 20 20 41 64 64 69 74 69 6f 6e  QLite.  Addition
e4f0: 61 6c 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65  al fields may be
e500: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 74 68 69   appended to thi
e510: 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e  s.** object when
e520: 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 76 61   the iVersion va
e530: 6c 75 65 20 69 73 20 69 6e 63 72 65 61 73 65 64  lue is increased
e540: 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65  .  Note that the
e550: 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66   structure.** of
e560: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73   the sqlite3_vfs
e570: 20 6f 62 6a 65 63 74 20 63 68 61 6e 67 65 73 20   object changes 
e580: 69 6e 20 74 68 65 20 74 72 61 6e 73 61 63 74 69  in the transacti
e590: 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53 51  on between.** SQ
e5a0: 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35  Lite version 3.5
e5b0: 2e 39 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e 64  .9 and 3.6.0 and
e5c0: 20 79 65 74 20 74 68 65 20 69 56 65 72 73 69 6f   yet the iVersio
e5d0: 6e 20 66 69 65 6c 64 20 77 61 73 20 6e 6f 74 0a  n field was not.
e5e0: 2a 2a 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a  ** modified..**.
e5f0: 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65 20  ** The szOsFile 
e600: 66 69 65 6c 64 20 69 73 20 74 68 65 20 73 69 7a  field is the siz
e610: 65 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61 73  e of the subclas
e620: 73 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  sed [sqlite3_fil
e630: 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20  e].** structure 
e640: 75 73 65 64 20 62 79 20 74 68 69 73 20 56 46 53  used by this VFS
e650: 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69 73  .  mxPathname is
e660: 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e   the maximum len
e670: 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68  gth of.** a path
e680: 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46 53  name in this VFS
e690: 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72  ..**.** Register
e6a0: 65 64 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f  ed sqlite3_vfs o
e6b0: 62 6a 65 63 74 73 20 61 72 65 20 6b 65 70 74 20  bjects are kept 
e6c0: 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74  on a linked list
e6d0: 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68   formed by.** th
e6e0: 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e  e pNext pointer.
e6f0: 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76    The [sqlite3_v
e700: 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a 2a  fs_register()].*
e710: 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76  * and [sqlite3_v
e720: 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29 5d  fs_unregister()]
e730: 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e 61   interfaces mana
e740: 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20  ge this list.** 
e750: 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66 65  in a thread-safe
e760: 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c 69   way.  The [sqli
e770: 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20  te3_vfs_find()] 
e780: 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 61  interface.** sea
e790: 72 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e 20  rches the list. 
e7a0: 20 4e 65 69 74 68 65 72 20 74 68 65 20 61 70 70   Neither the app
e7b0: 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f  lication code no
e7c0: 72 20 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70  r the VFS.** imp
e7d0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75  lementation shou
e7e0: 6c 64 20 75 73 65 20 74 68 65 20 70 4e 65 78 74  ld use the pNext
e7f0: 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
e800: 54 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64 20  The pNext field 
e810: 69 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c  is the only fiel
e820: 64 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33  d in the sqlite3
e830: 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63 74 75 72  _vfs.** structur
e840: 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69  e that SQLite wi
e850: 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e 20  ll ever modify. 
e860: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c   SQLite will onl
e870: 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d  y access.** or m
e880: 6f 64 69 66 79 20 74 68 69 73 20 66 69 65 6c 64  odify this field
e890: 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61   while holding a
e8a0: 20 70 61 72 74 69 63 75 6c 61 72 20 73 74 61 74   particular stat
e8b0: 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65  ic mutex..** The
e8c0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f   application sho
e8d0: 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 79  uld never modify
e8e0: 20 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69 6e   anything within
e8f0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73   the sqlite3_vfs
e900: 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20  .** object once 
e910: 74 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20 62  the object has b
e920: 65 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e 0a  een registered..
e930: 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20  **.** The zName 
e940: 66 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 20  field holds the 
e950: 6e 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53 20  name of the VFS 
e960: 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d  module.  The nam
e970: 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69  e must.** be uni
e980: 71 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 56  que across all V
e990: 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a  FS modules..**.*
e9a0: 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  * [[sqlite3_vfs.
e9b0: 78 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c 69  xOpen]].** ^SQLi
e9c0: 74 65 20 67 75 61 72 61 6e 74 65 65 73 20 74 68  te guarantees th
e9d0: 61 74 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65  at the zFilename
e9e0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f   parameter to xO
e9f0: 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65 72  pen.** is either
ea00: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
ea10: 6f 72 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e  or string obtain
ea20: 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c 6c  ed.** from xFull
ea30: 50 61 74 68 6e 61 6d 65 28 29 20 77 69 74 68 20  Pathname() with 
ea40: 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 73 75 66 66  an optional suff
ea50: 69 78 20 61 64 64 65 64 2e 0a 2a 2a 20 5e 49 66  ix added..** ^If
ea60: 20 61 20 73 75 66 66 69 78 20 69 73 20 61 64 64   a suffix is add
ea70: 65 64 20 74 6f 20 74 68 65 20 7a 46 69 6c 65 6e  ed to the zFilen
ea80: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 2c 20 69  ame parameter, i
ea90: 74 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69 73  t will.** consis
eaa0: 74 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 22 2d  t of a single "-
eab0: 22 20 63 68 61 72 61 63 74 65 72 20 66 6f 6c 6c  " character foll
eac0: 6f 77 65 64 20 62 79 20 6e 6f 20 6d 6f 72 65 20  owed by no more 
ead0: 74 68 61 6e 0a 2a 2a 20 31 31 20 61 6c 70 68 61  than.** 11 alpha
eae0: 6e 75 6d 65 72 69 63 20 61 6e 64 2f 6f 72 20 22  numeric and/or "
eaf0: 2d 22 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a  -" characters..*
eb00: 2a 20 5e 53 51 4c 69 74 65 20 66 75 72 74 68 65  * ^SQLite furthe
eb10: 72 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61  r guarantees tha
eb20: 74 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20  t.** the string 
eb30: 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 6e  will be valid an
eb40: 64 20 75 6e 63 68 61 6e 67 65 64 20 75 6e 74 69  d unchanged unti
eb50: 6c 20 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a  l xClose() is.**
eb60: 20 63 61 6c 6c 65 64 2e 20 42 65 63 61 75 73 65   called. Because
eb70: 20 6f 66 20 74 68 65 20 70 72 65 76 69 6f 75 73   of the previous
eb80: 20 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74 68   sentence,.** th
eb90: 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  e [sqlite3_file]
eba0: 20 63 61 6e 20 73 61 66 65 6c 79 20 73 74 6f 72   can safely stor
ebb0: 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  e a pointer to t
ebc0: 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69  he.** filename i
ebd0: 66 20 69 74 20 6e 65 65 64 73 20 74 6f 20 72 65  f it needs to re
ebe0: 6d 65 6d 62 65 72 20 74 68 65 20 66 69 6c 65 6e  member the filen
ebf0: 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72 65 61  ame for some rea
ec00: 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 20 7a  son..** If the z
ec10: 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74  Filename paramet
ec20: 65 72 20 74 6f 20 78 4f 70 65 6e 20 69 73 20 61  er to xOpen is a
ec30: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68   NULL pointer th
ec40: 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74  en xOpen.** must
ec50: 20 69 6e 76 65 6e 74 20 69 74 73 20 6f 77 6e 20   invent its own 
ec60: 74 65 6d 70 6f 72 61 72 79 20 6e 61 6d 65 20 66  temporary name f
ec70: 6f 72 20 74 68 65 20 66 69 6c 65 2e 20 20 5e 57  or the file.  ^W
ec80: 68 65 6e 65 76 65 72 20 74 68 65 20 0a 2a 2a 20  henever the .** 
ec90: 78 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65  xFilename parame
eca0: 74 65 72 20 69 73 20 4e 55 4c 4c 20 69 74 20 77  ter is NULL it w
ecb0: 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74 68 65 20  ill also be the 
ecc0: 63 61 73 65 20 74 68 61 74 20 74 68 65 0a 2a 2a  case that the.**
ecd0: 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72   flags parameter
ece0: 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65 20 5b 53   will include [S
ecf0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
ed00: 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a  EONCLOSE]..**.**
ed10: 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d   The flags argum
ed20: 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29 20 69  ent to xOpen() i
ed30: 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62 69 74 73  ncludes all bits
ed40: 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66   set in.** the f
ed50: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f  lags argument to
ed60: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
ed70: 32 28 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71  2()].  Or if [sq
ed80: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a  lite3_open()].**
ed90: 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   or [sqlite3_ope
eda0: 6e 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20  n16()] is used, 
edb0: 74 68 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75  then flags inclu
edc0: 64 65 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20  des at least.** 
edd0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
ede0: 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54  DWRITE] | [SQLIT
edf0: 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20  E_OPEN_CREATE]. 
ee00: 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29 20 6f  .** If xOpen() o
ee10: 70 65 6e 73 20 61 20 66 69 6c 65 20 72 65 61 64  pens a file read
ee20: 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20 73 65  -only then it se
ee30: 74 73 20 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f  ts *pOutFlags to
ee40: 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c  .** include [SQL
ee50: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
ee60: 59 5d 2e 20 20 4f 74 68 65 72 20 62 69 74 73 20  Y].  Other bits 
ee70: 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61  in *pOutFlags ma
ee80: 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20  y be set..**.** 
ee90: 5e 28 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c  ^(SQLite will al
eea0: 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68  so add one of th
eeb0: 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67  e following flag
eec0: 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29  s to the xOpen()
eed0: 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64  .** call, depend
eee0: 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63  ing on the objec
eef0: 74 20 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a  t being opened:.
ef00: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
ef10: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
ef20: 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69  _MAIN_DB].** <li
ef30: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
ef40: 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a  MAIN_JOURNAL].**
ef50: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
ef60: 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20  PEN_TEMP_DB].** 
ef70: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
ef80: 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d  EN_TEMP_JOURNAL]
ef90: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
efa0: 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54  E_OPEN_TRANSIENT
efb0: 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  _DB].** <li>  [S
efc0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f  QLITE_OPEN_SUBJO
efd0: 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  URNAL].** <li>  
efe0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53  [SQLITE_OPEN_MAS
eff0: 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20  TER_JOURNAL].** 
f000: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
f010: 45 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e  EN_WAL].** </ul>
f020: 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c  )^.**.** The fil
f030: 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61  e I/O implementa
f040: 74 69 6f 6e 20 63 61 6e 20 75 73 65 20 74 68 65  tion can use the
f050: 20 6f 62 6a 65 63 74 20 74 79 70 65 20 66 6c 61   object type fla
f060: 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 20  gs to.** change 
f070: 74 68 65 20 77 61 79 20 69 74 20 64 65 61 6c 73  the way it deals
f080: 20 77 69 74 68 20 66 69 6c 65 73 2e 20 20 46 6f   with files.  Fo
f090: 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70  r example, an ap
f0a0: 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61  plication.** tha
f0b0: 74 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20  t does not care 
f0c0: 61 62 6f 75 74 20 63 72 61 73 68 20 72 65 63 6f  about crash reco
f0d0: 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b  very or rollback
f0e0: 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74   might make.** t
f0f0: 68 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75  he open of a jou
f100: 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f  rnal file a no-o
f110: 70 2e 20 20 57 72 69 74 65 73 20 74 6f 20 74 68  p.  Writes to th
f120: 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64  is journal would
f130: 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f  .** also be no-o
f140: 70 73 2c 20 61 6e 64 20 61 6e 79 20 61 74 74 65  ps, and any atte
f150: 6d 70 74 20 74 6f 20 72 65 61 64 20 74 68 65 20  mpt to read the 
f160: 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65  journal would re
f170: 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 49  turn.** SQLITE_I
f180: 4f 45 52 52 2e 20 20 4f 72 20 74 68 65 20 69 6d  OERR.  Or the im
f190: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67  plementation mig
f1a0: 68 74 20 72 65 63 6f 67 6e 69 7a 65 20 74 68 61  ht recognize tha
f1b0: 74 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  t a database.** 
f1c0: 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f 69  file will be doi
f1d0: 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e 65 64 20  ng page-aligned 
f1e0: 73 65 63 74 6f 72 20 72 65 61 64 73 20 61 6e 64  sector reads and
f1f0: 20 77 72 69 74 65 73 20 69 6e 20 61 20 72 61 6e   writes in a ran
f200: 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e 64  dom.** order and
f210: 20 73 65 74 20 75 70 20 69 74 73 20 49 2f 4f 20   set up its I/O 
f220: 73 75 62 73 79 73 74 65 6d 20 61 63 63 6f 72 64  subsystem accord
f230: 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  ingly..**.** SQL
f240: 69 74 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 61  ite might also a
f250: 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f  dd one of the fo
f260: 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f  llowing flags to
f270: 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f   the xOpen metho
f280: 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  d:.**.** <ul>.**
f290: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50   <li> [SQLITE_OP
f2a0: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
f2b0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
f2c0: 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45  E_OPEN_EXCLUSIVE
f2d0: 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  ].** </ul>.**.**
f2e0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   The [SQLITE_OPE
f2f0: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d  N_DELETEONCLOSE]
f300: 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20   flag means the 
f310: 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a  file should be.*
f320: 2a 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 69  * deleted when i
f330: 74 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 5e 54  t is closed.  ^T
f340: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
f350: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a  DELETEONCLOSE].*
f360: 2a 20 77 69 6c 6c 20 62 65 20 73 65 74 20 66 6f  * will be set fo
f370: 72 20 54 45 4d 50 20 64 61 74 61 62 61 73 65 73  r TEMP databases
f380: 20 61 6e 64 20 74 68 65 69 72 20 6a 6f 75 72 6e   and their journ
f390: 61 6c 73 2c 20 74 72 61 6e 73 69 65 6e 74 0a 2a  als, transient.*
f3a0: 2a 20 64 61 74 61 62 61 73 65 73 2c 20 61 6e 64  * databases, and
f3b0: 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a   subjournals..**
f3c0: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
f3d0: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d  _OPEN_EXCLUSIVE]
f3e0: 20 66 6c 61 67 20 69 73 20 61 6c 77 61 79 73 20   flag is always 
f3f0: 75 73 65 64 20 69 6e 20 63 6f 6e 6a 75 6e 63 74  used in conjunct
f400: 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ion.** with the 
f410: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45  [SQLITE_OPEN_CRE
f420: 41 54 45 5d 20 66 6c 61 67 2c 20 77 68 69 63 68  ATE] flag, which
f430: 20 61 72 65 20 62 6f 74 68 20 64 69 72 65 63 74   are both direct
f440: 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73 20  ly.** analogous 
f450: 74 6f 20 74 68 65 20 4f 5f 45 58 43 4c 20 61 6e  to the O_EXCL an
f460: 64 20 4f 5f 43 52 45 41 54 20 66 6c 61 67 73 20  d O_CREAT flags 
f470: 6f 66 20 74 68 65 20 50 4f 53 49 58 20 6f 70 65  of the POSIX ope
f480: 6e 28 29 0a 2a 2a 20 41 50 49 2e 20 20 54 68 65  n().** API.  The
f490: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43   SQLITE_OPEN_EXC
f4a0: 4c 55 53 49 56 45 20 66 6c 61 67 2c 20 77 68 65  LUSIVE flag, whe
f4b0: 6e 20 70 61 69 72 65 64 20 77 69 74 68 20 74 68  n paired with th
f4c0: 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 50 45  e .** SQLITE_OPE
f4d0: 4e 5f 43 52 45 41 54 45 2c 20 69 73 20 75 73 65  N_CREATE, is use
f4e0: 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68  d to indicate th
f4f0: 61 74 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 61  at file should a
f500: 6c 77 61 79 73 0a 2a 2a 20 62 65 20 63 72 65 61  lways.** be crea
f510: 74 65 64 2c 20 61 6e 64 20 74 68 61 74 20 69 74  ted, and that it
f520: 20 69 73 20 61 6e 20 65 72 72 6f 72 20 69 66 20   is an error if 
f530: 69 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74  it already exist
f540: 73 2e 0a 2a 2a 20 49 74 20 69 73 20 3c 69 3e 6e  s..** It is <i>n
f550: 6f 74 3c 2f 69 3e 20 75 73 65 64 20 74 6f 20 69  ot</i> used to i
f560: 6e 64 69 63 61 74 65 20 74 68 65 20 66 69 6c 65  ndicate the file
f570: 20 73 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65   should be opene
f580: 64 20 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73  d .** for exclus
f590: 69 76 65 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a  ive access..**.*
f5a0: 2a 20 5e 41 74 20 6c 65 61 73 74 20 73 7a 4f 73  * ^At least szOs
f5b0: 46 69 6c 65 20 62 79 74 65 73 20 6f 66 20 6d 65  File bytes of me
f5c0: 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f 63 61 74  mory are allocat
f5d0: 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20  ed by SQLite.** 
f5e0: 74 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b 73 71  to hold the  [sq
f5f0: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73 74 72 75  lite3_file] stru
f600: 63 74 75 72 65 20 70 61 73 73 65 64 20 61 73 20  cture passed as 
f610: 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 67  the third.** arg
f620: 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20  ument to xOpen. 
f630: 20 54 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f   The xOpen metho
f640: 64 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20  d does not have 
f650: 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74  to.** allocate t
f660: 68 65 20 73 74 72 75 63 74 75 72 65 3b 20 69 74  he structure; it
f670: 20 73 68 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c   should just fil
f680: 6c 20 69 74 20 69 6e 2e 20 20 4e 6f 74 65 20 74  l it in.  Note t
f690: 68 61 74 0a 2a 2a 20 74 68 65 20 78 4f 70 65 6e  hat.** the xOpen
f6a0: 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 73 65 74   method must set
f6b0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c   the sqlite3_fil
f6c0: 65 2e 70 4d 65 74 68 6f 64 73 20 74 6f 20 65 69  e.pMethods to ei
f6d0: 74 68 65 72 0a 2a 2a 20 61 20 76 61 6c 69 64 20  ther.** a valid 
f6e0: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
f6f0: 6f 64 73 5d 20 6f 62 6a 65 63 74 20 6f 72 20 74  ods] object or t
f700: 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d  o NULL.  xOpen m
f710: 75 73 74 20 64 6f 0a 2a 2a 20 74 68 69 73 20 65  ust do.** this e
f720: 76 65 6e 20 69 66 20 74 68 65 20 6f 70 65 6e 20  ven if the open 
f730: 66 61 69 6c 73 2e 20 20 53 51 4c 69 74 65 20 65  fails.  SQLite e
f740: 78 70 65 63 74 73 20 74 68 61 74 20 74 68 65 20  xpects that the 
f750: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65  sqlite3_file.pMe
f760: 74 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74  thods.** element
f770: 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61   will be valid a
f780: 66 74 65 72 20 78 4f 70 65 6e 20 72 65 74 75 72  fter xOpen retur
f790: 6e 73 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66  ns regardless of
f7a0: 20 74 68 65 20 73 75 63 63 65 73 73 0a 2a 2a 20   the success.** 
f7b0: 6f 72 20 66 61 69 6c 75 72 65 20 6f 66 20 74 68  or failure of th
f7c0: 65 20 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a  e xOpen call..**
f7d0: 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66  .** [[sqlite3_vf
f7e0: 73 2e 78 41 63 63 65 73 73 5d 5d 0a 2a 2a 20 5e  s.xAccess]].** ^
f7f0: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  The flags argume
f800: 6e 74 20 74 6f 20 78 41 63 63 65 73 73 28 29 20  nt to xAccess() 
f810: 6d 61 79 20 62 65 20 5b 53 51 4c 49 54 45 5f 41  may be [SQLITE_A
f820: 43 43 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a  CCESS_EXISTS].**
f830: 20 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68 65   to test for the
f840: 20 65 78 69 73 74 65 6e 63 65 20 6f 66 20 61 20   existence of a 
f850: 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45  file, or [SQLITE
f860: 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
f870: 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68  E] to.** test wh
f880: 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20  ether a file is 
f890: 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69  readable and wri
f8a0: 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54  table, or [SQLIT
f8b0: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a  E_ACCESS_READ].*
f8c0: 2a 20 74 6f 20 74 65 73 74 20 77 68 65 74 68 65  * to test whethe
f8d0: 72 20 61 20 66 69 6c 65 20 69 73 20 61 74 20 6c  r a file is at l
f8e0: 65 61 73 74 20 72 65 61 64 61 62 6c 65 2e 20 20  east readable.  
f8f0: 20 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62 65   The file can be
f900: 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e   a.** directory.
f910: 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77  .**.** ^SQLite w
f920: 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63  ill always alloc
f930: 61 74 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50  ate at least mxP
f940: 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 20  athname+1 bytes 
f950: 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75  for the.** outpu
f960: 74 20 62 75 66 66 65 72 20 78 46 75 6c 6c 50 61  t buffer xFullPa
f970: 74 68 6e 61 6d 65 2e 20 20 54 68 65 20 65 78 61  thname.  The exa
f980: 63 74 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6f  ct size of the o
f990: 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20  utput buffer.** 
f9a0: 69 73 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61  is also passed a
f9b0: 73 20 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f  s a parameter to
f9c0: 20 62 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e 20   both  methods. 
f9d0: 49 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75  If the output bu
f9e0: 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c  ffer.** is not l
f9f0: 61 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51  arge enough, [SQ
fa00: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73  LITE_CANTOPEN] s
fa10: 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65  hould be returne
fa20: 64 2e 20 53 69 6e 63 65 20 74 68 69 73 20 69 73  d. Since this is
fa30: 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 61  .** handled as a
fa40: 20 66 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20   fatal error by 
fa50: 53 51 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 6c  SQLite, vfs impl
fa60: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75  ementations shou
fa70: 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74  ld endeavor.** t
fa80: 6f 20 70 72 65 76 65 6e 74 20 74 68 69 73 20 62  o prevent this b
fa90: 79 20 73 65 74 74 69 6e 67 20 6d 78 50 61 74 68  y setting mxPath
faa0: 6e 61 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63  name to a suffic
fab0: 69 65 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c  iently large val
fac0: 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52  ue..**.** The xR
fad0: 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c  andomness(), xSl
fae0: 65 65 70 28 29 2c 20 78 43 75 72 72 65 6e 74 54  eep(), xCurrentT
faf0: 69 6d 65 28 29 2c 20 61 6e 64 20 78 43 75 72 72  ime(), and xCurr
fb00: 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 0a 2a  entTimeInt64().*
fb10: 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  * interfaces are
fb20: 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 61 20   not strictly a 
fb30: 70 61 72 74 20 6f 66 20 74 68 65 20 66 69 6c 65  part of the file
fb40: 73 79 73 74 65 6d 2c 20 62 75 74 20 74 68 65 79  system, but they
fb50: 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64   are.** included
fb60: 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 72 75   in the VFS stru
fb70: 63 74 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65  cture for comple
fb80: 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78  teness..** The x
fb90: 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e  Randomness() fun
fba0: 63 74 69 6f 6e 20 61 74 74 65 6d 70 74 73 20 74  ction attempts t
fbb0: 6f 20 72 65 74 75 72 6e 20 6e 42 79 74 65 73 20  o return nBytes 
fbc0: 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64  bytes.** of good
fbd0: 2d 71 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e  -quality randomn
fbe0: 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20  ess into zOut.  
fbf0: 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  The return value
fc00: 20 69 73 0a 2a 2a 20 74 68 65 20 61 63 74 75 61   is.** the actua
fc10: 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  l number of byte
fc20: 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20  s of randomness 
fc30: 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65  obtained..** The
fc40: 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64   xSleep() method
fc50: 20 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c   causes the call
fc60: 69 6e 67 20 74 68 72 65 61 64 20 74 6f 20 73 6c  ing thread to sl
fc70: 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65  eep for at.** le
fc80: 61 73 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ast the number o
fc90: 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20 67  f microseconds g
fca0: 69 76 65 6e 2e 20 20 5e 54 68 65 20 78 43 75 72  iven.  ^The xCur
fcb0: 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65  rentTime().** me
fcc0: 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 4a  thod returns a J
fcd0: 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62 65 72  ulian Day Number
fce0: 20 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74   for the current
fcf0: 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 61   date and time a
fd00: 73 0a 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67 20  s.** a floating 
fd10: 70 6f 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 20  point value..** 
fd20: 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d  ^The xCurrentTim
fd30: 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20  eInt64() method 
fd40: 72 65 74 75 72 6e 73 2c 20 61 73 20 61 6e 20 69  returns, as an i
fd50: 6e 74 65 67 65 72 2c 20 74 68 65 20 4a 75 6c 69  nteger, the Juli
fd60: 61 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65 72  an.** Day Number
fd70: 20 6d 75 6c 74 69 70 6c 69 65 64 20 62 79 20 38   multiplied by 8
fd80: 36 34 30 30 30 30 30 20 28 74 68 65 20 6e 75 6d  6400000 (the num
fd90: 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f  ber of milliseco
fda0: 6e 64 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d  nds in .** a 24-
fdb0: 68 6f 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20  hour day).  .** 
fdc0: 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65  ^SQLite will use
fdd0: 20 74 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d   the xCurrentTim
fde0: 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20  eInt64() method 
fdf0: 74 6f 20 67 65 74 20 74 68 65 20 63 75 72 72 65  to get the curre
fe00: 6e 74 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20 74  nt.** date and t
fe10: 69 6d 65 20 69 66 20 74 68 61 74 20 6d 65 74 68  ime if that meth
fe20: 6f 64 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20  od is available 
fe30: 28 69 66 20 69 56 65 72 73 69 6f 6e 20 69 73 20  (if iVersion is 
fe40: 32 20 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65 72  2 or .** greater
fe50: 20 61 6e 64 20 74 68 65 20 66 75 6e 63 74 69 6f   and the functio
fe60: 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74  n pointer is not
fe70: 20 4e 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20   NULL) and will 
fe80: 66 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20  fall back.** to 
fe90: 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 20 69  xCurrentTime() i
fea0: 66 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e  f xCurrentTimeIn
feb0: 74 36 34 28 29 20 69 73 20 75 6e 61 76 61 69 6c  t64() is unavail
fec0: 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  able..**.** ^The
fed0: 20 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 28   xSetSystemCall(
fee0: 29 2c 20 78 47 65 74 53 79 73 74 65 6d 43 61 6c  ), xGetSystemCal
fef0: 6c 28 29 2c 20 61 6e 64 20 78 4e 65 73 74 53 79  l(), and xNestSy
ff00: 73 74 65 6d 43 61 6c 6c 28 29 20 69 6e 74 65 72  stemCall() inter
ff10: 66 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74  faces.** are not
ff20: 20 75 73 65 64 20 62 79 20 74 68 65 20 53 51 4c   used by the SQL
ff30: 69 74 65 20 63 6f 72 65 2e 20 20 54 68 65 73 65  ite core.  These
ff40: 20 6f 70 74 69 6f 6e 61 6c 20 69 6e 74 65 72 66   optional interf
ff50: 61 63 65 73 20 61 72 65 20 70 72 6f 76 69 64 65  aces are provide
ff60: 64 0a 2a 2a 20 62 79 20 73 6f 6d 65 20 56 46 53  d.** by some VFS
ff70: 65 73 20 74 6f 20 66 61 63 69 6c 69 74 61 74 65  es to facilitate
ff80: 20 74 65 73 74 69 6e 67 20 6f 66 20 74 68 65 20   testing of the 
ff90: 56 46 53 20 63 6f 64 65 2e 20 42 79 20 6f 76 65  VFS code. By ove
ffa0: 72 72 69 64 69 6e 67 20 0a 2a 2a 20 73 79 73 74  rriding .** syst
ffb0: 65 6d 20 63 61 6c 6c 73 20 77 69 74 68 20 66 75  em calls with fu
ffc0: 6e 63 74 69 6f 6e 73 20 75 6e 64 65 72 20 69 74  nctions under it
ffd0: 73 20 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 65 73  s control, a tes
ffe0: 74 20 70 72 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a  t program can.**
fff0: 20 73 69 6d 75 6c 61 74 65 20 66 61 75 6c 74 73   simulate faults
10000 20 61 6e 64 20 65 72 72 6f 72 20 63 6f 6e 64 69   and error condi
10010 74 69 6f 6e 73 20 74 68 61 74 20 77 6f 75 6c 64  tions that would
10020 20 6f 74 68 65 72 77 69 73 65 20 62 65 20 64 69   otherwise be di
10030 66 66 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d  fficult.** or im
10040 70 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e 64 75  possible to indu
10050 63 65 2e 20 20 54 68 65 20 73 65 74 20 6f 66 20  ce.  The set of 
10060 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 74 68 61  system calls tha
10070 74 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64  t can be overrid
10080 64 65 6e 0a 2a 2a 20 76 61 72 69 65 73 20 66 72  den.** varies fr
10090 6f 6d 20 6f 6e 65 20 56 46 53 20 74 6f 20 61 6e  om one VFS to an
100a0 6f 74 68 65 72 2c 20 61 6e 64 20 66 72 6f 6d 20  other, and from 
100b0 6f 6e 65 20 76 65 72 73 69 6f 6e 20 6f 66 20 74  one version of t
100c0 68 65 20 73 61 6d 65 20 56 46 53 20 74 6f 20 74  he same VFS to t
100d0 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70  he.** next.  App
100e0 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 75  lications that u
100f0 73 65 20 74 68 65 73 65 20 69 6e 74 65 72 66 61  se these interfa
10100 63 65 73 20 6d 75 73 74 20 62 65 20 70 72 65 70  ces must be prep
10110 61 72 65 64 20 66 6f 72 20 61 6e 79 0a 2a 2a 20  ared for any.** 
10120 6f 72 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20  or all of these 
10130 69 6e 74 65 72 66 61 63 65 73 20 74 6f 20 62 65  interfaces to be
10140 20 4e 55 4c 4c 20 6f 72 20 66 6f 72 20 74 68 65   NULL or for the
10150 69 72 20 62 65 68 61 76 69 6f 72 20 74 6f 20 63  ir behavior to c
10160 68 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e  hange.** from on
10170 65 20 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65  e release to the
10180 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74   next.  Applicat
10190 69 6f 6e 73 20 6d 75 73 74 20 6e 6f 74 20 61 74  ions must not at
101a0 74 65 6d 70 74 20 74 6f 20 61 63 63 65 73 73 0a  tempt to access.
101b0 2a 2a 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20  ** any of these 
101c0 6d 65 74 68 6f 64 73 20 69 66 20 74 68 65 20 69  methods if the i
101d0 56 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 56  Version of the V
101e0 46 53 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20  FS is less than 
101f0 33 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  3..*/.typedef st
10200 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73  ruct sqlite3_vfs
10210 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a 74 79   sqlite3_vfs;.ty
10220 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c  pedef void (*sql
10230 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72  ite3_syscall_ptr
10240 29 28 76 6f 69 64 29 3b 0a 73 74 72 75 63 74 20  )(void);.struct 
10250 73 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20  sqlite3_vfs {.  
10260 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20  int iVersion;   
10270 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75           /* Stru
10280 63 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75  cture version nu
10290 6d 62 65 72 20 28 63 75 72 72 65 6e 74 6c 79 20  mber (currently 
102a0 33 29 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73  3) */.  int szOs
102b0 46 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20  File;           
102c0 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63   /* Size of subc
102d0 6c 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66  lassed sqlite3_f
102e0 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50  ile */.  int mxP
102f0 61 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20  athname;        
10300 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c    /* Maximum fil
10310 65 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74  e pathname lengt
10320 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76  h */.  sqlite3_v
10330 66 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20  fs *pNext;      
10340 2f 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65 72  /* Next register
10350 65 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73  ed VFS */.  cons
10360 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20  t char *zName;  
10370 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20       /* Name of 
10380 74 68 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c  this virtual fil
10390 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f  e system */.  vo
103a0 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20  id *pAppData;   
103b0 20 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65         /* Pointe
103c0 72 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e  r to application
103d0 2d 73 70 65 63 69 66 69 63 20 64 61 74 61 20 2a  -specific data *
103e0 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29  /.  int (*xOpen)
103f0 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
10400 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
10410 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  , sqlite3_file*,
10420 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
10430 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a  int flags, int *
10440 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e  pOutFlags);.  in
10450 74 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c  t (*xDelete)(sql
10460 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
10470 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e   char *zName, in
10480 74 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e  t syncDir);.  in
10490 74 20 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c  t (*xAccess)(sql
104a0 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
104b0 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e   char *zName, in
104c0 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52  t flags, int *pR
104d0 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a  esOut);.  int (*
104e0 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73  xFullPathname)(s
104f0 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
10500 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
10510 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a  int nOut, char *
10520 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28  zOut);.  void *(
10530 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65  *xDlOpen)(sqlite
10540 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
10550 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a  ar *zFilename);.
10560 20 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f    void (*xDlErro
10570 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  r)(sqlite3_vfs*,
10580 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72   int nByte, char
10590 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f   *zErrMsg);.  vo
105a0 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73  id (*(*xDlSym)(s
105b0 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64  qlite3_vfs*,void
105c0 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
105d0 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a  Symbol))(void);.
105e0 20 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73    void (*xDlClos
105f0 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  e)(sqlite3_vfs*,
10600 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28   void*);.  int (
10610 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71  *xRandomness)(sq
10620 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20  lite3_vfs*, int 
10630 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75  nByte, char *zOu
10640 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65  t);.  int (*xSle
10650 65 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ep)(sqlite3_vfs*
10660 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e  , int microsecon
10670 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75  ds);.  int (*xCu
10680 72 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74  rrentTime)(sqlit
10690 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a  e3_vfs*, double*
106a0 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c  );.  int (*xGetL
106b0 61 73 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65  astError)(sqlite
106c0 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61  3_vfs*, int, cha
106d0 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20  r *);.  /*.  ** 
106e0 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76  The methods abov
106f0 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e  e are in version
10700 20 31 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65   1 of the sqlite
10710 5f 76 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a  _vfs object.  **
10720 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68   definition.  Th
10730 6f 73 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20  ose that follow 
10740 61 72 65 20 61 64 64 65 64 20 69 6e 20 76 65 72  are added in ver
10750 73 69 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a  sion 2 or later.
10760 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75    */.  int (*xCu
10770 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 29 28  rrentTimeInt64)(
10780 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73 71  sqlite3_vfs*, sq
10790 6c 69 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20  lite3_int64*);. 
107a0 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74   /*.  ** The met
107b0 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69  hods above are i
107c0 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 61 6e 64  n versions 1 and
107d0 20 32 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65   2 of the sqlite
107e0 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a  _vfs object..  *
107f0 2a 20 54 68 6f 73 65 20 62 65 6c 6f 77 20 61 72  * Those below ar
10800 65 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20  e for version 3 
10810 61 6e 64 20 67 72 65 61 74 65 72 2e 0a 20 20 2a  and greater..  *
10820 2f 0a 20 20 69 6e 74 20 28 2a 78 53 65 74 53 79  /.  int (*xSetSy
10830 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65  stemCall)(sqlite
10840 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
10850 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74  ar *zName, sqlit
10860 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 3b  e3_syscall_ptr);
10870 0a 20 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61  .  sqlite3_sysca
10880 6c 6c 5f 70 74 72 20 28 2a 78 47 65 74 53 79 73  ll_ptr (*xGetSys
10890 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33  temCall)(sqlite3
108a0 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
108b0 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e  r *zName);.  con
108c0 73 74 20 63 68 61 72 20 2a 28 2a 78 4e 65 78 74  st char *(*xNext
108d0 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69  SystemCall)(sqli
108e0 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
108f0 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20  char *zName);.  
10900 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68  /*.  ** The meth
10910 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e  ods above are in
10920 20 76 65 72 73 69 6f 6e 73 20 31 20 74 68 72 6f   versions 1 thro
10930 75 67 68 20 33 20 6f 66 20 74 68 65 20 73 71 6c  ugh 3 of the sql
10940 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a  ite_vfs object..
10950 20 20 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73 20    ** New fields 
10960 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20  may be appended 
10970 69 6e 20 66 69 67 75 72 65 20 76 65 72 73 69 6f  in figure versio
10980 6e 73 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f  ns.  The iVersio
10990 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c  n.  ** value wil
109a0 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e  l increment when
109b0 65 76 65 72 20 74 68 69 73 20 68 61 70 70 65 6e  ever this happen
109c0 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a  s. .  */.};../*.
109d0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61  ** CAPI3REF: Fla
109e0 67 73 20 66 6f 72 20 74 68 65 20 78 41 63 63 65  gs for the xAcce
109f0 73 73 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a  ss VFS method.**
10a00 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65  .** These intege
10a10 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20  r constants can 
10a20 62 65 20 75 73 65 64 20 61 73 20 74 68 65 20 74  be used as the t
10a30 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
10a40 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73  o.** the xAccess
10a50 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73   method of an [s
10a60 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
10a70 63 74 2e 20 20 54 68 65 79 20 64 65 74 65 72 6d  ct.  They determ
10a80 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64  ine.** what kind
10a90 20 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 20   of permissions 
10aa0 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
10ab0 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f  od is looking fo
10ac0 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54  r..** With SQLIT
10ad0 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c  E_ACCESS_EXISTS,
10ae0 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
10af0 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68  hod.** simply ch
10b00 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65  ecks whether the
10b10 20 66 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a   file exists..**
10b20 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43   With SQLITE_ACC
10b30 45 53 53 5f 52 45 41 44 57 52 49 54 45 2c 20 74  ESS_READWRITE, t
10b40 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
10b50 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74  d.** checks whet
10b60 68 65 72 20 74 68 65 20 6e 61 6d 65 64 20 64 69  her the named di
10b70 72 65 63 74 6f 72 79 20 69 73 20 62 6f 74 68 20  rectory is both 
10b80 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69  readable and wri
10b90 74 61 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68  table.** (in oth
10ba0 65 72 20 77 6f 72 64 73 2c 20 69 66 20 66 69 6c  er words, if fil
10bb0 65 73 20 63 61 6e 20 62 65 20 61 64 64 65 64 2c  es can be added,
10bc0 20 72 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65   removed, and re
10bd0 6e 61 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20  named within.** 
10be0 74 68 65 20 64 69 72 65 63 74 6f 72 79 29 2e 0a  the directory)..
10bf0 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43  ** The SQLITE_AC
10c00 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 63  CESS_READWRITE c
10c10 6f 6e 73 74 61 6e 74 20 69 73 20 63 75 72 72 65  onstant is curre
10c20 6e 74 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20 62  ntly used only b
10c30 79 20 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73  y the.** [temp_s
10c40 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70  tore_directory p
10c50 72 61 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74  ragma], though t
10c60 68 69 73 20 63 6f 75 6c 64 20 63 68 61 6e 67 65  his could change
10c70 20 69 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20   in a future.** 
10c80 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74  release of SQLit
10c90 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54  e..** With SQLIT
10ca0 45 5f 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74  E_ACCESS_READ, t
10cb0 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
10cc0 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74  d.** checks whet
10cd0 68 65 72 20 74 68 65 20 66 69 6c 65 20 69 73 20  her the file is 
10ce0 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20 53  readable.  The S
10cf0 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
10d00 44 20 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a  D constant is.**
10d10 20 63 75 72 72 65 6e 74 6c 79 20 75 6e 75 73 65   currently unuse
10d20 64 2c 20 74 68 6f 75 67 68 20 69 74 20 6d 69 67  d, though it mig
10d30 68 74 20 62 65 20 75 73 65 64 20 69 6e 20 61 20  ht be used in a 
10d40 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f  future release o
10d50 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  f.** SQLite..*/.
10d60 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
10d70 43 43 45 53 53 5f 45 58 49 53 54 53 20 20 20 20  CCESS_EXISTS    
10d80 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
10d90 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
10da0 45 20 31 20 20 20 2f 2a 20 55 73 65 64 20 62 79  E 1   /* Used by
10db0 20 50 52 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f   PRAGMA temp_sto
10dc0 72 65 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a  re_directory */.
10dd0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
10de0 43 43 45 53 53 5f 52 45 41 44 20 20 20 20 20 20  CCESS_READ      
10df0 32 20 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f  2   /* Unused */
10e00 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
10e10 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20  : Flags for the 
10e20 78 53 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74  xShmLock VFS met
10e30 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  hod.**.** These 
10e40 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74  integer constant
10e50 73 20 64 65 66 69 6e 65 20 74 68 65 20 76 61 72  s define the var
10e60 69 6f 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65  ious locking ope
10e70 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77  rations.** allow
10e80 65 64 20 62 79 20 74 68 65 20 78 53 68 6d 4c 6f  ed by the xShmLo
10e90 63 6b 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71  ck method of [sq
10ea0 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
10eb0 5d 2e 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f  ].  The.** follo
10ec0 77 69 6e 67 20 61 72 65 20 74 68 65 20 6f 6e 6c  wing are the onl
10ed0 79 20 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74  y legal combinat
10ee0 69 6f 6e 73 20 6f 66 20 66 6c 61 67 73 20 74 6f  ions of flags to
10ef0 20 74 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b   the.** xShmLock
10f00 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c   method:.**.** <
10f10 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  ul>.** <li>  SQL
10f20 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53  ITE_SHM_LOCK | S
10f30 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44  QLITE_SHM_SHARED
10f40 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
10f50 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49  _SHM_LOCK | SQLI
10f60 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45  TE_SHM_EXCLUSIVE
10f70 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
10f80 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51  _SHM_UNLOCK | SQ
10f90 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a  LITE_SHM_SHARED.
10fa0 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f  ** <li>  SQLITE_
10fb0 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c  SHM_UNLOCK | SQL
10fc0 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56  ITE_SHM_EXCLUSIV
10fd0 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  E.** </ul>.**.**
10fe0 20 57 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c   When unlocking,
10ff0 20 74 68 65 20 73 61 6d 65 20 53 48 41 52 45 44   the same SHARED
11000 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 66 6c   or EXCLUSIVE fl
11010 61 67 20 6d 75 73 74 20 62 65 20 73 75 70 70 6c  ag must be suppl
11020 69 65 64 20 61 73 0a 2a 2a 20 77 61 73 20 67 69  ied as.** was gi
11030 76 65 6e 20 6f 6e 20 74 68 65 20 63 6f 72 72 65  ven on the corre
11040 73 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20  sponding lock.  
11050 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c  .**.** The xShmL
11060 6f 63 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20 74  ock method can t
11070 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65  ransition betwee
11080 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53  n unlocked and S
11090 48 41 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77  HARED or.** betw
110a0 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64  een unlocked and
110b0 20 45 58 43 4c 55 53 49 56 45 2e 20 20 49 74 20   EXCLUSIVE.  It 
110c0 63 61 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f  cannot transitio
110d0 6e 20 62 65 74 77 65 65 6e 20 53 48 41 52 45 44  n between SHARED
110e0 0a 2a 2a 20 61 6e 64 20 45 58 43 4c 55 53 49 56  .** and EXCLUSIV
110f0 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  E..*/.#define SQ
11100 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20  LITE_SHM_UNLOCK 
11110 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
11120 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20  SQLITE_SHM_LOCK 
11130 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e          2.#defin
11140 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41  e SQLITE_SHM_SHA
11150 52 45 44 20 20 20 20 20 20 20 34 0a 23 64 65 66  RED       4.#def
11160 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45  ine SQLITE_SHM_E
11170 58 43 4c 55 53 49 56 45 20 20 20 20 38 0a 0a 2f  XCLUSIVE    8../
11180 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
11190 61 78 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20  aximum xShmLock 
111a0 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20  index.**.** The 
111b0 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20  xShmLock method 
111c0 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  on [sqlite3_io_m
111d0 65 74 68 6f 64 73 5d 20 6d 61 79 20 75 73 65 20  ethods] may use 
111e0 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65  values.** betwee
111f0 6e 20 30 20 61 6e 64 20 74 68 69 73 20 75 70 70  n 0 and this upp
11200 65 72 20 62 6f 75 6e 64 20 61 73 20 69 74 73 20  er bound as its 
11210 22 6f 66 66 73 65 74 22 20 61 72 67 75 6d 65 6e  "offset" argumen
11220 74 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65  t..** The SQLite
11230 20 63 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65 72   core will never
11240 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63 71 75   attempt to acqu
11250 69 72 65 20 6f 72 20 72 65 6c 65 61 73 65 20 61  ire or release a
11260 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65  .** lock outside
11270 20 6f 66 20 74 68 69 73 20 72 61 6e 67 65 0a 2a   of this range.*
11280 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
11290 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20  _SHM_NLOCK      
112a0 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49    8.../*.** CAPI
112b0 33 52 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65  3REF: Initialize
112c0 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72   The SQLite Libr
112d0 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ary.**.** ^The s
112e0 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
112f0 65 28 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74  e() routine init
11300 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53  ializes the.** S
11310 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20  QLite library.  
11320 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75  ^The sqlite3_shu
11330 74 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a  tdown() routine.
11340 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61  ** deallocates a
11350 6e 79 20 72 65 73 6f 75 72 63 65 73 20 74 68 61  ny resources tha
11360 74 20 77 65 72 65 20 61 6c 6c 6f 63 61 74 65 64  t were allocated
11370 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   by sqlite3_init
11380 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65  ialize()..** The
11390 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
113a0 64 65 73 69 67 6e 65 64 20 74 6f 20 61 69 64 20  designed to aid 
113b0 69 6e 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69  in process initi
113c0 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a  alization and.**
113d0 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62   shutdown on emb
113e0 65 64 64 65 64 20 73 79 73 74 65 6d 73 2e 20 20  edded systems.  
113f0 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c  Workstation appl
11400 69 63 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a  ications using.*
11410 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c  * SQLite normall
11420 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f  y do not need to
11430 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 6f   invoke either o
11440 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
11450 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74  ..**.** A call t
11460 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  o sqlite3_initia
11470 6c 69 7a 65 28 29 20 69 73 20 61 6e 20 22 65 66  lize() is an "ef
11480 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66  fective" call if
11490 20 69 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 69   it is.** the fi
114a0 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33  rst time sqlite3
114b0 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
114c0 20 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 20   invoked during 
114d0 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a  the lifetime of.
114e0 2a 2a 20 74 68 65 20 70 72 6f 63 65 73 73 2c 20  ** the process, 
114f0 6f 72 20 69 66 20 69 74 20 69 73 20 74 68 65 20  or if it is the 
11500 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74  first time sqlit
11510 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
11520 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f  is invoked.** fo
11530 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74  llowing a call t
11540 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
11550 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e  wn().  ^(Only an
11560 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 0a   effective call.
11570 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e  ** of sqlite3_in
11580 69 74 69 61 6c 69 7a 65 28 29 20 64 6f 65 73 20  itialize() does 
11590 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  any initializati
115a0 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 63  on.  All other c
115b0 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d  alls.** are harm
115c0 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a  less no-ops.)^.*
115d0 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73  *.** A call to s
115e0 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
115f0 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 74 69  ) is an "effecti
11600 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69  ve" call if it i
11610 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 63  s the first.** c
11620 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
11630 68 75 74 64 6f 77 6e 28 29 20 73 69 6e 63 65 20  hutdown() since 
11640 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33  the last sqlite3
11650 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20 20  _initialize().  
11660 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66  ^(Only.** an eff
11670 65 63 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 73  ective call to s
11680 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
11690 29 20 64 6f 65 73 20 61 6e 79 20 64 65 69 6e 69  ) does any deini
116a0 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20  tialization..** 
116b0 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 69 64 20  All other valid 
116c0 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
116d0 5f 73 68 75 74 64 6f 77 6e 28 29 20 61 72 65 20  _shutdown() are 
116e0 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e  harmless no-ops.
116f0 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  )^.**.** The sql
11700 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
11710 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74  ) interface is t
11720 68 72 65 61 64 73 61 66 65 2c 20 62 75 74 20 73  hreadsafe, but s
11730 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
11740 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68  ).** is not.  Th
11750 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  e sqlite3_shutdo
11760 77 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d  wn() interface m
11770 75 73 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c  ust only be call
11780 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e  ed from a.** sin
11790 67 6c 65 20 74 68 72 65 61 64 2e 20 20 41 6c 6c  gle thread.  All
117a0 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20   open [database 
117b0 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73  connections] mus
117c0 74 20 62 65 20 63 6c 6f 73 65 64 20 61 6e 64 20  t be closed and 
117d0 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c  all.** other SQL
117e0 69 74 65 20 72 65 73 6f 75 72 63 65 73 20 6d 75  ite resources mu
117f0 73 74 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65  st be deallocate
11800 64 20 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b  d prior to invok
11810 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  ing.** sqlite3_s
11820 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a  hutdown()..**.**
11830 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69   Among other thi
11840 6e 67 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e  ngs, ^sqlite3_in
11850 69 74 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20  itialize() will 
11860 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65  invoke.** sqlite
11870 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69  3_os_init().  Si
11880 6d 69 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65  milarly, ^sqlite
11890 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20  3_shutdown().** 
118a0 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69  will invoke sqli
118b0 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a  te3_os_end()..**
118c0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
118d0 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f  _initialize() ro
118e0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53  utine returns [S
118f0 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63  QLITE_OK] on suc
11900 63 65 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72  cess..** ^If for
11910 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71   some reason, sq
11920 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
11930 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  () is unable to 
11940 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68  initialize.** th
11950 65 20 6c 69 62 72 61 72 79 20 28 70 65 72 68 61  e library (perha
11960 70 73 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20  ps it is unable 
11970 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65  to allocate a ne
11980 65 64 65 64 20 72 65 73 6f 75 72 63 65 20 73 75  eded resource su
11990 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 78  ch.** as a mutex
119a0 29 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20  ) it returns an 
119b0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68  [error code] oth
119c0 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
119d0 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  OK]..**.** ^The 
119e0 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
119f0 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20  ze() routine is 
11a00 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c  called internall
11a10 79 20 62 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a  y by many other.
11a20 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  ** SQLite interf
11a30 61 63 65 73 20 73 6f 20 74 68 61 74 20 61 6e 20  aces so that an 
11a40 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 75 61  application usua
11a50 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  lly does not nee
11a60 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73  d to.** invoke s
11a70 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
11a80 65 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 46  e() directly.  F
11a90 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c  or example, [sql
11aa0 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20  ite3_open()].** 
11ab0 63 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e  calls sqlite3_in
11ac0 69 74 69 61 6c 69 7a 65 28 29 20 73 6f 20 74 68  itialize() so th
11ad0 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  e SQLite library
11ae0 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74   will be automat
11af0 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61  ically.** initia
11b00 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c 69  lized when [sqli
11b10 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63  te3_open()] is c
11b20 61 6c 6c 65 64 20 69 66 20 69 74 20 68 61 73 20  alled if it has 
11b30 6e 6f 74 20 62 65 20 69 6e 69 74 69 61 6c 69 7a  not be initializ
11b40 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20  ed.** already.  
11b50 5e 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c  ^However, if SQL
11b60 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
11b70 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45  with the [SQLITE
11b80 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a  _OMIT_AUTOINIT].
11b90 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  ** compile-time 
11ba0 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65  option, then the
11bb0 20 61 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73   automatic calls
11bc0 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   to sqlite3_init
11bd0 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20  ialize().** are 
11be0 6f 6d 69 74 74 65 64 20 61 6e 64 20 74 68 65 20  omitted and the 
11bf0 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
11c00 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e   call sqlite3_in
11c10 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63  itialize() direc
11c20 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20  tly.** prior to 
11c30 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20  using any other 
11c40 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
11c50 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70  .  For maximum p
11c60 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69  ortability,.** i
11c70 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  t is recommended
11c80 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f   that applicatio
11c90 6e 73 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65  ns always invoke
11ca0 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
11cb0 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c  ize().** directl
11cc0 79 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67  y prior to using
11cd0 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74   any other SQLit
11ce0 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 75  e interface.  Fu
11cf0 74 75 72 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a  ture releases.**
11d00 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 72   of SQLite may r
11d10 65 71 75 69 72 65 20 74 68 69 73 2e 20 20 49 6e  equire this.  In
11d20 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
11d30 65 20 62 65 68 61 76 69 6f 72 20 65 78 68 69 62  e behavior exhib
11d40 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c  ited.** when SQL
11d50 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
11d60 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49  with [SQLITE_OMI
11d70 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68  T_AUTOINIT] migh
11d80 74 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20  t become the.** 
11d90 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72  default behavior
11da0 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20   in some future 
11db0 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74  release of SQLit
11dc0 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  e..**.** The sql
11dd0 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72  ite3_os_init() r
11de0 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72  outine does oper
11df0 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65  ating-system spe
11e00 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c  cific.** initial
11e10 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53  ization of the S
11e20 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20  QLite library.  
11e30 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  The sqlite3_os_e
11e40 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  nd().** routine 
11e50 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65 63  undoes the effec
11e60 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f  t of sqlite3_os_
11e70 69 6e 69 74 28 29 2e 20 20 54 79 70 69 63 61 6c  init().  Typical
11e80 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72   tasks.** perfor
11e90 6d 65 64 20 62 79 20 74 68 65 73 65 20 72 6f 75  med by these rou
11ea0 74 69 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 6c  tines include al
11eb0 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c  location or deal
11ec0 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73  location.** of s
11ed0 74 61 74 69 63 20 72 65 73 6f 75 72 63 65 73 2c  tatic resources,
11ee0 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
11ef0 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62  of global variab
11f00 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20  les,.** setting 
11f10 75 70 20 61 20 64 65 66 61 75 6c 74 20 5b 73 71  up a default [sq
11f20 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c  lite3_vfs] modul
11f30 65 2c 20 6f 72 20 73 65 74 74 69 6e 67 20 75 70  e, or setting up
11f40 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74 20 63 6f  .** a default co
11f50 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 73 69 6e  nfiguration usin
11f60 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  g [sqlite3_confi
11f70 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  g()]..**.** The 
11f80 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
11f90 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20  ld never invoke 
11fa0 65 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f  either sqlite3_o
11fb0 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73  s_init().** or s
11fc0 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20  qlite3_os_end() 
11fd0 64 69 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61  directly.  The a
11fe0 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
11ff0 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a  d only invoke.**
12000 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
12010 69 7a 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ize() and sqlite
12020 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54  3_shutdown().  T
12030 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  he sqlite3_os_in
12040 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  it().** interfac
12050 65 20 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f  e is called auto
12060 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c  matically by sql
12070 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
12080 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ) and.** sqlite3
12090 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20 63 61 6c  _os_end() is cal
120a0 6c 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73  led by sqlite3_s
120b0 68 75 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 72  hutdown().  Appr
120c0 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65  opriate.** imple
120d0 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 73  mentations for s
120e0 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
120f0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f   and sqlite3_os_
12100 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 69  end().** are bui
12110 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 77  lt into SQLite w
12120 68 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c  hen it is compil
12130 65 64 20 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e  ed for Unix, Win
12140 64 6f 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a  dows, or OS/2..*
12150 2a 20 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62  * When [custom b
12160 75 69 6c 64 73 20 7c 20 62 75 69 6c 74 20 66 6f  uilds | built fo
12170 72 20 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d  r other platform
12180 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68 65  s].** (using the
12190 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45   [SQLITE_OS_OTHE
121a0 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  R=1] compile-tim
121b0 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65  e.** option) the
121c0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
121d0 74 20 73 75 70 70 6c 79 20 61 20 73 75 69 74 61  t supply a suita
121e0 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ble implementati
121f0 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  on for.** sqlite
12200 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20  3_os_init() and 
12210 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
12220 2e 20 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f  .  An applicatio
12230 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d  n-supplied.** im
12240 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
12250 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
12260 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f  ) or sqlite3_os_
12270 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65  end().** must re
12280 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
12290 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20   on success and 
122a0 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72 72 6f  some other [erro
122b0 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20  r code] upon.** 
122c0 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 53 51 4c 49  failure..*/.SQLI
122d0 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54  TE_API int SQLIT
122e0 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
122f0 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69  3_initialize(voi
12300 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  d);.SQLITE_API i
12310 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  nt SQLITE_STDCAL
12320 4c 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  L sqlite3_shutdo
12330 77 6e 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45  wn(void);.SQLITE
12340 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f  _API int SQLITE_
12350 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
12360 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a 53  os_init(void);.S
12370 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51  QLITE_API int SQ
12380 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
12390 69 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64  ite3_os_end(void
123a0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
123b0 45 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67 20  EF: Configuring 
123c0 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61  The SQLite Libra
123d0 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  ry.**.** The sql
123e0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e  ite3_config() in
123f0 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20  terface is used 
12400 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 63  to make global c
12410 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20  onfiguration.** 
12420 63 68 61 6e 67 65 73 20 74 6f 20 53 51 4c 69 74  changes to SQLit
12430 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 74 75  e in order to tu
12440 6e 65 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65  ne SQLite to the
12450 20 73 70 65 63 69 66 69 63 20 6e 65 65 64 73 20   specific needs 
12460 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  of.** the applic
12470 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 66 61  ation.  The defa
12480 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ult configuratio
12490 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  n is recommended
124a0 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 70   for most.** app
124b0 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64 20 73 6f  lications and so
124c0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73   this routine is
124d0 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 63   usually not nec
124e0 65 73 73 61 72 79 2e 20 20 49 74 20 69 73 0a 2a  essary.  It is.*
124f0 2a 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 75  * provided to su
12500 70 70 6f 72 74 20 72 61 72 65 20 61 70 70 6c 69  pport rare appli
12510 63 61 74 69 6f 6e 73 20 77 69 74 68 20 75 6e 75  cations with unu
12520 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a  sual needs..**.*
12530 2a 20 3c 62 3e 54 68 65 20 73 71 6c 69 74 65 33  * <b>The sqlite3
12540 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66  _config() interf
12550 61 63 65 20 69 73 20 6e 6f 74 20 74 68 72 65 61  ace is not threa
12560 64 73 61 66 65 2e 20 54 68 65 20 61 70 70 6c 69  dsafe. The appli
12570 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 65  cation.** must e
12580 6e 73 75 72 65 20 74 68 61 74 20 6e 6f 20 6f 74  nsure that no ot
12590 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72  her SQLite inter
125a0 66 61 63 65 73 20 61 72 65 20 69 6e 76 6f 6b 65  faces are invoke
125b0 64 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68  d by other.** th
125c0 72 65 61 64 73 20 77 68 69 6c 65 20 73 71 6c 69  reads while sqli
125d0 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20  te3_config() is 
125e0 72 75 6e 6e 69 6e 67 2e 3c 2f 62 3e 0a 2a 2a 0a  running.</b>.**.
125f0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63  ** The sqlite3_c
12600 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63  onfig() interfac
12610 65 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65  e.** may only be
12620 20 69 6e 76 6f 6b 65 64 20 70 72 69 6f 72 20 74   invoked prior t
12630 6f 20 6c 69 62 72 61 72 79 20 69 6e 69 74 69 61  o library initia
12640 6c 69 7a 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a  lization using.*
12650 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  * [sqlite3_initi
12660 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65  alize()] or afte
12670 72 20 73 68 75 74 64 6f 77 6e 20 62 79 20 5b 73  r shutdown by [s
12680 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
12690 29 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74  )]..** ^If sqlit
126a0 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 63  e3_config() is c
126b0 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c  alled after [sql
126c0 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
126d0 29 5d 20 61 6e 64 20 62 65 66 6f 72 65 0a 2a 2a  )] and before.**
126e0 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   [sqlite3_shutdo
126f0 77 6e 28 29 5d 20 74 68 65 6e 20 69 74 20 77 69  wn()] then it wi
12700 6c 6c 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45  ll return SQLITE
12710 5f 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65  _MISUSE..** Note
12720 2c 20 68 6f 77 65 76 65 72 2c 20 74 68 61 74 20  , however, that 
12730 5e 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  ^sqlite3_config(
12740 29 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20  ) can be called 
12750 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 0a 2a  as part of the.*
12760 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
12770 20 6f 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69   of an applicati
12780 6f 6e 2d 64 65 66 69 6e 65 64 20 5b 73 71 6c 69  on-defined [sqli
12790 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a  te3_os_init()]..
127a0 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
127b0 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
127c0 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20  te3_config() is 
127d0 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 63  an integer.** [c
127e0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
127f0 69 6f 6e 5d 20 74 68 61 74 20 64 65 74 65 72 6d  ion] that determ
12800 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f  ines.** what pro
12810 70 65 72 74 79 20 6f 66 20 53 51 4c 69 74 65 20  perty of SQLite 
12820 69 73 20 74 6f 20 62 65 20 63 6f 6e 66 69 67 75  is to be configu
12830 72 65 64 2e 20 20 53 75 62 73 65 71 75 65 6e 74  red.  Subsequent
12840 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61   arguments.** va
12850 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  ry depending on 
12860 74 68 65 20 5b 63 6f 6e 66 69 67 75 72 61 74 69  the [configurati
12870 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e  on option].** in
12880 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
12890 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e  ent..**.** ^When
128a0 20 61 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e   a configuration
128b0 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 2c 20   option is set, 
128c0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
128d0 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
128e0 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  _OK]..** ^If the
128f0 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f   option is unkno
12900 77 6e 20 6f 72 20 53 51 4c 69 74 65 20 69 73 20  wn or SQLite is 
12910 75 6e 61 62 6c 65 20 74 6f 20 73 65 74 20 74 68  unable to set th
12920 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e  e option.** then
12930 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65   this routine re
12940 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f  turns a non-zero
12950 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a   [error code]..*
12960 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
12970 20 53 51 4c 49 54 45 5f 43 44 45 43 4c 20 73 71   SQLITE_CDECL sq
12980 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74  lite3_config(int
12990 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  , ...);../*.** C
129a0 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75  API3REF: Configu
129b0 72 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  re database conn
129c0 65 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f  ections.** METHO
129d0 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
129e0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f   The sqlite3_db_
129f0 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61  config() interfa
12a00 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61  ce is used to ma
12a10 6b 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ke configuration
12a20 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 61  .** changes to a
12a30 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
12a40 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74  ction].  The int
12a50 65 72 66 61 63 65 20 69 73 20 73 69 6d 69 6c 61  erface is simila
12a60 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  r to.** [sqlite3
12a70 5f 63 6f 6e 66 69 67 28 29 5d 20 65 78 63 65 70  _config()] excep
12a80 74 20 74 68 61 74 20 74 68 65 20 63 68 61 6e 67  t that the chang
12a90 65 73 20 61 70 70 6c 79 20 74 6f 20 61 20 73 69  es apply to a si
12aa0 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73  ngle.** [databas
12ab0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73  e connection] (s
12ac0 70 65 63 69 66 69 65 64 20 69 6e 20 74 68 65 20  pecified in the 
12ad0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 29 2e  first argument).
12ae0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  .**.** The secon
12af0 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  d argument to sq
12b00 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
12b10 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65  D,V,...)  is the
12b20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f  .** [SQLITE_DBCO
12b30 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 7c  NFIG_LOOKASIDE |
12b40 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76   configuration v
12b50 65 72 62 5d 20 2d 20 61 6e 20 69 6e 74 65 67 65  erb] - an intege
12b60 72 20 63 6f 64 65 20 0a 2a 2a 20 74 68 61 74 20  r code .** that 
12b70 69 6e 64 69 63 61 74 65 73 20 77 68 61 74 20 61  indicates what a
12b80 73 70 65 63 74 20 6f 66 20 74 68 65 20 5b 64 61  spect of the [da
12b90 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
12ba0 6e 5d 20 69 73 20 62 65 69 6e 67 20 63 6f 6e 66  n] is being conf
12bb0 69 67 75 72 65 64 2e 0a 2a 2a 20 53 75 62 73 65  igured..** Subse
12bc0 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 20  quent arguments 
12bd0 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f  vary depending o
12be0 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74  n the configurat
12bf0 69 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20  ion verb..**.** 
12c00 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65  ^Calls to sqlite
12c10 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 72 65  3_db_config() re
12c20 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69  turn SQLITE_OK i
12c30 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a  f and only if.**
12c40 20 74 68 65 20 63 61 6c 6c 20 69 73 20 63 6f 6e   the call is con
12c50 73 69 64 65 72 65 64 20 73 75 63 63 65 73 73 66  sidered successf
12c60 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ul..*/.SQLITE_AP
12c70 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 43 44 45  I int SQLITE_CDE
12c80 43 4c 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  CL sqlite3_db_co
12c90 6e 66 69 67 28 73 71 6c 69 74 65 33 2a 2c 20 69  nfig(sqlite3*, i
12ca0 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a  nt op, ...);../*
12cb0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65  .** CAPI3REF: Me
12cc0 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20  mory Allocation 
12cd0 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 41  Routines.**.** A
12ce0 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
12cf0 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65  is object define
12d00 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20  s the interface 
12d10 62 65 74 77 65 65 6e 20 53 51 4c 69 74 65 0a 2a  between SQLite.*
12d20 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c 20  * and low-level 
12d30 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
12d40 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a  n routines..**.*
12d50 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73  * This object is
12d60 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e   used in only on
12d70 65 20 70 6c 61 63 65 20 69 6e 20 74 68 65 20 53  e place in the S
12d80 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e  QLite interface.
12d90 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f  .** A pointer to
12da0 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
12db0 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 74  this object is t
12dc0 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  he argument to.*
12dd0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
12de0 67 28 29 5d 20 77 68 65 6e 20 74 68 65 20 63 6f  g()] when the co
12df0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
12e00 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 45  on is.** [SQLITE
12e10 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20  _CONFIG_MALLOC] 
12e20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  or [SQLITE_CONFI
12e30 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a  G_GETMALLOC].  .
12e40 2a 2a 20 42 79 20 63 72 65 61 74 69 6e 67 20 61  ** By creating a
12e50 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
12e60 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64  is object.** and
12e70 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b   passing it to [
12e80 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28  sqlite3_config](
12e90 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
12ea0 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 69 6e  ALLOC]).** durin
12eb0 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c  g configuration,
12ec0 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
12ed0 63 61 6e 20 73 70 65 63 69 66 79 20 61 6e 20 61  can specify an a
12ee0 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65  lternative.** me
12ef0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
12f00 73 75 62 73 79 73 74 65 6d 20 66 6f 72 20 53 51  subsystem for SQ
12f10 4c 69 74 65 20 74 6f 20 75 73 65 20 66 6f 72 20  Lite to use for 
12f20 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 64 79  all of its.** dy
12f30 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65  namic memory nee
12f40 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  ds..**.** Note t
12f50 68 61 74 20 53 51 4c 69 74 65 20 63 6f 6d 65 73  hat SQLite comes
12f60 20 77 69 74 68 20 73 65 76 65 72 61 6c 20 5b 62   with several [b
12f70 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61  uilt-in memory a
12f80 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 74 68  llocators].** th
12f90 61 74 20 61 72 65 20 70 65 72 66 65 63 74 6c 79  at are perfectly
12fa0 20 61 64 65 71 75 61 74 65 20 66 6f 72 20 74 68   adequate for th
12fb0 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20 6d  e overwhelming m
12fc0 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69  ajority of appli
12fd0 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74  cations.** and t
12fe0 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63 74 20  hat this object 
12ff0 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20 74  is only useful t
13000 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69 74  o a tiny minorit
13010 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e  y of application
13020 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63 69 61  s.** with specia
13030 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c  lized memory all
13040 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72 65 6d  ocation requirem
13050 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62 6a 65  ents.  This obje
13060 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 73  ct is.** also us
13070 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e  ed during testin
13080 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e 20 6f  g of SQLite in o
13090 72 64 65 72 20 74 6f 20 73 70 65 63 69 66 79 20  rder to specify 
130a0 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a  an alternative.*
130b0 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * memory allocat
130c0 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 65  or that simulate
130d0 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d  s memory out-of-
130e0 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f 6e  memory condition
130f0 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 6f  s in.** order to
13100 20 76 65 72 69 66 79 20 74 68 61 74 20 53 51 4c   verify that SQL
13110 69 74 65 20 72 65 63 6f 76 65 72 73 20 67 72 61  ite recovers gra
13120 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75 63  cefully from suc
13130 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 2e  h.** conditions.
13140 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c 6c  .**.** The xMall
13150 6f 63 2c 20 78 52 65 61 6c 6c 6f 63 2c 20 61 6e  oc, xRealloc, an
13160 64 20 78 46 72 65 65 20 6d 65 74 68 6f 64 73 20  d xFree methods 
13170 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20 74  must work like t
13180 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 2c 20  he.** malloc(), 
13190 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72  realloc() and fr
131a0 65 65 28 29 20 66 75 6e 63 74 69 6f 6e 73 20 66  ee() functions f
131b0 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64  rom the standard
131c0 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 5e   C library..** ^
131d0 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65  SQLite guarantee
131e0 73 20 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e  s that the secon
131f0 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  d argument to.**
13200 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 61 6c 77   xRealloc is alw
13210 61 79 73 20 61 20 76 61 6c 75 65 20 72 65 74 75  ays a value retu
13220 72 6e 65 64 20 62 79 20 61 20 70 72 69 6f 72 20  rned by a prior 
13230 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 75 70  call to xRoundup
13240 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68  ..**.** xSize sh
13250 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20  ould return the 
13260 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f  allocated size o
13270 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  f a memory alloc
13280 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75  ation.** previou
13290 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  sly obtained fro
132a0 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65  m xMalloc or xRe
132b0 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f  alloc.  The allo
132c0 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73  cated size.** is
132d0 20 61 6c 77 61 79 73 20 61 74 20 6c 65 61 73 74   always at least
132e0 20 61 73 20 62 69 67 20 61 73 20 74 68 65 20 72   as big as the r
132f0 65 71 75 65 73 74 65 64 20 73 69 7a 65 20 62 75  equested size bu
13300 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72 2e  t may be larger.
13310 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e  .**.** The xRoun
13320 64 75 70 20 6d 65 74 68 6f 64 20 72 65 74 75 72  dup method retur
13330 6e 73 20 77 68 61 74 20 77 6f 75 6c 64 20 62 65  ns what would be
13340 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73   the allocated s
13350 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f  ize of.** a memo
13360 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69  ry allocation gi
13370 76 65 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72  ven a particular
13380 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 2e   requested size.
13390 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a    Most memory.**
133a0 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e   allocators roun
133b0 64 20 75 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  d up memory allo
133c0 63 61 74 69 6f 6e 73 20 61 74 20 6c 65 61 73 74  cations at least
133d0 20 74 6f 20 74 68 65 20 6e 65 78 74 20 6d 75 6c   to the next mul
133e0 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20  tiple.** of 8.  
133f0 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20  Some allocators 
13400 72 6f 75 6e 64 20 75 70 20 74 6f 20 61 20 6c 61  round up to a la
13410 72 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72  rger multiple or
13420 20 74 6f 20 61 20 70 6f 77 65 72 20 6f 66 20 32   to a power of 2
13430 2e 0a 2a 2a 20 45 76 65 72 79 20 6d 65 6d 6f 72  ..** Every memor
13440 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71  y allocation req
13450 75 65 73 74 20 63 6f 6d 69 6e 67 20 69 6e 20 74  uest coming in t
13460 68 72 6f 75 67 68 20 5b 73 71 6c 69 74 65 33 5f  hrough [sqlite3_
13470 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20  malloc()].** or 
13480 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
13490 28 29 5d 20 66 69 72 73 74 20 63 61 6c 6c 73 20  ()] first calls 
134a0 78 52 6f 75 6e 64 75 70 2e 20 20 49 66 20 78 52  xRoundup.  If xR
134b0 6f 75 6e 64 75 70 20 72 65 74 75 72 6e 73 20 30  oundup returns 0
134c0 2c 20 0a 2a 2a 20 74 68 61 74 20 63 61 75 73 65  , .** that cause
134d0 73 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  s the correspond
134e0 69 6e 67 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ing memory alloc
134f0 61 74 69 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a  ation to fail..*
13500 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74 20 6d  *.** The xInit m
13510 65 74 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65  ethod initialize
13520 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  s the memory all
13530 6f 63 61 74 6f 72 2e 20 20 46 6f 72 20 65 78 61  ocator.  For exa
13540 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68  mple,.** it migh
13550 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72  t allocate any r
13560 65 71 75 69 72 65 20 6d 75 74 65 78 65 73 20 6f  equire mutexes o
13570 72 20 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74  r initialize int
13580 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74  ernal data.** st
13590 72 75 63 74 75 72 65 73 2e 20 20 54 68 65 20 78  ructures.  The x
135a0 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20  Shutdown method 
135b0 69 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69  is invoked (indi
135c0 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73  rectly) by.** [s
135d0 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
135e0 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20 64 65  )] and should de
135f0 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 73  allocate any res
13600 6f 75 72 63 65 73 20 61 63 71 75 69 72 65 64 0a  ources acquired.
13610 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20 20 54 68  ** by xInit.  Th
13620 65 20 70 41 70 70 44 61 74 61 20 70 6f 69 6e 74  e pAppData point
13630 65 72 20 69 73 20 75 73 65 64 20 61 73 20 74 68  er is used as th
13640 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72  e only parameter
13650 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64   to.** xInit and
13660 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a   xShutdown..**.*
13670 2a 20 53 51 4c 69 74 65 20 68 6f 6c 64 73 20 74  * SQLite holds t
13680 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58  he [SQLITE_MUTEX
13690 5f 53 54 41 54 49 43 5f 4d 41 53 54 45 52 5d 20  _STATIC_MASTER] 
136a0 6d 75 74 65 78 20 77 68 65 6e 20 69 74 20 69 6e  mutex when it in
136b0 76 6f 6b 65 73 0a 2a 2a 20 74 68 65 20 78 49 6e  vokes.** the xIn
136c0 69 74 20 6d 65 74 68 6f 64 2c 20 73 6f 20 74 68  it method, so th
136d0 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 6e  e xInit method n
136e0 65 65 64 20 6e 6f 74 20 62 65 20 74 68 72 65 61  eed not be threa
136f0 64 73 61 66 65 2e 20 20 54 68 65 0a 2a 2a 20 78  dsafe.  The.** x
13700 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20  Shutdown method 
13710 69 73 20 6f 6e 6c 79 20 63 61 6c 6c 65 64 20 66  is only called f
13720 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73 68 75  rom [sqlite3_shu
13730 74 64 6f 77 6e 28 29 5d 20 73 6f 20 69 74 20 64  tdown()] so it d
13740 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64 20  oes.** not need 
13750 74 6f 20 62 65 20 74 68 72 65 61 64 73 61 66 65  to be threadsafe
13760 20 65 69 74 68 65 72 2e 20 20 46 6f 72 20 61 6c   either.  For al
13770 6c 20 6f 74 68 65 72 20 6d 65 74 68 6f 64 73 2c  l other methods,
13780 20 53 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64 73   SQLite.** holds
13790 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54   the [SQLITE_MUT
137a0 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 5d 20 6d  EX_STATIC_MEM] m
137b0 75 74 65 78 20 61 73 20 6c 6f 6e 67 20 61 73 20  utex as long as 
137c0 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43  the.** [SQLITE_C
137d0 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d  ONFIG_MEMSTATUS]
137e0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
137f0 70 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20  ption is turned 
13800 6f 6e 20 28 77 68 69 63 68 0a 2a 2a 20 69 74 20  on (which.** it 
13810 69 73 20 62 79 20 64 65 66 61 75 6c 74 29 20 61  is by default) a
13820 6e 64 20 73 6f 20 74 68 65 20 6d 65 74 68 6f 64  nd so the method
13830 73 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61  s are automatica
13840 6c 6c 79 20 73 65 72 69 61 6c 69 7a 65 64 2e 0a  lly serialized..
13850 2a 2a 20 48 6f 77 65 76 65 72 2c 20 69 66 20 5b  ** However, if [
13860 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
13870 4d 53 54 41 54 55 53 5d 20 69 73 20 64 69 73 61  MSTATUS] is disa
13880 62 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20 6f  bled, then the o
13890 74 68 65 72 0a 2a 2a 20 6d 65 74 68 6f 64 73 20  ther.** methods 
138a0 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 73 61  must be threadsa
138b0 66 65 20 6f 72 20 65 6c 73 65 20 6d 61 6b 65 20  fe or else make 
138c0 74 68 65 69 72 20 6f 77 6e 20 61 72 72 61 6e 67  their own arrang
138d0 65 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a 20 73 65  ements for.** se
138e0 72 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a  rialization..**.
138f0 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e  ** SQLite will n
13900 65 76 65 72 20 69 6e 76 6f 6b 65 20 78 49 6e 69  ever invoke xIni
13910 74 28 29 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e  t() more than on
13920 63 65 20 77 69 74 68 6f 75 74 20 61 6e 20 69 6e  ce without an in
13930 74 65 72 76 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c  tervening.** cal
13940 6c 20 74 6f 20 78 53 68 75 74 64 6f 77 6e 28 29  l to xShutdown()
13950 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
13960 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  uct sqlite3_mem_
13970 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f  methods sqlite3_
13980 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72  mem_methods;.str
13990 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  uct sqlite3_mem_
139a0 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64  methods {.  void
139b0 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74   *(*xMalloc)(int
139c0 29 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 65  );         /* Me
139d0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
139e0 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f  function */.  vo
139f0 69 64 20 28 2a 78 46 72 65 65 29 28 76 6f 69 64  id (*xFree)(void
13a00 2a 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20  *);          /* 
13a10 46 72 65 65 20 61 20 70 72 69 6f 72 20 61 6c 6c  Free a prior all
13a20 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69  ocation */.  voi
13a30 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76  d *(*xRealloc)(v
13a40 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52  oid*,int);  /* R
13a50 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74  esize an allocat
13a60 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ion */.  int (*x
13a70 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20 20  Size)(void*);   
13a80 20 20 20 20 20 20 20 20 2f 2a 20 52 65 74 75 72          /* Retur
13a90 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 6e  n the size of an
13aa0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20   allocation */. 
13ab0 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70 29   int (*xRoundup)
13ac0 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 20  (int);          
13ad0 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72 65 71 75  /* Round up requ
13ae0 65 73 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f  est size to allo
13af0 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20  cation size */. 
13b00 20 69 6e 74 20 28 2a 78 49 6e 69 74 29 28 76 6f   int (*xInit)(vo
13b10 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20  id*);           
13b20 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65 20 74 68  /* Initialize th
13b30 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
13b40 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78  or */.  void (*x
13b50 53 68 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29  Shutdown)(void*)
13b60 3b 20 20 20 20 20 20 2f 2a 20 44 65 69 6e 69 74  ;      /* Deinit
13b70 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72  ialize the memor
13b80 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20  y allocator */. 
13b90 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b   void *pAppData;
13ba0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
13bb0 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74 6f 20 78  /* Argument to x
13bc0 49 6e 69 74 28 29 20 61 6e 64 20 78 53 68 75 74  Init() and xShut
13bd0 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  down() */.};../*
13be0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
13bf0 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69  nfiguration Opti
13c00 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ons.** KEYWORDS:
13c10 20 7b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20   {configuration 
13c20 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68  option}.**.** Th
13c30 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ese constants ar
13c40 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20  e the available 
13c50 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72  integer configur
13c60 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68  ation options th
13c70 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73  at.** can be pas
13c80 73 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74  sed as the first
13c90 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
13ca0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
13cb0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ()] interface..*
13cc0 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75  *.** New configu
13cd0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d  ration options m
13ce0 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
13cf0 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f  uture releases o
13d00 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69  f SQLite..** Exi
13d10 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74  sting configurat
13d20 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68  ion options migh
13d30 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65  t be discontinue
13d40 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  d.  Applications
13d50 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b  .** should check
13d60 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65   the return code
13d70 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63   from [sqlite3_c
13d80 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65  onfig()] to make
13d90 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68   sure that.** th
13da0 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20  e call worked.  
13db0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  The [sqlite3_con
13dc0 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  fig()] interface
13dd0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a   will return a.*
13de0 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f  * non-zero [erro
13df0 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73  r code] if a dis
13e00 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73  continued or uns
13e10 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75  upported configu
13e20 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a  ration option.**
13e30 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a   is invoked..**.
13e40 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c  ** <dl>.** [[SQL
13e50 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
13e60 45 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51  ETHREAD]] <dt>SQ
13e70 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
13e80 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a  LETHREAD</dt>.**
13e90 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e   <dd>There are n
13ea0 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  o arguments to t
13eb0 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68  his option.  ^Th
13ec0 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74  is option sets t
13ed0 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67  he.** [threading
13ee0 20 6d 6f 64 65 5d 20 74 6f 20 53 69 6e 67 6c 65   mode] to Single
13ef0 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68  -thread.  In oth
13f00 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73  er words, it dis
13f10 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74  ables.** all mut
13f20 65 78 69 6e 67 20 61 6e 64 20 70 75 74 73 20 53  exing and puts S
13f30 51 4c 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64  QLite into a mod
13f40 65 20 77 68 65 72 65 20 69 74 20 63 61 6e 20 6f  e where it can o
13f50 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a 2a 20 62  nly be used.** b
13f60 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61  y a single threa
13f70 64 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20  d.   ^If SQLite 
13f80 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
13f90 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
13fa0 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c  THREADSAFE | SQL
13fb0 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
13fc0 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
13fd0 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74  ption then.** it
13fe0 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65   is not possible
13ff0 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 5b   to change the [
14000 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
14010 66 72 6f 6d 20 69 74 73 20 64 65 66 61 75 6c 74  from its default
14020 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 53 69 6e  .** value of Sin
14030 67 6c 65 2d 74 68 72 65 61 64 20 61 6e 64 20 73  gle-thread and s
14040 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  o [sqlite3_confi
14050 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  g()] will return
14060 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52   .** [SQLITE_ERR
14070 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69  OR] if called wi
14080 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f  th the SQLITE_CO
14090 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
140a0 44 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69  D.** configurati
140b0 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a  on option.</dd>.
140c0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
140d0 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
140e0 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  D]] <dt>SQLITE_C
140f0 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
14100 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
14110 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d  ere are no argum
14120 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74  ents to this opt
14130 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69  ion.  ^This opti
14140 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b  on sets the.** [
14150 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
14160 74 6f 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 2e  to Multi-thread.
14170 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73    In other words
14180 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a  , it disables.**
14190 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61   mutexing on [da
141a0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
141b0 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  n] and [prepared
141c0 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65   statement] obje
141d0 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  cts..** The appl
141e0 69 63 61 74 69 6f 6e 20 69 73 20 72 65 73 70 6f  ication is respo
141f0 6e 73 69 62 6c 65 20 66 6f 72 20 73 65 72 69 61  nsible for seria
14200 6c 69 7a 69 6e 67 20 61 63 63 65 73 73 20 74 6f  lizing access to
14210 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
14220 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b  nnections] and [
14230 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
14240 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74 68 65 72  nts].  But other
14250 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20   mutexes.** are 
14260 65 6e 61 62 6c 65 64 20 73 6f 20 74 68 61 74 20  enabled so that 
14270 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 73  SQLite will be s
14280 61 66 65 20 74 6f 20 75 73 65 20 69 6e 20 61 20  afe to use in a 
14290 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 0a 2a  multi-threaded.*
142a0 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73  * environment as
142b0 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20   long as no two 
142c0 74 68 72 65 61 64 73 20 61 74 74 65 6d 70 74 20  threads attempt 
142d0 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 0a  to use the same.
142e0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
142f0 6e 65 63 74 69 6f 6e 5d 20 61 74 20 74 68 65 20  nection] at the 
14300 73 61 6d 65 20 74 69 6d 65 2e 20 20 5e 49 66 20  same time.  ^If 
14310 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
14320 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
14330 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
14340 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41  E | SQLITE_THREA
14350 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65  DSAFE=0] compile
14360 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65  -time option the
14370 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70  n.** it is not p
14380 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74  ossible to set t
14390 68 65 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 20  he Multi-thread 
143a0 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
143b0 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
143c0 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20  _config()] will 
143d0 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45  return [SQLITE_E
143e0 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20  RROR] if called 
143f0 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49  with the.** SQLI
14400 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
14410 48 52 45 41 44 20 63 6f 6e 66 69 67 75 72 61 74  HREAD configurat
14420 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e  ion option.</dd>
14430 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
14440 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
14450 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  D]] <dt>SQLITE_C
14460 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44  ONFIG_SERIALIZED
14470 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
14480 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65  re are no argume
14490 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69  nts to this opti
144a0 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f  on.  ^This optio
144b0 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74  n sets the.** [t
144c0 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74  hreading mode] t
144d0 6f 20 53 65 72 69 61 6c 69 7a 65 64 2e 20 49 6e  o Serialized. In
144e0 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
144f0 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65  is option enable
14500 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73  s.** all mutexes
14510 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 65 20 72   including the r
14520 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65  ecursive.** mute
14530 78 65 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65  xes on [database
14540 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64   connection] and
14550 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
14560 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  ment] objects..*
14570 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64 65 20 28  * In this mode (
14580 77 68 69 63 68 20 69 73 20 74 68 65 20 64 65 66  which is the def
14590 61 75 6c 74 20 77 68 65 6e 20 53 51 4c 69 74 65  ault when SQLite
145a0 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
145b0 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52  h.** [SQLITE_THR
145c0 45 41 44 53 41 46 45 3d 31 5d 29 20 74 68 65 20  EADSAFE=1]) the 
145d0 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77  SQLite library w
145e0 69 6c 6c 20 69 74 73 65 6c 66 20 73 65 72 69 61  ill itself seria
145f0 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20 74  lize access.** t
14600 6f 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  o [database conn
14610 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72  ections] and [pr
14620 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
14630 73 5d 20 73 6f 20 74 68 61 74 20 74 68 65 0a 2a  s] so that the.*
14640 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73  * application is
14650 20 66 72 65 65 20 74 6f 20 75 73 65 20 74 68 65   free to use the
14660 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20   same [database 
14670 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74  connection] or t
14680 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70  he.** same [prep
14690 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
146a0 69 6e 20 64 69 66 66 65 72 65 6e 74 20 74 68 72  in different thr
146b0 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65  eads at the same
146c0 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53 51   time..** ^If SQ
146d0 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
146e0 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
146f0 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
14700 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
14710 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
14720 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
14730 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73  ** it is not pos
14740 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65  sible to set the
14750 20 53 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72   Serialized [thr
14760 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64  eading mode] and
14770 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
14780 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75  fig()] will retu
14790 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  rn [SQLITE_ERROR
147a0 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68  ] if called with
147b0 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43   the.** SQLITE_C
147c0 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44  ONFIG_SERIALIZED
147d0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
147e0 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ption.</dd>.**.*
147f0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
14800 47 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53  G_MALLOC]] <dt>S
14810 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
14820 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  LOC</dt>.** <dd>
14830 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f   ^(The SQLITE_CO
14840 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 6f 70 74 69  NFIG_MALLOC opti
14850 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
14860 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
14870 20 69 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65   is .** a pointe
14880 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65  r to an instance
14890 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
148a0 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74  _mem_methods] st
148b0 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20  ructure..** The 
148c0 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69  argument specifi
148d0 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76  es.** alternativ
148e0 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f  e low-level memo
148f0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f  ry allocation ro
14900 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65  utines to be use
14910 64 20 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a  d in place of.**
14920 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
14930 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20  cation routines 
14940 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74  built into SQLit
14950 65 2e 29 5e 20 5e 53 51 4c 69 74 65 20 6d 61 6b  e.)^ ^SQLite mak
14960 65 73 0a 2a 2a 20 69 74 73 20 6f 77 6e 20 70 72  es.** its own pr
14970 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68  ivate copy of th
14980 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
14990 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65   [sqlite3_mem_me
149a0 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
149b0 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 65 20 5b  .** before the [
149c0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
149d0 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 3c  ] call returns.<
149e0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
149f0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41  ITE_CONFIG_GETMA
14a00 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  LLOC]] <dt>SQLIT
14a10 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c  E_CONFIG_GETMALL
14a20 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  OC</dt>.** <dd> 
14a30 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  ^(The SQLITE_CON
14a40 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 6f 70  FIG_GETMALLOC op
14a50 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
14a60 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
14a70 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74  ch.** is a point
14a80 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
14a90 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  e of the [sqlite
14aa0 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73  3_mem_methods] s
14ab0 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65  tructure..** The
14ac0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65   [sqlite3_mem_me
14ad0 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74  thods].** struct
14ae0 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69  ure is filled wi
14af0 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79  th the currently
14b00 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f 72 79 20   defined memory 
14b10 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69  allocation routi
14b20 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f  nes.)^.** This o
14b30 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65  ption can be use
14b40 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68  d to overload th
14b50 65 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79  e default memory
14b60 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72   allocation.** r
14b70 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77  outines with a w
14b80 72 61 70 70 65 72 20 74 68 61 74 20 73 69 6d 75  rapper that simu
14b90 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 20 61  lations memory a
14ba0 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 72  llocation failur
14bb0 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 20 6d  e or.** tracks m
14bc0 65 6d 6f 72 79 20 75 73 61 67 65 2c 20 66 6f 72  emory usage, for
14bd0 20 65 78 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e 0a   example. </dd>.
14be0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
14bf0 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d  ONFIG_MEMSTATUS]
14c00 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
14c10 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64  FIG_MEMSTATUS</d
14c20 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20  t>.** <dd> ^The 
14c30 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
14c40 4d 53 54 41 54 55 53 20 6f 70 74 69 6f 6e 20 74  MSTATUS option t
14c50 61 6b 65 73 20 73 69 6e 67 6c 65 20 61 72 67 75  akes single argu
14c60 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74  ment of type int
14c70 2c 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 65 64  ,.** interpreted
14c80 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e 2c 20 77   as a boolean, w
14c90 68 69 63 68 20 65 6e 61 62 6c 65 73 20 6f 72 20  hich enables or 
14ca0 64 69 73 61 62 6c 65 73 20 74 68 65 20 63 6f 6c  disables the col
14cb0 6c 65 63 74 69 6f 6e 20 6f 66 0a 2a 2a 20 6d 65  lection of.** me
14cc0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
14cd0 73 74 61 74 69 73 74 69 63 73 2e 20 5e 28 57 68  statistics. ^(Wh
14ce0 65 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  en memory alloca
14cf0 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20  tion statistics 
14d00 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2c  are.** disabled,
14d10 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53   the following S
14d20 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73  QLite interfaces
14d30 20 62 65 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72   become non-oper
14d40 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75  ational:.**   <u
14d50 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71  l>.**   <li> [sq
14d60 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
14d70 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b  d()].**   <li> [
14d80 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
14d90 69 67 68 77 61 74 65 72 28 29 5d 0a 2a 2a 20 20  ighwater()].**  
14da0 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73   <li> [sqlite3_s
14db0 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34  oft_heap_limit64
14dc0 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73  ()].**   <li> [s
14dd0 71 6c 69 74 65 33 5f 73 74 61 74 75 73 36 34 28  qlite3_status64(
14de0 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e 0a  )].**   </ul>)^.
14df0 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ** ^Memory alloc
14e00 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73  ation statistics
14e10 20 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20   are enabled by 
14e20 64 65 66 61 75 6c 74 20 75 6e 6c 65 73 73 20 53  default unless S
14e30 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70  QLite is.** comp
14e40 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54  iled with [SQLIT
14e50 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41  E_DEFAULT_MEMSTA
14e60 54 55 53 5d 3d 30 20 69 6e 20 77 68 69 63 68 20  TUS]=0 in which 
14e70 63 61 73 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61  case memory.** a
14e80 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73  llocation statis
14e90 74 69 63 73 20 61 72 65 20 64 69 73 61 62 6c 65  tics are disable
14ea0 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a  d by default..**
14eb0 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
14ec0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
14ed0 41 54 43 48 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  ATCH]] <dt>SQLIT
14ee0 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48  E_CONFIG_SCRATCH
14ef0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
14f00 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
14f10 5f 53 43 52 41 54 43 48 20 6f 70 74 69 6f 6e 20  _SCRATCH option 
14f20 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74  specifies a stat
14f30 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  ic memory buffer
14f40 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20  .** that SQLite 
14f50 63 61 6e 20 75 73 65 20 66 6f 72 20 73 63 72 61  can use for scra
14f60 74 63 68 20 6d 65 6d 6f 72 79 2e 20 20 5e 28 54  tch memory.  ^(T
14f70 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61  here are three a
14f80 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 74 6f 20 53  rguments.** to S
14f90 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
14fa0 41 54 43 48 3a 20 20 41 20 70 6f 69 6e 74 65 72  ATCH:  A pointer
14fb0 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c   an 8-byte.** al
14fc0 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20 62 75 66  igned memory buf
14fd0 66 65 72 20 66 72 6f 6d 20 77 68 69 63 68 20 74  fer from which t
14fe0 68 65 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63  he scratch alloc
14ff0 61 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65 0a 2a  ations will be.*
15000 2a 20 64 72 61 77 6e 2c 20 74 68 65 20 73 69 7a  * drawn, the siz
15010 65 20 6f 66 20 65 61 63 68 20 73 63 72 61 74 63  e of each scratc
15020 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 28 73 7a  h allocation (sz
15030 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6d 61  ),.** and the ma
15040 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
15050 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69  scratch allocati
15060 6f 6e 73 20 28 4e 29 2e 29 5e 0a 2a 2a 20 54 68  ons (N).)^.** Th
15070 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
15080 20 6d 75 73 74 20 62 65 20 61 20 70 6f 69 6e 74   must be a point
15090 65 72 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20  er to an 8-byte 
150a0 61 6c 69 67 6e 65 64 20 62 75 66 66 65 72 0a 2a  aligned buffer.*
150b0 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a  * of at least sz
150c0 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f  *N bytes of memo
150d0 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77  ry..** ^SQLite w
150e0 69 6c 6c 20 6e 6f 74 20 75 73 65 20 6d 6f 72 65  ill not use more
150f0 20 74 68 61 6e 20 6f 6e 65 20 73 63 72 61 74 63   than one scratc
15100 68 20 62 75 66 66 65 72 73 20 70 65 72 20 74 68  h buffers per th
15110 72 65 61 64 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  read..** ^SQLite
15120 20 77 69 6c 6c 20 6e 65 76 65 72 20 72 65 71 75   will never requ
15130 65 73 74 20 61 20 73 63 72 61 74 63 68 20 62 75  est a scratch bu
15140 66 66 65 72 20 74 68 61 74 20 69 73 20 6d 6f 72  ffer that is mor
15150 65 20 74 68 61 6e 20 36 0a 2a 2a 20 74 69 6d 65  e than 6.** time
15160 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 70  s the database p
15170 61 67 65 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66  age size..** ^If
15180 20 53 51 4c 69 74 65 20 6e 65 65 64 73 20 6e 65   SQLite needs ne
15190 65 64 73 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  eds additional.*
151a0 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79  * scratch memory
151b0 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20   beyond what is 
151c0 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 69 73  provided by this
151d0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
151e0 70 74 69 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a 20  ption, then .** 
151f0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
15200 29 5d 20 77 69 6c 6c 20 62 65 20 75 73 65 64 20  )] will be used 
15210 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6d 65  to obtain the me
15220 6d 6f 72 79 20 6e 65 65 64 65 64 2e 3c 70 3e 0a  mory needed.<p>.
15230 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 61 70 70  ** ^When the app
15240 6c 69 63 61 74 69 6f 6e 20 70 72 6f 76 69 64 65  lication provide
15250 73 20 61 6e 79 20 61 6d 6f 75 6e 74 20 6f 66 20  s any amount of 
15260 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 75  scratch memory u
15270 73 69 6e 67 0a 2a 2a 20 53 51 4c 49 54 45 5f 43  sing.** SQLITE_C
15280 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 2c 20 53  ONFIG_SCRATCH, S
15290 51 4c 69 74 65 20 61 76 6f 69 64 73 20 75 6e 6e  QLite avoids unn
152a0 65 63 65 73 73 61 72 79 20 6c 61 72 67 65 0a 2a  ecessary large.*
152b0 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  * [sqlite3_mallo
152c0 63 7c 68 65 61 70 20 61 6c 6c 6f 63 61 74 69 6f  c|heap allocatio
152d0 6e 73 5d 2e 0a 2a 2a 20 54 68 69 73 20 63 61 6e  ns]..** This can
152e0 20 68 65 6c 70 20 5b 52 6f 62 73 6f 6e 20 70 72   help [Robson pr
152f0 6f 6f 66 7c 70 72 65 76 65 6e 74 20 6d 65 6d 6f  oof|prevent memo
15300 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61  ry allocation fa
15310 69 6c 75 72 65 73 5d 20 64 75 65 20 74 6f 20 68  ilures] due to h
15320 65 61 70 0a 2a 2a 20 66 72 61 67 6d 65 6e 74 61  eap.** fragmenta
15330 74 69 6f 6e 20 69 6e 20 6c 6f 77 2d 6d 65 6d 6f  tion in low-memo
15340 72 79 20 65 6d 62 65 64 64 65 64 20 73 79 73 74  ry embedded syst
15350 65 6d 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a  ems..** </dd>.**
15360 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
15370 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 5d 20  FIG_PAGECACHE]] 
15380 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
15390 47 5f 50 41 47 45 43 41 43 48 45 3c 2f 64 74 3e  G_PAGECACHE</dt>
153a0 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51  .** <dd> ^The SQ
153b0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
153c0 43 41 43 48 45 20 6f 70 74 69 6f 6e 20 73 70 65  CACHE option spe
153d0 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20  cifies a static 
153e0 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 0a 2a 2a  memory buffer.**
153f0 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e   that SQLite can
15400 20 75 73 65 20 66 6f 72 20 74 68 65 20 64 61 74   use for the dat
15410 61 62 61 73 65 20 70 61 67 65 20 63 61 63 68 65  abase page cache
15420 20 77 69 74 68 20 74 68 65 20 64 65 66 61 75 6c   with the defaul
15430 74 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20  t page.** cache 
15440 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20  implementation. 
15450 20 0a 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69 67   .** This config
15460 75 72 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e  uration should n
15470 6f 74 20 62 65 20 75 73 65 64 20 69 66 20 61 6e  ot be used if an
15480 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
15490 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63 61 63 68  ine page.** cach
154a0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
154b0 20 69 73 20 6c 6f 61 64 65 64 20 75 73 69 6e 67   is loaded using
154c0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e   the [SQLITE_CON
154d0 46 49 47 5f 50 43 41 43 48 45 32 5d 0a 2a 2a 20  FIG_PCACHE2].** 
154e0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
154f0 74 69 6f 6e 2e 0a 2a 2a 20 5e 54 68 65 72 65 20  tion..** ^There 
15500 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65  are three argume
15510 6e 74 73 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f  nts to SQLITE_CO
15520 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 3a 20  NFIG_PAGECACHE: 
15530 41 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20  A pointer to.** 
15540 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 0a 2a  8-byte aligned.*
15550 2a 20 6d 65 6d 6f 72 79 2c 20 74 68 65 20 73 69  * memory, the si
15560 7a 65 20 6f 66 20 65 61 63 68 20 70 61 67 65 20  ze of each page 
15570 62 75 66 66 65 72 20 28 73 7a 29 2c 20 61 6e 64  buffer (sz), and
15580 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70   the number of p
15590 61 67 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65  ages (N)..** The
155a0 20 73 7a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f   sz argument sho
155b0 75 6c 64 20 62 65 20 74 68 65 20 73 69 7a 65 20  uld be the size 
155c0 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 64  of the largest d
155d0 61 74 61 62 61 73 65 20 70 61 67 65 0a 2a 2a 20  atabase page.** 
155e0 28 61 20 70 6f 77 65 72 20 6f 66 20 74 77 6f 20  (a power of two 
155f0 62 65 74 77 65 65 6e 20 35 31 32 20 61 6e 64 20  between 512 and 
15600 36 35 35 33 36 29 20 70 6c 75 73 20 73 6f 6d 65  65536) plus some
15610 20 65 78 74 72 61 20 62 79 74 65 73 20 66 6f 72   extra bytes for
15620 20 65 61 63 68 0a 2a 2a 20 70 61 67 65 20 68 65   each.** page he
15630 61 64 65 72 2e 20 20 5e 54 68 65 20 6e 75 6d 62  ader.  ^The numb
15640 65 72 20 6f 66 20 65 78 74 72 61 20 62 79 74 65  er of extra byte
15650 73 20 6e 65 65 64 65 64 20 62 79 20 74 68 65 20  s needed by the 
15660 70 61 67 65 20 68 65 61 64 65 72 0a 2a 2a 20 63  page header.** c
15670 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64  an be determined
15680 20 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49   using the [SQLI
15690 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
156a0 5f 48 44 52 53 5a 5d 20 6f 70 74 69 6f 6e 20 0a  _HDRSZ] option .
156b0 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ** to [sqlite3_c
156c0 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 20 5e 49 74  onfig()]..** ^It
156d0 20 69 73 20 68 61 72 6d 6c 65 73 73 2c 20 61 70   is harmless, ap
156e0 61 72 74 20 66 72 6f 6d 20 74 68 65 20 77 61 73  art from the was
156f0 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 66  ted memory,.** f
15700 6f 72 20 74 68 65 20 73 7a 20 70 61 72 61 6d 65  or the sz parame
15710 74 65 72 20 74 6f 20 62 65 20 6c 61 72 67 65 72  ter to be larger
15720 20 74 68 61 6e 20 6e 65 63 65 73 73 61 72 79 2e   than necessary.
15730 20 20 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 61    The first.** a
15740 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70  rgument should p
15750 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d 62  ointer to an 8-b
15760 79 74 65 20 61 6c 69 67 6e 65 64 20 62 6c 6f 63  yte aligned bloc
15770 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 74 68 61 74  k of memory that
15780 0a 2a 2a 20 69 73 20 61 74 20 6c 65 61 73 74 20  .** is at least 
15790 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65  sz*N bytes of me
157a0 6d 6f 72 79 2c 20 6f 74 68 65 72 77 69 73 65 20  mory, otherwise 
157b0 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 76  subsequent behav
157c0 69 6f 72 20 69 73 0a 2a 2a 20 75 6e 64 65 66 69  ior is.** undefi
157d0 6e 65 64 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ned..** ^SQLite 
157e0 77 69 6c 6c 20 75 73 65 20 74 68 65 20 6d 65 6d  will use the mem
157f0 6f 72 79 20 70 72 6f 76 69 64 65 64 20 62 79 20  ory provided by 
15800 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
15810 6e 74 20 74 6f 20 73 61 74 69 73 66 79 20 69 74  nt to satisfy it
15820 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e 65 65 64  s.** memory need
15830 73 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20  s for the first 
15840 4e 20 70 61 67 65 73 20 74 68 61 74 20 69 74 20  N pages that it 
15850 61 64 64 73 20 74 6f 20 63 61 63 68 65 2e 20 20  adds to cache.  
15860 5e 49 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  ^If additional.*
15870 2a 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d  * page cache mem
15880 6f 72 79 20 69 73 20 6e 65 65 64 65 64 20 62 65  ory is needed be
15890 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f  yond what is pro
158a0 76 69 64 65 64 20 62 79 20 74 68 69 73 20 6f 70  vided by this op
158b0 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20 53 51  tion, then.** SQ
158c0 4c 69 74 65 20 67 6f 65 73 20 74 6f 20 5b 73 71  Lite goes to [sq
158d0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
158e0 66 6f 72 20 74 68 65 20 61 64 64 69 74 69 6f 6e  for the addition
158f0 61 6c 20 73 74 6f 72 61 67 65 20 73 70 61 63 65  al storage space
15900 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
15910 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41  QLITE_CONFIG_HEA
15920 50 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  P]] <dt>SQLITE_C
15930 4f 4e 46 49 47 5f 48 45 41 50 3c 2f 64 74 3e 0a  ONFIG_HEAP</dt>.
15940 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c  ** <dd> ^The SQL
15950 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20  ITE_CONFIG_HEAP 
15960 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73  option specifies
15970 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79   a static memory
15980 20 62 75 66 66 65 72 20 0a 2a 2a 20 74 68 61 74   buffer .** that
15990 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65   SQLite will use
159a0 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20   for all of its 
159b0 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61  dynamic memory a
159c0 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 0a  llocation needs.
159d0 2a 2a 20 62 65 79 6f 6e 64 20 74 68 6f 73 65 20  ** beyond those 
159e0 70 72 6f 76 69 64 65 64 20 66 6f 72 20 62 79 20  provided for by 
159f0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
15a00 43 52 41 54 43 48 5d 20 61 6e 64 0a 2a 2a 20 5b  CRATCH] and.** [
15a10 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
15a20 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 5e 54 68  GECACHE]..** ^Th
15a30 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
15a40 48 45 41 50 20 6f 70 74 69 6f 6e 20 69 73 20 6f  HEAP option is o
15a50 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66  nly available if
15a60 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
15a70 6c 65 64 0a 2a 2a 20 77 69 74 68 20 65 69 74 68  led.** with eith
15a80 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  er [SQLITE_ENABL
15a90 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 20 5b 53  E_MEMSYS3] or [S
15aa0 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d  QLITE_ENABLE_MEM
15ab0 53 59 53 35 5d 20 61 6e 64 20 72 65 74 75 72 6e  SYS5] and return
15ac0 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52  s.** [SQLITE_ERR
15ad0 4f 52 5d 20 69 66 20 69 6e 76 6f 6b 65 64 20 6f  OR] if invoked o
15ae0 74 68 65 72 77 69 73 65 2e 0a 2a 2a 20 5e 54 68  therwise..** ^Th
15af0 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72  ere are three ar
15b00 67 75 6d 65 6e 74 73 20 74 6f 20 53 51 4c 49 54  guments to SQLIT
15b10 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3a 0a 2a  E_CONFIG_HEAP:.*
15b20 2a 20 41 6e 20 38 2d 62 79 74 65 20 61 6c 69 67  * An 8-byte alig
15b30 6e 65 64 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  ned pointer to t
15b40 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68  he memory,.** th
15b50 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
15b60 73 20 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20  s in the memory 
15b70 62 75 66 66 65 72 2c 20 61 6e 64 20 74 68 65 20  buffer, and the 
15b80 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69  minimum allocati
15b90 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20  on size..** ^If 
15ba0 74 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65  the first pointe
15bb0 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f  r (the memory po
15bc0 69 6e 74 65 72 29 20 69 73 20 4e 55 4c 4c 2c 20  inter) is NULL, 
15bd0 74 68 65 6e 20 53 51 4c 69 74 65 20 72 65 76 65  then SQLite reve
15be0 72 74 73 0a 2a 2a 20 74 6f 20 75 73 69 6e 67 20  rts.** to using 
15bf0 69 74 73 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f  its default memo
15c00 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 28 74 68  ry allocator (th
15c10 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28  e system malloc(
15c20 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  ) implementation
15c30 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20 61 6e  ),.** undoing an
15c40 79 20 70 72 69 6f 72 20 69 6e 76 6f 63 61 74 69  y prior invocati
15c50 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f 43 4f  on of [SQLITE_CO
15c60 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 5e  NFIG_MALLOC].  ^
15c70 49 66 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79  If the.** memory
15c80 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20   pointer is not 
15c90 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 61 6c  NULL then the al
15ca0 74 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79  ternative memory
15cb0 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 20 69 73  .** allocator is
15cc0 20 65 6e 67 61 67 65 64 20 74 6f 20 68 61 6e 64   engaged to hand
15cd0 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c 69 74 65  le all of SQLite
15ce0 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  s memory allocat
15cf0 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20 54 68  ion needs..** Th
15d00 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20  e first pointer 
15d10 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e  (the memory poin
15d20 74 65 72 29 20 6d 75 73 74 20 62 65 20 61 6c 69  ter) must be ali
15d30 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74  gned to an 8-byt
15d40 65 0a 2a 2a 20 62 6f 75 6e 64 61 72 79 20 6f 72  e.** boundary or
15d50 20 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61   subsequent beha
15d60 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 20 77  vior of SQLite w
15d70 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64  ill be undefined
15d80 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e 69 6d 75 6d  ..** The minimum
15d90 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65   allocation size
15da0 20 69 73 20 63 61 70 70 65 64 20 61 74 20 32 2a   is capped at 2*
15db0 2a 31 32 2e 20 52 65 61 73 6f 6e 61 62 6c 65 20  *12. Reasonable 
15dc0 76 61 6c 75 65 73 0a 2a 2a 20 66 6f 72 20 74 68  values.** for th
15dd0 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61  e minimum alloca
15de0 74 69 6f 6e 20 73 69 7a 65 20 61 72 65 20 32 2a  tion size are 2*
15df0 2a 35 20 74 68 72 6f 75 67 68 20 32 2a 2a 38 2e  *5 through 2**8.
15e00 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
15e10 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45  LITE_CONFIG_MUTE
15e20 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  X]] <dt>SQLITE_C
15e30 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e  ONFIG_MUTEX</dt>
15e40 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53  .** <dd> ^(The S
15e50 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54  QLITE_CONFIG_MUT
15e60 45 58 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  EX option takes 
15e70 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
15e80 74 20 77 68 69 63 68 20 69 73 20 61 0a 2a 2a 20  t which is a.** 
15e90 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
15ea0 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73  stance of the [s
15eb0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
15ec0 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
15ed0 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74  .** The argument
15ee0 20 73 70 65 63 69 66 69 65 73 20 61 6c 74 65 72   specifies alter
15ef0 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c  native low-level
15f00 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20   mutex routines 
15f10 74 6f 20 62 65 20 75 73 65 64 0a 2a 2a 20 69 6e  to be used.** in
15f20 20 70 6c 61 63 65 20 74 68 65 20 6d 75 74 65 78   place the mutex
15f30 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20   routines built 
15f40 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 20  into SQLite.)^  
15f50 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20  ^SQLite makes a 
15f60 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63  copy of.** the c
15f70 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73  ontent of the [s
15f80 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
15f90 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 20  hods] structure 
15fa0 62 65 66 6f 72 65 20 74 68 65 20 63 61 6c 6c 20  before the call 
15fb0 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  to.** [sqlite3_c
15fc0 6f 6e 66 69 67 28 29 5d 20 72 65 74 75 72 6e 73  onfig()] returns
15fd0 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20  . ^If SQLite is 
15fe0 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
15ff0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
16000 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45  EADSAFE | SQLITE
16010 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63  _THREADSAFE=0] c
16020 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
16030 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65  on then.** the e
16040 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73  ntire mutexing s
16050 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74  ubsystem is omit
16060 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69  ted from the bui
16070 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c  ld and hence cal
16080 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ls to.** [sqlite
16090 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68  3_config()] with
160a0 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46   the SQLITE_CONF
160b0 49 47 5f 4d 55 54 45 58 20 63 6f 6e 66 69 67 75  IG_MUTEX configu
160c0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69  ration option wi
160d0 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51  ll.** return [SQ
160e0 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64  LITE_ERROR].</dd
160f0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
16100 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58  _CONFIG_GETMUTEX
16110 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
16120 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 3c 2f 64  NFIG_GETMUTEX</d
16130 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65  t>.** <dd> ^(The
16140 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
16150 45 54 4d 55 54 45 58 20 6f 70 74 69 6f 6e 20 74  ETMUTEX option t
16160 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
16170 67 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20  gument which.** 
16180 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
16190 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
161a0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  he [sqlite3_mute
161b0 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  x_methods] struc
161c0 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73  ture.  The.** [s
161d0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
161e0 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75  hods].** structu
161f0 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74  re is filled wit
16200 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20  h the currently 
16210 64 65 66 69 6e 65 64 20 6d 75 74 65 78 20 72 6f  defined mutex ro
16220 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69  utines.)^.** Thi
16230 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20  s option can be 
16240 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64  used to overload
16250 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74   the default mut
16260 65 78 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  ex allocation.**
16270 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61   routines with a
16280 20 77 72 61 70 70 65 72 20 75 73 65 64 20 74 6f   wrapper used to
16290 20 74 72 61 63 6b 20 6d 75 74 65 78 20 75 73 61   track mutex usa
162a0 67 65 20 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e  ge for performan
162b0 63 65 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20  ce.** profiling 
162c0 6f 72 20 74 65 73 74 69 6e 67 2c 20 66 6f 72 20  or testing, for 
162d0 65 78 61 6d 70 6c 65 2e 20 20 20 5e 49 66 20 53  example.   ^If S
162e0 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
162f0 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53  d with.** the [S
16300 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
16310 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44   | SQLITE_THREAD
16320 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d  SAFE=0] compile-
16330 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e  time option then
16340 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d  .** the entire m
16350 75 74 65 78 69 6e 67 20 73 75 62 73 79 73 74 65  utexing subsyste
16360 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f  m is omitted fro
16370 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20  m the build and 
16380 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a  hence calls to.*
16390 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
163a0 67 28 29 5d 20 77 69 74 68 20 74 68 65 20 53 51  g()] with the SQ
163b0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
163c0 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69  UTEX configurati
163d0 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a  on option will.*
163e0 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  * return [SQLITE
163f0 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a  _ERROR].</dd>.**
16400 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
16410 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 5d 20  FIG_LOOKASIDE]] 
16420 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
16430 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e  G_LOOKASIDE</dt>
16440 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53  .** <dd> ^(The S
16450 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f  QLITE_CONFIG_LOO
16460 4b 41 53 49 44 45 20 6f 70 74 69 6f 6e 20 74 61  KASIDE option ta
16470 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74  kes two argument
16480 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65  s that determine
16490 0a 2a 2a 20 74 68 65 20 64 65 66 61 75 6c 74 20  .** the default 
164a0 73 69 7a 65 20 6f 66 20 6c 6f 6f 6b 61 73 69 64  size of lookasid
164b0 65 20 6d 65 6d 6f 72 79 20 6f 6e 20 65 61 63 68  e memory on each
164c0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
164d0 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 68 65 20 66  ction]..** The f
164e0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73  irst argument is
164f0 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20   the.** size of 
16500 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62  each lookaside b
16510 75 66 66 65 72 20 73 6c 6f 74 20 61 6e 64 20 74  uffer slot and t
16520 68 65 20 73 65 63 6f 6e 64 20 69 73 20 74 68 65  he second is the
16530 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c   number of.** sl
16540 6f 74 73 20 61 6c 6c 6f 63 61 74 65 64 20 74 6f  ots allocated to
16550 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63   each database c
16560 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20 20 5e 28  onnection.)^  ^(
16570 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
16580 4f 4b 41 53 49 44 45 0a 2a 2a 20 73 65 74 73 20  OKASIDE.** sets 
16590 74 68 65 20 3c 69 3e 64 65 66 61 75 6c 74 3c 2f  the <i>default</
165a0 69 3e 20 6c 6f 6f 6b 61 73 69 64 65 20 73 69 7a  i> lookaside siz
165b0 65 2e 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 44  e. The [SQLITE_D
165c0 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
165d0 45 5d 0a 2a 2a 20 6f 70 74 69 6f 6e 20 74 6f 20  E].** option to 
165e0 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
165f0 69 67 28 29 5d 20 63 61 6e 20 62 65 20 75 73 65  ig()] can be use
16600 64 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20  d to change the 
16610 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 63 6f 6e  lookaside.** con
16620 66 69 67 75 72 61 74 69 6f 6e 20 6f 6e 20 69 6e  figuration on in
16630 64 69 76 69 64 75 61 6c 20 63 6f 6e 6e 65 63 74  dividual connect
16640 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a  ions.)^ </dd>.**
16650 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
16660 46 49 47 5f 50 43 41 43 48 45 32 5d 5d 20 3c 64  FIG_PCACHE2]] <d
16670 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
16680 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20  PCACHE2</dt>.** 
16690 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54  <dd> ^(The SQLIT
166a0 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32  E_CONFIG_PCACHE2
166b0 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
166c0 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
166d0 77 68 69 63 68 20 69 73 20 0a 2a 2a 20 61 20 70  which is .** a p
166e0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 5b 73 71  ointer to an [sq
166f0 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74  lite3_pcache_met
16700 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20  hods2] object.  
16710 54 68 69 73 20 6f 62 6a 65 63 74 20 73 70 65 63  This object spec
16720 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 69 6e 74  ifies.** the int
16730 65 72 66 61 63 65 20 74 6f 20 61 20 63 75 73 74  erface to a cust
16740 6f 6d 20 70 61 67 65 20 63 61 63 68 65 20 69 6d  om page cache im
16750 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 29 5e 0a  plementation.)^.
16760 2a 2a 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73  ** ^SQLite makes
16770 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b   a copy of the [
16780 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d  sqlite3_pcache_m
16790 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e  ethods2] object.
167a0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
167b0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
167c0 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c  CACHE2]] <dt>SQL
167d0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
167e0 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ACHE2</dt>.** <d
167f0 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f  d> ^(The SQLITE_
16800 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
16810 32 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  2 option takes a
16820 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
16830 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70   which.** is a p
16840 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 5b 73 71  ointer to an [sq
16850 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74  lite3_pcache_met
16860 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20  hods2] object.  
16870 53 51 4c 69 74 65 20 63 6f 70 69 65 73 20 6f 66  SQLite copies of
16880 0a 2a 2a 20 74 68 65 20 63 75 72 72 65 6e 74 20  .** the current 
16890 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65  page cache imple
168a0 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74 6f 20 74  mentation into t
168b0 68 61 74 20 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f  hat object.)^ </
168c0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
168d0 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 5d 5d 20  TE_CONFIG_LOG]] 
168e0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
168f0 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  G_LOG</dt>.** <d
16900 64 3e 20 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  d> The SQLITE_CO
16910 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20  NFIG_LOG option 
16920 69 73 20 75 73 65 64 20 74 6f 20 63 6f 6e 66 69  is used to confi
16930 67 75 72 65 20 74 68 65 20 53 51 4c 69 74 65 0a  gure the SQLite.
16940 2a 2a 20 67 6c 6f 62 61 6c 20 5b 65 72 72 6f 72  ** global [error
16950 20 6c 6f 67 5d 2e 0a 2a 2a 20 28 5e 54 68 65 20   log]..** (^The 
16960 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
16970 47 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74  G option takes t
16980 77 6f 20 61 72 67 75 6d 65 6e 74 73 3a 20 61 20  wo arguments: a 
16990 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a 2a 2a 20  pointer to a.** 
169a0 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20  function with a 
169b0 63 61 6c 6c 20 73 69 67 6e 61 74 75 72 65 20 6f  call signature o
169c0 66 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c  f void(*)(void*,
169d0 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29  int,const char*)
169e0 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 70 6f 69 6e  , .** and a poin
169f0 74 65 72 20 74 6f 20 76 6f 69 64 2e 20 5e 49 66  ter to void. ^If
16a00 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f   the function po
16a10 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c  inter is not NUL
16a20 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 69 6e 76 6f  L, it is.** invo
16a30 6b 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ked by [sqlite3_
16a40 6c 6f 67 28 29 5d 20 74 6f 20 70 72 6f 63 65 73  log()] to proces
16a50 73 20 65 61 63 68 20 6c 6f 67 67 69 6e 67 20 65  s each logging e
16a60 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a  vent.  ^If the.*
16a70 2a 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74  * function point
16a80 65 72 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 20  er is NULL, the 
16a90 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20  [sqlite3_log()] 
16aa0 69 6e 74 65 72 66 61 63 65 20 62 65 63 6f 6d 65  interface become
16ab0 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54  s a no-op..** ^T
16ac0 68 65 20 76 6f 69 64 20 70 6f 69 6e 74 65 72 20  he void pointer 
16ad0 74 68 61 74 20 69 73 20 74 68 65 20 73 65 63 6f  that is the seco
16ae0 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 53  nd argument to S
16af0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47  QLITE_CONFIG_LOG
16b00 20 69 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 68   is.** passed th
16b10 72 6f 75 67 68 20 61 73 20 74 68 65 20 66 69 72  rough as the fir
16b20 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
16b30 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
16b40 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a  defined logger.*
16b50 2a 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 6e 65  * function whene
16b60 76 65 72 20 74 68 61 74 20 66 75 6e 63 74 69 6f  ver that functio
16b70 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e  n is invoked.  ^
16b80 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
16b90 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 6c  eter to.** the l
16ba0 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 20 69  ogger function i
16bb0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
16bc0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
16bd0 74 6f 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  to the correspon
16be0 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ding.** [sqlite3
16bf0 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c 20 61 6e 64  _log()] call and
16c00 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20   is intended to 
16c10 62 65 20 61 20 5b 72 65 73 75 6c 74 20 63 6f 64  be a [result cod
16c20 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 78 74  e] or an.** [ext
16c30 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
16c40 65 5d 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20  e].  ^The third 
16c50 70 61 72 61 6d 65 74 65 72 20 70 61 73 73 65 64  parameter passed
16c60 20 74 6f 20 74 68 65 20 6c 6f 67 67 65 72 20 69   to the logger i
16c70 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73 61 67 65  s.** log message
16c80 20 61 66 74 65 72 20 66 6f 72 6d 61 74 74 69 6e   after formattin
16c90 67 20 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 73  g via [sqlite3_s
16ca0 6e 70 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a 20 54  nprintf()]..** T
16cb0 68 65 20 53 51 4c 69 74 65 20 6c 6f 67 67 69 6e  he SQLite loggin
16cc0 67 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e  g interface is n
16cd0 6f 74 20 72 65 65 6e 74 72 61 6e 74 3b 20 74 68  ot reentrant; th
16ce0 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f  e logger functio
16cf0 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20 62 79  n.** supplied by
16d00 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
16d10 20 6d 75 73 74 20 6e 6f 74 20 69 6e 76 6f 6b 65   must not invoke
16d20 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65   any SQLite inte
16d30 72 66 61 63 65 2e 0a 2a 2a 20 49 6e 20 61 20 6d  rface..** In a m
16d40 75 6c 74 69 2d 74 68 72 65 61 64 65 64 20 61 70  ulti-threaded ap
16d50 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65 20 61  plication, the a
16d60 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
16d70 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e  ed logger.** fun
16d80 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 74 68  ction must be th
16d90 72 65 61 64 73 61 66 65 2e 20 3c 2f 64 64 3e 0a  readsafe. </dd>.
16da0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
16db0 4f 4e 46 49 47 5f 55 52 49 5d 5d 20 3c 64 74 3e  ONFIG_URI]] <dt>
16dc0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52  SQLITE_CONFIG_UR
16dd0 49 0a 2a 2a 20 3c 64 64 3e 5e 28 54 68 65 20 53  I.** <dd>^(The S
16de0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49  QLITE_CONFIG_URI
16df0 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
16e00 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
16e10 6f 66 20 74 79 70 65 20 69 6e 74 2e 0a 2a 2a 20  of type int..** 
16e20 49 66 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  If non-zero, the
16e30 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69  n URI handling i
16e40 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c  s globally enabl
16e50 65 64 2e 20 49 66 20 74 68 65 20 70 61 72 61 6d  ed. If the param
16e60 65 74 65 72 20 69 73 20 7a 65 72 6f 2c 0a 2a 2a  eter is zero,.**
16e70 20 74 68 65 6e 20 55 52 49 20 68 61 6e 64 6c 69   then URI handli
16e80 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64  ng is globally d
16e90 69 73 61 62 6c 65 64 2e 29 5e 20 5e 49 66 20 55  isabled.)^ ^If U
16ea0 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67  RI handling is g
16eb0 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 65 6e 61 62 6c  lobally.** enabl
16ec0 65 64 2c 20 61 6c 6c 20 66 69 6c 65 6e 61 6d 65  ed, all filename
16ed0 73 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c  s passed to [sql
16ee0 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
16ef0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
16f00 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f  ],.** [sqlite3_o
16f10 70 65 6e 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 73  pen16()] or.** s
16f20 70 65 63 69 66 69 65 64 20 61 73 20 70 61 72 74  pecified as part
16f30 20 6f 66 20 5b 41 54 54 41 43 48 5d 20 63 6f 6d   of [ATTACH] com
16f40 6d 61 6e 64 73 20 61 72 65 20 69 6e 74 65 72 70  mands are interp
16f50 72 65 74 65 64 20 61 73 20 55 52 49 73 2c 20 72  reted as URIs, r
16f60 65 67 61 72 64 6c 65 73 73 0a 2a 2a 20 6f 66 20  egardless.** of 
16f70 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
16f80 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
16f90 55 52 49 5d 20 66 6c 61 67 20 69 73 20 73 65 74  URI] flag is set
16fa0 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   when the databa
16fb0 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
16fc0 20 69 73 20 6f 70 65 6e 65 64 2e 20 5e 49 66 20   is opened. ^If 
16fd0 69 74 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64  it is globally d
16fe0 69 73 61 62 6c 65 64 2c 20 66 69 6c 65 6e 61 6d  isabled, filenam
16ff0 65 73 20 61 72 65 0a 2a 2a 20 6f 6e 6c 79 20 69  es are.** only i
17000 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55 52  nterpreted as UR
17010 49 73 20 69 66 20 74 68 65 20 53 51 4c 49 54 45  Is if the SQLITE
17020 5f 4f 50 45 4e 5f 55 52 49 20 66 6c 61 67 20 69  _OPEN_URI flag i
17030 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 0a 2a  s set when the.*
17040 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
17050 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e  ction is opened.
17060 20 5e 28 42 79 20 64 65 66 61 75 6c 74 2c 20 55   ^(By default, U
17070 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67  RI handling is g
17080 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 64 69 73 61 62  lobally.** disab
17090 6c 65 64 2e 20 54 68 65 20 64 65 66 61 75 6c 74  led. The default
170a0 20 76 61 6c 75 65 20 6d 61 79 20 62 65 20 63 68   value may be ch
170b0 61 6e 67 65 64 20 62 79 20 63 6f 6d 70 69 6c 69  anged by compili
170c0 6e 67 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b  ng with the.** [
170d0 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20  SQLITE_USE_URI] 
170e0 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 29  symbol defined.)
170f0 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
17100 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47  _CONFIG_COVERING
17110 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 5d 20 3c 64  _INDEX_SCAN]] <d
17120 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
17130 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53  COVERING_INDEX_S
17140 43 41 4e 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20  CAN.** <dd>^The 
17150 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f  SQLITE_CONFIG_CO
17160 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41  VERING_INDEX_SCA
17170 4e 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  N option takes a
17180 20 73 69 6e 67 6c 65 20 69 6e 74 65 67 65 72 0a   single integer.
17190 2a 2a 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  ** argument whic
171a0 68 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64  h is interpreted
171b0 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e   as a boolean in
171c0 20 6f 72 64 65 72 20 74 6f 20 65 6e 61 62 6c 65   order to enable
171d0 20 6f 72 20 64 69 73 61 62 6c 65 0a 2a 2a 20 74   or disable.** t
171e0 68 65 20 75 73 65 20 6f 66 20 63 6f 76 65 72 69  he use of coveri
171f0 6e 67 20 69 6e 64 69 63 65 73 20 66 6f 72 20 66  ng indices for f
17200 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e 73 20  ull table scans 
17210 69 6e 20 74 68 65 20 71 75 65 72 79 20 6f 70 74  in the query opt
17220 69 6d 69 7a 65 72 2e 0a 2a 2a 20 5e 54 68 65 20  imizer..** ^The 
17230 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20  default setting 
17240 69 73 20 64 65 74 65 72 6d 69 6e 65 64 0a 2a 2a  is determined.**
17250 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   by the [SQLITE_
17260 41 4c 4c 4f 57 5f 43 4f 56 45 52 49 4e 47 5f 49  ALLOW_COVERING_I
17270 4e 44 45 58 5f 53 43 41 4e 5d 20 63 6f 6d 70 69  NDEX_SCAN] compi
17280 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20  le-time option, 
17290 6f 72 20 69 73 20 22 6f 6e 22 0a 2a 2a 20 69 66  or is "on".** if
172a0 20 74 68 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69   that compile-ti
172b0 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6d 69  me option is omi
172c0 74 74 65 64 2e 0a 2a 2a 20 54 68 65 20 61 62 69  tted..** The abi
172d0 6c 69 74 79 20 74 6f 20 64 69 73 61 62 6c 65 20  lity to disable 
172e0 74 68 65 20 75 73 65 20 6f 66 20 63 6f 76 65 72  the use of cover
172f0 69 6e 67 20 69 6e 64 69 63 65 73 20 66 6f 72 20  ing indices for 
17300 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e 73  full table scans
17310 0a 2a 2a 20 69 73 20 62 65 63 61 75 73 65 20 73  .** is because s
17320 6f 6d 65 20 69 6e 63 6f 72 72 65 63 74 6c 79 20  ome incorrectly 
17330 63 6f 64 65 64 20 6c 65 67 61 63 79 20 61 70 70  coded legacy app
17340 6c 69 63 61 74 69 6f 6e 73 20 6d 69 67 68 74 20  lications might 
17350 6d 61 6c 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77  malfunction.** w
17360 68 65 6e 20 74 68 65 20 6f 70 74 69 6d 69 7a 61  hen the optimiza
17370 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e  tion is enabled.
17380 20 20 50 72 6f 76 69 64 69 6e 67 20 74 68 65 20    Providing the 
17390 61 62 69 6c 69 74 79 20 74 6f 0a 2a 2a 20 64 69  ability to.** di
173a0 73 61 62 6c 65 20 74 68 65 20 6f 70 74 69 6d 69  sable the optimi
173b0 7a 61 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 74 68  zation allows th
173c0 65 20 6f 6c 64 65 72 2c 20 62 75 67 67 79 20 61  e older, buggy a
173d0 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20  pplication code 
173e0 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69 74 68 6f  to work.** witho
173f0 75 74 20 63 68 61 6e 67 65 20 65 76 65 6e 20 77  ut change even w
17400 69 74 68 20 6e 65 77 65 72 20 76 65 72 73 69 6f  ith newer versio
17410 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  ns of SQLite..**
17420 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
17430 46 49 47 5f 50 43 41 43 48 45 5d 5d 20 5b 5b 53  FIG_PCACHE]] [[S
17440 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
17450 50 43 41 43 48 45 5d 5d 0a 2a 2a 20 3c 64 74 3e  PCACHE]].** <dt>
17460 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
17470 41 43 48 45 20 61 6e 64 20 53 51 4c 49 54 45 5f  ACHE and SQLITE_
17480 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
17490 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 73 65 20 6f  .** <dd> These o
174a0 70 74 69 6f 6e 73 20 61 72 65 20 6f 62 73 6f 6c  ptions are obsol
174b0 65 74 65 20 61 6e 64 20 73 68 6f 75 6c 64 20 6e  ete and should n
174c0 6f 74 20 62 65 20 75 73 65 64 20 62 79 20 6e 65  ot be used by ne
174d0 77 20 63 6f 64 65 2e 0a 2a 2a 20 54 68 65 79 20  w code..** They 
174e0 61 72 65 20 72 65 74 61 69 6e 65 64 20 66 6f 72  are retained for
174f0 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
17500 74 69 62 69 6c 69 74 79 20 62 75 74 20 61 72 65  tibility but are
17510 20 6e 6f 77 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20   now no-ops..** 
17520 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
17530 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c  LITE_CONFIG_SQLL
17540 4f 47 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  OG]].** <dt>SQLI
17550 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47  TE_CONFIG_SQLLOG
17560 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74  .** <dd>This opt
17570 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69  ion is only avai
17580 6c 61 62 6c 65 20 69 66 20 73 71 6c 69 74 65 20  lable if sqlite 
17590 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
175a0 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
175b0 45 4e 41 42 4c 45 5f 53 51 4c 4c 4f 47 5d 20 70  ENABLE_SQLLOG] p
175c0 72 65 2d 70 72 6f 63 65 73 73 6f 72 20 6d 61 63  re-processor mac
175d0 72 6f 20 64 65 66 69 6e 65 64 2e 20 54 68 65 20  ro defined. The 
175e0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 73  first argument s
175f0 68 6f 75 6c 64 0a 2a 2a 20 62 65 20 61 20 70 6f  hould.** be a po
17600 69 6e 74 65 72 20 74 6f 20 61 20 66 75 6e 63 74  inter to a funct
17610 69 6f 6e 20 6f 66 20 74 79 70 65 20 76 6f 69 64  ion of type void
17620 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65  (*)(void*,sqlite
17630 33 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  3*,const char*, 
17640 69 6e 74 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63  int)..** The sec
17650 6f 6e 64 20 73 68 6f 75 6c 64 20 62 65 20 6f 66  ond should be of
17660 20 74 79 70 65 20 28 76 6f 69 64 2a 29 2e 20 54   type (void*). T
17670 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  he callback is i
17680 6e 76 6f 6b 65 64 20 62 79 20 74 68 65 20 6c 69  nvoked by the li
17690 62 72 61 72 79 0a 2a 2a 20 69 6e 20 74 68 72 65  brary.** in thre
176a0 65 20 73 65 70 61 72 61 74 65 20 63 69 72 63 75  e separate circu
176b0 6d 73 74 61 6e 63 65 73 2c 20 69 64 65 6e 74 69  mstances, identi
176c0 66 69 65 64 20 62 79 20 74 68 65 20 76 61 6c 75  fied by the valu
176d0 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 0a  e passed as the.
176e0 2a 2a 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  ** fourth parame
176f0 74 65 72 2e 20 49 66 20 74 68 65 20 66 6f 75 72  ter. If the four
17700 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
17710 30 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  0, then the data
17720 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
17730 2a 2a 20 70 61 73 73 65 64 20 61 73 20 74 68 65  ** passed as the
17740 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
17750 20 68 61 73 20 6a 75 73 74 20 62 65 65 6e 20 6f   has just been o
17760 70 65 6e 65 64 2e 20 54 68 65 20 74 68 69 72 64  pened. The third
17770 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 70 6f 69   argument.** poi
17780 6e 74 73 20 74 6f 20 61 20 62 75 66 66 65 72 20  nts to a buffer 
17790 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e  containing the n
177a0 61 6d 65 20 6f 66 20 74 68 65 20 6d 61 69 6e 20  ame of the main 
177b0 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 20 49  database file. I
177c0 66 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20  f the.** fourth 
177d0 70 61 72 61 6d 65 74 65 72 20 69 73 20 31 2c 20  parameter is 1, 
177e0 74 68 65 6e 20 74 68 65 20 53 51 4c 20 73 74 61  then the SQL sta
177f0 74 65 6d 65 6e 74 20 74 68 61 74 20 74 68 65 20  tement that the 
17800 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 0a  third parameter.
17810 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20 68 61 73  ** points to has
17820 20 6a 75 73 74 20 62 65 65 6e 20 65 78 65 63 75   just been execu
17830 74 65 64 2e 20 4f 72 2c 20 69 66 20 74 68 65 20  ted. Or, if the 
17840 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
17850 20 69 73 20 32 2c 20 74 68 65 6e 0a 2a 2a 20 74   is 2, then.** t
17860 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 65  he connection be
17870 69 6e 67 20 70 61 73 73 65 64 20 61 73 20 74 68  ing passed as th
17880 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
17890 65 72 20 69 73 20 62 65 69 6e 67 20 63 6c 6f 73  er is being clos
178a0 65 64 2e 20 54 68 65 0a 2a 2a 20 74 68 69 72 64  ed. The.** third
178b0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 61   parameter is pa
178c0 73 73 65 64 20 4e 55 4c 4c 20 49 6e 20 74 68 69  ssed NULL In thi
178d0 73 20 63 61 73 65 2e 20 20 41 6e 20 65 78 61 6d  s case.  An exam
178e0 70 6c 65 20 6f 66 20 75 73 69 6e 67 20 74 68 69  ple of using thi
178f0 73 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69  s.** configurati
17900 6f 6e 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65  on option can be
17910 20 73 65 65 6e 20 69 6e 20 74 68 65 20 22 74 65   seen in the "te
17920 73 74 5f 73 71 6c 6c 6f 67 2e 63 22 20 73 6f 75  st_sqllog.c" sou
17930 72 63 65 20 66 69 6c 65 20 69 6e 0a 2a 2a 20 74  rce file in.** t
17940 68 65 20 63 61 6e 6f 6e 69 63 61 6c 20 53 51 4c  he canonical SQL
17950 69 74 65 20 73 6f 75 72 63 65 20 74 72 65 65 2e  ite source tree.
17960 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
17970 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50  LITE_CONFIG_MMAP
17980 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53  _SIZE]].** <dt>S
17990 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41  QLITE_CONFIG_MMA
179a0 50 5f 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 53  P_SIZE.** <dd>^S
179b0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41  QLITE_CONFIG_MMA
179c0 50 5f 53 49 5a 45 20 74 61 6b 65 73 20 74 77 6f  P_SIZE takes two
179d0 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20   64-bit integer 
179e0 28 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 20  (sqlite3_int64) 
179f0 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 61  values.** that a
17a00 72 65 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d  re the default m
17a10 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69 74 20 28  map size limit (
17a20 74 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74  the default sett
17a30 69 6e 67 20 66 6f 72 0a 2a 2a 20 5b 50 52 41 47  ing for.** [PRAG
17a40 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 29 20 61  MA mmap_size]) a
17a50 6e 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 61  nd the maximum a
17a60 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a 65  llowed mmap size
17a70 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 54 68 65 20   limit..** ^The 
17a80 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20  default setting 
17a90 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64 65  can be overridde
17aa0 6e 20 62 79 20 65 61 63 68 20 64 61 74 61 62 61  n by each databa
17ab0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 75 73  se connection us
17ac0 69 6e 67 0a 2a 2a 20 65 69 74 68 65 72 20 74 68  ing.** either th
17ad0 65 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73  e [PRAGMA mmap_s
17ae0 69 7a 65 5d 20 63 6f 6d 6d 61 6e 64 2c 20 6f 72  ize] command, or
17af0 20 62 79 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a   by using the.**
17b00 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d   [SQLITE_FCNTL_M
17b10 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c 65 20 63  MAP_SIZE] file c
17b20 6f 6e 74 72 6f 6c 2e 20 20 5e 28 54 68 65 20 6d  ontrol.  ^(The m
17b30 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d  aximum allowed m
17b40 6d 61 70 20 73 69 7a 65 0a 2a 2a 20 77 69 6c 6c  map size.** will
17b50 20 62 65 20 73 69 6c 65 6e 74 6c 79 20 74 72 75   be silently tru
17b60 6e 63 61 74 65 64 20 69 66 20 6e 65 63 65 73 73  ncated if necess
17b70 61 72 79 20 73 6f 20 74 68 61 74 20 69 74 20 64  ary so that it d
17b80 6f 65 73 20 6e 6f 74 20 65 78 63 65 65 64 20 74  oes not exceed t
17b90 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69  he.** compile-ti
17ba0 6d 65 20 6d 61 78 69 6d 75 6d 20 6d 6d 61 70 20  me maximum mmap 
17bb0 73 69 7a 65 20 73 65 74 20 62 79 20 74 68 65 0a  size set by the.
17bc0 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 4d  ** [SQLITE_MAX_M
17bd0 4d 41 50 5f 53 49 5a 45 5d 20 63 6f 6d 70 69 6c  MAP_SIZE] compil
17be0 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 29 5e  e-time option.)^
17bf0 0a 2a 2a 20 5e 49 66 20 65 69 74 68 65 72 20 61  .** ^If either a
17c00 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 69 73 20  rgument to this 
17c10 6f 70 74 69 6f 6e 20 69 73 20 6e 65 67 61 74 69  option is negati
17c20 76 65 2c 20 74 68 65 6e 20 74 68 61 74 20 61 72  ve, then that ar
17c30 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 63 68 61  gument is.** cha
17c40 6e 67 65 64 20 74 6f 20 69 74 73 20 63 6f 6d 70  nged to its comp
17c50 69 6c 65 2d 74 69 6d 65 20 64 65 66 61 75 6c 74  ile-time default
17c60 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ..**.** [[SQLITE
17c70 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45  _CONFIG_WIN32_HE
17c80 41 50 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e  APSIZE]].** <dt>
17c90 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49  SQLITE_CONFIG_WI
17ca0 4e 33 32 5f 48 45 41 50 53 49 5a 45 0a 2a 2a 20  N32_HEAPSIZE.** 
17cb0 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f  <dd>^The SQLITE_
17cc0 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41  CONFIG_WIN32_HEA
17cd0 50 53 49 5a 45 20 6f 70 74 69 6f 6e 20 69 73 20  PSIZE option is 
17ce0 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69  only available i
17cf0 66 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63  f SQLite is.** c
17d00 6f 6d 70 69 6c 65 64 20 66 6f 72 20 57 69 6e 64  ompiled for Wind
17d10 6f 77 73 20 77 69 74 68 20 74 68 65 20 5b 53 51  ows with the [SQ
17d20 4c 49 54 45 5f 57 49 4e 33 32 5f 4d 41 4c 4c 4f  LITE_WIN32_MALLO
17d30 43 5d 20 70 72 65 2d 70 72 6f 63 65 73 73 6f 72  C] pre-processor
17d40 20 6d 61 63 72 6f 0a 2a 2a 20 64 65 66 69 6e 65   macro.** define
17d50 64 2e 20 5e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  d. ^SQLITE_CONFI
17d60 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45  G_WIN32_HEAPSIZE
17d70 20 74 61 6b 65 73 20 61 20 33 32 2d 62 69 74 20   takes a 32-bit 
17d80 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  unsigned integer
17d90 20 76 61 6c 75 65 0a 2a 2a 20 74 68 61 74 20 73   value.** that s
17da0 70 65 63 69 66 69 65 73 20 74 68 65 20 6d 61 78  pecifies the max
17db0 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 74 68 65  imum size of the
17dc0 20 63 72 65 61 74 65 64 20 68 65 61 70 2e 0a 2a   created heap..*
17dd0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
17de0 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53  NFIG_PCACHE_HDRS
17df0 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  Z]].** <dt>SQLIT
17e00 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f  E_CONFIG_PCACHE_
17e10 48 44 52 53 5a 0a 2a 2a 20 3c 64 64 3e 5e 54 68  HDRSZ.** <dd>^Th
17e20 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
17e30 50 43 41 43 48 45 5f 48 44 52 53 5a 20 6f 70 74  PCACHE_HDRSZ opt
17e40 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
17e50 6c 65 20 70 61 72 61 6d 65 74 65 72 20 77 68 69  le parameter whi
17e60 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74  ch.** is a point
17e70 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  er to an integer
17e80 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e 74 6f   and writes into
17e90 20 74 68 61 74 20 69 6e 74 65 67 65 72 20 74 68   that integer th
17ea0 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 72  e number of extr
17eb0 61 0a 2a 2a 20 62 79 74 65 73 20 70 65 72 20 70  a.** bytes per p
17ec0 61 67 65 20 72 65 71 75 69 72 65 64 20 66 6f 72  age required for
17ed0 20 65 61 63 68 20 70 61 67 65 20 69 6e 20 5b 53   each page in [S
17ee0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
17ef0 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 20  ECACHE]..** The 
17f00 61 6d 6f 75 6e 74 20 6f 66 20 65 78 74 72 61 20  amount of extra 
17f10 73 70 61 63 65 20 72 65 71 75 69 72 65 64 20 63  space required c
17f20 61 6e 20 63 68 61 6e 67 65 20 64 65 70 65 6e 64  an change depend
17f30 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69  ing on the compi
17f40 6c 65 72 2c 0a 2a 2a 20 74 61 72 67 65 74 20 70  ler,.** target p
17f50 6c 61 74 66 6f 72 6d 2c 20 61 6e 64 20 53 51 4c  latform, and SQL
17f60 69 74 65 20 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a  ite version..**.
17f70 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
17f80 49 47 5f 50 4d 41 53 5a 5d 5d 0a 2a 2a 20 3c 64  IG_PMASZ]].** <d
17f90 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
17fa0 50 4d 41 53 5a 0a 2a 2a 20 3c 64 64 3e 5e 54 68  PMASZ.** <dd>^Th
17fb0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
17fc0 50 4d 41 53 5a 20 6f 70 74 69 6f 6e 20 74 61 6b  PMASZ option tak
17fd0 65 73 20 61 20 73 69 6e 67 6c 65 20 70 61 72 61  es a single para
17fe0 6d 65 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69  meter which.** i
17ff0 73 20 61 6e 20 75 6e 73 69 67 6e 65 64 20 69 6e  s an unsigned in
18000 74 65 67 65 72 20 61 6e 64 20 73 65 74 73 20 74  teger and sets t
18010 68 65 20 22 4d 69 6e 69 6d 75 6d 20 50 4d 41 20  he "Minimum PMA 
18020 53 69 7a 65 22 20 66 6f 72 20 74 68 65 20 6d 75  Size" for the mu
18030 6c 74 69 74 68 72 65 61 64 65 64 0a 2a 2a 20 73  ltithreaded.** s
18040 6f 72 74 65 72 20 74 6f 20 74 68 61 74 20 69 6e  orter to that in
18050 74 65 67 65 72 2e 20 20 54 68 65 20 64 65 66 61  teger.  The defa
18060 75 6c 74 20 6d 69 6e 69 6d 75 6d 20 50 4d 41 20  ult minimum PMA 
18070 53 69 7a 65 20 69 73 20 73 65 74 20 62 79 20 74  Size is set by t
18080 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 4f  he.** [SQLITE_SO
18090 52 54 45 52 5f 50 4d 41 53 5a 5d 20 63 6f 6d 70  RTER_PMASZ] comp
180a0 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e  ile-time option.
180b0 20 20 4e 65 77 20 74 68 72 65 61 64 73 20 61 72    New threads ar
180c0 65 20 6c 61 75 6e 63 68 65 64 0a 2a 2a 20 74 6f  e launched.** to
180d0 20 68 65 6c 70 20 77 69 74 68 20 73 6f 72 74 20   help with sort 
180e0 6f 70 65 72 61 74 69 6f 6e 73 20 77 68 65 6e 20  operations when 
180f0 6d 75 6c 74 69 74 68 72 65 61 64 65 64 20 73 6f  multithreaded so
18100 72 74 69 6e 67 0a 2a 2a 20 69 73 20 65 6e 61 62  rting.** is enab
18110 6c 65 64 20 28 75 73 69 6e 67 20 74 68 65 20 5b  led (using the [
18120 50 52 41 47 4d 41 20 74 68 72 65 61 64 73 5d 20  PRAGMA threads] 
18130 63 6f 6d 6d 61 6e 64 29 20 61 6e 64 20 74 68 65  command) and the
18140 20 61 6d 6f 75 6e 74 20 6f 66 20 63 6f 6e 74 65   amount of conte
18150 6e 74 0a 2a 2a 20 74 6f 20 62 65 20 73 6f 72 74  nt.** to be sort
18160 65 64 20 65 78 63 65 65 64 73 20 74 68 65 20 70  ed exceeds the p
18170 61 67 65 20 73 69 7a 65 20 74 69 6d 65 73 20 74  age size times t
18180 68 65 20 6d 69 6e 69 6d 75 6d 20 6f 66 20 74 68  he minimum of th
18190 65 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 63 61 63  e.** [PRAGMA cac
181a0 68 65 5f 73 69 7a 65 5d 20 73 65 74 74 69 6e 67  he_size] setting
181b0 20 61 6e 64 20 74 68 69 73 20 76 61 6c 75 65 2e   and this value.
181c0 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65  .** </dl>.*/.#de
181d0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
181e0 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20  IG_SINGLETHREAD 
181f0 20 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64   1  /* nil */.#d
18200 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
18210 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20  FIG_MULTITHREAD 
18220 20 20 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23    2  /* nil */.#
18230 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
18240 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20  NFIG_SERIALIZED 
18250 20 20 20 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a     3  /* nil */.
18260 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
18270 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 20 20 20  ONFIG_MALLOC    
18280 20 20 20 20 34 20 20 2f 2a 20 73 71 6c 69 74 65      4  /* sqlite
18290 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a  3_mem_methods* *
182a0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
182b0 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f  _CONFIG_GETMALLO
182c0 43 20 20 20 20 20 35 20 20 2f 2a 20 73 71 6c 69  C     5  /* sqli
182d0 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a  te3_mem_methods*
182e0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
182f0 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43  TE_CONFIG_SCRATC
18300 48 20 20 20 20 20 20 20 36 20 20 2f 2a 20 76 6f  H       6  /* vo
18310 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74  id*, int sz, int
18320 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51   N */.#define SQ
18330 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
18340 43 41 43 48 45 20 20 20 20 20 37 20 20 2f 2a 20  CACHE     7  /* 
18350 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69  void*, int sz, i
18360 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nt N */.#define 
18370 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45  SQLITE_CONFIG_HE
18380 41 50 20 20 20 20 20 20 20 20 20 20 38 20 20 2f  AP          8  /
18390 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 79  * void*, int nBy
183a0 74 65 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23  te, int min */.#
183b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
183c0 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 20  NFIG_MEMSTATUS  
183d0 20 20 20 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e     9  /* boolean
183e0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
183f0 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20  TE_CONFIG_MUTEX 
18400 20 20 20 20 20 20 20 31 30 20 20 2f 2a 20 73 71         10  /* sq
18410 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
18420 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ods* */.#define 
18430 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
18440 54 4d 55 54 45 58 20 20 20 20 20 31 31 20 20 2f  TMUTEX     11  /
18450 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  * sqlite3_mutex_
18460 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70  methods* */./* p
18470 72 65 76 69 6f 75 73 6c 79 20 53 51 4c 49 54 45  reviously SQLITE
18480 5f 43 4f 4e 46 49 47 5f 43 48 55 4e 4b 41 4c 4c  _CONFIG_CHUNKALL
18490 4f 43 20 31 32 20 77 68 69 63 68 20 69 73 20 6e  OC 12 which is n
184a0 6f 77 20 75 6e 75 73 65 64 2e 20 2a 2f 20 0a 23  ow unused. */ .#
184b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
184c0 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20  NFIG_LOOKASIDE  
184d0 20 20 31 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74    13  /* int int
184e0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
184f0 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
18500 20 20 20 20 20 20 20 31 34 20 20 2f 2a 20 6e 6f         14  /* no
18510 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  -op */.#define S
18520 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
18530 50 43 41 43 48 45 20 20 20 20 31 35 20 20 2f 2a  PCACHE    15  /*
18540 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e   no-op */.#defin
18550 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
18560 4c 4f 47 20 20 20 20 20 20 20 20 20 20 31 36 20  LOG          16 
18570 20 2f 2a 20 78 46 75 6e 63 2c 20 76 6f 69 64 2a   /* xFunc, void*
18580 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
18590 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 20 20 20  TE_CONFIG_URI   
185a0 20 20 20 20 20 20 20 31 37 20 20 2f 2a 20 69 6e         17  /* in
185b0 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
185c0 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
185d0 45 32 20 20 20 20 20 20 31 38 20 20 2f 2a 20 73  E2      18  /* s
185e0 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65  qlite3_pcache_me
185f0 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69  thods2* */.#defi
18600 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
18610 5f 47 45 54 50 43 41 43 48 45 32 20 20 20 31 39  _GETPCACHE2   19
18620 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61    /* sqlite3_pca
18630 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f  che_methods2* */
18640 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18650 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f  CONFIG_COVERING_
18660 49 4e 44 45 58 5f 53 43 41 4e 20 32 30 20 20 2f  INDEX_SCAN 20  /
18670 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65  * int */.#define
18680 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
18690 51 4c 4c 4f 47 20 20 20 20 20 20 20 32 31 20 20  QLLOG       21  
186a0 2f 2a 20 78 53 71 6c 6c 6f 67 2c 20 76 6f 69 64  /* xSqllog, void
186b0 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
186c0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f  ITE_CONFIG_MMAP_
186d0 53 49 5a 45 20 20 20 20 32 32 20 20 2f 2a 20 73  SIZE    22  /* s
186e0 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c 20 73 71  qlite3_int64, sq
186f0 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 2f 0a 23  lite3_int64 */.#
18700 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
18710 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53  NFIG_WIN32_HEAPS
18720 49 5a 45 20 20 20 20 20 20 32 33 20 20 2f 2a 20  IZE      23  /* 
18730 69 6e 74 20 6e 42 79 74 65 20 2a 2f 0a 23 64 65  int nByte */.#de
18740 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
18750 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 20  IG_PCACHE_HDRSZ 
18760 20 20 20 20 20 20 20 32 34 20 20 2f 2a 20 69 6e         24  /* in
18770 74 20 2a 70 73 7a 20 2a 2f 0a 23 64 65 66 69 6e  t *psz */.#defin
18780 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
18790 50 4d 41 53 5a 20 20 20 20 20 20 20 20 20 20 20  PMASZ           
187a0 20 20 20 20 32 35 20 20 2f 2a 20 75 6e 73 69 67      25  /* unsig
187b0 6e 65 64 20 69 6e 74 20 73 7a 50 6d 61 20 2a 2f  ned int szPma */
187c0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
187d0 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  : Database Conne
187e0 63 74 69 6f 6e 20 43 6f 6e 66 69 67 75 72 61 74  ction Configurat
187f0 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a  ion Options.**.*
18800 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
18810 73 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61  s are the availa
18820 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66  ble integer conf
18830 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
18840 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65  s that.** can be
18850 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73   passed as the s
18860 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
18870 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64  o the [sqlite3_d
18880 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65  b_config()] inte
18890 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77  rface..**.** New
188a0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
188b0 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64  ptions may be ad
188c0 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
188d0 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
188e0 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f  ..** Existing co
188f0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
18900 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73  ons might be dis
18910 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c  continued.  Appl
18920 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75  ications.** shou
18930 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74  ld check the ret
18940 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73  urn code from [s
18950 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
18960 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65  ()] to make sure
18970 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c   that.** the cal
18980 6c 20 77 6f 72 6b 65 64 2e 20 20 5e 54 68 65 20  l worked.  ^The 
18990 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
189a0 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  ig()] interface 
189b0 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a  will return a.**
189c0 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72   non-zero [error
189d0 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63   code] if a disc
189e0 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75  ontinued or unsu
189f0 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72  pported configur
18a00 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20  ation option.** 
18a10 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a  is invoked..**.*
18a20 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51  * <dl>.** <dt>SQ
18a30 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
18a40 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20  OKASIDE</dt>.** 
18a50 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
18a60 6e 20 74 61 6b 65 73 20 74 68 72 65 65 20 61 64  n takes three ad
18a70 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e  ditional argumen
18a80 74 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e  ts that determin
18a90 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61  e the .** [looka
18aa0 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  side memory allo
18ab0 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61  cator] configura
18ac0 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64 61  tion for the [da
18ad0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
18ae0 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  n]..** ^The firs
18af0 74 20 61 72 67 75 6d 65 6e 74 20 28 74 68 65 20  t argument (the 
18b00 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
18b10 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  to [sqlite3_db_c
18b20 6f 6e 66 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a  onfig()] is a.**
18b30 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65   pointer to a me
18b40 6d 6f 72 79 20 62 75 66 66 65 72 20 74 6f 20 75  mory buffer to u
18b50 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65  se for lookaside
18b60 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65   memory..** ^The
18b70 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
18b80 61 66 74 65 72 20 74 68 65 20 53 51 4c 49 54 45  after the SQLITE
18b90 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
18ba0 49 44 45 20 76 65 72 62 0a 2a 2a 20 6d 61 79 20  IDE verb.** may 
18bb0 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68  be NULL in which
18bc0 20 63 61 73 65 20 53 51 4c 69 74 65 20 77 69 6c   case SQLite wil
18bd0 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a 2a  l allocate the.*
18be0 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66  * lookaside buff
18bf0 65 72 20 69 74 73 65 6c 66 20 75 73 69 6e 67 20  er itself using 
18c00 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
18c10 29 5d 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  )]. ^The second 
18c20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a  argument is the.
18c30 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20  ** size of each 
18c40 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72  lookaside buffer
18c50 20 73 6c 6f 74 2e 20 20 5e 54 68 65 20 74 68 69   slot.  ^The thi
18c60 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  rd argument is t
18c70 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
18c80 73 6c 6f 74 73 2e 20 20 54 68 65 20 73 69 7a 65  slots.  The size
18c90 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 69   of the buffer i
18ca0 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
18cb0 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 67 72 65  ment must be gre
18cc0 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20  ater than.** or 
18cd0 65 71 75 61 6c 20 74 6f 20 74 68 65 20 70 72 6f  equal to the pro
18ce0 64 75 63 74 20 6f 66 20 74 68 65 20 73 65 63 6f  duct of the seco
18cf0 6e 64 20 61 6e 64 20 74 68 69 72 64 20 61 72 67  nd and third arg
18d00 75 6d 65 6e 74 73 2e 20 20 54 68 65 20 62 75 66  uments.  The buf
18d10 66 65 72 0a 2a 2a 20 6d 75 73 74 20 62 65 20 61  fer.** must be a
18d20 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62  ligned to an 8-b
18d30 79 74 65 20 62 6f 75 6e 64 61 72 79 2e 20 20 5e  yte boundary.  ^
18d40 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  If the second ar
18d50 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c  gument to.** SQL
18d60 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
18d70 4b 41 53 49 44 45 20 69 73 20 6e 6f 74 20 61 20  KASIDE is not a 
18d80 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20 69  multiple of 8, i
18d90 74 20 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79 0a  t is internally.
18da0 2a 2a 20 72 6f 75 6e 64 65 64 20 64 6f 77 6e 20  ** rounded down 
18db0 74 6f 20 74 68 65 20 6e 65 78 74 20 73 6d 61 6c  to the next smal
18dc0 6c 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20  ler multiple of 
18dd0 38 2e 20 20 5e 28 54 68 65 20 6c 6f 6f 6b 61 73  8.  ^(The lookas
18de0 69 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f  ide memory.** co
18df0 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20  nfiguration for 
18e00 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  a database conne
18e10 63 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20 62  ction can only b
18e20 65 20 63 68 61 6e 67 65 64 20 77 68 65 6e 20 74  e changed when t
18e30 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  hat.** connectio
18e40 6e 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74  n is not current
18e50 6c 79 20 75 73 69 6e 67 20 6c 6f 6f 6b 61 73 69  ly using lookasi
18e60 64 65 20 6d 65 6d 6f 72 79 2c 20 6f 72 20 69 6e  de memory, or in
18e70 20 6f 74 68 65 72 20 77 6f 72 64 73 0a 2a 2a 20   other words.** 
18e80 77 68 65 6e 20 74 68 65 20 22 63 75 72 72 65 6e  when the "curren
18e90 74 20 76 61 6c 75 65 22 20 72 65 74 75 72 6e 65  t value" returne
18ea0 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  d by.** [sqlite3
18eb0 5f 64 62 5f 73 74 61 74 75 73 5d 28 44 2c 5b 53  _db_status](D,[S
18ec0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f  QLITE_CONFIG_LOO
18ed0 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29 20 69 73 20  KASIDE],...) is 
18ee0 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74 74  zero..** Any att
18ef0 65 6d 70 74 20 74 6f 20 63 68 61 6e 67 65 20 74  empt to change t
18f00 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  he lookaside mem
18f10 6f 72 79 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ory configuratio
18f20 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61 73 69 64 65  n when lookaside
18f30 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69 73 20 69 6e  .** memory is in
18f40 20 75 73 65 20 6c 65 61 76 65 73 20 74 68 65 20   use leaves the 
18f50 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 6e  configuration un
18f60 63 68 61 6e 67 65 64 20 61 6e 64 20 72 65 74 75  changed and retu
18f70 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  rns .** [SQLITE_
18f80 42 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a  BUSY].)^</dd>.**
18f90 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44  .** <dt>SQLITE_D
18fa0 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46  BCONFIG_ENABLE_F
18fb0 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  KEY</dt>.** <dd>
18fc0 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73   ^This option is
18fd0 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20   used to enable 
18fe0 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65 20 65  or disable the e
18ff0 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 66 0a 2a 2a  nforcement of.**
19000 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 63 6f   [foreign key co
19010 6e 73 74 72 61 69 6e 74 73 5d 2e 20 20 54 68 65  nstraints].  The
19020 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f  re should be two
19030 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75   additional argu
19040 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69  ments..** The fi
19050 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20  rst argument is 
19060 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68  an integer which
19070 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65   is 0 to disable
19080 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 2c   FK enforcement,
19090 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20  .** positive to 
190a0 65 6e 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63  enable FK enforc
190b0 65 6d 65 6e 74 20 6f 72 20 6e 65 67 61 74 69 76  ement or negativ
190c0 65 20 74 6f 20 6c 65 61 76 65 20 46 4b 20 65 6e  e to leave FK en
190d0 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e 63  forcement.** unc
190e0 68 61 6e 67 65 64 2e 20 20 54 68 65 20 73 65 63  hanged.  The sec
190f0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
19100 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
19110 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68   integer into wh
19120 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65  ich.** is writte
19130 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69  n 0 or 1 to indi
19140 63 61 74 65 20 77 68 65 74 68 65 72 20 46 4b 20  cate whether FK 
19150 65 6e 66 6f 72 63 65 6d 65 6e 74 20 69 73 20 6f  enforcement is o
19160 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c  ff or on.** foll
19170 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e  owing this call.
19180 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72    The second par
19190 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61 20  ameter may be a 
191a0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e  NULL pointer, in
191b0 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20 74  .** which case t
191c0 68 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e  he FK enforcemen
191d0 74 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74  t setting is not
191e0 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20   reported back. 
191f0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
19200 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
19210 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 3c 2f  ENABLE_TRIGGER</
19220 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69  dt>.** <dd> ^Thi
19230 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64  s option is used
19240 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69   to enable or di
19250 73 61 62 6c 65 20 5b 43 52 45 41 54 45 20 54 52  sable [CREATE TR
19260 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 73  IGGER | triggers
19270 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75  ]..** There shou
19280 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 69  ld be two additi
19290 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a  onal arguments..
192a0 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
192b0 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65  ument is an inte
192c0 67 65 72 20 77 68 69 63 68 20 69 73 20 30 20 74  ger which is 0 t
192d0 6f 20 64 69 73 61 62 6c 65 20 74 72 69 67 67 65  o disable trigge
192e0 72 73 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20  rs,.** positive 
192f0 74 6f 20 65 6e 61 62 6c 65 20 74 72 69 67 67 65  to enable trigge
19300 72 73 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74  rs or negative t
19310 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65 74 74  o leave the sett
19320 69 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a  ing unchanged..*
19330 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72  * The second par
19340 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e  ameter is a poin
19350 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ter to an intege
19360 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20  r into which.** 
19370 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20  is written 0 or 
19380 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68  1 to indicate wh
19390 65 74 68 65 72 20 74 72 69 67 67 65 72 73 20 61  ether triggers a
193a0 72 65 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65  re disabled or e
193b0 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77  nabled.** follow
193c0 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20  ing this call.  
193d0 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
193e0 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55  eter may be a NU
193f0 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a  LL pointer, in.*
19400 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65  * which case the
19410 20 74 72 69 67 67 65 72 20 73 65 74 74 69 6e 67   trigger setting
19420 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64   is not reported
19430 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a   back. </dd>.**.
19440 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66  ** </dl>.*/.#def
19450 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ine SQLITE_DBCON
19460 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20  FIG_LOOKASIDE   
19470 20 20 20 20 31 30 30 31 20 20 2f 2a 20 76 6f 69      1001  /* voi
19480 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64  d* int int */.#d
19490 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43  efine SQLITE_DBC
194a0 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45  ONFIG_ENABLE_FKE
194b0 59 20 20 20 20 20 31 30 30 32 20 20 2f 2a 20 69  Y     1002  /* i
194c0 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69  nt int* */.#defi
194d0 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  ne SQLITE_DBCONF
194e0 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45  IG_ENABLE_TRIGGE
194f0 52 20 20 31 30 30 33 20 20 2f 2a 20 69 6e 74 20  R  1003  /* int 
19500 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20  int* */.../*.** 
19510 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65  CAPI3REF: Enable
19520 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74 65   Or Disable Exte
19530 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65  nded Result Code
19540 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  s.** METHOD: sql
19550 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ite3.**.** ^The 
19560 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
19570 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 20  _result_codes() 
19580 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20  routine enables 
19590 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 0a  or disables the.
195a0 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  ** [extended res
195b0 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75  ult codes] featu
195c0 72 65 20 6f 66 20 53 51 4c 69 74 65 2e 20 5e 54  re of SQLite. ^T
195d0 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  he extended resu
195e0 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65 20  lt.** codes are 
195f0 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61  disabled by defa
19600 75 6c 74 20 66 6f 72 20 68 69 73 74 6f 72 69 63  ult for historic
19610 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  al compatibility
19620 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
19630 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41  int SQLITE_STDCA
19640 4c 4c 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  LL sqlite3_exten
19650 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73  ded_result_codes
19660 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f  (sqlite3*, int o
19670 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  noff);../*.** CA
19680 50 49 33 52 45 46 3a 20 4c 61 73 74 20 49 6e 73  PI3REF: Last Ins
19690 65 72 74 20 52 6f 77 69 64 0a 2a 2a 20 4d 45 54  ert Rowid.** MET
196a0 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
196b0 2a 2a 20 5e 45 61 63 68 20 65 6e 74 72 79 20 69  ** ^Each entry i
196c0 6e 20 6d 6f 73 74 20 53 51 4c 69 74 65 20 74 61  n most SQLite ta
196d0 62 6c 65 73 20 28 65 78 63 65 70 74 20 66 6f 72  bles (except for
196e0 20 5b 57 49 54 48 4f 55 54 20 52 4f 57 49 44 5d   [WITHOUT ROWID]
196f0 20 74 61 62 6c 65 73 29 0a 2a 2a 20 68 61 73 20   tables).** has 
19700 61 20 75 6e 69 71 75 65 20 36 34 2d 62 69 74 20  a unique 64-bit 
19710 73 69 67 6e 65 64 0a 2a 2a 20 69 6e 74 65 67 65  signed.** intege
19720 72 20 6b 65 79 20 63 61 6c 6c 65 64 20 74 68 65  r key called the
19730 20 5b 52 4f 57 49 44 20 7c 20 22 72 6f 77 69 64   [ROWID | "rowid
19740 22 5d 2e 20 5e 54 68 65 20 72 6f 77 69 64 20 69  "]. ^The rowid i
19750 73 20 61 6c 77 61 79 73 20 61 76 61 69 6c 61 62  s always availab
19760 6c 65 0a 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65  le.** as an unde
19770 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61  clared column na
19780 6d 65 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20  med ROWID, OID, 
19790 6f 72 20 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f  or _ROWID_ as lo
197a0 6e 67 20 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e  ng as those.** n
197b0 61 6d 65 73 20 61 72 65 20 6e 6f 74 20 61 6c 73  ames are not als
197c0 6f 20 75 73 65 64 20 62 79 20 65 78 70 6c 69 63  o used by explic
197d0 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f  itly declared co
197e0 6c 75 6d 6e 73 2e 20 5e 49 66 0a 2a 2a 20 74 68  lumns. ^If.** th
197f0 65 20 74 61 62 6c 65 20 68 61 73 20 61 20 63 6f  e table has a co
19800 6c 75 6d 6e 20 6f 66 20 74 79 70 65 20 5b 49 4e  lumn of type [IN
19810 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45  TEGER PRIMARY KE
19820 59 5d 20 74 68 65 6e 20 74 68 61 74 20 63 6f 6c  Y] then that col
19830 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 65  umn.** is anothe
19840 72 20 61 6c 69 61 73 20 66 6f 72 20 74 68 65 20  r alias for the 
19850 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  rowid..**.** ^Th
19860 65 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69  e sqlite3_last_i
19870 6e 73 65 72 74 5f 72 6f 77 69 64 28 44 29 20 69  nsert_rowid(D) i
19880 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
19890 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20   the [rowid] of 
198a0 74 68 65 20 0a 2a 2a 20 6d 6f 73 74 20 72 65 63  the .** most rec
198b0 65 6e 74 20 73 75 63 63 65 73 73 66 75 6c 20 5b  ent successful [
198c0 49 4e 53 45 52 54 5d 20 69 6e 74 6f 20 61 20 72  INSERT] into a r
198d0 6f 77 69 64 20 74 61 62 6c 65 20 6f 72 20 5b 76  owid table or [v
198e0 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a  irtual table].**
198f0 20 6f 6e 20 64 61 74 61 62 61 73 65 20 63 6f 6e   on database con
19900 6e 65 63 74 69 6f 6e 20 44 2e 0a 2a 2a 20 5e 49  nection D..** ^I
19910 6e 73 65 72 74 73 20 69 6e 74 6f 20 5b 57 49 54  nserts into [WIT
19920 48 4f 55 54 20 52 4f 57 49 44 5d 20 74 61 62 6c  HOUT ROWID] tabl
19930 65 73 20 61 72 65 20 6e 6f 74 20 72 65 63 6f 72  es are not recor
19940 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 6e 6f 20 73  ded..** ^If no s
19950 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52  uccessful [INSER
19960 54 5d 73 20 69 6e 74 6f 20 72 6f 77 69 64 20 74  T]s into rowid t
19970 61 62 6c 65 73 0a 2a 2a 20 68 61 76 65 20 65 76  ables.** have ev
19980 65 72 20 6f 63 63 75 72 72 65 64 20 6f 6e 20 74  er occurred on t
19990 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
199a0 65 63 74 69 6f 6e 20 44 2c 20 0a 2a 2a 20 74 68  ection D, .** th
199b0 65 6e 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f  en sqlite3_last_
199c0 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44 29 20  insert_rowid(D) 
199d0 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a  returns zero..**
199e0 0a 2a 2a 20 5e 28 49 66 20 61 6e 20 5b 49 4e 53  .** ^(If an [INS
199f0 45 52 54 5d 20 6f 63 63 75 72 73 20 77 69 74 68  ERT] occurs with
19a00 69 6e 20 61 20 74 72 69 67 67 65 72 20 6f 72 20  in a trigger or 
19a10 77 69 74 68 69 6e 20 61 20 5b 76 69 72 74 75 61  within a [virtua
19a20 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 6d 65 74 68  l table].** meth
19a30 6f 64 2c 20 74 68 65 6e 20 74 68 69 73 20 72 6f  od, then this ro
19a40 75 74 69 6e 65 20 77 69 6c 6c 20 72 65 74 75 72  utine will retur
19a50 6e 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66  n the [rowid] of
19a60 20 74 68 65 20 69 6e 73 65 72 74 65 64 0a 2a 2a   the inserted.**
19a70 20 72 6f 77 20 61 73 20 6c 6f 6e 67 20 61 73 20   row as long as 
19a80 74 68 65 20 74 72 69 67 67 65 72 20 6f 72 20 76  the trigger or v
19a90 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 65 74  irtual table met
19aa0 68 6f 64 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  hod is running..
19ab0 2a 2a 20 42 75 74 20 6f 6e 63 65 20 74 68 65 20  ** But once the 
19ac0 74 72 69 67 67 65 72 20 6f 72 20 76 69 72 74 75  trigger or virtu
19ad0 61 6c 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20  al table method 
19ae0 65 6e 64 73 2c 20 74 68 65 20 76 61 6c 75 65 20  ends, the value 
19af0 72 65 74 75 72 6e 65 64 20 0a 2a 2a 20 62 79 20  returned .** by 
19b00 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 76  this routine rev
19b10 65 72 74 73 20 74 6f 20 77 68 61 74 20 69 74 20  erts to what it 
19b20 77 61 73 20 62 65 66 6f 72 65 20 74 68 65 20 74  was before the t
19b30 72 69 67 67 65 72 20 6f 72 20 76 69 72 74 75 61  rigger or virtua
19b40 6c 0a 2a 2a 20 74 61 62 6c 65 20 6d 65 74 68 6f  l.** table metho
19b50 64 20 62 65 67 61 6e 2e 29 5e 0a 2a 2a 0a 2a 2a  d began.)^.**.**
19b60 20 5e 41 6e 20 5b 49 4e 53 45 52 54 5d 20 74 68   ^An [INSERT] th
19b70 61 74 20 66 61 69 6c 73 20 64 75 65 20 74 6f 20  at fails due to 
19b80 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f  a constraint vio
19b90 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61 0a  lation is not a.
19ba0 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49  ** successful [I
19bb0 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f 65 73 20  NSERT] and does 
19bc0 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76  not change the v
19bd0 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
19be0 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65   this.** routine
19bf0 2e 20 20 5e 54 68 75 73 20 49 4e 53 45 52 54 20  .  ^Thus INSERT 
19c00 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45 52 54 20  OR FAIL, INSERT 
19c10 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45 52  OR IGNORE, INSER
19c20 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a  T OR ROLLBACK,.*
19c30 2a 20 61 6e 64 20 49 4e 53 45 52 54 20 4f 52 20  * and INSERT OR 
19c40 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63 68  ABORT make no ch
19c50 61 6e 67 65 73 20 74 6f 20 74 68 65 20 72 65 74  anges to the ret
19c60 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69  urn value of thi
19c70 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68 65  s.** routine whe
19c80 6e 20 74 68 65 69 72 20 69 6e 73 65 72 74 69 6f  n their insertio
19c90 6e 20 66 61 69 6c 73 2e 20 20 5e 28 57 68 65 6e  n fails.  ^(When
19ca0 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41   INSERT OR REPLA
19cb0 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 73  CE.** encounters
19cc0 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69   a constraint vi
19cd0 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65 73  olation, it does
19ce0 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68 65 0a   not fail.  The.
19cf0 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74 69 6e  ** INSERT contin
19d00 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f  ues to completio
19d10 6e 20 61 66 74 65 72 20 64 65 6c 65 74 69 6e 67  n after deleting
19d20 20 72 6f 77 73 20 74 68 61 74 20 63 61 75 73 65   rows that cause
19d30 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72 61  d.** the constra
19d40 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20 49  int problem so I
19d50 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45  NSERT OR REPLACE
19d60 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 63 68 61   will always cha
19d70 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65 74 75 72  nge.** the retur
19d80 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20  n value of this 
19d90 69 6e 74 65 72 66 61 63 65 2e 29 5e 0a 2a 2a 0a  interface.)^.**.
19da0 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 75 72 70  ** ^For the purp
19db0 6f 73 65 73 20 6f 66 20 74 68 69 73 20 72 6f 75  oses of this rou
19dc0 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45 52 54  tine, an [INSERT
19dd0 5d 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20  ] is considered 
19de0 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65 73 73  to.** be success
19df0 66 75 6c 20 65 76 65 6e 20 69 66 20 69 74 20 69  ful even if it i
19e00 73 20 73 75 62 73 65 71 75 65 6e 74 6c 79 20 72  s subsequently r
19e10 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a  olled back..**.*
19e20 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  * This function 
19e30 69 73 20 61 63 63 65 73 73 69 62 6c 65 20 74 6f  is accessible to
19e40 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
19e50 76 69 61 20 74 68 65 0a 2a 2a 20 5b 6c 61 73 74  via the.** [last
19e60 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 20  _insert_rowid() 
19e70 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a  SQL function]..*
19e80 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61  *.** If a separa
19e90 74 65 20 74 68 72 65 61 64 20 70 65 72 66 6f 72  te thread perfor
19ea0 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53 45 52 54  ms a new [INSERT
19eb0 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a  ] on the same.**
19ec0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
19ed0 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 65 20 5b  tion while the [
19ee0 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73  sqlite3_last_ins
19ef0 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 20  ert_rowid()].** 
19f00 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
19f10 69 6e 67 20 61 6e 64 20 74 68 75 73 20 63 68 61  ing and thus cha
19f20 6e 67 65 73 20 74 68 65 20 6c 61 73 74 20 69 6e  nges the last in
19f30 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a  sert [rowid],.**
19f40 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20   then the value 
19f50 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
19f60 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74  ite3_last_insert
19f70 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a 20  _rowid()] is.** 
19f80 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e  unpredictable an
19f90 64 20 6d 69 67 68 74 20 6e 6f 74 20 65 71 75 61  d might not equa
19fa0 6c 20 65 69 74 68 65 72 20 74 68 65 20 6f 6c 64  l either the old
19fb0 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a 20 6c   or the new.** l
19fc0 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69  ast insert [rowi
19fd0 64 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  d]..*/.SQLITE_AP
19fe0 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  I sqlite3_int64 
19ff0 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
1a000 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
1a010 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 33  rt_rowid(sqlite3
1a020 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
1a030 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e  REF: Count The N
1a040 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f  umber Of Rows Mo
1a050 64 69 66 69 65 64 0a 2a 2a 20 4d 45 54 48 4f 44  dified.** METHOD
1a060 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
1a070 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72  ^This function r
1a080 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
1a090 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66 69  r of rows modifi
1a0a0 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 0a  ed, inserted or.
1a0b0 2a 2a 20 64 65 6c 65 74 65 64 20 62 79 20 74 68  ** deleted by th
1a0c0 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20  e most recently 
1a0d0 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45 52 54  completed INSERT
1a0e0 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45  , UPDATE or DELE
1a0f0 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  TE.** statement 
1a100 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  on the database 
1a110 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 70 65 63 69  connection speci
1a120 66 69 65 64 20 62 79 20 74 68 65 20 6f 6e 6c 79  fied by the only
1a130 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e   parameter..** ^
1a140 45 78 65 63 75 74 69 6e 67 20 61 6e 79 20 6f 74  Executing any ot
1a150 68 65 72 20 74 79 70 65 20 6f 66 20 53 51 4c 20  her type of SQL 
1a160 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e  statement does n
1a170 6f 74 20 6d 6f 64 69 66 79 20 74 68 65 20 76 61  ot modify the va
1a180 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  lue.** returned 
1a190 62 79 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  by this function
1a1a0 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 63 68  ..**.** ^Only ch
1a1b0 61 6e 67 65 73 20 6d 61 64 65 20 64 69 72 65 63  anges made direc
1a1c0 74 6c 79 20 62 79 20 74 68 65 20 49 4e 53 45 52  tly by the INSER
1a1d0 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c  T, UPDATE or DEL
1a1e0 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 61 72  ETE statement ar
1a1f0 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65 64 20  e.** considered 
1a200 2d 20 61 75 78 69 6c 69 61 72 79 20 63 68 61 6e  - auxiliary chan
1a210 67 65 73 20 63 61 75 73 65 64 20 62 79 20 5b 43  ges caused by [C
1a220 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c 20  REATE TRIGGER | 
1a230 74 72 69 67 67 65 72 73 5d 2c 20 0a 2a 2a 20 5b  triggers], .** [
1a240 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69  foreign key acti
1a250 6f 6e 73 5d 20 6f 72 20 5b 52 45 50 4c 41 43 45  ons] or [REPLACE
1a260 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73  ] constraint res
1a270 6f 6c 75 74 69 6f 6e 20 61 72 65 20 6e 6f 74 20  olution are not 
1a280 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20 0a 2a 2a 20  counted..** .** 
1a290 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65  Changes to a vie
1a2a0 77 20 74 68 61 74 20 61 72 65 20 69 6e 74 65 72  w that are inter
1a2b0 63 65 70 74 65 64 20 62 79 20 0a 2a 2a 20 5b 49  cepted by .** [I
1a2c0 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65  NSTEAD OF trigge
1a2d0 72 20 7c 20 49 4e 53 54 45 41 44 20 4f 46 20 74  r | INSTEAD OF t
1a2e0 72 69 67 67 65 72 73 5d 20 61 72 65 20 6e 6f 74  riggers] are not
1a2f0 20 63 6f 75 6e 74 65 64 2e 20 5e 54 68 65 20 76   counted. ^The v
1a300 61 6c 75 65 20 0a 2a 2a 20 72 65 74 75 72 6e 65  alue .** returne
1a310 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 68 61  d by sqlite3_cha
1a320 6e 67 65 73 28 29 20 69 6d 6d 65 64 69 61 74 65  nges() immediate
1a330 6c 79 20 61 66 74 65 72 20 61 6e 20 49 4e 53 45  ly after an INSE
1a340 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 0a 2a  RT, UPDATE or .*
1a350 2a 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65  * DELETE stateme
1a360 6e 74 20 72 75 6e 20 6f 6e 20 61 20 76 69 65 77  nt run on a view
1a370 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2e   is always zero.
1a380 20 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 6d 61   Only changes ma
1a390 64 65 20 74 6f 20 72 65 61 6c 20 0a 2a 2a 20 74  de to real .** t
1a3a0 61 62 6c 65 73 20 61 72 65 20 63 6f 75 6e 74 65  ables are counte
1a3b0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 67 73 20  d..**.** Things 
1a3c0 61 72 65 20 6d 6f 72 65 20 63 6f 6d 70 6c 69 63  are more complic
1a3d0 61 74 65 64 20 69 66 20 74 68 65 20 73 71 6c 69  ated if the sqli
1a3e0 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 66 75  te3_changes() fu
1a3f0 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 65 78 65  nction is.** exe
1a400 63 75 74 65 64 20 77 68 69 6c 65 20 61 20 74 72  cuted while a tr
1a410 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 69 73  igger program is
1a420 20 72 75 6e 6e 69 6e 67 2e 20 54 68 69 73 20 6d   running. This m
1a430 61 79 20 68 61 70 70 65 6e 20 69 66 20 74 68 65  ay happen if the
1a440 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 65 73  .** program uses
1a450 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20   the [changes() 
1a460 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2c 20 6f  SQL function], o
1a470 72 20 69 66 20 73 6f 6d 65 20 6f 74 68 65 72 20  r if some other 
1a480 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63  callback.** func
1a490 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 73 71 6c  tion invokes sql
1a4a0 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 64  ite3_changes() d
1a4b0 69 72 65 63 74 6c 79 2e 20 45 73 73 65 6e 74 69  irectly. Essenti
1a4c0 61 6c 6c 79 3a 0a 2a 2a 20 0a 2a 2a 20 3c 75 6c  ally:.** .** <ul
1a4d0 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28 42 65  >.**   <li> ^(Be
1a4e0 66 6f 72 65 20 65 6e 74 65 72 69 6e 67 20 61 20  fore entering a 
1a4f0 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20  trigger program 
1a500 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
1a510 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20  ed by.**        
1a520 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
1a530 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 73 61  ) function is sa
1a540 76 65 64 2e 20 41 66 74 65 72 20 74 68 65 20 74  ved. After the t
1a550 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 0a  rigger program .
1a560 2a 2a 20 20 20 20 20 20 20 20 68 61 73 20 66 69  **        has fi
1a570 6e 69 73 68 65 64 2c 20 74 68 65 20 6f 72 69 67  nished, the orig
1a580 69 6e 61 6c 20 76 61 6c 75 65 20 69 73 20 72 65  inal value is re
1a590 73 74 6f 72 65 64 2e 29 5e 0a 2a 2a 20 0a 2a 2a  stored.)^.** .**
1a5a0 20 20 20 3c 6c 69 3e 20 5e 28 57 69 74 68 69 6e     <li> ^(Within
1a5b0 20 61 20 74 72 69 67 67 65 72 20 70 72 6f 67 72   a trigger progr
1a5c0 61 6d 20 65 61 63 68 20 49 4e 53 45 52 54 2c 20  am each INSERT, 
1a5d0 55 50 44 41 54 45 20 61 6e 64 20 44 45 4c 45 54  UPDATE and DELET
1a5e0 45 20 0a 2a 2a 20 20 20 20 20 20 20 20 73 74 61  E .**        sta
1a5f0 74 65 6d 65 6e 74 20 73 65 74 73 20 74 68 65 20  tement sets the 
1a600 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
1a610 79 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65  y sqlite3_change
1a620 73 28 29 20 0a 2a 2a 20 20 20 20 20 20 20 20 75  s() .**        u
1a630 70 6f 6e 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61  pon completion a
1a640 73 20 6e 6f 72 6d 61 6c 2e 20 4f 66 20 63 6f 75  s normal. Of cou
1a650 72 73 65 2c 20 74 68 69 73 20 76 61 6c 75 65 20  rse, this value 
1a660 77 69 6c 6c 20 6e 6f 74 20 69 6e 63 6c 75 64 65  will not include
1a670 20 0a 2a 2a 20 20 20 20 20 20 20 20 61 6e 79 20   .**        any 
1a680 63 68 61 6e 67 65 73 20 70 65 72 66 6f 72 6d 65  changes performe
1a690 64 20 62 79 20 73 75 62 2d 74 72 69 67 67 65 72  d by sub-trigger
1a6a0 73 2c 20 61 73 20 74 68 65 20 73 71 6c 69 74 65  s, as the sqlite
1a6b0 33 5f 63 68 61 6e 67 65 73 28 29 20 0a 2a 2a 20  3_changes() .** 
1a6c0 20 20 20 20 20 20 20 76 61 6c 75 65 20 77 69 6c         value wil
1a6d0 6c 20 62 65 20 73 61 76 65 64 20 61 6e 64 20 72  l be saved and r
1a6e0 65 73 74 6f 72 65 64 20 61 66 74 65 72 20 65 61  estored after ea
1a6f0 63 68 20 73 75 62 2d 74 72 69 67 67 65 72 20 68  ch sub-trigger h
1a700 61 73 20 72 75 6e 2e 29 5e 0a 2a 2a 20 3c 2f 75  as run.)^.** </u
1a710 6c 3e 0a 2a 2a 20 0a 2a 2a 20 5e 54 68 69 73 20  l>.** .** ^This 
1a720 6d 65 61 6e 73 20 74 68 61 74 20 69 66 20 74 68  means that if th
1a730 65 20 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20  e changes() SQL 
1a740 66 75 6e 63 74 69 6f 6e 20 28 6f 72 20 73 69 6d  function (or sim
1a750 69 6c 61 72 29 20 69 73 20 75 73 65 64 0a 2a 2a  ilar) is used.**
1a760 20 62 79 20 74 68 65 20 66 69 72 73 74 20 49 4e   by the first IN
1a770 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20  SERT, UPDATE or 
1a780 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74  DELETE statement
1a790 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 65   within a trigge
1a7a0 72 2c 20 69 74 20 0a 2a 2a 20 72 65 74 75 72 6e  r, it .** return
1a7b0 73 20 74 68 65 20 76 61 6c 75 65 20 61 73 20 73  s the value as s
1a7c0 65 74 20 77 68 65 6e 20 74 68 65 20 63 61 6c 6c  et when the call
1a7d0 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 62 65  ing statement be
1a7e0 67 61 6e 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a  gan executing..*
1a7f0 2a 20 5e 49 66 20 69 74 20 69 73 20 75 73 65 64  * ^If it is used
1a800 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 6f   by the second o
1a810 72 20 73 75 62 73 65 71 75 65 6e 74 20 73 75 63  r subsequent suc
1a820 68 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68  h statement with
1a830 69 6e 20 61 20 74 72 69 67 67 65 72 20 0a 2a 2a  in a trigger .**
1a840 20 70 72 6f 67 72 61 6d 2c 20 74 68 65 20 76 61   program, the va
1a850 6c 75 65 20 72 65 74 75 72 6e 65 64 20 72 65 66  lue returned ref
1a860 6c 65 63 74 73 20 74 68 65 20 6e 75 6d 62 65 72  lects the number
1a870 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66 69 65   of rows modifie
1a880 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 70 72 65  d by the .** pre
1a890 76 69 6f 75 73 20 49 4e 53 45 52 54 2c 20 55 50  vious INSERT, UP
1a8a0 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73  DATE or DELETE s
1a8b0 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20  tatement within 
1a8c0 74 68 65 20 73 61 6d 65 20 74 72 69 67 67 65 72  the same trigger
1a8d0 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
1a8e0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f   the [sqlite3_to
1a8f0 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69  tal_changes()] i
1a900 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a  nterface, the.**
1a910 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20   [count_changes 
1a920 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65  pragma], and the
1a930 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20   [changes() SQL 
1a940 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a  function]..**.**
1a950 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74   If a separate t
1a960 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e  hread makes chan
1a970 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  ges on the same 
1a980 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1a990 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71  ion.** while [sq
1a9a0 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d  lite3_changes()]
1a9b0 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e   is running then
1a9c0 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
1a9d0 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64  ned.** is unpred
1a9e0 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20  ictable and not 
1a9f0 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 53  meaningful..*/.S
1aa00 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51  QLITE_API int SQ
1aa10 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
1aa20 69 74 65 33 5f 63 68 61 6e 67 65 73 28 73 71 6c  ite3_changes(sql
1aa30 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
1aa40 41 50 49 33 52 45 46 3a 20 54 6f 74 61 6c 20 4e  API3REF: Total N
1aa50 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f  umber Of Rows Mo
1aa60 64 69 66 69 65 64 0a 2a 2a 20 4d 45 54 48 4f 44  dified.** METHOD
1aa70 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
1aa80 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72  ^This function r
1aa90 65 74 75 72 6e 73 20 74 68 65 20 74 6f 74 61 6c  eturns the total
1aaa0 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20   number of rows 
1aab0 69 6e 73 65 72 74 65 64 2c 20 6d 6f 64 69 66 69  inserted, modifi
1aac0 65 64 20 6f 72 0a 2a 2a 20 64 65 6c 65 74 65 64  ed or.** deleted
1aad0 20 62 79 20 61 6c 6c 20 5b 49 4e 53 45 52 54 5d   by all [INSERT]
1aae0 2c 20 5b 55 50 44 41 54 45 5d 20 6f 72 20 5b 44  , [UPDATE] or [D
1aaf0 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65 6e 74  ELETE] statement
1ab00 73 20 63 6f 6d 70 6c 65 74 65 64 0a 2a 2a 20 73  s completed.** s
1ab10 69 6e 63 65 20 74 68 65 20 64 61 74 61 62 61 73  ince the databas
1ab20 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 61 73  e connection was
1ab30 20 6f 70 65 6e 65 64 2c 20 69 6e 63 6c 75 64 69   opened, includi
1ab40 6e 67 20 74 68 6f 73 65 20 65 78 65 63 75 74 65  ng those execute
1ab50 64 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20  d as.** part of 
1ab60 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 73  trigger programs
1ab70 2e 20 5e 45 78 65 63 75 74 69 6e 67 20 61 6e 79  . ^Executing any
1ab80 20 6f 74 68 65 72 20 74 79 70 65 20 6f 66 20 53   other type of S
1ab90 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  QL statement.** 
1aba0 64 6f 65 73 20 6e 6f 74 20 61 66 66 65 63 74 20  does not affect 
1abb0 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
1abc0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 6f  ed by sqlite3_to
1abd0 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 2e 0a 2a  tal_changes()..*
1abe0 2a 20 0a 2a 2a 20 5e 43 68 61 6e 67 65 73 20 6d  * .** ^Changes m
1abf0 61 64 65 20 61 73 20 70 61 72 74 20 6f 66 20 5b  ade as part of [
1ac00 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69  foreign key acti
1ac10 6f 6e 73 5d 20 61 72 65 20 69 6e 63 6c 75 64 65  ons] are include
1ac20 64 20 69 6e 20 74 68 65 0a 2a 2a 20 63 6f 75 6e  d in the.** coun
1ac30 74 2c 20 62 75 74 20 74 68 6f 73 65 20 6d 61 64  t, but those mad
1ac40 65 20 61 73 20 70 61 72 74 20 6f 66 20 52 45 50  e as part of REP
1ac50 4c 41 43 45 20 63 6f 6e 73 74 72 61 69 6e 74 20  LACE constraint 
1ac60 72 65 73 6f 6c 75 74 69 6f 6e 20 61 72 65 0a 2a  resolution are.*
1ac70 2a 20 6e 6f 74 2e 20 5e 43 68 61 6e 67 65 73 20  * not. ^Changes 
1ac80 74 6f 20 61 20 76 69 65 77 20 74 68 61 74 20 61  to a view that a
1ac90 72 65 20 69 6e 74 65 72 63 65 70 74 65 64 20 62  re intercepted b
1aca0 79 20 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69  y INSTEAD OF tri
1acb0 67 67 65 72 73 20 0a 2a 2a 20 61 72 65 20 6e 6f  ggers .** are no
1acc0 74 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20 0a 2a  t counted..** .*
1acd0 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b  * See also the [
1ace0 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
1acf0 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68  )] interface, th
1ad00 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e  e.** [count_chan
1ad10 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64  ges pragma], and
1ad20 20 74 68 65 20 5b 74 6f 74 61 6c 5f 63 68 61 6e   the [total_chan
1ad30 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69  ges() SQL functi
1ad40 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20  on]..**.** If a 
1ad50 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20  separate thread 
1ad60 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e  makes changes on
1ad70 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
1ad80 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
1ad90 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f   while [sqlite3_
1ada0 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d  total_changes()]
1adb0 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e   is running then
1adc0 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65   the value.** re
1add0 74 75 72 6e 65 64 20 69 73 20 75 6e 70 72 65 64  turned is unpred
1ade0 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20  ictable and not 
1adf0 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 53  meaningful..*/.S
1ae00 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51  QLITE_API int SQ
1ae10 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
1ae20 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
1ae30 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  es(sqlite3*);../
1ae40 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49  *.** CAPI3REF: I
1ae50 6e 74 65 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d  nterrupt A Long-
1ae60 52 75 6e 6e 69 6e 67 20 51 75 65 72 79 0a 2a 2a  Running Query.**
1ae70 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
1ae80 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e  .**.** ^This fun
1ae90 63 74 69 6f 6e 20 63 61 75 73 65 73 20 61 6e 79  ction causes any
1aea0 20 70 65 6e 64 69 6e 67 20 64 61 74 61 62 61 73   pending databas
1aeb0 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 61  e operation to a
1aec0 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75  bort and.** retu
1aed0 72 6e 20 61 74 20 69 74 73 20 65 61 72 6c 69 65  rn at its earlie
1aee0 73 74 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20  st opportunity. 
1aef0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20  This routine is 
1af00 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c  typically.** cal
1af10 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e 73 65 20  led in response 
1af20 74 6f 20 61 20 75 73 65 72 20 61 63 74 69 6f 6e  to a user action
1af30 20 73 75 63 68 20 61 73 20 70 72 65 73 73 69 6e   such as pressin
1af40 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72  g "Cancel".** or
1af50 20 43 74 72 6c 2d 43 20 77 68 65 72 65 20 74 68   Ctrl-C where th
1af60 65 20 75 73 65 72 20 77 61 6e 74 73 20 61 20 6c  e user wants a l
1af70 6f 6e 67 20 71 75 65 72 79 20 6f 70 65 72 61 74  ong query operat
1af80 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69  ion to halt.** i
1af90 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a  mmediately..**.*
1afa0 2a 20 5e 49 74 20 69 73 20 73 61 66 65 20 74 6f  * ^It is safe to
1afb0 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69   call this routi
1afc0 6e 65 20 66 72 6f 6d 20 61 20 74 68 72 65 61 64  ne from a thread
1afd0 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20   different from 
1afe0 74 68 65 0a 2a 2a 20 74 68 72 65 61 64 20 74 68  the.** thread th
1aff0 61 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20  at is currently 
1b000 72 75 6e 6e 69 6e 67 20 74 68 65 20 64 61 74 61  running the data
1b010 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20  base operation. 
1b020 20 42 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f   But it.** is no
1b030 74 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74  t safe to call t
1b040 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68  his routine with
1b050 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   a [database con
1b060 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a  nection] that.**
1b070 20 69 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69   is closed or mi
1b080 67 68 74 20 63 6c 6f 73 65 20 62 65 66 6f 72 65  ght close before
1b090 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
1b0a0 70 74 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a  pt() returns..**
1b0b0 0a 2a 2a 20 5e 49 66 20 61 6e 20 53 51 4c 20 6f  .** ^If an SQL o
1b0c0 70 65 72 61 74 69 6f 6e 20 69 73 20 76 65 72 79  peration is very
1b0d0 20 6e 65 61 72 6c 79 20 66 69 6e 69 73 68 65 64   nearly finished
1b0e0 20 61 74 20 74 68 65 20 74 69 6d 65 20 77 68 65   at the time whe
1b0f0 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74  n.** sqlite3_int
1b100 65 72 72 75 70 74 28 29 20 69 73 20 63 61 6c 6c  errupt() is call
1b110 65 64 2c 20 74 68 65 6e 20 69 74 20 6d 69 67 68  ed, then it migh
1b120 74 20 6e 6f 74 20 68 61 76 65 20 61 6e 20 6f 70  t not have an op
1b130 70 6f 72 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20  portunity.** to 
1b140 62 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 61  be interrupted a
1b150 6e 64 20 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75  nd might continu
1b160 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e  e to completion.
1b170 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f  .**.** ^An SQL o
1b180 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20 69 73  peration that is
1b190 20 69 6e 74 65 72 72 75 70 74 65 64 20 77 69 6c   interrupted wil
1b1a0 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  l return [SQLITE
1b1b0 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20  _INTERRUPT]..** 
1b1c0 5e 49 66 20 74 68 65 20 69 6e 74 65 72 72 75 70  ^If the interrup
1b1d0 74 65 64 20 53 51 4c 20 6f 70 65 72 61 74 69 6f  ted SQL operatio
1b1e0 6e 20 69 73 20 61 6e 20 49 4e 53 45 52 54 2c 20  n is an INSERT, 
1b1f0 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54  UPDATE, or DELET
1b200 45 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 73  E.** that is ins
1b210 69 64 65 20 61 6e 20 65 78 70 6c 69 63 69 74 20  ide an explicit 
1b220 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65  transaction, the
1b230 6e 20 74 68 65 20 65 6e 74 69 72 65 20 74 72 61  n the entire tra
1b240 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c  nsaction.** will
1b250 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20   be rolled back 
1b260 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a  automatically..*
1b270 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1b280 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20 63  3_interrupt(D) c
1b290 61 6c 6c 20 69 73 20 69 6e 20 65 66 66 65 63 74  all is in effect
1b2a0 20 75 6e 74 69 6c 20 61 6c 6c 20 63 75 72 72 65   until all curre
1b2b0 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20  ntly running.** 
1b2c0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 6f  SQL statements o
1b2d0 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
1b2e0 65 63 74 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65  ection] D comple
1b2f0 74 65 2e 20 20 5e 41 6e 79 20 6e 65 77 20 53 51  te.  ^Any new SQ
1b300 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
1b310 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64  that are started
1b320 20 61 66 74 65 72 20 74 68 65 20 73 71 6c 69 74   after the sqlit
1b330 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63  e3_interrupt() c
1b340 61 6c 6c 20 61 6e 64 20 62 65 66 6f 72 65 20 74  all and before t
1b350 68 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 73  he .** running s
1b360 74 61 74 65 6d 65 6e 74 73 20 72 65 61 63 68 65  tatements reache
1b370 73 20 7a 65 72 6f 20 61 72 65 20 69 6e 74 65 72  s zero are inter
1b380 72 75 70 74 65 64 20 61 73 20 69 66 20 74 68 65  rupted as if the
1b390 79 20 68 61 64 20 62 65 65 6e 0a 2a 2a 20 72 75  y had been.** ru
1b3a0 6e 6e 69 6e 67 20 70 72 69 6f 72 20 74 6f 20 74  nning prior to t
1b3b0 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  he sqlite3_inter
1b3c0 72 75 70 74 28 29 20 63 61 6c 6c 2e 20 20 5e 4e  rupt() call.  ^N
1b3d0 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ew SQL statement
1b3e0 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74  s.** that are st
1b3f0 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20  arted after the 
1b400 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e  running statemen
1b410 74 20 63 6f 75 6e 74 20 72 65 61 63 68 65 73 20  t count reaches 
1b420 7a 65 72 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74 20  zero are.** not 
1b430 65 66 66 65 63 74 65 64 20 62 79 20 74 68 65 20  effected by the 
1b440 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
1b450 74 28 29 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20  t()..** ^A call 
1b460 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  to sqlite3_inter
1b470 72 75 70 74 28 44 29 20 74 68 61 74 20 6f 63 63  rupt(D) that occ
1b480 75 72 73 20 77 68 65 6e 20 74 68 65 72 65 20 61  urs when there a
1b490 72 65 20 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a  re no running.**
1b4a0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
1b4b0 69 73 20 61 20 6e 6f 2d 6f 70 20 61 6e 64 20 68  is a no-op and h
1b4c0 61 73 20 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20  as no effect on 
1b4d0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
1b4e0 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74  * that are start
1b4f0 65 64 20 61 66 74 65 72 20 74 68 65 20 73 71 6c  ed after the sql
1b500 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
1b510 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 0a 2a   call returns..*
1b520 2a 0a 2a 2a 20 49 66 20 74 68 65 20 64 61 74 61  *.** If the data
1b530 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1b540 63 6c 6f 73 65 73 20 77 68 69 6c 65 20 5b 73 71  closes while [sq
1b550 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
1b560 29 5d 0a 2a 2a 20 69 73 20 72 75 6e 6e 69 6e 67  )].** is running
1b570 20 74 68 65 6e 20 62 61 64 20 74 68 69 6e 67 73   then bad things
1b580 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 68 61 70   will likely hap
1b590 70 65 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  pen..*/.SQLITE_A
1b5a0 50 49 20 76 6f 69 64 20 53 51 4c 49 54 45 5f 53  PI void SQLITE_S
1b5b0 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 69  TDCALL sqlite3_i
1b5c0 6e 74 65 72 72 75 70 74 28 73 71 6c 69 74 65 33  nterrupt(sqlite3
1b5d0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
1b5e0 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49  REF: Determine I
1b5f0 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65  f An SQL Stateme
1b600 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a  nt Is Complete.*
1b610 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
1b620 6e 65 73 20 61 72 65 20 75 73 65 66 75 6c 20 64  nes are useful d
1b630 75 72 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69  uring command-li
1b640 6e 65 20 69 6e 70 75 74 20 74 6f 20 64 65 74 65  ne input to dete
1b650 72 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20  rmine if the.** 
1b660 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65  currently entere
1b670 64 20 74 65 78 74 20 73 65 65 6d 73 20 74 6f 20  d text seems to 
1b680 66 6f 72 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20  form a complete 
1b690 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f 72  SQL statement or
1b6a0 0a 2a 2a 20 69 66 20 61 64 64 69 74 69 6f 6e 61  .** if additiona
1b6b0 6c 20 69 6e 70 75 74 20 69 73 20 6e 65 65 64 65  l input is neede
1b6c0 64 20 62 65 66 6f 72 65 20 73 65 6e 64 69 6e 67  d before sending
1b6d0 20 74 68 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a   the text into.*
1b6e0 2a 20 53 51 4c 69 74 65 20 66 6f 72 20 70 61 72  * SQLite for par
1b6f0 73 69 6e 67 2e 20 20 5e 54 68 65 73 65 20 72 6f  sing.  ^These ro
1b700 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 31 20  utines return 1 
1b710 69 66 20 74 68 65 20 69 6e 70 75 74 20 73 74 72  if the input str
1b720 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73 20 74  ing.** appears t
1b730 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65 74 65 20  o be a complete 
1b740 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  SQL statement.  
1b750 5e 41 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  ^A statement is 
1b760 6a 75 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20  judged to be.** 
1b770 63 6f 6d 70 6c 65 74 65 20 69 66 20 69 74 20 65  complete if it e
1b780 6e 64 73 20 77 69 74 68 20 61 20 73 65 6d 69 63  nds with a semic
1b790 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69  olon token and i
1b7a0 73 20 6e 6f 74 20 61 20 70 72 65 66 69 78 20 6f  s not a prefix o
1b7b0 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d  f a.** well-form
1b7c0 65 64 20 43 52 45 41 54 45 20 54 52 49 47 47 45  ed CREATE TRIGGE
1b7d0 52 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 53  R statement.  ^S
1b7e0 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61  emicolons that a
1b7f0 72 65 20 65 6d 62 65 64 64 65 64 20 77 69 74 68  re embedded with
1b800 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74  in.** string lit
1b810 65 72 61 6c 73 20 6f 72 20 71 75 6f 74 65 64 20  erals or quoted 
1b820 69 64 65 6e 74 69 66 69 65 72 20 6e 61 6d 65 73  identifier names
1b830 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65   or comments are
1b840 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64   not.** independ
1b850 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68 65 79  ent tokens (they
1b860 20 61 72 65 20 70 61 72 74 20 6f 66 20 74 68 65   are part of the
1b870 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68 20   token in which 
1b880 74 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65  they are.** embe
1b890 64 64 65 64 29 20 61 6e 64 20 74 68 75 73 20 64  dded) and thus d
1b8a0 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 61  o not count as a
1b8b0 20 73 74 61 74 65 6d 65 6e 74 20 74 65 72 6d 69   statement termi
1b8c0 6e 61 74 6f 72 2e 20 20 5e 57 68 69 74 65 73 70  nator.  ^Whitesp
1b8d0 61 63 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65  ace.** and comme
1b8e0 6e 74 73 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20  nts that follow 
1b8f0 74 68 65 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f  the final semico
1b900 6c 6f 6e 20 61 72 65 20 69 67 6e 6f 72 65 64 2e  lon are ignored.
1b910 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
1b920 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 30 20  utines return 0 
1b930 69 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  if the statement
1b940 20 69 73 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20   is incomplete. 
1b950 20 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79   ^If a.** memory
1b960 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c   allocation fail
1b970 73 2c 20 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e  s, then SQLITE_N
1b980 4f 4d 45 4d 20 69 73 20 72 65 74 75 72 6e 65 64  OMEM is returned
1b990 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  ..**.** ^These r
1b9a0 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70  outines do not p
1b9b0 61 72 73 65 20 74 68 65 20 53 51 4c 20 73 74 61  arse the SQL sta
1b9c0 74 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20  tements thus.** 
1b9d0 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74 20  will not detect 
1b9e0 73 79 6e 74 61 63 74 69 63 61 6c 6c 79 20 69 6e  syntactically in
1b9f0 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a  correct SQL..**.
1ba00 2a 2a 20 5e 28 49 66 20 53 51 4c 69 74 65 20 68  ** ^(If SQLite h
1ba10 61 73 20 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74  as not been init
1ba20 69 61 6c 69 7a 65 64 20 75 73 69 6e 67 20 5b 73  ialized using [s
1ba30 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
1ba40 65 28 29 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74  e()] prior .** t
1ba50 6f 20 69 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74  o invoking sqlit
1ba60 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20  e3_complete16() 
1ba70 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69  then sqlite3_ini
1ba80 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76  tialize() is inv
1ba90 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69  oked.** automati
1baa0 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33  cally by sqlite3
1bab0 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 2e 20 20  _complete16().  
1bac0 49 66 20 74 68 61 74 20 69 6e 69 74 69 61 6c 69  If that initiali
1bad0 7a 61 74 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a  zation fails,.**
1bae0 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e   then the return
1baf0 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69   value from sqli
1bb00 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29  te3_complete16()
1bb10 20 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72   will be non-zer
1bb20 6f 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73 73 20  o.** regardless 
1bb30 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
1bb40 74 20 74 68 65 20 69 6e 70 75 74 20 53 51 4c 20  t the input SQL 
1bb50 69 73 20 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a  is complete.)^.*
1bb60 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74  *.** The input t
1bb70 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  o [sqlite3_compl
1bb80 65 74 65 28 29 5d 20 6d 75 73 74 20 62 65 20 61  ete()] must be a
1bb90 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
1bba0 0a 2a 2a 20 55 54 46 2d 38 20 73 74 72 69 6e 67  .** UTF-8 string
1bbb0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75  ..**.** The inpu
1bbc0 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  t to [sqlite3_co
1bbd0 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d 75 73 74  mplete16()] must
1bbe0 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   be a zero-termi
1bbf0 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20  nated.** UTF-16 
1bc00 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65  string in native
1bc10 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a   byte order..*/.
1bc20 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53  SQLITE_API int S
1bc30 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
1bc40 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63  lite3_complete(c
1bc50 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 29 3b  onst char *sql);
1bc60 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
1bc70 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
1bc80 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
1bc90 36 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  6(const void *sq
1bca0 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  l);../*.** CAPI3
1bcb0 52 45 46 3a 20 52 65 67 69 73 74 65 72 20 41 20  REF: Register A 
1bcc0 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64  Callback To Hand
1bcd0 6c 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 45  le SQLITE_BUSY E
1bce0 72 72 6f 72 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  rrors.** KEYWORD
1bcf0 53 3a 20 7b 62 75 73 79 2d 68 61 6e 64 6c 65 72  S: {busy-handler
1bd00 20 63 61 6c 6c 62 61 63 6b 7d 20 7b 62 75 73 79   callback} {busy
1bd10 20 68 61 6e 64 6c 65 72 7d 0a 2a 2a 20 4d 45 54   handler}.** MET
1bd20 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
1bd30 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1bd40 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 44 2c 58  busy_handler(D,X
1bd50 2c 50 29 20 72 6f 75 74 69 6e 65 20 73 65 74 73  ,P) routine sets
1bd60 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63   a callback func
1bd70 74 69 6f 6e 20 58 0a 2a 2a 20 74 68 61 74 20 6d  tion X.** that m
1bd80 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20  ight be invoked 
1bd90 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20 50 20  with argument P 
1bda0 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 61  whenever.** an a
1bdb0 74 74 65 6d 70 74 20 69 73 20 6d 61 64 65 20 74  ttempt is made t
1bdc0 6f 20 61 63 63 65 73 73 20 61 20 64 61 74 61 62  o access a datab
1bdd0 61 73 65 20 74 61 62 6c 65 20 61 73 73 6f 63 69  ase table associ
1bde0 61 74 65 64 20 77 69 74 68 0a 2a 2a 20 5b 64 61  ated with.** [da
1bdf0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1be00 6e 5d 20 44 20 77 68 65 6e 20 61 6e 6f 74 68 65  n] D when anothe
1be10 72 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72 20 70  r thread.** or p
1be20 72 6f 63 65 73 73 20 68 61 73 20 74 68 65 20 74  rocess has the t
1be30 61 62 6c 65 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 20  able locked..** 
1be40 54 68 65 20 73 71 6c 69 74 65 33 5f 62 75 73 79  The sqlite3_busy
1be50 5f 68 61 6e 64 6c 65 72 28 29 20 69 6e 74 65 72  _handler() inter
1be60 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20  face is used to 
1be70 69 6d 70 6c 65 6d 65 6e 74 0a 2a 2a 20 5b 73 71  implement.** [sq
1be80 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f  lite3_busy_timeo
1be90 75 74 28 29 5d 20 61 6e 64 20 5b 50 52 41 47 4d  ut()] and [PRAGM
1bea0 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 74 5d 2e  A busy_timeout].
1beb0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 62  .**.** ^If the b
1bec0 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  usy callback is 
1bed0 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49  NULL, then [SQLI
1bee0 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 69 73 20 72  TE_BUSY].** is r
1bef0 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74  eturned immediat
1bf00 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74  ely upon encount
1bf10 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20  ering the lock. 
1bf20 20 5e 49 66 20 74 68 65 20 62 75 73 79 20 63 61   ^If the busy ca
1bf30 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74  llback.** is not
1bf40 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20   NULL, then the 
1bf50 63 61 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 62  callback might b
1bf60 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74  e invoked with t
1bf70 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a  wo arguments..**
1bf80 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61  .** ^The first a
1bf90 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 62  rgument to the b
1bfa0 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 61  usy handler is a
1bfb0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69   copy of the voi
1bfc0 64 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68  d* pointer which
1bfd0 0a 2a 2a 20 69 73 20 74 68 65 20 74 68 69 72 64  .** is the third
1bfe0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
1bff0 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
1c000 72 28 29 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e  r().  ^The secon
1c010 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  d argument to.**
1c020 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
1c030 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68  r callback is th
1c040 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65  e number of time
1c050 73 20 74 68 61 74 20 74 68 65 20 62 75 73 79 20  s that the busy 
1c060 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62  handler has.** b
1c070 65 65 6e 20 69 6e 76 6f 6b 65 64 20 70 72 65 76  een invoked prev
1c080 69 6f 75 73 6c 79 20 66 6f 72 20 74 68 65 20 73  iously for the s
1c090 61 6d 65 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e  ame locking even
1c0a0 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 62  t.  ^If the.** b
1c0b0 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  usy callback ret
1c0c0 75 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20  urns 0, then no 
1c0d0 61 64 64 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d  additional attem
1c0e0 70 74 73 20 61 72 65 20 6d 61 64 65 20 74 6f 0a  pts are made to.
1c0f0 2a 2a 20 61 63 63 65 73 73 20 74 68 65 20 64 61  ** access the da
1c100 74 61 62 61 73 65 20 61 6e 64 20 5b 53 51 4c 49  tabase and [SQLI
1c110 54 45 5f 42 55 53 59 5d 20 69 73 20 72 65 74 75  TE_BUSY] is retu
1c120 72 6e 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 61  rned.** to the a
1c130 70 70 6c 69 63 61 74 69 6f 6e 2e 0a 2a 2a 20 5e  pplication..** ^
1c140 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  If the callback 
1c150 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f  returns non-zero
1c160 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65 72 20 61  , then another a
1c170 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64  ttempt.** is mad
1c180 65 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20  e to access the 
1c190 64 61 74 61 62 61 73 65 20 61 6e 64 20 74 68 65  database and the
1c1a0 20 63 79 63 6c 65 20 72 65 70 65 61 74 73 2e 0a   cycle repeats..
1c1b0 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73 65 6e  **.** The presen
1c1c0 63 65 20 6f 66 20 61 20 62 75 73 79 20 68 61 6e  ce of a busy han
1c1d0 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20 67 75  dler does not gu
1c1e0 61 72 61 6e 74 65 65 20 74 68 61 74 20 69 74 20  arantee that it 
1c1f0 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a  will be invoked.
1c200 2a 2a 20 77 68 65 6e 20 74 68 65 72 65 20 69 73  ** when there is
1c210 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e   lock contention
1c220 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 64 65 74  . ^If SQLite det
1c230 65 72 6d 69 6e 65 73 20 74 68 61 74 20 69 6e 76  ermines that inv
1c240 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79 0a 2a  oking the busy.*
1c250 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20  * handler could 
1c260 72 65 73 75 6c 74 20 69 6e 20 61 20 64 65 61 64  result in a dead
1c270 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f  lock, it will go
1c280 20 61 68 65 61 64 20 61 6e 64 20 72 65 74 75 72   ahead and retur
1c290 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a  n [SQLITE_BUSY].
1c2a0 2a 2a 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63  ** to the applic
1c2b0 61 74 69 6f 6e 20 69 6e 73 74 65 61 64 20 6f 66  ation instead of
1c2c0 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 0a 2a   invoking the .*
1c2d0 2a 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a  * busy handler..
1c2e0 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61 20 73 63  ** Consider a sc
1c2f0 65 6e 61 72 69 6f 20 77 68 65 72 65 20 6f 6e 65  enario where one
1c300 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64   process is hold
1c310 69 6e 67 20 61 20 72 65 61 64 20 6c 6f 63 6b 20  ing a read lock 
1c320 74 68 61 74 0a 2a 2a 20 69 74 20 69 73 20 74 72  that.** it is tr
1c330 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20  ying to promote 
1c340 74 6f 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f  to a reserved lo
1c350 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f  ck and.** a seco
1c360 6e 64 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f  nd process is ho
1c370 6c 64 69 6e 67 20 61 20 72 65 73 65 72 76 65 64  lding a reserved
1c380 20 6c 6f 63 6b 20 74 68 61 74 20 69 74 20 69 73   lock that it is
1c390 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72   trying.** to pr
1c3a0 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78 63 6c  omote to an excl
1c3b0 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65  usive lock.  The
1c3c0 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 63   first process c
1c3d0 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a  annot proceed.**
1c3e0 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62   because it is b
1c3f0 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 73 65  locked by the se
1c400 63 6f 6e 64 20 61 6e 64 20 74 68 65 20 73 65 63  cond and the sec
1c410 6f 6e 64 20 70 72 6f 63 65 73 73 20 63 61 6e 6e  ond process cann
1c420 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62 65  ot.** proceed be
1c430 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63  cause it is bloc
1c440 6b 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  ked by the first
1c450 2e 20 20 49 66 20 62 6f 74 68 20 70 72 6f 63 65  .  If both proce
1c460 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74  sses.** invoke t
1c470 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73  he busy handlers
1c480 2c 20 6e 65 69 74 68 65 72 20 77 69 6c 6c 20 6d  , neither will m
1c490 61 6b 65 20 61 6e 79 20 70 72 6f 67 72 65 73 73  ake any progress
1c4a0 2e 20 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a  .  Therefore,.**
1c4b0 20 53 51 4c 69 74 65 20 72 65 74 75 72 6e 73 20   SQLite returns 
1c4c0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f  [SQLITE_BUSY] fo
1c4d0 72 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63  r the first proc
1c4e0 65 73 73 2c 20 68 6f 70 69 6e 67 20 74 68 61 74  ess, hoping that
1c4f0 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e   this.** will in
1c500 64 75 63 65 20 74 68 65 20 66 69 72 73 74 20 70  duce the first p
1c510 72 6f 63 65 73 73 20 74 6f 20 72 65 6c 65 61 73  rocess to releas
1c520 65 20 69 74 73 20 72 65 61 64 20 6c 6f 63 6b 20  e its read lock 
1c530 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65  and allow.** the
1c540 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20   second process 
1c550 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a  to proceed..**.*
1c560 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 62  * ^The default b
1c570 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  usy callback is 
1c580 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  NULL..**.** ^(Th
1c590 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20  ere can only be 
1c5a0 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61  a single busy ha
1c5b0 6e 64 6c 65 72 20 64 65 66 69 6e 65 64 20 66 6f  ndler defined fo
1c5c0 72 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62  r each.** [datab
1c5d0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
1c5e0 20 20 53 65 74 74 69 6e 67 20 61 20 6e 65 77 20    Setting a new 
1c5f0 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 6c 65  busy handler cle
1c600 61 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69  ars any.** previ
1c610 6f 75 73 6c 79 20 73 65 74 20 68 61 6e 64 6c 65  ously set handle
1c620 72 2e 29 5e 20 20 5e 4e 6f 74 65 20 74 68 61 74  r.)^  ^Note that
1c630 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
1c640 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29  3_busy_timeout()
1c650 5d 0a 2a 2a 20 6f 72 20 65 76 61 6c 75 61 74 69  ].** or evaluati
1c660 6e 67 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f  ng [PRAGMA busy_
1c670 74 69 6d 65 6f 75 74 3d 4e 5d 20 77 69 6c 6c 20  timeout=N] will 
1c680 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 62 75  change the.** bu
1c690 73 79 20 68 61 6e 64 6c 65 72 20 61 6e 64 20 74  sy handler and t
1c6a0 68 75 73 20 63 6c 65 61 72 20 61 6e 79 20 70 72  hus clear any pr
1c6b0 65 76 69 6f 75 73 6c 79 20 73 65 74 20 62 75 73  eviously set bus
1c6c0 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a  y handler..**.**
1c6d0 20 54 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61   The busy callba
1c6e0 63 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 20 74 61  ck should not ta
1c6f0 6b 65 20 61 6e 79 20 61 63 74 69 6f 6e 73 20 77  ke any actions w
1c700 68 69 63 68 20 6d 6f 64 69 66 79 20 74 68 65 0a  hich modify the.
1c710 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
1c720 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f  ection that invo
1c730 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e  ked the busy han
1c740 64 6c 65 72 2e 20 20 49 6e 20 6f 74 68 65 72 20  dler.  In other 
1c750 77 6f 72 64 73 2c 0a 2a 2a 20 74 68 65 20 62 75  words,.** the bu
1c760 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 6e 6f  sy handler is no
1c770 74 20 72 65 65 6e 74 72 61 6e 74 2e 20 20 41 6e  t reentrant.  An
1c780 79 20 73 75 63 68 20 61 63 74 69 6f 6e 73 0a 2a  y such actions.*
1c790 2a 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65  * result in unde
1c7a0 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a  fined behavior..
1c7b0 2a 2a 20 0a 2a 2a 20 41 20 62 75 73 79 20 68 61  ** .** A busy ha
1c7c0 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 63  ndler must not c
1c7d0 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62 61 73  lose the databas
1c7e0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
1c7f0 6f 72 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  or [prepared sta
1c800 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e 76  tement] that inv
1c810 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 61  oked the busy ha
1c820 6e 64 6c 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45  ndler..*/.SQLITE
1c830 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f  _API int SQLITE_
1c840 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
1c850 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c  busy_handler(sql
1c860 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f  ite3*, int(*)(vo
1c870 69 64 2a 2c 69 6e 74 29 2c 20 76 6f 69 64 2a 29  id*,int), void*)
1c880 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1c890 46 3a 20 53 65 74 20 41 20 42 75 73 79 20 54 69  F: Set A Busy Ti
1c8a0 6d 65 6f 75 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a  meout.** METHOD:
1c8b0 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e   sqlite3.**.** ^
1c8c0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74  This routine set
1c8d0 73 20 61 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  s a [sqlite3_bus
1c8e0 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75 73 79  y_handler | busy
1c8f0 20 68 61 6e 64 6c 65 72 5d 20 74 68 61 74 20 73   handler] that s
1c900 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20 61 20 73  leeps.** for a s
1c910 70 65 63 69 66 69 65 64 20 61 6d 6f 75 6e 74 20  pecified amount 
1c920 6f 66 20 74 69 6d 65 20 77 68 65 6e 20 61 20 74  of time when a t
1c930 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20  able is locked. 
1c940 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 0a 2a 2a   ^The handler.**
1c950 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74   will sleep mult
1c960 69 70 6c 65 20 74 69 6d 65 73 20 75 6e 74 69 6c  iple times until
1c970 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d   at least "ms" m
1c980 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73  illiseconds of s
1c990 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61 76 65 20  leeping.** have 
1c9a0 61 63 63 75 6d 75 6c 61 74 65 64 2e 20 20 5e 41  accumulated.  ^A
1c9b0 66 74 65 72 20 61 74 20 6c 65 61 73 74 20 22 6d  fter at least "m
1c9c0 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  s" milliseconds 
1c9d0 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20  of sleeping,.** 
1c9e0 74 68 65 20 68 61 6e 64 6c 65 72 20 72 65 74 75  the handler retu
1c9f0 72 6e 73 20 30 20 77 68 69 63 68 20 63 61 75 73  rns 0 which caus
1ca00 65 73 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  es [sqlite3_step
1ca10 28 29 5d 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a  ()] to return.**
1ca20 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a   [SQLITE_BUSY]..
1ca30 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 74  **.** ^Calling t
1ca40 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68  his routine with
1ca50 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65 73   an argument les
1ca60 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20  s than or equal 
1ca70 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73  to zero.** turns
1ca80 20 6f 66 66 20 61 6c 6c 20 62 75 73 79 20 68 61   off all busy ha
1ca90 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ndlers..**.** ^(
1caa0 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62  There can only b
1cab0 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20  e a single busy 
1cac0 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 20 70 61  handler for a pa
1cad0 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74  rticular.** [dat
1cae0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1caf0 5d 20 61 74 20 61 6e 79 20 67 69 76 65 6e 20 6d  ] at any given m
1cb00 6f 6d 65 6e 74 2e 20 20 49 66 20 61 6e 6f 74 68  oment.  If anoth
1cb10 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 0a  er busy handler.
1cb20 2a 2a 20 77 61 73 20 64 65 66 69 6e 65 64 20 20  ** was defined  
1cb30 28 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  (using [sqlite3_
1cb40 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29  busy_handler()])
1cb50 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e   prior to callin
1cb60 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e  g.** this routin
1cb70 65 2c 20 74 68 61 74 20 6f 74 68 65 72 20 62 75  e, that other bu
1cb80 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 63 6c  sy handler is cl
1cb90 65 61 72 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53  eared.)^.**.** S
1cba0 65 65 20 61 6c 73 6f 3a 20 20 5b 50 52 41 47 4d  ee also:  [PRAGM
1cbb0 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 74 5d 0a  A busy_timeout].
1cbc0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
1cbd0 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
1cbe0 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69   sqlite3_busy_ti
1cbf0 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c 20  meout(sqlite3*, 
1cc00 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20  int ms);../*.** 
1cc10 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e  CAPI3REF: Conven
1cc20 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 73 20 46  ience Routines F
1cc30 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 65 72 69  or Running Queri
1cc40 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  es.** METHOD: sq
1cc50 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 69 73  lite3.**.** This
1cc60 20 69 73 20 61 20 6c 65 67 61 63 79 20 69 6e 74   is a legacy int
1cc70 65 72 66 61 63 65 20 74 68 61 74 20 69 73 20 70  erface that is p
1cc80 72 65 73 65 72 76 65 64 20 66 6f 72 20 62 61 63  reserved for bac
1cc90 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
1cca0 6c 69 74 79 2e 0a 2a 2a 20 55 73 65 20 6f 66 20  lity..** Use of 
1ccb0 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69  this interface i
1ccc0 73 20 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e 64 65  s not recommende
1ccd0 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74  d..**.** Definit
1cce0 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74  ion: A <b>result
1ccf0 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65   table</b> is me
1cd00 6d 6f 72 79 20 64 61 74 61 20 73 74 72 75 63 74  mory data struct
1cd10 75 72 65 20 63 72 65 61 74 65 64 20 62 79 20 74  ure created by t
1cd20 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67  he.** [sqlite3_g
1cd30 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74 65  et_table()] inte
1cd40 72 66 61 63 65 2e 20 20 41 20 72 65 73 75 6c 74  rface.  A result
1cd50 20 74 61 62 6c 65 20 72 65 63 6f 72 64 73 20 74   table records t
1cd60 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71  he.** complete q
1cd70 75 65 72 79 20 72 65 73 75 6c 74 73 20 66 72 6f  uery results fro
1cd80 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75  m one or more qu
1cd90 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  eries..**.** The
1cda0 20 74 61 62 6c 65 20 63 6f 6e 63 65 70 74 75 61   table conceptua
1cdb0 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d 62 65 72  lly has a number
1cdc0 20 6f 66 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c   of rows and col
1cdd0 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68  umns.  But.** th
1cde0 65 73 65 20 6e 75 6d 62 65 72 73 20 61 72 65 20  ese numbers are 
1cdf0 6e 6f 74 20 70 61 72 74 20 6f 66 20 74 68 65 20  not part of the 
1ce00 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 74 73  result table its
1ce10 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e  elf.  These.** n
1ce20 75 6d 62 65 72 73 20 61 72 65 20 6f 62 74 61 69  umbers are obtai
1ce30 6e 65 64 20 73 65 70 61 72 61 74 65 6c 79 2e 20  ned separately. 
1ce40 20 4c 65 74 20 4e 20 62 65 20 74 68 65 20 6e 75   Let N be the nu
1ce50 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20  mber of rows.** 
1ce60 61 6e 64 20 4d 20 62 65 20 74 68 65 20 6e 75 6d  and M be the num
1ce70 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a  ber of columns..
1ce80 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74  **.** A result t
1ce90 61 62 6c 65 20 69 73 20 61 6e 20 61 72 72 61 79  able is an array
1cea0 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20   of pointers to 
1ceb0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
1cec0 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a  UTF-8 strings..*
1ced0 2a 20 54 68 65 72 65 20 61 72 65 20 28 4e 2b 31  * There are (N+1
1cee0 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20  )*M elements in 
1cef0 74 68 65 20 61 72 72 61 79 2e 20 20 54 68 65 20  the array.  The 
1cf00 66 69 72 73 74 20 4d 20 70 6f 69 6e 74 65 72 73  first M pointers
1cf10 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72   point.** to zer
1cf20 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72  o-terminated str
1cf30 69 6e 67 73 20 74 68 61 74 20 20 63 6f 6e 74 61  ings that  conta
1cf40 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20  in the names of 
1cf50 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20  the columns..** 
1cf60 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e  The remaining en
1cf70 74 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20  tries all point 
1cf80 74 6f 20 71 75 65 72 79 20 72 65 73 75 6c 74 73  to query results
1cf90 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72  .  NULL values r
1cfa0 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c  esult.** in NULL
1cfb0 20 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20   pointers.  All 
1cfc0 6f 74 68 65 72 20 76 61 6c 75 65 73 20 61 72 65  other values are
1cfd0 20 69 6e 20 74 68 65 69 72 20 55 54 46 2d 38 20   in their UTF-8 
1cfe0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
1cff0 2a 2a 20 73 74 72 69 6e 67 20 72 65 70 72 65 73  ** string repres
1d000 65 6e 74 61 74 69 6f 6e 20 61 73 20 72 65 74 75  entation as retu
1d010 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
1d020 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e  _column_text()].
1d030 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20  .**.** A result 
1d040 74 61 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73  table might cons
1d050 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f  ist of one or mo
1d060 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  re memory alloca
1d070 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20  tions..** It is 
1d080 6e 6f 74 20 73 61 66 65 20 74 6f 20 70 61 73 73  not safe to pass
1d090 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   a result table 
1d0a0 64 69 72 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c  directly to [sql
1d0b0 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a  ite3_free()]..**
1d0c0 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
1d0d0 73 68 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f  should be deallo
1d0e0 63 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  cated using [sql
1d0f0 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28  ite3_free_table(
1d100 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20 61  )]..**.** ^(As a
1d110 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 74 68 65  n example of the
1d120 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 66 6f   result table fo
1d130 72 6d 61 74 2c 20 73 75 70 70 6f 73 65 20 61 20  rmat, suppose a 
1d140 71 75 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20  query result.** 
1d150 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  is as follows:.*
1d160 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
1d170 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20  ><pre>.**       
1d180 20 4e 61 6d 65 20 20 20 20 20 20 20 20 7c 20 41   Name        | A
1d190 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d  ge.**        ---
1d1a0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1d1b0 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41  ----.**        A
1d1c0 6c 69 63 65 20 20 20 20 20 20 20 7c 20 34 33 0a  lice       | 43.
1d1d0 2a 2a 20 20 20 20 20 20 20 20 42 6f 62 20 20 20  **        Bob   
1d1e0 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20        | 28.**   
1d1f0 20 20 20 20 20 43 69 6e 64 79 20 20 20 20 20 20       Cindy      
1d200 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c   | 21.** </pre><
1d210 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
1d220 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 77 6f  ** There are two
1d230 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61   column (M==2) a
1d240 6e 64 20 74 68 72 65 65 20 72 6f 77 73 20 28 4e  nd three rows (N
1d250 3d 3d 33 29 2e 20 20 54 68 75 73 20 74 68 65 0a  ==3).  Thus the.
1d260 2a 2a 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  ** result table 
1d270 68 61 73 20 38 20 65 6e 74 72 69 65 73 2e 20 20  has 8 entries.  
1d280 53 75 70 70 6f 73 65 20 74 68 65 20 72 65 73 75  Suppose the resu
1d290 6c 74 20 74 61 62 6c 65 20 69 73 20 73 74 6f 72  lt table is stor
1d2a0 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61  ed.** in an arra
1d2b0 79 20 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c 74  y names azResult
1d2c0 2e 20 20 54 68 65 6e 20 61 7a 52 65 73 75 6c 74  .  Then azResult
1d2d0 20 68 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e 74   holds this cont
1d2e0 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ent:.**.** <bloc
1d2f0 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
1d300 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
1d310 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b  #91;0] = "Name";
1d320 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
1d330 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 41 67  ult&#91;1] = "Ag
1d340 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  e";.**        az
1d350 52 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20  Result&#91;2] = 
1d360 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20  "Alice";.**     
1d370 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
1d380 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20  3] = "43";.**   
1d390 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
1d3a0 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a  1;4] = "Bob";.**
1d3b0 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
1d3c0 26 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a  &#91;5] = "28";.
1d3d0 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
1d3e0 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e  lt&#91;6] = "Cin
1d3f0 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  dy";.**        a
1d400 7a 52 65 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d  zResult&#91;7] =
1d410 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e   "21";.** </pre>
1d420 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a  </blockquote>)^.
1d430 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1d440 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 66  e3_get_table() f
1d450 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 74 65  unction evaluate
1d460 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a  s one or more.**
1d470 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72   semicolon-separ
1d480 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65  ated SQL stateme
1d490 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d  nts in the zero-
1d4a0 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
1d4b0 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 69 74  .** string of it
1d4c0 73 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  s 2nd parameter 
1d4d0 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 72 65  and returns a re
1d4e0 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 74 68  sult table to th
1d4f0 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69 76  e.** pointer giv
1d500 65 6e 20 69 6e 20 69 74 73 20 33 72 64 20 70 61  en in its 3rd pa
1d510 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41  rameter..**.** A
1d520 66 74 65 72 20 74 68 65 20 61 70 70 6c 69 63 61  fter the applica
1d530 74 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 68 65  tion has finishe
1d540 64 20 77 69 74 68 20 74 68 65 20 72 65 73 75 6c  d with the resul
1d550 74 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 67  t from sqlite3_g
1d560 65 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a 20 69  et_table(),.** i
1d570 74 20 6d 75 73 74 20 70 61 73 73 20 74 68 65 20  t must pass the 
1d580 72 65 73 75 6c 74 20 74 61 62 6c 65 20 70 6f 69  result table poi
1d590 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  nter to sqlite3_
1d5a0 66 72 65 65 5f 74 61 62 6c 65 28 29 20 69 6e 20  free_table() in 
1d5b0 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65  order to.** rele
1d5c0 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74  ase the memory t
1d5d0 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64  hat was malloced
1d5e0 2e 20 20 42 65 63 61 75 73 65 20 6f 66 20 74 68  .  Because of th
1d5f0 65 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71  e way the.** [sq
1d600 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
1d610 68 61 70 70 65 6e 73 20 77 69 74 68 69 6e 20 73  happens within s
1d620 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
1d630 28 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a  (), the calling.
1d640 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74  ** function must
1d650 20 6e 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c   not try to call
1d660 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
1d670 5d 20 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c  ] directly.  Onl
1d680 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72  y.** [sqlite3_fr
1d690 65 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 61  ee_table()] is a
1d6a0 62 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 20 74  ble to release t
1d6b0 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72  he memory proper
1d6c0 6c 79 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a  ly and safely..*
1d6d0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
1d6e0 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 69 6e 74  _get_table() int
1d6f0 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d  erface is implem
1d700 65 6e 74 65 64 20 61 73 20 61 20 77 72 61 70 70  ented as a wrapp
1d710 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71  er around.** [sq
1d720 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2e 20 20  lite3_exec()].  
1d730 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
1d740 74 61 62 6c 65 28 29 20 72 6f 75 74 69 6e 65 20  table() routine 
1d750 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 61 63  does not have ac
1d760 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69  cess.** to any i
1d770 6e 74 65 72 6e 61 6c 20 64 61 74 61 20 73 74 72  nternal data str
1d780 75 63 74 75 72 65 73 20 6f 66 20 53 51 4c 69 74  uctures of SQLit
1d790 65 2e 20 20 49 74 20 75 73 65 73 20 6f 6e 6c 79  e.  It uses only
1d7a0 20 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69   the public.** i
1d7b0 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e 65 64  nterface defined
1d7c0 20 68 65 72 65 2e 20 20 41 73 20 61 20 63 6f 6e   here.  As a con
1d7d0 73 65 71 75 65 6e 63 65 2c 20 65 72 72 6f 72 73  sequence, errors
1d7e0 20 74 68 61 74 20 6f 63 63 75 72 20 69 6e 20 74   that occur in t
1d7f0 68 65 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c 61  he.** wrapper la
1d800 79 65 72 20 6f 75 74 73 69 64 65 20 6f 66 20 74  yer outside of t
1d810 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c  he internal [sql
1d820 69 74 65 33 5f 65 78 65 63 28 29 5d 20 63 61 6c  ite3_exec()] cal
1d830 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66  l are not.** ref
1d840 6c 65 63 74 65 64 20 69 6e 20 73 75 62 73 65 71  lected in subseq
1d850 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73  uent calls to [s
1d860 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
1d870 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
1d880 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 53  _errmsg()]..*/.S
1d890 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51  QLITE_API int SQ
1d8a0 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
1d8b0 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a  ite3_get_table(.
1d8c0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
1d8d0 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70          /* An op
1d8e0 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20  en database */. 
1d8f0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71   const char *zSq
1d900 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f  l,     /* SQL to
1d910 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f   be evaluated */
1d920 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65  .  char ***pazRe
1d930 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73 75  sult,    /* Resu
1d940 6c 74 73 20 6f 66 20 74 68 65 20 71 75 65 72 79  lts of the query
1d950 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77   */.  int *pnRow
1d960 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e  ,           /* N
1d970 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20  umber of result 
1d980 72 6f 77 73 20 77 72 69 74 74 65 6e 20 68 65 72  rows written her
1d990 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f  e */.  int *pnCo
1d9a0 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20  lumn,        /* 
1d9b0 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74  Number of result
1d9c0 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e   columns written
1d9d0 20 68 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20   here */.  char 
1d9e0 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20 20 20 20  **pzErrmsg      
1d9f0 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72   /* Error msg wr
1da00 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b  itten here */.);
1da10 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
1da20 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
1da30 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62  sqlite3_free_tab
1da40 6c 65 28 63 68 61 72 20 2a 2a 72 65 73 75 6c 74  le(char **result
1da50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1da60 45 46 3a 20 46 6f 72 6d 61 74 74 65 64 20 53 74  EF: Formatted St
1da70 72 69 6e 67 20 50 72 69 6e 74 69 6e 67 20 46 75  ring Printing Fu
1da80 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  nctions.**.** Th
1da90 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
1daa0 20 77 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f 66 20   work-alikes of 
1dab0 74 68 65 20 22 70 72 69 6e 74 66 28 29 22 20 66  the "printf()" f
1dac0 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f  amily of functio
1dad0 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73  ns.** from the s
1dae0 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72  tandard C librar
1daf0 79 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  y..** These rout
1db00 69 6e 65 73 20 75 6e 64 65 72 73 74 61 6e 64 20  ines understand 
1db10 6d 6f 73 74 20 6f 66 20 74 68 65 20 63 6f 6d 6d  most of the comm
1db20 6f 6e 20 4b 26 52 20 66 6f 72 6d 61 74 74 69 6e  on K&R formattin
1db30 67 20 6f 70 74 69 6f 6e 73 2c 0a 2a 2a 20 70 6c  g options,.** pl
1db40 75 73 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e  us some addition
1db50 61 6c 20 6e 6f 6e 2d 73 74 61 6e 64 61 72 64 20  al non-standard 
1db60 66 6f 72 6d 61 74 73 2c 20 64 65 74 61 69 6c 65  formats, detaile
1db70 64 20 62 65 6c 6f 77 2e 0a 2a 2a 20 4e 6f 74 65  d below..** Note
1db80 20 74 68 61 74 20 73 6f 6d 65 20 6f 66 20 74 68   that some of th
1db90 65 20 6d 6f 72 65 20 6f 62 73 63 75 72 65 20 66  e more obscure f
1dba0 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e  ormatting option
1dbb0 73 20 66 72 6f 6d 20 72 65 63 65 6e 74 0a 2a 2a  s from recent.**
1dbc0 20 43 2d 6c 69 62 72 61 72 79 20 73 74 61 6e 64   C-library stand
1dbd0 61 72 64 73 20 61 72 65 20 6f 6d 69 74 74 65 64  ards are omitted
1dbe0 20 66 72 6f 6d 20 74 68 69 73 20 69 6d 70 6c 65   from this imple
1dbf0 6d 65 6e 74 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  mentation..**.**
1dc00 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 70   ^The sqlite3_mp
1dc10 72 69 6e 74 66 28 29 20 61 6e 64 20 73 71 6c 69  rintf() and sqli
1dc20 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 29 20 72  te3_vmprintf() r
1dc30 6f 75 74 69 6e 65 73 20 77 72 69 74 65 20 74 68  outines write th
1dc40 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69  eir.** results i
1dc50 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69  nto memory obtai
1dc60 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
1dc70 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20  3_malloc()]..** 
1dc80 54 68 65 20 73 74 72 69 6e 67 73 20 72 65 74 75  The strings retu
1dc90 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 74 77  rned by these tw
1dca0 6f 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c  o routines shoul
1dcb0 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64  d be.** released
1dcc0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 72 65   by [sqlite3_fre
1dcd0 65 28 29 5d 2e 20 20 5e 42 6f 74 68 20 72 6f 75  e()].  ^Both rou
1dce0 74 69 6e 65 73 20 72 65 74 75 72 6e 20 61 0a 2a  tines return a.*
1dcf0 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  * NULL pointer i
1dd00 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  f [sqlite3_mallo
1dd10 63 28 29 5d 20 69 73 20 75 6e 61 62 6c 65 20 74  c()] is unable t
1dd20 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 67  o allocate enoug
1dd30 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 68  h.** memory to h
1dd40 6f 6c 64 20 74 68 65 20 72 65 73 75 6c 74 69 6e  old the resultin
1dd50 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  g string..**.** 
1dd60 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6e  ^(The sqlite3_sn
1dd70 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65  printf() routine
1dd80 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 22   is similar to "
1dd90 73 6e 70 72 69 6e 74 66 28 29 22 20 66 72 6f 6d  snprintf()" from
1dda0 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64 61 72 64  .** the standard
1ddb0 20 43 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65   C library.  The
1ddc0 20 72 65 73 75 6c 74 20 69 73 20 77 72 69 74 74   result is writt
1ddd0 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62  en into the.** b
1dde0 75 66 66 65 72 20 73 75 70 70 6c 69 65 64 20 61  uffer supplied a
1ddf0 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  s the second par
1de00 61 6d 65 74 65 72 20 77 68 6f 73 65 20 73 69 7a  ameter whose siz
1de10 65 20 69 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a  e is given by.**
1de20 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
1de30 65 74 65 72 2e 20 4e 6f 74 65 20 74 68 61 74 20  eter. Note that 
1de40 74 68 65 20 6f 72 64 65 72 20 6f 66 20 74 68 65  the order of the
1de50 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f 20 70 61  .** first two pa
1de60 72 61 6d 65 74 65 72 73 20 69 73 20 72 65 76 65  rameters is reve
1de70 72 73 65 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e  rsed from snprin
1de80 74 66 28 29 2e 29 5e 20 20 54 68 69 73 20 69 73  tf().)^  This is
1de90 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61   an.** historica
1dea0 6c 20 61 63 63 69 64 65 6e 74 20 74 68 61 74 20  l accident that 
1deb0 63 61 6e 6e 6f 74 20 62 65 20 66 69 78 65 64 20  cannot be fixed 
1dec0 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67  without breaking
1ded0 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f  .** backwards co
1dee0 6d 70 61 74 69 62 69 6c 69 74 79 2e 20 20 5e 28  mpatibility.  ^(
1def0 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61 74 20 73  Note also that s
1df00 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
1df10 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 70  ).** returns a p
1df20 6f 69 6e 74 65 72 20 74 6f 20 69 74 73 20 62 75  ointer to its bu
1df30 66 66 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20  ffer instead of 
1df40 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
1df50 20 63 68 61 72 61 63 74 65 72 73 20 61 63 74 75   characters actu
1df60 61 6c 6c 79 20 77 72 69 74 74 65 6e 20 69 6e 74  ally written int
1df70 6f 20 74 68 65 20 62 75 66 66 65 72 2e 29 5e 20  o the buffer.)^ 
1df80 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 0a 2a   We admit that.*
1df90 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
1dfa0 63 68 61 72 61 63 74 65 72 73 20 77 72 69 74 74  characters writt
1dfb0 65 6e 20 77 6f 75 6c 64 20 62 65 20 61 20 6d 6f  en would be a mo
1dfc0 72 65 20 75 73 65 66 75 6c 20 72 65 74 75 72 6e  re useful return
1dfd0 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74 20 77 65  .** value but we
1dfe0 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74   cannot change t
1dff0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
1e000 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70  n of sqlite3_snp
1e010 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 20 77  rintf().** now w
1e020 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20  ithout breaking 
1e030 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a  compatibility..*
1e040 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67 20 61 73  *.** ^As long as
1e050 20 74 68 65 20 62 75 66 66 65 72 20 73 69 7a 65   the buffer size
1e060 20 69 73 20 67 72 65 61 74 65 72 20 74 68 61 6e   is greater than
1e070 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f 73   zero, sqlite3_s
1e080 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75 61  nprintf().** gua
1e090 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65  rantees that the
1e0a0 20 62 75 66 66 65 72 20 69 73 20 61 6c 77 61 79   buffer is alway
1e0b0 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  s zero-terminate
1e0c0 64 2e 20 20 5e 54 68 65 20 66 69 72 73 74 0a 2a  d.  ^The first.*
1e0d0 2a 20 70 61 72 61 6d 65 74 65 72 20 22 6e 22 20  * parameter "n" 
1e0e0 69 73 20 74 68 65 20 74 6f 74 61 6c 20 73 69 7a  is the total siz
1e0f0 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 2c  e of the buffer,
1e100 20 69 6e 63 6c 75 64 69 6e 67 20 73 70 61 63 65   including space
1e110 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f   for.** the zero
1e120 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 53 6f   terminator.  So
1e130 20 74 68 65 20 6c 6f 6e 67 65 73 74 20 73 74 72   the longest str
1e140 69 6e 67 20 74 68 61 74 20 63 61 6e 20 62 65 20  ing that can be 
1e150 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72  completely.** wr
1e160 69 74 74 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d  itten will be n-
1e170 31 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a  1 characters..**
1e180 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1e190 5f 76 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75  _vsnprintf() rou
1e1a0 74 69 6e 65 20 69 73 20 61 20 76 61 72 61 72 67  tine is a vararg
1e1b0 73 20 76 65 72 73 69 6f 6e 20 6f 66 20 73 71 6c  s version of sql
1e1c0 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 2e  ite3_snprintf().
1e1d0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
1e1e0 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d  tines all implem
1e1f0 65 6e 74 20 73 6f 6d 65 20 61 64 64 69 74 69 6f  ent some additio
1e200 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a  nal formatting.*
1e210 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 61  * options that a
1e220 72 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63 6f  re useful for co
1e230 6e 73 74 72 75 63 74 69 6e 67 20 53 51 4c 20 73  nstructing SQL s
1e240 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c  tatements..** Al
1e250 6c 20 6f 66 20 74 68 65 20 75 73 75 61 6c 20 70  l of the usual p
1e260 72 69 6e 74 66 28 29 20 66 6f 72 6d 61 74 74 69  rintf() formatti
1e270 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70 70 6c 79  ng options apply
1e280 2e 20 20 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20  .  In addition, 
1e290 74 68 65 72 65 0a 2a 2a 20 69 73 20 61 72 65 20  there.** is are 
1e2a0 22 25 71 22 2c 20 22 25 51 22 2c 20 22 25 77 22  "%q", "%Q", "%w"
1e2b0 20 61 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e   and "%z" option
1e2c0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25  s..**.** ^(The %
1e2d0 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c  q option works l
1e2e0 69 6b 65 20 25 73 20 69 6e 20 74 68 61 74 20 69  ike %s in that i
1e2f0 74 20 73 75 62 73 74 69 74 75 74 65 73 20 61 20  t substitutes a 
1e300 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  nul-terminated.*
1e310 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 74 68  * string from th
1e320 65 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e  e argument list.
1e330 20 20 42 75 74 20 25 71 20 61 6c 73 6f 20 64 6f    But %q also do
1e340 75 62 6c 65 73 20 65 76 65 72 79 20 27 5c 27 27  ubles every '\''
1e350 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25   character..** %
1e360 71 20 69 73 20 64 65 73 69 67 6e 65 64 20 66 6f  q is designed fo
1e370 72 20 75 73 65 20 69 6e 73 69 64 65 20 61 20 73  r use inside a s
1e380 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 29 5e  tring literal.)^
1e390 20 20 42 79 20 64 6f 75 62 6c 69 6e 67 20 65 61    By doubling ea
1e3a0 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61  ch '\''.** chara
1e3b0 63 74 65 72 20 69 74 20 65 73 63 61 70 65 73 20  cter it escapes 
1e3c0 74 68 61 74 20 63 68 61 72 61 63 74 65 72 20 61  that character a
1e3d0 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20  nd allows it to 
1e3e0 62 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f  be inserted into
1e3f0 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 2e 0a  .** the string..
1e400 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c  **.** For exampl
1e410 65 2c 20 61 73 73 75 6d 65 20 74 68 65 20 73 74  e, assume the st
1e420 72 69 6e 67 20 76 61 72 69 61 62 6c 65 20 7a 54  ring variable zT
1e430 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 74 65 78  ext contains tex
1e440 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  t as follows:.**
1e450 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
1e460 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a  <pre>.**  char *
1e470 7a 54 65 78 74 20 3d 20 22 49 74 27 73 20 61 20  zText = "It's a 
1e480 68 61 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20  happy day!";.** 
1e490 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
1e4a0 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61  te>.**.** One ca
1e4b0 6e 20 75 73 65 20 74 68 69 73 20 74 65 78 74 20  n use this text 
1e4c0 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  in an SQL statem
1e4d0 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a  ent as follows:.
1e4e0 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
1e4f0 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72  e><pre>.**  char
1e500 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33   *zSQL = sqlite3
1e510 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54  _mprintf("INSERT
1e520 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55   INTO table VALU
1e530 45 53 28 27 25 71 27 29 22 2c 20 7a 54 65 78 74  ES('%q')", zText
1e540 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65  );.**  sqlite3_e
1e550 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c  xec(db, zSQL, 0,
1e560 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69   0, 0);.**  sqli
1e570 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a  te3_free(zSQL);.
1e580 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
1e590 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63  quote>.**.** Bec
1e5a0 61 75 73 65 20 74 68 65 20 25 71 20 66 6f 72 6d  ause the %q form
1e5b0 61 74 20 73 74 72 69 6e 67 20 69 73 20 75 73 65  at string is use
1e5c0 64 2c 20 74 68 65 20 27 5c 27 27 20 63 68 61 72  d, the '\'' char
1e5d0 61 63 74 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a  acter in zText.*
1e5e0 2a 20 69 73 20 65 73 63 61 70 65 64 20 61 6e 64  * is escaped and
1e5f0 20 74 68 65 20 53 51 4c 20 67 65 6e 65 72 61 74   the SQL generat
1e600 65 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73  ed is as follows
1e610 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
1e620 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e  ote><pre>.**  IN
1e630 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31  SERT INTO table1
1e640 20 56 41 4c 55 45 53 28 27 49 74 27 27 73 20 61   VALUES('It''s a
1e650 20 68 61 70 70 79 20 64 61 79 21 27 29 0a 2a 2a   happy day!').**
1e660 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
1e670 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ote>.**.** This 
1e680 69 73 20 63 6f 72 72 65 63 74 2e 20 20 48 61 64  is correct.  Had
1e690 20 77 65 20 75 73 65 64 20 25 73 20 69 6e 73 74   we used %s inst
1e6a0 65 61 64 20 6f 66 20 25 71 2c 20 74 68 65 20 67  ead of %q, the g
1e6b0 65 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20  enerated SQL.** 
1e6c0 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65  would have looke
1e6d0 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a  d like this:.**.
1e6e0 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
1e6f0 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20  pre>.**  INSERT 
1e700 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55  INTO table1 VALU
1e710 45 53 28 27 49 74 27 73 20 61 20 68 61 70 70 79  ES('It's a happy
1e720 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72   day!');.** </pr
1e730 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
1e740 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e  **.** This secon
1e750 64 20 65 78 61 6d 70 6c 65 20 69 73 20 61 6e 20  d example is an 
1e760 53 51 4c 20 73 79 6e 74 61 78 20 65 72 72 6f 72  SQL syntax error
1e770 2e 20 20 41 73 20 61 20 67 65 6e 65 72 61 6c 20  .  As a general 
1e780 72 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a  rule you should.
1e790 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 20 25 71  ** always use %q
1e7a0 20 69 6e 73 74 65 61 64 20 6f 66 20 25 73 20 77   instead of %s w
1e7b0 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 74 65  hen inserting te
1e7c0 78 74 20 69 6e 74 6f 20 61 20 73 74 72 69 6e 67  xt into a string
1e7d0 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20   literal..**.** 
1e7e0 5e 28 54 68 65 20 25 51 20 6f 70 74 69 6f 6e 20  ^(The %Q option 
1e7f0 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20 65 78  works like %q ex
1e800 63 65 70 74 20 69 74 20 61 6c 73 6f 20 61 64 64  cept it also add
1e810 73 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 20  s single quotes 
1e820 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75  around.** the ou
1e830 74 73 69 64 65 20 6f 66 20 74 68 65 20 74 6f 74  tside of the tot
1e840 61 6c 20 73 74 72 69 6e 67 2e 20 20 41 64 64 69  al string.  Addi
1e850 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68 65  tionally, if the
1e860 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68   parameter in th
1e870 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c 69  e.** argument li
1e880 73 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  st is a NULL poi
1e890 6e 74 65 72 2c 20 25 51 20 73 75 62 73 74 69 74  nter, %Q substit
1e8a0 75 74 65 73 20 74 68 65 20 74 65 78 74 20 22 4e  utes the text "N
1e8b0 55 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a 2a  ULL" (without.**
1e8c0 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 29 2e   single quotes).
1e8d0 29 5e 20 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d  )^  So, for exam
1e8e0 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73  ple, one could s
1e8f0 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ay:.**.** <block
1e900 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
1e910 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c  char *zSQL = sql
1e920 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e  ite3_mprintf("IN
1e930 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20  SERT INTO table 
1e940 56 41 4c 55 45 53 28 25 51 29 22 2c 20 7a 54 65  VALUES(%Q)", zTe
1e950 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33  xt);.**  sqlite3
1e960 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20  _exec(db, zSQL, 
1e970 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71  0, 0, 0);.**  sq
1e980 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29  lite3_free(zSQL)
1e990 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
1e9a0 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
1e9b0 68 65 20 63 6f 64 65 20 61 62 6f 76 65 20 77 69  he code above wi
1e9c0 6c 6c 20 72 65 6e 64 65 72 20 61 20 63 6f 72 72  ll render a corr
1e9d0 65 63 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ect SQL statemen
1e9e0 74 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a  t in the zSQL.**
1e9f0 20 76 61 72 69 61 62 6c 65 20 65 76 65 6e 20 69   variable even i
1ea00 66 20 74 68 65 20 7a 54 65 78 74 20 76 61 72 69  f the zText vari
1ea10 61 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20 70  able is a NULL p
1ea20 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ointer..**.** ^(
1ea30 54 68 65 20 22 25 77 22 20 66 6f 72 6d 61 74 74  The "%w" formatt
1ea40 69 6e 67 20 6f 70 74 69 6f 6e 20 69 73 20 6c 69  ing option is li
1ea50 6b 65 20 22 25 71 22 20 65 78 63 65 70 74 20 74  ke "%q" except t
1ea60 68 61 74 20 69 74 20 65 78 70 65 63 74 73 20 74  hat it expects t
1ea70 6f 0a 2a 2a 20 62 65 20 63 6f 6e 74 61 69 6e 65  o.** be containe
1ea80 64 20 77 69 74 68 69 6e 20 64 6f 75 62 6c 65 2d  d within double-
1ea90 71 75 6f 74 65 73 20 69 6e 73 74 65 61 64 20 6f  quotes instead o
1eaa0 66 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 2c  f single quotes,
1eab0 20 61 6e 64 20 69 74 0a 2a 2a 20 65 73 63 61 70   and it.** escap
1eac0 65 73 20 74 68 65 20 64 6f 75 62 6c 65 2d 71 75  es the double-qu
1ead0 6f 74 65 20 63 68 61 72 61 63 74 65 72 20 69 6e  ote character in
1eae0 73 74 65 61 64 20 6f 66 20 74 68 65 20 73 69 6e  stead of the sin
1eaf0 67 6c 65 2d 71 75 6f 74 65 0a 2a 2a 20 63 68 61  gle-quote.** cha
1eb00 72 61 63 74 65 72 2e 29 5e 20 20 54 68 65 20 22  racter.)^  The "
1eb10 25 77 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f  %w" formatting o
1eb20 70 74 69 6f 6e 20 69 73 20 69 6e 74 65 6e 64 65  ption is intende
1eb30 64 20 66 6f 72 20 73 61 66 65 6c 79 20 69 6e 73  d for safely ins
1eb40 65 72 74 69 6e 67 0a 2a 2a 20 74 61 62 6c 65 20  erting.** table 
1eb50 61 6e 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 73  and column names
1eb60 20 69 6e 74 6f 20 61 20 63 6f 6e 73 74 72 75 63   into a construc
1eb70 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ted SQL statemen
1eb80 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 22  t..**.** ^(The "
1eb90 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f  %z" formatting o
1eba0 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65  ption works like
1ebb0 20 22 25 73 22 20 62 75 74 20 77 69 74 68 20 74   "%s" but with t
1ebc0 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 20 74  he.** addition t
1ebd0 68 61 74 20 61 66 74 65 72 20 74 68 65 20 73 74  hat after the st
1ebe0 72 69 6e 67 20 68 61 73 20 62 65 65 6e 20 72 65  ring has been re
1ebf0 61 64 20 61 6e 64 20 63 6f 70 69 65 64 20 69 6e  ad and copied in
1ec00 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74  to.** the result
1ec10 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  , [sqlite3_free(
1ec20 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20  )] is called on 
1ec30 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67  the input string
1ec40 2e 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  .)^.*/.SQLITE_AP
1ec50 49 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f 43  I char *SQLITE_C
1ec60 44 45 43 4c 20 73 71 6c 69 74 65 33 5f 6d 70 72  DECL sqlite3_mpr
1ec70 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a  intf(const char*
1ec80 2c 2e 2e 2e 29 3b 0a 53 51 4c 49 54 45 5f 41 50  ,...);.SQLITE_AP
1ec90 49 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f 53  I char *SQLITE_S
1eca0 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76  TDCALL sqlite3_v
1ecb0 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68  mprintf(const ch
1ecc0 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 53  ar*, va_list);.S
1ecd0 51 4c 49 54 45 5f 41 50 49 20 63 68 61 72 20 2a  QLITE_API char *
1ece0 53 51 4c 49 54 45 5f 43 44 45 43 4c 20 73 71 6c  SQLITE_CDECL sql
1ecf0 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 69 6e  ite3_snprintf(in
1ed00 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t,char*,const ch
1ed10 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 53 51 4c 49 54  ar*, ...);.SQLIT
1ed20 45 5f 41 50 49 20 63 68 61 72 20 2a 53 51 4c 49  E_API char *SQLI
1ed30 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
1ed40 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 69 6e 74  e3_vsnprintf(int
1ed50 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61  ,char*,const cha
1ed60 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f  r*, va_list);../
1ed70 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
1ed80 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e  emory Allocation
1ed90 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a   Subsystem.**.**
1eda0 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   The SQLite core
1edb0 20 75 73 65 73 20 74 68 65 73 65 20 74 68 72 65   uses these thre
1edc0 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 61  e routines for a
1edd0 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a  ll of its own.**
1ede0 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79   internal memory
1edf0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64   allocation need
1ee00 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 74 68 65  s. "Core" in the
1ee10 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e   previous senten
1ee20 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69  ce.** does not i
1ee30 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 69 6e 67  nclude operating
1ee40 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 63  -system specific
1ee50 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
1ee60 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e  ion.  The.** Win
1ee70 64 6f 77 73 20 56 46 53 20 75 73 65 73 20 6e 61  dows VFS uses na
1ee80 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e  tive malloc() an
1ee90 64 20 66 72 65 65 28 29 20 66 6f 72 20 73 6f 6d  d free() for som
1eea0 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a  e operations..**
1eeb0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1eec0 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e  _malloc() routin
1eed0 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
1eee0 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a  ter to a block.*
1eef0 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c  * of memory at l
1ef00 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20  east N bytes in 
1ef10 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 20 4e 20  length, where N 
1ef20 69 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  is the parameter
1ef30 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33  ..** ^If sqlite3
1ef40 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61  _malloc() is una
1ef50 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 73 75  ble to obtain su
1ef60 66 66 69 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a  fficient free.**
1ef70 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65 74 75   memory, it retu
1ef80 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  rns a NULL point
1ef90 65 72 2e 20 20 5e 49 66 20 74 68 65 20 70 61 72  er.  ^If the par
1efa0 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73  ameter N to.** s
1efb0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
1efc0 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74  is zero or negat
1efd0 69 76 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ive then sqlite3
1efe0 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e  _malloc() return
1eff0 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  s.** a NULL poin
1f000 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ter..**.** ^The 
1f010 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34  sqlite3_malloc64
1f020 28 4e 29 20 72 6f 75 74 69 6e 65 20 77 6f 72 6b  (N) routine work
1f030 73 20 6a 75 73 74 20 6c 69 6b 65 0a 2a 2a 20 73  s just like.** s
1f040 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29  qlite3_malloc(N)
1f050 20 65 78 63 65 70 74 20 74 68 61 74 20 4e 20 69   except that N i
1f060 73 20 61 6e 20 75 6e 73 69 67 6e 65 64 20 36 34  s an unsigned 64
1f070 2d 62 69 74 20 69 6e 74 65 67 65 72 20 69 6e 73  -bit integer ins
1f080 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20 73 69 67  tead.** of a sig
1f090 6e 65 64 20 33 32 2d 62 69 74 20 69 6e 74 65 67  ned 32-bit integ
1f0a0 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69  er..**.** ^Calli
1f0b0 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  ng sqlite3_free(
1f0c0 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72  ) with a pointer
1f0d0 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75   previously retu
1f0e0 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74  rned.** by sqlit
1f0f0 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73  e3_malloc() or s
1f100 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1f110 20 72 65 6c 65 61 73 65 73 20 74 68 61 74 20 6d   releases that m
1f120 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74  emory so.** that
1f130 20 69 74 20 6d 69 67 68 74 20 62 65 20 72 65 75   it might be reu
1f140 73 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  sed.  ^The sqlit
1f150 65 33 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e  e3_free() routin
1f160 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20  e is.** a no-op 
1f170 69 66 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74  if is called wit
1f180 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  h a NULL pointer
1f190 2e 20 20 50 61 73 73 69 6e 67 20 61 20 4e 55 4c  .  Passing a NUL
1f1a0 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20  L pointer.** to 
1f1b0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69  sqlite3_free() i
1f1c0 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 41 66 74  s harmless.  Aft
1f1d0 65 72 20 62 65 69 6e 67 20 66 72 65 65 64 2c 20  er being freed, 
1f1e0 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64  memory.** should
1f1f0 20 6e 65 69 74 68 65 72 20 62 65 20 72 65 61 64   neither be read
1f200 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20 20 45   nor written.  E
1f210 76 65 6e 20 72 65 61 64 69 6e 67 20 70 72 65 76  ven reading prev
1f220 69 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20  iously freed.** 
1f230 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 72 65 73  memory might res
1f240 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 6e 74  ult in a segment
1f250 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f  ation fault or o
1f260 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f  ther severe erro
1f270 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72  r..** Memory cor
1f280 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65  ruption, a segme
1f290 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f  ntation fault, o
1f2a0 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65  r other severe e
1f2b0 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65  rror.** might re
1f2c0 73 75 6c 74 20 69 66 20 73 71 6c 69 74 65 33 5f  sult if sqlite3_
1f2d0 66 72 65 65 28 29 20 69 73 20 63 61 6c 6c 65 64  free() is called
1f2e0 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c   with a non-NULL
1f2f0 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a   pointer that.**
1f300 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65   was not obtaine
1f310 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d  d from sqlite3_m
1f320 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74  alloc() or sqlit
1f330 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a  e3_realloc()..**
1f340 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1f350 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 69 6e  _realloc(X,N) in
1f360 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73  terface attempts
1f370 20 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20   to resize a.** 
1f380 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c  prior memory all
1f390 6f 63 61 74 69 6f 6e 20 58 20 74 6f 20 62 65 20  ocation X to be 
1f3a0 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73  at least N bytes
1f3b0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 58 20 70  ..** ^If the X p
1f3c0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
1f3d0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29  te3_realloc(X,N)
1f3e0 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  .** is a NULL po
1f3f0 69 6e 74 65 72 20 74 68 65 6e 20 69 74 73 20 62  inter then its b
1f400 65 68 61 76 69 6f 72 20 69 73 20 69 64 65 6e 74  ehavior is ident
1f410 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a  ical to calling.
1f420 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  ** sqlite3_mallo
1f430 63 28 4e 29 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  c(N)..** ^If the
1f440 20 4e 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20   N parameter to 
1f450 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1f460 58 2c 4e 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a  X,N) is zero or.
1f470 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e  ** negative then
1f480 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
1f490 20 65 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d   exactly the sam
1f4a0 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20  e as calling.** 
1f4b0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 58 29 2e  sqlite3_free(X).
1f4c0 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65 61  .** ^sqlite3_rea
1f4d0 6c 6c 6f 63 28 58 2c 4e 29 20 72 65 74 75 72 6e  lloc(X,N) return
1f4e0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
1f4f0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
1f500 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73  on.** of at leas
1f510 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a  t N bytes in siz
1f520 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 69 6e 73  e or NULL if ins
1f530 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79  ufficient memory
1f540 20 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a   is available..*
1f550 2a 20 5e 49 66 20 4d 20 69 73 20 74 68 65 20 73  * ^If M is the s
1f560 69 7a 65 20 6f 66 20 74 68 65 20 70 72 69 6f 72  ize of the prior
1f570 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65   allocation, the
1f580 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73  n min(N,M) bytes
1f590 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 6f 72  .** of the prior
1f5a0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20   allocation are 
1f5b0 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 65 20  copied into the 
1f5c0 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66  beginning of buf
1f5d0 66 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  fer returned.** 
1f5e0 62 79 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  by sqlite3_reall
1f5f0 6f 63 28 58 2c 4e 29 20 61 6e 64 20 74 68 65 20  oc(X,N) and the 
1f600 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
1f610 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49   is freed..** ^I
1f620 66 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  f sqlite3_reallo
1f630 63 28 58 2c 4e 29 20 72 65 74 75 72 6e 73 20 4e  c(X,N) returns N
1f640 55 4c 4c 20 61 6e 64 20 4e 20 69 73 20 70 6f 73  ULL and N is pos
1f650 69 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 0a  itive, then the.
1f660 2a 2a 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  ** prior allocat
1f670 69 6f 6e 20 69 73 20 6e 6f 74 20 66 72 65 65 64  ion is not freed
1f680 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
1f690 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 58  ite3_realloc64(X
1f6a0 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 73 20 77  ,N) interfaces w
1f6b0 6f 72 6b 73 20 74 68 65 20 73 61 6d 65 20 61 73  orks the same as
1f6c0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  .** sqlite3_real
1f6d0 6c 6f 63 28 58 2c 4e 29 20 65 78 63 65 70 74 20  loc(X,N) except 
1f6e0 74 68 61 74 20 4e 20 69 73 20 61 20 36 34 2d 62  that N is a 64-b
1f6f0 69 74 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65  it unsigned inte
1f700 67 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f  ger instead.** o
1f710 66 20 61 20 33 32 2d 62 69 74 20 73 69 67 6e 65  f a 32-bit signe
1f720 64 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a  d integer..**.**
1f730 20 5e 49 66 20 58 20 69 73 20 61 20 6d 65 6d 6f   ^If X is a memo
1f740 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 70 72  ry allocation pr
1f750 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65  eviously obtaine
1f760 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d  d from sqlite3_m
1f770 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c 69  alloc(),.** sqli
1f780 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c 20  te3_malloc64(), 
1f790 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1f7a0 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  ), or sqlite3_re
1f7b0 61 6c 6c 6f 63 36 34 28 29 2c 20 74 68 65 6e 0a  alloc64(), then.
1f7c0 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65  ** sqlite3_msize
1f7d0 28 58 29 20 72 65 74 75 72 6e 73 20 74 68 65 20  (X) returns the 
1f7e0 73 69 7a 65 20 6f 66 20 74 68 61 74 20 6d 65 6d  size of that mem
1f7f0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69  ory allocation i
1f800 6e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 54 68 65  n bytes..** ^The
1f810 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
1f820 62 79 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65  by sqlite3_msize
1f830 28 58 29 20 6d 69 67 68 74 20 62 65 20 6c 61 72  (X) might be lar
1f840 67 65 72 20 74 68 61 6e 20 74 68 65 20 6e 75 6d  ger than the num
1f850 62 65 72 0a 2a 2a 20 6f 66 20 62 79 74 65 73 20  ber.** of bytes 
1f860 72 65 71 75 65 73 74 65 64 20 77 68 65 6e 20 58  requested when X
1f870 20 77 61 73 20 61 6c 6c 6f 63 61 74 65 64 2e 20   was allocated. 
1f880 20 5e 49 66 20 58 20 69 73 20 61 20 4e 55 4c 4c   ^If X is a NULL
1f890 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 0a 2a 2a   pointer then.**
1f8a0 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58   sqlite3_msize(X
1f8b0 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 20  ) returns zero. 
1f8c0 20 49 66 20 58 20 70 6f 69 6e 74 73 20 74 6f 20   If X points to 
1f8d0 73 6f 6d 65 74 68 69 6e 67 20 74 68 61 74 20 69  something that i
1f8e0 73 20 6e 6f 74 0a 2a 2a 20 74 68 65 20 62 65 67  s not.** the beg
1f8f0 69 6e 6e 69 6e 67 20 6f 66 20 6d 65 6d 6f 72 79  inning of memory
1f900 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 6f 72 20   allocation, or 
1f910 69 66 20 69 74 20 70 6f 69 6e 74 73 20 74 6f 20  if it points to 
1f920 61 20 66 6f 72 6d 65 72 6c 79 0a 2a 2a 20 76 61  a formerly.** va
1f930 6c 69 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  lid memory alloc
1f940 61 74 69 6f 6e 20 74 68 61 74 20 68 61 73 20 6e  ation that has n
1f950 6f 77 20 62 65 65 6e 20 66 72 65 65 64 2c 20 74  ow been freed, t
1f960 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
1f970 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6d  .** of sqlite3_m
1f980 73 69 7a 65 28 58 29 20 69 73 20 75 6e 64 65 66  size(X) is undef
1f990 69 6e 65 64 20 61 6e 64 20 70 6f 73 73 69 62 6c  ined and possibl
1f9a0 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a  y harmful..**.**
1f9b0 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 72 65 74   ^The memory ret
1f9c0 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
1f9d0 5f 6d 61 6c 6c 6f 63 28 29 2c 20 73 71 6c 69 74  _malloc(), sqlit
1f9e0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2c 0a 2a 2a  e3_realloc(),.**
1f9f0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36   sqlite3_malloc6
1fa00 34 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33  4(), and sqlite3
1fa10 5f 72 65 61 6c 6c 6f 63 36 34 28 29 0a 2a 2a 20  _realloc64().** 
1fa20 69 73 20 61 6c 77 61 79 73 20 61 6c 69 67 6e 65  is always aligne
1fa30 64 20 74 6f 20 61 74 20 6c 65 61 73 74 20 61 6e  d to at least an
1fa40 20 38 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79   8 byte boundary
1fa50 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a 20 34 20 62  , or to a.** 4 b
1fa60 79 74 65 20 62 6f 75 6e 64 61 72 79 20 69 66 20  yte boundary if 
1fa70 74 68 65 20 5b 53 51 4c 49 54 45 5f 34 5f 42 59  the [SQLITE_4_BY
1fa80 54 45 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f  TE_ALIGNED_MALLO
1fa90 43 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a  C] compile-time.
1faa0 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  ** option is use
1fab0 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69  d..**.** In SQLi
1fac0 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30  te version 3.5.0
1fad0 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20 77   and 3.5.1, it w
1fae0 61 73 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 64  as possible to d
1faf0 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51 4c  efine.** the SQL
1fb00 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f  ITE_OMIT_MEMORY_
1fb10 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63 68  ALLOCATION which
1fb20 20 77 6f 75 6c 64 20 63 61 75 73 65 20 74 68 65   would cause the
1fb30 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70   built-in.** imp
1fb40 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74  lementation of t
1fb50 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 6f  hese routines to
1fb60 20 62 65 20 6f 6d 69 74 74 65 64 2e 20 20 54 68   be omitted.  Th
1fb70 61 74 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a  at capability.**
1fb80 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70 72   is no longer pr
1fb90 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62 75  ovided.  Only bu
1fba0 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c  ilt-in memory al
1fbb0 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20 62 65 20  locators can be 
1fbc0 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f  used..**.** Prio
1fbd0 72 20 74 6f 20 53 51 4c 69 74 65 20 76 65 72 73  r to SQLite vers
1fbe0 69 6f 6e 20 33 2e 37 2e 31 30 2c 20 74 68 65 20  ion 3.7.10, the 
1fbf0 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65 72  Windows OS inter
1fc00 66 61 63 65 20 6c 61 79 65 72 20 63 61 6c 6c 65  face layer calle
1fc10 64 0a 2a 2a 20 74 68 65 20 73 79 73 74 65 6d 20  d.** the system 
1fc20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65  malloc() and fre
1fc30 65 28 29 20 64 69 72 65 63 74 6c 79 20 77 68 65  e() directly whe
1fc40 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20  n converting.** 
1fc50 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 77 65 65  filenames betwee
1fc60 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f  n the UTF-8 enco
1fc70 64 69 6e 67 20 75 73 65 64 20 62 79 20 53 51 4c  ding used by SQL
1fc80 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65  ite.** and whate
1fc90 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63  ver filename enc
1fca0 6f 64 69 6e 67 20 69 73 20 75 73 65 64 20 62 79  oding is used by
1fcb0 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20   the particular 
1fcc0 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61  Windows.** insta
1fcd0 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79  llation.  Memory
1fce0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f   allocation erro
1fcf0 72 73 20 77 65 72 65 20 64 65 74 65 63 74 65 64  rs were detected
1fd00 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79 20 77 65  , but.** they we
1fd10 72 65 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b  re reported back
1fd20 20 61 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54   as [SQLITE_CANT
1fd30 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c  OPEN] or.** [SQL
1fd40 49 54 45 5f 49 4f 45 52 52 5d 20 72 61 74 68 65  ITE_IOERR] rathe
1fd50 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e  r than [SQLITE_N
1fd60 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  OMEM]..**.** The
1fd70 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e   pointer argumen
1fd80 74 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  ts to [sqlite3_f
1fd90 72 65 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ree()] and [sqli
1fda0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a  te3_realloc()].*
1fdb0 2a 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72  * must be either
1fdc0 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70 6f   NULL or else po
1fdd0 69 6e 74 65 72 73 20 6f 62 74 61 69 6e 65 64 20  inters obtained 
1fde0 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20  from a prior.** 
1fdf0 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73  invocation of [s
1fe00 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
1fe10 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61   or [sqlite3_rea
1fe20 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 68 61 76  lloc()] that hav
1fe30 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62 65 65  e.** not yet bee
1fe40 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a  n released..**.*
1fe50 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
1fe60 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65 61 64 20  n must not read 
1fe70 6f 72 20 77 72 69 74 65 20 61 6e 79 20 70 61 72  or write any par
1fe80 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20  t of.** a block 
1fe90 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 65 72 20  of memory after 
1fea0 69 74 20 68 61 73 20 62 65 65 6e 20 72 65 6c 65  it has been rele
1feb0 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  ased using.** [s
1fec0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f  qlite3_free()] o
1fed0 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  r [sqlite3_reall
1fee0 6f 63 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45  oc()]..*/.SQLITE
1fef0 5f 41 50 49 20 76 6f 69 64 20 2a 53 51 4c 49 54  _API void *SQLIT
1ff00 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
1ff10 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 53  3_malloc(int);.S
1ff20 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a  QLITE_API void *
1ff30 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
1ff40 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28  qlite3_malloc64(
1ff50 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 3b  sqlite3_uint64);
1ff60 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
1ff70 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c   *SQLITE_STDCALL
1ff80 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1ff90 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 53 51  (void*, int);.SQ
1ffa0 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 53  LITE_API void *S
1ffb0 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
1ffc0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28  lite3_realloc64(
1ffd0 76 6f 69 64 2a 2c 20 73 71 6c 69 74 65 33 5f 75  void*, sqlite3_u
1ffe0 69 6e 74 36 34 29 3b 0a 53 51 4c 49 54 45 5f 41  int64);.SQLITE_A
1fff0 50 49 20 76 6f 69 64 20 53 51 4c 49 54 45 5f 53  PI void SQLITE_S
20000 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 66  TDCALL sqlite3_f
20010 72 65 65 28 76 6f 69 64 2a 29 3b 0a 53 51 4c 49  ree(void*);.SQLI
20020 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 75  TE_API sqlite3_u
20030 69 6e 74 36 34 20 53 51 4c 49 54 45 5f 53 54 44  int64 SQLITE_STD
20040 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6d 73 69  CALL sqlite3_msi
20050 7a 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a  ze(void*);../*.*
20060 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f  * CAPI3REF: Memo
20070 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61  ry Allocator Sta
20080 74 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51  tistics.**.** SQ
20090 4c 69 74 65 20 70 72 6f 76 69 64 65 73 20 74 68  Lite provides th
200a0 65 73 65 20 74 77 6f 20 69 6e 74 65 72 66 61 63  ese two interfac
200b0 65 73 20 66 6f 72 20 72 65 70 6f 72 74 69 6e 67  es for reporting
200c0 20 6f 6e 20 74 68 65 20 73 74 61 74 75 73 0a 2a   on the status.*
200d0 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * of the [sqlite
200e0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71  3_malloc()], [sq
200f0 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2c 20 61  lite3_free()], a
20100 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  nd [sqlite3_real
20110 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e  loc()].** routin
20120 65 73 2c 20 77 68 69 63 68 20 66 6f 72 6d 20 74  es, which form t
20130 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f  he built-in memo
20140 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75  ry allocation su
20150 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e  bsystem..**.** ^
20160 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  The [sqlite3_mem
20170 6f 72 79 5f 75 73 65 64 28 29 5d 20 72 6f 75 74  ory_used()] rout
20180 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ine returns the 
20190 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 0a  number of bytes.
201a0 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72  ** of memory cur
201b0 72 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64 69  rently outstandi
201c0 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74  ng (malloced but
201d0 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a 20   not freed)..** 
201e0 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65  ^The [sqlite3_me
201f0 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
20200 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ] routine return
20210 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a  s the maximum.**
20220 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74   value of [sqlit
20230 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
20240 5d 20 73 69 6e 63 65 20 74 68 65 20 68 69 67 68  ] since the high
20250 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 77  -water mark.** w
20260 61 73 20 6c 61 73 74 20 72 65 73 65 74 2e 20 20  as last reset.  
20270 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 75  ^The values retu
20280 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
20290 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20  _memory_used()] 
202a0 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
202b0 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
202c0 28 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79 20  ()] include any 
202d0 6f 76 65 72 68 65 61 64 0a 2a 2a 20 61 64 64 65  overhead.** adde
202e0 64 20 62 79 20 53 51 4c 69 74 65 20 69 6e 20 69  d by SQLite in i
202f0 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ts implementatio
20300 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61  n of [sqlite3_ma
20310 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75 74 20  lloc()],.** but 
20320 6e 6f 74 20 6f 76 65 72 68 65 61 64 20 61 64 64  not overhead add
20330 65 64 20 62 79 20 74 68 65 20 61 6e 79 20 75 6e  ed by the any un
20340 64 65 72 6c 79 69 6e 67 20 73 79 73 74 65 6d 20  derlying system 
20350 6c 69 62 72 61 72 79 0a 2a 2a 20 72 6f 75 74 69  library.** routi
20360 6e 65 73 20 74 68 61 74 20 5b 73 71 6c 69 74 65  nes that [sqlite
20370 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20  3_malloc()] may 
20380 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  call..**.** ^The
20390 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77 61 74   memory high-wat
203a0 65 72 20 6d 61 72 6b 20 69 73 20 72 65 73 65 74  er mark is reset
203b0 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20   to the current 
203c0 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c  value of.** [sql
203d0 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
203e0 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20  ()] if and only 
203f0 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
20400 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
20410 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
20420 28 29 5d 20 69 73 20 74 72 75 65 2e 20 20 5e 54  ()] is true.  ^T
20430 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
20440 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33  d.** by [sqlite3
20450 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
20460 72 28 31 29 5d 20 69 73 20 74 68 65 20 68 69 67  r(1)] is the hig
20470 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20  h-water mark.** 
20480 70 72 69 6f 72 20 74 6f 20 74 68 65 20 72 65 73  prior to the res
20490 65 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  et..*/.SQLITE_AP
204a0 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  I sqlite3_int64 
204b0 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
204c0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
204d0 65 64 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45  ed(void);.SQLITE
204e0 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74  _API sqlite3_int
204f0 36 34 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  64 SQLITE_STDCAL
20500 4c 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79  L sqlite3_memory
20510 5f 68 69 67 68 77 61 74 65 72 28 69 6e 74 20 72  _highwater(int r
20520 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a  esetFlag);../*.*
20530 2a 20 43 41 50 49 33 52 45 46 3a 20 50 73 65 75  * CAPI3REF: Pseu
20540 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72  do-Random Number
20550 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a   Generator.**.**
20560 20 53 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73   SQLite contains
20570 20 61 20 68 69 67 68 2d 71 75 61 6c 69 74 79 20   a high-quality 
20580 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75  pseudo-random nu
20590 6d 62 65 72 20 67 65 6e 65 72 61 74 6f 72 20 28  mber generator (
205a0 50 52 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a  PRNG) used to.**
205b0 20 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20 5b   select random [
205c0 52 4f 57 49 44 20 7c 20 52 4f 57 49 44 73 5d 20  ROWID | ROWIDs] 
205d0 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e  when inserting n
205e0 65 77 20 72 65 63 6f 72 64 73 20 69 6e 74 6f 20  ew records into 
205f0 61 20 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20  a table that.** 
20600 61 6c 72 65 61 64 79 20 75 73 65 73 20 74 68 65  already uses the
20610 20 6c 61 72 67 65 73 74 20 70 6f 73 73 69 62 6c   largest possibl
20620 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68 65 20  e [ROWID].  The 
20630 50 52 4e 47 20 69 73 20 61 6c 73 6f 20 75 73 65  PRNG is also use
20640 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69  d for.** the bui
20650 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61  ld-in random() a
20660 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20  nd randomblob() 
20670 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20  SQL functions.  
20680 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61  This interface a
20690 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61  llows.** applica
206a0 74 69 6f 6e 73 20 74 6f 20 61 63 63 65 73 73 20  tions to access 
206b0 74 68 65 20 73 61 6d 65 20 50 52 4e 47 20 66 6f  the same PRNG fo
206c0 72 20 6f 74 68 65 72 20 70 75 72 70 6f 73 65 73  r other purposes
206d0 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20  ..**.** ^A call 
206e0 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  to this routine 
206f0 73 74 6f 72 65 73 20 4e 20 62 79 74 65 73 20 6f  stores N bytes o
20700 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74  f randomness int
20710 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a 20 5e  o buffer P..** ^
20720 54 68 65 20 50 20 70 61 72 61 6d 65 74 65 72 20  The P parameter 
20730 63 61 6e 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f  can be a NULL po
20740 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  inter..**.** ^If
20750 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 68 61   this routine ha
20760 73 20 6e 6f 74 20 62 65 65 6e 20 70 72 65 76 69  s not been previ
20770 6f 75 73 6c 79 20 63 61 6c 6c 65 64 20 6f 72 20  ously called or 
20780 69 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 0a  if the previous.
20790 2a 2a 20 63 61 6c 6c 20 68 61 64 20 4e 20 6c 65  ** call had N le
207a0 73 73 20 74 68 61 6e 20 6f 6e 65 20 6f 72 20 61  ss than one or a
207b0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f   NULL pointer fo
207c0 72 20 50 2c 20 74 68 65 6e 20 74 68 65 20 50 52  r P, then the PR
207d0 4e 47 20 69 73 0a 2a 2a 20 73 65 65 64 65 64 20  NG is.** seeded 
207e0 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73  using randomness
207f0 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 74   obtained from t
20800 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d  he xRandomness m
20810 65 74 68 6f 64 20 6f 66 0a 2a 2a 20 74 68 65 20  ethod of.** the 
20820 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
20830 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  _vfs] object..**
20840 20 5e 49 66 20 74 68 65 20 70 72 65 76 69 6f 75   ^If the previou
20850 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72  s call to this r
20860 6f 75 74 69 6e 65 20 68 61 64 20 61 6e 20 4e 20  outine had an N 
20870 6f 66 20 31 20 6f 72 20 6d 6f 72 65 20 61 6e 64  of 1 or more and
20880 20 61 0a 2a 2a 20 6e 6f 6e 2d 4e 55 4c 4c 20 50   a.** non-NULL P
20890 20 74 68 65 6e 20 74 68 65 20 70 73 65 75 64 6f   then the pseudo
208a0 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67  -randomness is g
208b0 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65  enerated.** inte
208c0 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f  rnally and witho
208d0 75 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20 74  ut recourse to t
208e0 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  he [sqlite3_vfs]
208f0 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20   xRandomness.** 
20900 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 53 51 4c 49 54  method..*/.SQLIT
20910 45 5f 41 50 49 20 76 6f 69 64 20 53 51 4c 49 54  E_API void SQLIT
20920 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
20930 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e 74  3_randomness(int
20940 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f   N, void *P);../
20950 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
20960 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75 74 68  ompile-Time Auth
20970 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 61  orization Callba
20980 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  cks.** METHOD: s
20990 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68  qlite3.**.** ^Th
209a0 69 73 20 72 6f 75 74 69 6e 65 20 72 65 67 69 73  is routine regis
209b0 74 65 72 73 20 61 6e 20 61 75 74 68 6f 72 69 7a  ters an authoriz
209c0 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 68  er callback with
209d0 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a   a particular.**
209e0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
209f0 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 64  ction], supplied
20a00 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
20a10 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20  gument..** ^The 
20a20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
20a30 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 61  ack is invoked a
20a40 73 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  s SQL statements
20a50 20 61 72 65 20 62 65 69 6e 67 20 63 6f 6d 70 69   are being compi
20a60 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74  led.** by [sqlit
20a70 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72  e3_prepare()] or
20a80 20 69 74 73 20 76 61 72 69 61 6e 74 73 20 5b 73   its variants [s
20a90 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
20aa0 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  2()],.** [sqlite
20ab0 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 61  3_prepare16()] a
20ac0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  nd [sqlite3_prep
20ad0 61 72 65 31 36 5f 76 32 28 29 5d 2e 20 20 5e 41  are16_v2()].  ^A
20ae0 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69  t various.** poi
20af0 6e 74 73 20 64 75 72 69 6e 67 20 74 68 65 20 63  nts during the c
20b00 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65  ompilation proce
20b10 73 73 2c 20 61 73 20 6c 6f 67 69 63 20 69 73 20  ss, as logic is 
20b20 62 65 69 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a  being created.**
20b30 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69   to perform vari
20b40 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20 74 68 65  ous actions, the
20b50 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
20b60 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
20b70 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74 68 6f  to.** see if tho
20b80 73 65 20 61 63 74 69 6f 6e 73 20 61 72 65 20 61  se actions are a
20b90 6c 6c 6f 77 65 64 2e 20 20 5e 54 68 65 20 61 75  llowed.  ^The au
20ba0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
20bb0 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75  k should.** retu
20bc0 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74  rn [SQLITE_OK] t
20bd0 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61 63 74 69  o allow the acti
20be0 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  on, [SQLITE_IGNO
20bf0 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20  RE] to disallow 
20c00 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20  the.** specific 
20c10 61 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77  action but allow
20c20 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
20c30 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74  nt to continue t
20c40 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64  o be.** compiled
20c50 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e  , or [SQLITE_DEN
20c60 59 5d 20 74 6f 20 63 61 75 73 65 20 74 68 65 20  Y] to cause the 
20c70 65 6e 74 69 72 65 20 53 51 4c 20 73 74 61 74 65  entire SQL state
20c80 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65  ment to be.** re
20c90 6a 65 63 74 65 64 20 77 69 74 68 20 61 6e 20 65  jected with an e
20ca0 72 72 6f 72 2e 20 20 5e 49 66 20 74 68 65 20 61  rror.  ^If the a
20cb0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
20cc0 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e  ck returns.** an
20cd0 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68  y value other th
20ce0 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  an [SQLITE_IGNOR
20cf0 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c  E], [SQLITE_OK],
20d00 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59   or [SQLITE_DENY
20d10 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b 73  ].** then the [s
20d20 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
20d30 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65  2()] or equivale
20d40 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69  nt call that tri
20d50 67 67 65 72 65 64 0a 2a 2a 20 74 68 65 20 61 75  ggered.** the au
20d60 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61  thorizer will fa
20d70 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72  il with an error
20d80 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20   message..**.** 
20d90 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63  When the callbac
20da0 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  k returns [SQLIT
20db0 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e  E_OK], that mean
20dc0 73 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a  s the operation.
20dd0 2a 2a 20 72 65 71 75 65 73 74 65 64 20 69 73 20  ** requested is 
20de0 6f 6b 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 63  ok.  ^When the c
20df0 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
20e00 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74  [SQLITE_DENY], t
20e10 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  he.** [sqlite3_p
20e20 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
20e30 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20  equivalent call 
20e40 74 68 61 74 20 74 72 69 67 67 65 72 65 64 20 74  that triggered t
20e50 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72  he.** authorizer
20e60 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20   will fail with 
20e70 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  an error message
20e80 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68 61 74   explaining that
20e90 0a 2a 2a 20 61 63 63 65 73 73 20 69 73 20 64 65  .** access is de
20ea0 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68  nied. .**.** ^Th
20eb0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
20ec0 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69  r to the authori
20ed0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
20ee0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68  a copy of the th
20ef0 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ird.** parameter
20f00 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
20f10 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29  set_authorizer()
20f20 20 69 6e 74 65 72 66 61 63 65 2e 20 5e 54 68 65   interface. ^The
20f30 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
20f40 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c  r.** to the call
20f50 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67  back is an integ
20f60 65 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20  er [SQLITE_COPY 
20f70 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74  | action code] t
20f80 68 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  hat specifies.**
20f90 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20   the particular 
20fa0 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74  action to be aut
20fb0 68 6f 72 69 7a 65 64 2e 20 5e 54 68 65 20 74 68  horized. ^The th
20fc0 69 72 64 20 74 68 72 6f 75 67 68 20 73 69 78 74  ird through sixt
20fd0 68 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20  h parameters.** 
20fe0 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
20ff0 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  are zero-termina
21000 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74  ted strings that
21010 20 63 6f 6e 74 61 69 6e 20 61 64 64 69 74 69 6f   contain additio
21020 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 6c 73 20 61  nal.** details a
21030 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f 6e 20  bout the action 
21040 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64  to be authorized
21050 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
21060 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b  action code is [
21070 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20  SQLITE_READ].** 
21080 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  and the callback
21090 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
210a0 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68  _IGNORE] then th
210b0 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
210c0 74 61 74 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d  tatement] statem
210d0 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 75 63 74  ent is construct
210e0 65 64 20 74 6f 20 73 75 62 73 74 69 74 75 74 65  ed to substitute
210f0 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65  .** a NULL value
21100 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65   in place of the
21110 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68   table column th
21120 61 74 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a  at would have.**
21130 20 62 65 65 6e 20 72 65 61 64 20 69 66 20 5b 53   been read if [S
21140 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65  QLITE_OK] had be
21150 65 6e 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68  en returned.  Th
21160 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  e [SQLITE_IGNORE
21170 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e 20  ].** return can 
21180 62 65 20 75 73 65 64 20 74 6f 20 64 65 6e 79 20  be used to deny 
21190 61 6e 20 75 6e 74 72 75 73 74 65 64 20 75 73 65  an untrusted use
211a0 72 20 61 63 63 65 73 73 20 74 6f 20 69 6e 64 69  r access to indi
211b0 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e  vidual.** column
211c0 73 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a  s of a table..**
211d0 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20   ^If the action 
211e0 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f  code is [SQLITE_
211f0 44 45 4c 45 54 45 5d 20 61 6e 64 20 74 68 65 20  DELETE] and the 
21200 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
21210 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  .** [SQLITE_IGNO
21220 52 45 5d 20 74 68 65 6e 20 74 68 65 20 5b 44 45  RE] then the [DE
21230 4c 45 54 45 5d 20 6f 70 65 72 61 74 69 6f 6e 20  LETE] operation 
21240 70 72 6f 63 65 65 64 73 20 62 75 74 20 74 68 65  proceeds but the
21250 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 65 20 6f 70  .** [truncate op
21260 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 69 73 20 64  timization] is d
21270 69 73 61 62 6c 65 64 20 61 6e 64 20 61 6c 6c 20  isabled and all 
21280 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65 64  rows are deleted
21290 20 69 6e 64 69 76 69 64 75 61 6c 6c 79 2e 0a 2a   individually..*
212a0 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a  *.** An authoriz
212b0 65 72 20 69 73 20 75 73 65 64 20 77 68 65 6e 20  er is used when 
212c0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
212d0 20 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a 2a   | preparing].**
212e0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
212f0 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74 65  from an untruste
21300 64 20 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73  d source, to ens
21310 75 72 65 20 74 68 61 74 20 74 68 65 20 53 51 4c  ure that the SQL
21320 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 64   statements.** d
21330 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20 61 63 63  o not try to acc
21340 65 73 73 20 64 61 74 61 20 74 68 65 79 20 61 72  ess data they ar
21350 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f  e not allowed to
21360 20 73 65 65 2c 20 6f 72 20 74 68 61 74 20 74 68   see, or that th
21370 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79  ey do not.** try
21380 20 74 6f 20 65 78 65 63 75 74 65 20 6d 61 6c 69   to execute mali
21390 63 69 6f 75 73 20 73 74 61 74 65 6d 65 6e 74 73  cious statements
213a0 20 74 68 61 74 20 64 61 6d 61 67 65 20 74 68 65   that damage the
213b0 20 64 61 74 61 62 61 73 65 2e 20 20 46 6f 72 0a   database.  For.
213c0 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61  ** example, an a
213d0 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20 61  pplication may a
213e0 6c 6c 6f 77 20 61 20 75 73 65 72 20 74 6f 20 65  llow a user to e
213f0 6e 74 65 72 20 61 72 62 69 74 72 61 72 79 0a 2a  nter arbitrary.*
21400 2a 20 53 51 4c 20 71 75 65 72 69 65 73 20 66 6f  * SQL queries fo
21410 72 20 65 76 61 6c 75 61 74 69 6f 6e 20 62 79 20  r evaluation by 
21420 61 20 64 61 74 61 62 61 73 65 2e 20 20 42 75 74  a database.  But
21430 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
21440 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e   does.** not wan
21450 74 20 74 68 65 20 75 73 65 72 20 74 6f 20 62 65  t the user to be
21460 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72   able to make ar
21470 62 69 74 72 61 72 79 20 63 68 61 6e 67 65 73 20  bitrary changes 
21480 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  to the.** databa
21490 73 65 2e 20 20 41 6e 20 61 75 74 68 6f 72 69 7a  se.  An authoriz
214a0 65 72 20 63 6f 75 6c 64 20 74 68 65 6e 20 62 65  er could then be
214b0 20 70 75 74 20 69 6e 20 70 6c 61 63 65 20 77 68   put in place wh
214c0 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d  ile the.** user-
214d0 65 6e 74 65 72 65 64 20 53 51 4c 20 69 73 20 62  entered SQL is b
214e0 65 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72  eing [sqlite3_pr
214f0 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 65 64  epare | prepared
21500 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c 6c  ] that.** disall
21510 6f 77 73 20 65 76 65 72 79 74 68 69 6e 67 20 65  ows everything e
21520 78 63 65 70 74 20 5b 53 45 4c 45 43 54 5d 20 73  xcept [SELECT] s
21530 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  tatements..**.**
21540 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   Applications th
21550 61 74 20 6e 65 65 64 20 74 6f 20 70 72 6f 63 65  at need to proce
21560 73 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74 72  ss SQL from untr
21570 75 73 74 65 64 20 73 6f 75 72 63 65 73 0a 2a 2a  usted sources.**
21580 20 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e 73   might also cons
21590 69 64 65 72 20 6c 6f 77 65 72 69 6e 67 20 72 65  ider lowering re
215a0 73 6f 75 72 63 65 20 6c 69 6d 69 74 73 20 75 73  source limits us
215b0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d  ing [sqlite3_lim
215c0 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d  it()].** and lim
215d0 69 74 69 6e 67 20 64 61 74 61 62 61 73 65 20 73  iting database s
215e0 69 7a 65 20 75 73 69 6e 67 20 74 68 65 20 5b 6d  ize using the [m
215f0 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b  ax_page_count] [
21600 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64  PRAGMA].** in ad
21610 64 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67 20  dition to using 
21620 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a  an authorizer..*
21630 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20 73 69  *.** ^(Only a si
21640 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a 65 72 20  ngle authorizer 
21650 63 61 6e 20 62 65 20 69 6e 20 70 6c 61 63 65 20  can be in place 
21660 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 63 6f  on a database co
21670 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61  nnection.** at a
21680 20 74 69 6d 65 2e 20 20 45 61 63 68 20 63 61 6c   time.  Each cal
21690 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74  l to sqlite3_set
216a0 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f 76 65 72  _authorizer over
216b0 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 70 72 65  rides the.** pre
216c0 76 69 6f 75 73 20 63 61 6c 6c 2e 29 5e 20 20 5e  vious call.)^  ^
216d0 44 69 73 61 62 6c 65 20 74 68 65 20 61 75 74 68  Disable the auth
216e0 6f 72 69 7a 65 72 20 62 79 20 69 6e 73 74 61 6c  orizer by instal
216f0 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c  ling a NULL call
21700 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74  back..** The aut
21710 68 6f 72 69 7a 65 72 20 69 73 20 64 69 73 61 62  horizer is disab
21720 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a  led by default..
21730 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72  **.** The author
21740 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75  izer callback mu
21750 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69  st not do anythi
21760 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64  ng that will mod
21770 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  ify.** the datab
21780 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
21790 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20  hat invoked the 
217a0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
217b0 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ack..** Note tha
217c0 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  t [sqlite3_prepa
217d0 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71  re_v2()] and [sq
217e0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f  lite3_step()] bo
217f0 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a  th modify their.
21800 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
21810 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20  ections for the 
21820 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69  meaning of "modi
21830 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61  fy" in this para
21840 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68  graph..**.** ^Wh
21850 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  en [sqlite3_prep
21860 61 72 65 5f 76 32 28 29 5d 20 69 73 20 75 73 65  are_v2()] is use
21870 64 20 74 6f 20 70 72 65 70 61 72 65 20 61 20 73  d to prepare a s
21880 74 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a  tatement, the.**
21890 20 73 74 61 74 65 6d 65 6e 74 20 6d 69 67 68 74   statement might
218a0 20 62 65 20 72 65 2d 70 72 65 70 61 72 65 64 20   be re-prepared 
218b0 64 75 72 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  during [sqlite3_
218c0 73 74 65 70 28 29 5d 20 64 75 65 20 74 6f 20 61  step()] due to a
218d0 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68 61 6e   .** schema chan
218e0 67 65 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20  ge.  Hence, the 
218f0 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
21900 6c 64 20 65 6e 73 75 72 65 20 74 68 61 74 20 74  ld ensure that t
21910 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20 61 75  he.** correct au
21920 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
21930 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20 70 6c 61  k remains in pla
21940 63 65 20 64 75 72 69 6e 67 20 74 68 65 20 5b 73  ce during the [s
21950 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a  qlite3_step()]..
21960 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74  **.** ^Note that
21970 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
21980 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
21990 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67 0a  ked only during.
219a0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
219b0 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61  are()] or its va
219c0 72 69 61 6e 74 73 2e 20 20 41 75 74 68 6f 72 69  riants.  Authori
219d0 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a  zation is not.**
219e0 20 70 65 72 66 6f 72 6d 65 64 20 64 75 72 69 6e   performed durin
219f0 67 20 73 74 61 74 65 6d 65 6e 74 20 65 76 61 6c  g statement eval
21a00 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74  uation in [sqlit
21a10 65 33 5f 73 74 65 70 28 29 5d 2c 20 75 6e 6c 65  e3_step()], unle
21a20 73 73 0a 2a 2a 20 61 73 20 73 74 61 74 65 64 20  ss.** as stated 
21a30 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  in the previous 
21a40 70 61 72 61 67 72 61 70 68 2c 20 73 71 6c 69 74  paragraph, sqlit
21a50 65 33 5f 73 74 65 70 28 29 20 69 6e 76 6f 6b 65  e3_step() invoke
21a60 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 65  s.** sqlite3_pre
21a70 70 61 72 65 5f 76 32 28 29 20 74 6f 20 72 65 70  pare_v2() to rep
21a80 72 65 70 61 72 65 20 61 20 73 74 61 74 65 6d 65  repare a stateme
21a90 6e 74 20 61 66 74 65 72 20 61 20 73 63 68 65 6d  nt after a schem
21aa0 61 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 53 51 4c  a change..*/.SQL
21ab0 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49  ITE_API int SQLI
21ac0 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
21ad0 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
21ae0 72 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20  r(.  sqlite3*,. 
21af0 20 69 6e 74 20 28 2a 78 41 75 74 68 29 28 76 6f   int (*xAuth)(vo
21b00 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68  id*,int,const ch
21b10 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ar*,const char*,
21b20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73  const char*,cons
21b30 74 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64  t char*),.  void
21b40 20 2a 70 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a   *pUserData.);..
21b50 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
21b60 41 75 74 68 6f 72 69 7a 65 72 20 52 65 74 75 72  Authorizer Retur
21b70 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68  n Codes.**.** Th
21b80 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  e [sqlite3_set_a
21b90 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68  uthorizer | auth
21ba0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
21bb0 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a  function] must.*
21bc0 2a 20 72 65 74 75 72 6e 20 65 69 74 68 65 72 20  * return either 
21bd0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f  [SQLITE_OK] or o
21be0 6e 65 20 6f 66 20 74 68 65 73 65 20 74 77 6f 20  ne of these two 
21bf0 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72 64  constants in ord
21c00 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20  er.** to signal 
21c10 53 51 4c 69 74 65 20 77 68 65 74 68 65 72 20 6f  SQLite whether o
21c20 72 20 6e 6f 74 20 74 68 65 20 61 63 74 69 6f 6e  r not the action
21c30 20 69 73 20 70 65 72 6d 69 74 74 65 64 2e 20 20   is permitted.  
21c40 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  See the.** [sqli
21c50 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
21c60 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20  er | authorizer 
21c70 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66  documentation] f
21c80 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  or additional.**
21c90 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
21ca0 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51  .** Note that SQ
21cb0 4c 49 54 45 5f 49 47 4e 4f 52 45 20 69 73 20 61  LITE_IGNORE is a
21cc0 6c 73 6f 20 75 73 65 64 20 61 73 20 61 20 5b 63  lso used as a [c
21cd0 6f 6e 66 6c 69 63 74 20 72 65 73 6f 6c 75 74 69  onflict resoluti
21ce0 6f 6e 20 6d 6f 64 65 5d 0a 2a 2a 20 72 65 74 75  on mode].** retu
21cf0 72 6e 65 64 20 66 72 6f 6d 20 74 68 65 20 5b 73  rned from the [s
21d00 71 6c 69 74 65 33 5f 76 74 61 62 5f 6f 6e 5f 63  qlite3_vtab_on_c
21d10 6f 6e 66 6c 69 63 74 28 29 5d 20 69 6e 74 65 72  onflict()] inter
21d20 66 61 63 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  face..*/.#define
21d30 20 53 51 4c 49 54 45 5f 44 45 4e 59 20 20 20 31   SQLITE_DENY   1
21d40 20 20 20 2f 2a 20 41 62 6f 72 74 20 74 68 65 20     /* Abort the 
21d50 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 69  SQL statement wi
21d60 74 68 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 23  th an error */.#
21d70 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 47  define SQLITE_IG
21d80 4e 4f 52 45 20 32 20 20 20 2f 2a 20 44 6f 6e 27  NORE 2   /* Don'
21d90 74 20 61 6c 6c 6f 77 20 61 63 63 65 73 73 2c 20  t allow access, 
21da0 62 75 74 20 64 6f 6e 27 74 20 67 65 6e 65 72 61  but don't genera
21db0 74 65 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a  te an error */..
21dc0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
21dd0 41 75 74 68 6f 72 69 7a 65 72 20 41 63 74 69 6f  Authorizer Actio
21de0 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68  n Codes.**.** Th
21df0 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  e [sqlite3_set_a
21e00 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74  uthorizer()] int
21e10 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73  erface registers
21e20 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63   a callback func
21e30 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20  tion.** that is 
21e40 69 6e 76 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f  invoked to autho
21e50 72 69 7a 65 20 63 65 72 74 61 69 6e 20 53 51 4c  rize certain SQL
21e60 20 73 74 61 74 65 6d 65 6e 74 20 61 63 74 69 6f   statement actio
21e70 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f  ns.  The.** seco
21e80 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  nd parameter to 
21e90 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  the callback is 
21ea0 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20  an integer code 
21eb0 74 68 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a  that specifies.*
21ec0 2a 20 77 68 61 74 20 61 63 74 69 6f 6e 20 69 73  * what action is
21ed0 20 62 65 69 6e 67 20 61 75 74 68 6f 72 69 7a 65   being authorize
21ee0 64 2e 20 20 54 68 65 73 65 20 61 72 65 20 74 68  d.  These are th
21ef0 65 20 69 6e 74 65 67 65 72 20 61 63 74 69 6f 6e  e integer action
21f00 20 63 6f 64 65 73 20 74 68 61 74 0a 2a 2a 20 74   codes that.** t
21f10 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
21f20 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65 20 70 61  llback may be pa
21f30 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ssed..**.** Thes
21f40 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 76 61  e action code va
21f50 6c 75 65 73 20 73 69 67 6e 69 66 79 20 77 68 61  lues signify wha
21f60 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65 72 61 74  t kind of operat
21f70 69 6f 6e 20 69 73 20 74 6f 20 62 65 0a 2a 2a 20  ion is to be.** 
21f80 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65  authorized.  The
21f90 20 33 72 64 20 61 6e 64 20 34 74 68 20 70 61 72   3rd and 4th par
21fa0 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65 20 61  ameters to the a
21fb0 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20  uthorization.** 
21fc0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
21fd0 6e 20 77 69 6c 6c 20 62 65 20 70 61 72 61 6d 65  n will be parame
21fe0 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70  ters or NULL dep
21ff0 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63 68 20  ending on which 
22000 6f 66 20 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65  of these.** code
22010 73 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65  s is used as the
22020 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
22030 72 2e 20 20 5e 28 54 68 65 20 35 74 68 20 70 61  r.  ^(The 5th pa
22040 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 0a 2a  rameter to the.*
22050 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  * authorizer cal
22060 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e 61 6d  lback is the nam
22070 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  e of the databas
22080 65 20 28 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70  e ("main", "temp
22090 22 2c 0a 2a 2a 20 65 74 63 2e 29 20 69 66 20 61  ",.** etc.) if a
220a0 70 70 6c 69 63 61 62 6c 65 2e 29 5e 20 20 5e 54  pplicable.)^  ^T
220b0 68 65 20 36 74 68 20 70 61 72 61 6d 65 74 65 72  he 6th parameter
220c0 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a   to the authoriz
220d0 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69  er callback.** i
220e0 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
220f0 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69  e inner-most tri
22100 67 67 65 72 20 6f 72 20 76 69 65 77 20 74 68 61  gger or view tha
22110 74 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65  t is responsible
22120 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 63 63 65   for.** the acce
22130 73 73 20 61 74 74 65 6d 70 74 20 6f 72 20 4e 55  ss attempt or NU
22140 4c 4c 20 69 66 20 74 68 69 73 20 61 63 63 65 73  LL if this acces
22150 73 20 61 74 74 65 6d 70 74 20 69 73 20 64 69 72  s attempt is dir
22160 65 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f  ectly from.** to
22170 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64 65  p-level SQL code
22180 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ..*/./**********
22190 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
221a0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
221b0 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  * 3rd **********
221c0 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a  ** 4th *********
221d0 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  **/.#define SQLI
221e0 54 45 5f 43 52 45 41 54 45 5f 49 4e 44 45 58 20  TE_CREATE_INDEX 
221f0 20 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20           1   /* 
22200 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
22210 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
22220 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
22230 45 5f 43 52 45 41 54 45 5f 54 41 42 4c 45 20 20  E_CREATE_TABLE  
22240 20 20 20 20 20 20 20 20 32 20 20 20 2f 2a 20 54          2   /* T
22250 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
22260 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
22270 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
22280 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44  _CREATE_TEMP_IND
22290 45 58 20 20 20 20 20 33 20 20 20 2f 2a 20 49 6e  EX     3   /* In
222a0 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61  dex Name      Ta
222b0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
222c0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
222d0 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c  CREATE_TEMP_TABL
222e0 45 20 20 20 20 20 34 20 20 20 2f 2a 20 54 61 62  E     4   /* Tab
222f0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
22300 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
22310 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
22320 52 45 41 54 45 5f 54 45 4d 50 5f 54 52 49 47 47  REATE_TEMP_TRIGG
22330 45 52 20 20 20 35 20 20 20 2f 2a 20 54 72 69 67  ER   5   /* Trig
22340 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c  ger Name    Tabl
22350 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
22360 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
22370 45 41 54 45 5f 54 45 4d 50 5f 56 49 45 57 20 20  EATE_TEMP_VIEW  
22380 20 20 20 20 36 20 20 20 2f 2a 20 56 69 65 77 20      6   /* View 
22390 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20  Name       NULL 
223a0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
223b0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
223c0 41 54 45 5f 54 52 49 47 47 45 52 20 20 20 20 20  ATE_TRIGGER     
223d0 20 20 20 37 20 20 20 2f 2a 20 54 72 69 67 67 65     7   /* Trigge
223e0 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20  r Name    Table 
223f0 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
22400 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
22410 54 45 5f 56 49 45 57 20 20 20 20 20 20 20 20 20  TE_VIEW         
22420 20 20 38 20 20 20 2f 2a 20 56 69 65 77 20 4e 61    8   /* View Na
22430 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  me       NULL   
22440 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
22450 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c 45 54  ine SQLITE_DELET
22460 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  E               
22470 20 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61   9   /* Table Na
22480 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
22490 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
224a0 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49  ne SQLITE_DROP_I
224b0 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20 31  NDEX           1
224c0 30 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  0   /* Index Nam
224d0 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  e      Table Nam
224e0 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
224f0 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41  e SQLITE_DROP_TA
22500 42 4c 45 20 20 20 20 20 20 20 20 20 20 20 31 31  BLE           11
22510 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
22520 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
22530 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
22540 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d   SQLITE_DROP_TEM
22550 50 5f 49 4e 44 45 58 20 20 20 20 20 20 31 32 20  P_INDEX      12 
22560 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
22570 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20       Table Name 
22580 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
22590 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50  SQLITE_DROP_TEMP
225a0 5f 54 41 42 4c 45 20 20 20 20 20 20 31 33 20 20  _TABLE      13  
225b0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
225c0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
225d0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
225e0 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f  QLITE_DROP_TEMP_
225f0 54 52 49 47 47 45 52 20 20 20 20 31 34 20 20 20  TRIGGER    14   
22600 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20  /* Trigger Name 
22610 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
22620 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
22630 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56  LITE_DROP_TEMP_V
22640 49 45 57 20 20 20 20 20 20 20 31 35 20 20 20 2f  IEW       15   /
22650 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20  * View Name     
22660 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
22670 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
22680 49 54 45 5f 44 52 4f 50 5f 54 52 49 47 47 45 52  ITE_DROP_TRIGGER
22690 20 20 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a           16   /*
226a0 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20   Trigger Name   
226b0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
226c0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
226d0 54 45 5f 44 52 4f 50 5f 56 49 45 57 20 20 20 20  TE_DROP_VIEW    
226e0 20 20 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20          17   /* 
226f0 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20  View Name       
22700 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
22710 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
22720 45 5f 49 4e 53 45 52 54 20 20 20 20 20 20 20 20  E_INSERT        
22730 20 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20 54         18   /* T
22740 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
22750 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
22760 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
22770 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20 20 20  _PRAGMA         
22780 20 20 20 20 20 20 31 39 20 20 20 2f 2a 20 50 72        19   /* Pr
22790 61 67 6d 61 20 4e 61 6d 65 20 20 20 20 20 31 73  agma Name     1s
227a0 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f  t arg or NULL */
227b0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
227c0 52 45 41 44 20 20 20 20 20 20 20 20 20 20 20 20  READ            
227d0 20 20 20 20 20 32 30 20 20 20 2f 2a 20 54 61 62       20   /* Tab
227e0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c  le Name      Col
227f0 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a  umn Name     */.
22800 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
22810 45 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 20  ELECT           
22820 20 20 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c      21   /* NULL
22830 20 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c              NULL
22840 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
22850 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52  define SQLITE_TR
22860 41 4e 53 41 43 54 49 4f 4e 20 20 20 20 20 20 20  ANSACTION       
22870 20 20 20 32 32 20 20 20 2f 2a 20 4f 70 65 72 61     22   /* Opera
22880 74 69 6f 6e 20 20 20 20 20 20 20 4e 55 4c 4c 20  tion       NULL 
22890 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
228a0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 50 44  efine SQLITE_UPD
228b0 41 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ATE             
228c0 20 20 32 33 20 20 20 2f 2a 20 54 61 62 6c 65 20    23   /* Table 
228d0 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e  Name      Column
228e0 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65   Name     */.#de
228f0 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 54 54 41  fine SQLITE_ATTA
22900 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CH              
22910 20 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d   24   /* Filenam
22920 65 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  e        NULL   
22930 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
22940 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 41 43  ine SQLITE_DETAC
22950 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  H               
22960 32 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  25   /* Database
22970 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20   Name   NULL    
22980 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
22990 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f  ne SQLITE_ALTER_
229a0 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32  TABLE          2
229b0 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  6   /* Database 
229c0 4e 61 6d 65 20 20 20 54 61 62 6c 65 20 4e 61 6d  Name   Table Nam
229d0 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
229e0 65 20 53 51 4c 49 54 45 5f 52 45 49 4e 44 45 58  e SQLITE_REINDEX
229f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 37                27
22a00 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
22a10 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
22a20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
22a30 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20   SQLITE_ANALYZE 
22a40 20 20 20 20 20 20 20 20 20 20 20 20 20 32 38 20               28 
22a50 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
22a60 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
22a70 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
22a80 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 54  SQLITE_CREATE_VT
22a90 41 42 4c 45 20 20 20 20 20 20 20 20 32 39 20 20  ABLE        29  
22aa0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
22ab0 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20      Module Name 
22ac0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
22ad0 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c  QLITE_DROP_VTABL
22ae0 45 20 20 20 20 20 20 20 20 20 20 33 30 20 20 20  E          30   
22af0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
22b00 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20     Module Name  
22b10 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
22b20 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20  LITE_FUNCTION   
22b30 20 20 20 20 20 20 20 20 20 20 33 31 20 20 20 2f            31   /
22b40 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20  * NULL          
22b50 20 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20    Function Name 
22b60 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
22b70 49 54 45 5f 53 41 56 45 50 4f 49 4e 54 20 20 20  ITE_SAVEPOINT   
22b80 20 20 20 20 20 20 20 20 20 33 32 20 20 20 2f 2a           32   /*
22b90 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20   Operation      
22ba0 20 53 61 76 65 70 6f 69 6e 74 20 4e 61 6d 65 20   Savepoint Name 
22bb0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
22bc0 54 45 5f 43 4f 50 59 20 20 20 20 20 20 20 20 20  TE_COPY         
22bd0 20 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20           0   /* 
22be0 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a  No longer used *
22bf0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
22c00 5f 52 45 43 55 52 53 49 56 45 20 20 20 20 20 20  _RECURSIVE      
22c10 20 20 20 20 20 20 33 33 20 20 20 2f 2a 20 4e 55        33   /* NU
22c20 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e 55  LL            NU
22c30 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
22c40 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
22c50 3a 20 54 72 61 63 69 6e 67 20 41 6e 64 20 50 72  : Tracing And Pr
22c60 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e  ofiling Function
22c70 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  s.** METHOD: sql
22c80 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ite3.**.** These
22c90 20 72 6f 75 74 69 6e 65 73 20 72 65 67 69 73 74   routines regist
22ca0 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  er callback func
22cb0 74 69 6f 6e 73 20 74 68 61 74 20 63 61 6e 20 62  tions that can b
22cc0 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72  e used for.** tr
22cd0 61 63 69 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c  acing and profil
22ce0 69 6e 67 20 74 68 65 20 65 78 65 63 75 74 69 6f  ing the executio
22cf0 6e 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65  n of SQL stateme
22d00 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  nts..**.** ^The 
22d10 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
22d20 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20  n registered by 
22d30 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20  sqlite3_trace() 
22d40 69 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a  is invoked at.**
22d50 20 76 61 72 69 6f 75 73 20 74 69 6d 65 73 20 77   various times w
22d60 68 65 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65  hen an SQL state
22d70 6d 65 6e 74 20 69 73 20 62 65 69 6e 67 20 72 75  ment is being ru
22d80 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 74  n by [sqlite3_st
22d90 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73  ep()]..** ^The s
22da0 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 63  qlite3_trace() c
22db0 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
22dc0 65 64 20 77 69 74 68 20 61 20 55 54 46 2d 38 20  ed with a UTF-8 
22dd0 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65  rendering of the
22de0 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
22df0 74 20 74 65 78 74 20 61 73 20 74 68 65 20 73 74  t text as the st
22e00 61 74 65 6d 65 6e 74 20 66 69 72 73 74 20 62 65  atement first be
22e10 67 69 6e 73 20 65 78 65 63 75 74 69 6e 67 2e 0a  gins executing..
22e20 2a 2a 20 5e 28 41 64 64 69 74 69 6f 6e 61 6c 20  ** ^(Additional 
22e30 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20  sqlite3_trace() 
22e40 63 61 6c 6c 62 61 63 6b 73 20 6d 69 67 68 74 20  callbacks might 
22e50 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65 61 63 68  occur.** as each
22e60 20 74 72 69 67 67 65 72 65 64 20 73 75 62 70 72   triggered subpr
22e70 6f 67 72 61 6d 20 69 73 20 65 6e 74 65 72 65 64  ogram is entered
22e80 2e 20 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 73  .  The callbacks
22e90 20 66 6f 72 20 74 72 69 67 67 65 72 73 0a 2a 2a   for triggers.**
22ea0 20 63 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d 38   contain a UTF-8
22eb0 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61   SQL comment tha
22ec0 74 20 69 64 65 6e 74 69 66 69 65 73 20 74 68 65  t identifies the
22ed0 20 74 72 69 67 67 65 72 2e 29 5e 0a 2a 2a 0a 2a   trigger.)^.**.*
22ee0 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 54 52  * The [SQLITE_TR
22ef0 41 43 45 5f 53 49 5a 45 5f 4c 49 4d 49 54 5d 20  ACE_SIZE_LIMIT] 
22f00 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
22f10 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20  ion can be used 
22f20 74 6f 20 6c 69 6d 69 74 0a 2a 2a 20 74 68 65 20  to limit.** the 
22f30 6c 65 6e 67 74 68 20 6f 66 20 5b 62 6f 75 6e 64  length of [bound
22f40 20 70 61 72 61 6d 65 74 65 72 5d 20 65 78 70 61   parameter] expa
22f50 6e 73 69 6f 6e 20 69 6e 20 74 68 65 20 6f 75 74  nsion in the out
22f60 70 75 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 74  put of sqlite3_t
22f70 72 61 63 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54  race()..**.** ^T
22f80 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  he callback func
22f90 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20  tion registered 
22fa0 62 79 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69  by sqlite3_profi
22fb0 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a  le() is invoked.
22fc0 2a 2a 20 61 73 20 65 61 63 68 20 53 51 4c 20 73  ** as each SQL s
22fd0 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65  tatement finishe
22fe0 73 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65  s.  ^The profile
22ff0 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69   callback contai
23000 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e  ns.** the origin
23010 61 6c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78  al statement tex
23020 74 20 61 6e 64 20 61 6e 20 65 73 74 69 6d 61 74  t and an estimat
23030 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20  e of wall-clock 
23040 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c  time.** of how l
23050 6f 6e 67 20 74 68 61 74 20 73 74 61 74 65 6d 65  ong that stateme
23060 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 20  nt took to run. 
23070 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61   ^The profile ca
23080 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d 65 20 69  llback.** time i
23090 73 20 69 6e 20 75 6e 69 74 73 20 6f 66 20 6e 61  s in units of na
230a0 6e 6f 73 65 63 6f 6e 64 73 2c 20 68 6f 77 65 76  noseconds, howev
230b0 65 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 69  er the current i
230c0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a  mplementation.**
230d0 20 69 73 20 6f 6e 6c 79 20 63 61 70 61 62 6c 65   is only capable
230e0 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20   of millisecond 
230f0 72 65 73 6f 6c 75 74 69 6f 6e 20 73 6f 20 74 68  resolution so th
23100 65 20 73 69 78 20 6c 65 61 73 74 20 73 69 67 6e  e six least sign
23110 69 66 69 63 61 6e 74 0a 2a 2a 20 64 69 67 69 74  ificant.** digit
23120 73 20 69 6e 20 74 68 65 20 74 69 6d 65 20 61 72  s in the time ar
23130 65 20 6d 65 61 6e 69 6e 67 6c 65 73 73 2e 20 20  e meaningless.  
23140 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  Future versions 
23150 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 69 67  of SQLite.** mig
23160 68 74 20 70 72 6f 76 69 64 65 20 67 72 65 61 74  ht provide great
23170 65 72 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6f 6e  er resolution on
23180 20 74 68 65 20 70 72 6f 66 69 6c 65 72 20 63 61   the profiler ca
23190 6c 6c 62 61 63 6b 2e 20 20 54 68 65 0a 2a 2a 20  llback.  The.** 
231a0 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28  sqlite3_profile(
231b0 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 6f  ) function is co
231c0 6e 73 69 64 65 72 65 64 20 65 78 70 65 72 69 6d  nsidered experim
231d0 65 6e 74 61 6c 20 61 6e 64 20 69 73 0a 2a 2a 20  ental and is.** 
231e0 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67  subject to chang
231f0 65 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 73  e in future vers
23200 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ions of SQLite..
23210 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  */.SQLITE_API vo
23220 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41  id *SQLITE_STDCA
23230 4c 4c 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  LL sqlite3_trace
23240 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28  (sqlite3*, void(
23250 2a 78 54 72 61 63 65 29 28 76 6f 69 64 2a 2c 63  *xTrace)(void*,c
23260 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 76 6f 69  onst char*), voi
23270 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  d*);.SQLITE_API 
23280 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e  SQLITE_EXPERIMEN
23290 54 41 4c 20 76 6f 69 64 20 2a 53 51 4c 49 54 45  TAL void *SQLITE
232a0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
232b0 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69 74 65 33  _profile(sqlite3
232c0 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50 72 6f  *,.   void(*xPro
232d0 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73  file)(void*,cons
232e0 74 20 63 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f  t char*,sqlite3_
232f0 75 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b  uint64), void*);
23300 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
23310 3a 20 51 75 65 72 79 20 50 72 6f 67 72 65 73 73  : Query Progress
23320 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 20 4d 45   Callbacks.** ME
23330 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
23340 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
23350 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65  _progress_handle
23360 72 28 44 2c 4e 2c 58 2c 50 29 20 69 6e 74 65 72  r(D,N,X,P) inter
23370 66 61 63 65 20 63 61 75 73 65 73 20 74 68 65 20  face causes the 
23380 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63  callback.** func
23390 74 69 6f 6e 20 58 20 74 6f 20 62 65 20 69 6e 76  tion X to be inv
233a0 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c  oked periodicall
233b0 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 20 72 75  y during long ru
233c0 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 0a 2a  nning calls to.*
233d0 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  * [sqlite3_exec(
233e0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  )], [sqlite3_ste
233f0 70 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  p()] and [sqlite
23400 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 66  3_get_table()] f
23410 6f 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  or.** database c
23420 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 20 41 6e  onnection D.  An
23430 20 65 78 61 6d 70 6c 65 20 75 73 65 20 66 6f 72   example use for
23440 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61   this.** interfa
23450 63 65 20 69 73 20 74 6f 20 6b 65 65 70 20 61 20  ce is to keep a 
23460 47 55 49 20 75 70 64 61 74 65 64 20 64 75 72 69  GUI updated duri
23470 6e 67 20 61 20 6c 61 72 67 65 20 71 75 65 72 79  ng a large query
23480 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 61 72  ..**.** ^The par
23490 61 6d 65 74 65 72 20 50 20 69 73 20 70 61 73 73  ameter P is pass
234a0 65 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 68  ed through as th
234b0 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72  e only parameter
234c0 20 74 6f 20 74 68 65 20 0a 2a 2a 20 63 61 6c 6c   to the .** call
234d0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 2e  back function X.
234e0 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72    ^The parameter
234f0 20 4e 20 69 73 20 74 68 65 20 61 70 70 72 6f 78   N is the approx
23500 69 6d 61 74 65 20 6e 75 6d 62 65 72 20 6f 66 20  imate number of 
23510 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 6d 61 63  .** [virtual mac
23520 68 69 6e 65 20 69 6e 73 74 72 75 63 74 69 6f 6e  hine instruction
23530 73 5d 20 74 68 61 74 20 61 72 65 20 65 76 61 6c  s] that are eval
23540 75 61 74 65 64 20 62 65 74 77 65 65 6e 20 73 75  uated between su
23550 63 63 65 73 73 69 76 65 0a 2a 2a 20 69 6e 76 6f  ccessive.** invo
23560 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 63  cations of the c
23570 61 6c 6c 62 61 63 6b 20 58 2e 20 20 5e 49 66 20  allback X.  ^If 
23580 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 6f  N is less than o
23590 6e 65 20 74 68 65 6e 20 74 68 65 20 70 72 6f 67  ne then the prog
235a0 72 65 73 73 0a 2a 2a 20 68 61 6e 64 6c 65 72 20  ress.** handler 
235b0 69 73 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a  is disabled..**.
235c0 2a 2a 20 5e 4f 6e 6c 79 20 61 20 73 69 6e 67 6c  ** ^Only a singl
235d0 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  e progress handl
235e0 65 72 20 6d 61 79 20 62 65 20 64 65 66 69 6e 65  er may be define
235f0 64 20 61 74 20 6f 6e 65 20 74 69 6d 65 20 70 65  d at one time pe
23600 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  r.** [database c
23610 6f 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73 65 74 74  onnection]; sett
23620 69 6e 67 20 61 20 6e 65 77 20 70 72 6f 67 72 65  ing a new progre
23630 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6e 63 65  ss handler cance
23640 6c 73 20 74 68 65 0a 2a 2a 20 6f 6c 64 20 6f 6e  ls the.** old on
23650 65 2e 20 20 5e 53 65 74 74 69 6e 67 20 70 61 72  e.  ^Setting par
23660 61 6d 65 74 65 72 20 58 20 74 6f 20 4e 55 4c 4c  ameter X to NULL
23670 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 70 72   disables the pr
23680 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a  ogress handler..
23690 2a 2a 20 5e 54 68 65 20 70 72 6f 67 72 65 73 73  ** ^The progress
236a0 20 68 61 6e 64 6c 65 72 20 69 73 20 61 6c 73 6f   handler is also
236b0 20 64 69 73 61 62 6c 65 64 20 62 79 20 73 65 74   disabled by set
236c0 74 69 6e 67 20 4e 20 74 6f 20 61 20 76 61 6c 75  ting N to a valu
236d0 65 20 6c 65 73 73 0a 2a 2a 20 74 68 61 6e 20 31  e less.** than 1
236e0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
236f0 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63  progress callbac
23700 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65  k returns non-ze
23710 72 6f 2c 20 74 68 65 20 6f 70 65 72 61 74 69 6f  ro, the operatio
23720 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72 75 70  n is.** interrup
23730 74 65 64 2e 20 20 54 68 69 73 20 66 65 61 74 75  ted.  This featu
23740 72 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  re can be used t
23750 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a  o implement a.**
23760 20 22 43 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e   "Cancel" button
23770 20 6f 6e 20 61 20 47 55 49 20 70 72 6f 67 72 65   on a GUI progre
23780 73 73 20 64 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a  ss dialog box..*
23790 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72 65 73  *.** The progres
237a0 73 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61  s handler callba
237b0 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61  ck must not do a
237c0 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c  nything that wil
237d0 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20  l modify.** the 
237e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
237f0 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64  ion that invoked
23800 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 61   the progress ha
23810 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74  ndler..** Note t
23820 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  hat [sqlite3_pre
23830 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b  pare_v2()] and [
23840 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
23850 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69  both modify thei
23860 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  r.** database co
23870 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68  nnections for th
23880 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f  e meaning of "mo
23890 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61  dify" in this pa
238a0 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 53  ragraph..**.*/.S
238b0 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 53  QLITE_API void S
238c0 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
238d0 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68  lite3_progress_h
238e0 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c  andler(sqlite3*,
238f0 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69   int, int(*)(voi
23900 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  d*), void*);../*
23910 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70  .** CAPI3REF: Op
23920 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74 61  ening A New Data
23930 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a  base Connection.
23940 2a 2a 20 43 4f 4e 53 54 52 55 43 54 4f 52 3a 20  ** CONSTRUCTOR: 
23950 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54  sqlite3.**.** ^T
23960 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 70  hese routines op
23970 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 64 61 74  en an SQLite dat
23980 61 62 61 73 65 20 66 69 6c 65 20 61 73 20 73 70  abase file as sp
23990 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 0a  ecified by the .
239a0 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75  ** filename argu
239b0 6d 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c 65 6e  ment. ^The filen
239c0 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ame argument is 
239d0 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55  interpreted as U
239e0 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69  TF-8 for.** sqli
239f0 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73  te3_open() and s
23a00 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
23a10 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36 20 69   and as UTF-16 i
23a20 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74  n the native byt
23a30 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20 73  e.** order for s
23a40 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e  qlite3_open16().
23a50 20 5e 28 41 20 5b 64 61 74 61 62 61 73 65 20 63   ^(A [database c
23a60 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c  onnection] handl
23a70 65 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20  e is usually.** 
23a80 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 70 44  returned in *ppD
23a90 62 2c 20 65 76 65 6e 20 69 66 20 61 6e 20 65 72  b, even if an er
23aa0 72 6f 72 20 6f 63 63 75 72 73 2e 20 20 54 68 65  ror occurs.  The
23ab0 20 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e 20   only exception 
23ac0 69 73 20 74 68 61 74 0a 2a 2a 20 69 66 20 53 51  is that.** if SQ
23ad0 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74  Lite is unable t
23ae0 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72  o allocate memor
23af0 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73  y to hold the [s
23b00 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a  qlite3] object,.
23b10 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62  ** a NULL will b
23b20 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a  e written into *
23b30 70 70 44 62 20 69 6e 73 74 65 61 64 20 6f 66 20  ppDb instead of 
23b40 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
23b50 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62   [sqlite3].** ob
23b60 6a 65 63 74 2e 29 5e 20 5e 28 49 66 20 74 68 65  ject.)^ ^(If the
23b70 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
23b80 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 72 65 61  ned (and/or crea
23b90 74 65 64 29 20 73 75 63 63 65 73 73 66 75 6c 6c  ted) successfull
23ba0 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49  y, then.** [SQLI
23bb0 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e  TE_OK] is return
23bc0 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61  ed.  Otherwise a
23bd0 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  n [error code] i
23be0 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 5e 54  s returned.)^ ^T
23bf0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  he.** [sqlite3_e
23c00 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c  rrmsg()] or [sql
23c10 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d  ite3_errmsg16()]
23c20 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 65   routines can be
23c30 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a   used to obtain.
23c40 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61  ** an English la
23c50 6e 67 75 61 67 65 20 64 65 73 63 72 69 70 74 69  nguage descripti
23c60 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20  on of the error 
23c70 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c  following a fail
23c80 75 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66  ure of any.** of
23c90 20 74 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65   the sqlite3_ope
23ca0 6e 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  n() routines..**
23cb0 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74  .** ^The default
23cc0 20 65 6e 63 6f 64 69 6e 67 20 77 69 6c 6c 20 62   encoding will b
23cd0 65 20 55 54 46 2d 38 20 66 6f 72 20 64 61 74 61  e UTF-8 for data
23ce0 62 61 73 65 73 20 63 72 65 61 74 65 64 20 75 73  bases created us
23cf0 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  ing.** sqlite3_o
23d00 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33  pen() or sqlite3
23d10 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20 5e 54 68  _open_v2().  ^Th
23d20 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69  e default encodi
23d30 6e 67 20 66 6f 72 20 64 61 74 61 62 61 73 65 73  ng for databases
23d40 0a 2a 2a 20 63 72 65 61 74 65 64 20 75 73 69 6e  .** created usin
23d50 67 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36  g sqlite3_open16
23d60 28 29 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 31  () will be UTF-1
23d70 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20  6 in the native 
23d80 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a  byte order..**.*
23d90 2a 20 57 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  * Whether or not
23da0 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
23db0 20 77 68 65 6e 20 69 74 20 69 73 20 6f 70 65 6e   when it is open
23dc0 65 64 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a  ed, resources.**
23dd0 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
23de0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
23df0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c  onnection] handl
23e00 65 20 73 68 6f 75 6c 64 20 62 65 20 72 65 6c 65  e should be rele
23e10 61 73 65 64 20 62 79 0a 2a 2a 20 70 61 73 73 69  ased by.** passi
23e20 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65  ng it to [sqlite
23e30 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20  3_close()] when 
23e40 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20  it is no longer 
23e50 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  required..**.** 
23e60 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  The sqlite3_open
23e70 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 20  _v2() interface 
23e80 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74  works like sqlit
23e90 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63  e3_open().** exc
23ea0 65 70 74 20 74 68 61 74 20 69 74 20 61 63 63 65  ept that it acce
23eb0 70 74 73 20 74 77 6f 20 61 64 64 69 74 69 6f 6e  pts two addition
23ec0 61 6c 20 70 61 72 61 6d 65 74 65 72 73 20 66 6f  al parameters fo
23ed0 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e  r additional con
23ee0 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65  trol.** over the
23ef0 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f   new database co
23f00 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28 54 68 65  nnection.  ^(The
23f10 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72   flags parameter
23f20 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f   to.** sqlite3_o
23f30 70 65 6e 5f 76 32 28 29 20 63 61 6e 20 74 61 6b  pen_v2() can tak
23f40 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20  e one of.** the 
23f50 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65 20  following three 
23f60 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61 6c  values, optional
23f70 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68  ly combined with
23f80 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45   the .** [SQLITE
23f90 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20  _OPEN_NOMUTEX], 
23fa0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c  [SQLITE_OPEN_FUL
23fb0 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45  LMUTEX], [SQLITE
23fc0 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48  _OPEN_SHAREDCACH
23fd0 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  E],.** [SQLITE_O
23fe0 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45  PEN_PRIVATECACHE
23ff0 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54  ], and/or [SQLIT
24000 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67  E_OPEN_URI] flag
24010 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  s:)^.**.** <dl>.
24020 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45  ** ^(<dt>[SQLITE
24030 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c  _OPEN_READONLY]<
24040 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
24050 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
24060 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20  ed in read-only 
24070 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 64 61  mode.  If the da
24080 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a  tabase does not.
24090 2a 2a 20 61 6c 72 65 61 64 79 20 65 78 69 73 74  ** already exist
240a0 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65  , an error is re
240b0 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a  turned.</dd>)^.*
240c0 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49  *.** ^(<dt>[SQLI
240d0 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
240e0 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  E]</dt>.** <dd>T
240f0 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
24100 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e  pened for readin
24110 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69 66  g and writing if
24120 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72 65   possible, or re
24130 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66  ading.** only if
24140 20 74 68 65 20 66 69 6c 65 20 69 73 20 77 72 69   the file is wri
24150 74 65 20 70 72 6f 74 65 63 74 65 64 20 62 79 20  te protected by 
24160 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79  the operating sy
24170 73 74 65 6d 2e 20 20 49 6e 20 65 69 74 68 65 72  stem.  In either
24180 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 64 61 74  .** case the dat
24190 61 62 61 73 65 20 6d 75 73 74 20 61 6c 72 65 61  abase must alrea
241a0 64 79 20 65 78 69 73 74 2c 20 6f 74 68 65 72 77  dy exist, otherw
241b0 69 73 65 20 61 6e 20 65 72 72 6f 72 20 69 73 20  ise an error is 
241c0 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e  returned.</dd>)^
241d0 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51  .**.** ^(<dt>[SQ
241e0 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
241f0 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f  ITE] | [SQLITE_O
24200 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e  PEN_CREATE]</dt>
24210 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61  .** <dd>The data
24220 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66  base is opened f
24230 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77  or reading and w
24240 72 69 74 69 6e 67 2c 20 61 6e 64 20 69 73 20 63  riting, and is c
24250 72 65 61 74 65 64 20 69 66 0a 2a 2a 20 69 74 20  reated if.** it 
24260 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61 64 79  does not already
24270 20 65 78 69 73 74 2e 20 54 68 69 73 20 69 73 20   exist. This is 
24280 74 68 65 20 62 65 68 61 76 69 6f 72 20 74 68 61  the behavior tha
24290 74 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64  t is always used
242a0 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   for.** sqlite3_
242b0 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  open() and sqlit
242c0 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64  e3_open16().</dd
242d0 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a  >)^.** </dl>.**.
242e0 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20 70 61  ** If the 3rd pa
242f0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
24300 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20  e3_open_v2() is 
24310 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a  not one of the.*
24320 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73  * combinations s
24330 68 6f 77 6e 20 61 62 6f 76 65 20 6f 70 74 69 6f  hown above optio
24340 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77  nally combined w
24350 69 74 68 20 6f 74 68 65 72 0a 2a 2a 20 5b 53 51  ith other.** [SQ
24360 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
24370 4c 59 20 7c 20 53 51 4c 49 54 45 5f 4f 50 45 4e  LY | SQLITE_OPEN
24380 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20 74 68 65 6e  _* bits].** then
24390 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
243a0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
243b0 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54  * ^If the [SQLIT
243c0 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20  E_OPEN_NOMUTEX] 
243d0 66 6c 61 67 20 69 73 20 73 65 74 2c 20 74 68 65  flag is set, the
243e0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
243f0 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65  onnection.** ope
24400 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c 74 69 2d  ns in the multi-
24410 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e  thread [threadin
24420 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 20  g mode] as long 
24430 61 73 20 74 68 65 20 73 69 6e 67 6c 65 2d 74 68  as the single-th
24440 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 73  read.** mode has
24450 20 6e 6f 74 20 62 65 65 6e 20 73 65 74 20 61 74   not been set at
24460 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72   compile-time or
24470 20 73 74 61 72 74 2d 74 69 6d 65 2e 20 20 5e 49   start-time.  ^I
24480 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  f the.** [SQLITE
24490 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d  _OPEN_FULLMUTEX]
244a0 20 66 6c 61 67 20 69 73 20 73 65 74 20 74 68 65   flag is set the
244b0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
244c0 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73 0a  onnection opens.
244d0 2a 2a 20 69 6e 20 74 68 65 20 73 65 72 69 61 6c  ** in the serial
244e0 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20  ized [threading 
244f0 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73 69 6e  mode] unless sin
24500 67 6c 65 2d 74 68 72 65 61 64 20 77 61 73 0a 2a  gle-thread was.*
24510 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 6c  * previously sel
24520 65 63 74 65 64 20 61 74 20 63 6f 6d 70 69 6c 65  ected at compile
24530 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74  -time or start-t
24540 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  ime..** ^The [SQ
24550 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44  LITE_OPEN_SHARED
24560 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73  CACHE] flag caus
24570 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  es the database 
24580 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 62 65  connection to be
24590 0a 2a 2a 20 65 6c 69 67 69 62 6c 65 20 74 6f 20  .** eligible to 
245a0 75 73 65 20 5b 73 68 61 72 65 64 20 63 61 63 68  use [shared cach
245b0 65 20 6d 6f 64 65 5d 2c 20 72 65 67 61 72 64 6c  e mode], regardl
245c0 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f  ess of whether o
245d0 72 20 6e 6f 74 20 73 68 61 72 65 64 0a 2a 2a 20  r not shared.** 
245e0 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65 64  cache is enabled
245f0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
24600 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61  enable_shared_ca
24610 63 68 65 28 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a  che()].  ^The.**
24620 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52   [SQLITE_OPEN_PR
24630 49 56 41 54 45 43 41 43 48 45 5d 20 66 6c 61 67  IVATECACHE] flag
24640 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74 61   causes the data
24650 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
24660 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72 74 69 63  to not.** partic
24670 69 70 61 74 65 20 69 6e 20 5b 73 68 61 72 65 64  ipate in [shared
24680 20 63 61 63 68 65 20 6d 6f 64 65 5d 20 65 76 65   cache mode] eve
24690 6e 20 69 66 20 69 74 20 69 73 20 65 6e 61 62 6c  n if it is enabl
246a0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  ed..**.** ^The f
246b0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
246c0 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
246d0 76 32 28 29 20 69 73 20 74 68 65 20 6e 61 6d 65  v2() is the name
246e0 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   of the.** [sqli
246f0 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20  te3_vfs] object 
24700 74 68 61 74 20 64 65 66 69 6e 65 73 20 74 68 65  that defines the
24710 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
24720 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  m interface that
24730 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 61 74 61  .** the new data
24740 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
24750 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 5e 49 66  should use.  ^If
24760 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
24770 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55  meter is.** a NU
24780 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20  LL pointer then 
24790 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c  the default [sql
247a0 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
247b0 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20   is used..**.** 
247c0 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  ^If the filename
247d0 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20   is ":memory:", 
247e0 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20  then a private, 
247f0 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d  temporary in-mem
24800 6f 72 79 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  ory database.** 
24810 69 73 20 63 72 65 61 74 65 64 20 66 6f 72 20 74  is created for t
24820 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  he connection.  
24830 5e 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20  ^This in-memory 
24840 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 76 61  database will va
24850 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65  nish when.** the
24860 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
24870 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20  tion is closed. 
24880 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   Future versions
24890 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74   of SQLite might
248a0 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66 20  .** make use of 
248b0 61 64 64 69 74 69 6f 6e 61 6c 20 73 70 65 63 69  additional speci
248c0 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74 68 61  al filenames tha
248d0 74 20 62 65 67 69 6e 20 77 69 74 68 20 74 68 65  t begin with the
248e0 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 2e 0a   ":" character..
248f0 2a 2a 20 49 74 20 69 73 20 72 65 63 6f 6d 6d 65  ** It is recomme
24900 6e 64 65 64 20 74 68 61 74 20 77 68 65 6e 20 61  nded that when a
24910 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   database filena
24920 6d 65 20 61 63 74 75 61 6c 6c 79 20 64 6f 65 73  me actually does
24930 20 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61   begin with.** a
24940 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 20 79   ":" character y
24950 6f 75 20 73 68 6f 75 6c 64 20 70 72 65 66 69 78  ou should prefix
24960 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 69   the filename wi
24970 74 68 20 61 20 70 61 74 68 6e 61 6d 65 20 73 75  th a pathname su
24980 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f  ch as.** "./" to
24990 20 61 76 6f 69 64 20 61 6d 62 69 67 75 69 74 79   avoid ambiguity
249a0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
249b0 66 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20 65  filename is an e
249c0 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65  mpty string, the
249d0 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d  n a private, tem
249e0 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73  porary.** on-dis
249f0 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20  k database will 
24a00 62 65 20 63 72 65 61 74 65 64 2e 20 20 5e 54 68  be created.  ^Th
24a10 69 73 20 70 72 69 76 61 74 65 20 64 61 74 61 62  is private datab
24a20 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61  ase will be.** a
24a30 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c  utomatically del
24a40 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20  eted as soon as 
24a50 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
24a60 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65  nection is close
24a70 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66  d..**.** [[URI f
24a80 69 6c 65 6e 61 6d 65 73 20 69 6e 20 73 71 6c 69  ilenames in sqli
24a90 74 65 33 5f 6f 70 65 6e 28 29 5d 5d 20 3c 68 33  te3_open()]] <h3
24aa0 3e 55 52 49 20 46 69 6c 65 6e 61 6d 65 73 3c 2f  >URI Filenames</
24ab0 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 55  h3>.**.** ^If [U
24ac0 52 49 20 66 69 6c 65 6e 61 6d 65 5d 20 69 6e 74  RI filename] int
24ad0 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65  erpretation is e
24ae0 6e 61 62 6c 65 64 2c 20 61 6e 64 20 74 68 65 20  nabled, and the 
24af0 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
24b00 74 0a 2a 2a 20 62 65 67 69 6e 73 20 77 69 74 68  t.** begins with
24b10 20 22 66 69 6c 65 3a 22 2c 20 74 68 65 6e 20 74   "file:", then t
24b20 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 69  he filename is i
24b30 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20  nterpreted as a 
24b40 55 52 49 2e 20 5e 55 52 49 0a 2a 2a 20 66 69 6c  URI. ^URI.** fil
24b50 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61  ename interpreta
24b60 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 20  tion is enabled 
24b70 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  if the [SQLITE_O
24b80 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73  PEN_URI] flag is
24b90 0a 2a 2a 20 73 65 74 20 69 6e 20 74 68 65 20 66  .** set in the f
24ba0 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74  ourth argument t
24bb0 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
24bc0 32 28 29 2c 20 6f 72 20 69 66 20 69 74 20 68 61  2(), or if it ha
24bd0 73 0a 2a 2a 20 62 65 65 6e 20 65 6e 61 62 6c 65  s.** been enable
24be0 64 20 67 6c 6f 62 61 6c 6c 79 20 75 73 69 6e 67  d globally using
24bf0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e   the [SQLITE_CON
24c00 46 49 47 5f 55 52 49 5d 20 6f 70 74 69 6f 6e 20  FIG_URI] option 
24c10 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  with the.** [sql
24c20 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 6d  ite3_config()] m
24c30 65 74 68 6f 64 20 6f 72 20 62 79 20 74 68 65 20  ethod or by the 
24c40 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d  [SQLITE_USE_URI]
24c50 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
24c60 74 69 6f 6e 2e 0a 2a 2a 20 41 73 20 6f 66 20 53  tion..** As of S
24c70 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
24c80 37 2e 37 2c 20 55 52 49 20 66 69 6c 65 6e 61 6d  7.7, URI filenam
24c90 65 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e  e interpretation
24ca0 20 69 73 20 74 75 72 6e 65 64 20 6f 66 66 0a 2a   is turned off.*
24cb0 2a 20 62 79 20 64 65 66 61 75 6c 74 2c 20 62 75  * by default, bu
24cc0 74 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  t future release
24cd0 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68  s of SQLite migh
24ce0 74 20 65 6e 61 62 6c 65 20 55 52 49 20 66 69 6c  t enable URI fil
24cf0 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74 65 72 70 72  ename.** interpr
24d00 65 74 61 74 69 6f 6e 20 62 79 20 64 65 66 61 75  etation by defau
24d10 6c 74 2e 20 20 53 65 65 20 22 5b 55 52 49 20 66  lt.  See "[URI f
24d20 69 6c 65 6e 61 6d 65 73 5d 22 20 66 6f 72 20 61  ilenames]" for a
24d30 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66  dditional.** inf
24d40 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
24d50 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 61 72  URI filenames ar
24d60 65 20 70 61 72 73 65 64 20 61 63 63 6f 72 64 69  e parsed accordi
24d70 6e 67 20 74 6f 20 52 46 43 20 33 39 38 36 2e 20  ng to RFC 3986. 
24d80 5e 49 66 20 74 68 65 20 55 52 49 20 63 6f 6e 74  ^If the URI cont
24d90 61 69 6e 73 20 61 6e 0a 2a 2a 20 61 75 74 68 6f  ains an.** autho
24da0 72 69 74 79 2c 20 74 68 65 6e 20 69 74 20 6d 75  rity, then it mu
24db0 73 74 20 62 65 20 65 69 74 68 65 72 20 61 6e 20  st be either an 
24dc0 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20  empty string or 
24dd0 74 68 65 20 73 74 72 69 6e 67 20 0a 2a 2a 20 22  the string .** "
24de0 6c 6f 63 61 6c 68 6f 73 74 22 2e 20 5e 49 66 20  localhost". ^If 
24df0 74 68 65 20 61 75 74 68 6f 72 69 74 79 20 69 73  the authority is
24e00 20 6e 6f 74 20 61 6e 20 65 6d 70 74 79 20 73 74   not an empty st
24e10 72 69 6e 67 20 6f 72 20 22 6c 6f 63 61 6c 68 6f  ring or "localho
24e20 73 74 22 2c 20 61 6e 20 0a 2a 2a 20 65 72 72 6f  st", an .** erro
24e30 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 74 6f  r is returned to
24e40 20 74 68 65 20 63 61 6c 6c 65 72 2e 20 5e 54 68   the caller. ^Th
24e50 65 20 66 72 61 67 6d 65 6e 74 20 63 6f 6d 70 6f  e fragment compo
24e60 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 2c 20 69  nent of a URI, i
24e70 66 20 0a 2a 2a 20 70 72 65 73 65 6e 74 2c 20 69  f .** present, i
24e80 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a  s ignored..**.**
24e90 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74 68   ^SQLite uses th
24ea0 65 20 70 61 74 68 20 63 6f 6d 70 6f 6e 65 6e 74  e path component
24eb0 20 6f 66 20 74 68 65 20 55 52 49 20 61 73 20 74   of the URI as t
24ec0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64  he name of the d
24ed0 69 73 6b 20 66 69 6c 65 0a 2a 2a 20 77 68 69 63  isk file.** whic
24ee0 68 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 64  h contains the d
24ef0 61 74 61 62 61 73 65 2e 20 5e 49 66 20 74 68 65  atabase. ^If the
24f00 20 70 61 74 68 20 62 65 67 69 6e 73 20 77 69 74   path begins wit
24f10 68 20 61 20 27 2f 27 20 63 68 61 72 61 63 74 65  h a '/' characte
24f20 72 2c 20 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69  r, .** then it i
24f30 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  s interpreted as
24f40 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74   an absolute pat
24f50 68 2e 20 5e 49 66 20 74 68 65 20 70 61 74 68 20  h. ^If the path 
24f60 64 6f 65 73 20 6e 6f 74 20 62 65 67 69 6e 20 0a  does not begin .
24f70 2a 2a 20 77 69 74 68 20 61 20 27 2f 27 20 28 6d  ** with a '/' (m
24f80 65 61 6e 69 6e 67 20 74 68 61 74 20 74 68 65 20  eaning that the 
24f90 61 75 74 68 6f 72 69 74 79 20 73 65 63 74 69 6f  authority sectio
24fa0 6e 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f  n is omitted fro
24fb0 6d 20 74 68 65 20 55 52 49 29 0a 2a 2a 20 74 68  m the URI).** th
24fc0 65 6e 20 74 68 65 20 70 61 74 68 20 69 73 20 69  en the path is i
24fd0 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20  nterpreted as a 
24fe0 72 65 6c 61 74 69 76 65 20 70 61 74 68 2e 20 0a  relative path. .
24ff0 2a 2a 20 5e 28 4f 6e 20 77 69 6e 64 6f 77 73 2c  ** ^(On windows,
25000 20 74 68 65 20 66 69 72 73 74 20 63 6f 6d 70 6f   the first compo
25010 6e 65 6e 74 20 6f 66 20 61 6e 20 61 62 73 6f 6c  nent of an absol
25020 75 74 65 20 70 61 74 68 20 0a 2a 2a 20 69 73 20  ute path .** is 
25030 61 20 64 72 69 76 65 20 73 70 65 63 69 66 69 63  a drive specific
25040 61 74 69 6f 6e 20 28 65 2e 67 2e 20 22 43 3a 22  ation (e.g. "C:"
25050 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72  ).)^.**.** [[cor
25060 65 20 55 52 49 20 71 75 65 72 79 20 70 61 72 61  e URI query para
25070 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20 54 68 65 20  meters]].** The 
25080 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20  query component 
25090 6f 66 20 61 20 55 52 49 20 6d 61 79 20 63 6f 6e  of a URI may con
250a0 74 61 69 6e 20 70 61 72 61 6d 65 74 65 72 73 20  tain parameters 
250b0 74 68 61 74 20 61 72 65 20 69 6e 74 65 72 70 72  that are interpr
250c0 65 74 65 64 0a 2a 2a 20 65 69 74 68 65 72 20 62  eted.** either b
250d0 79 20 53 51 4c 69 74 65 20 69 74 73 65 6c 66 2c  y SQLite itself,
250e0 20 6f 72 20 62 79 20 61 20 5b 56 46 53 20 7c 20   or by a [VFS | 
250f0 63 75 73 74 6f 6d 20 56 46 53 20 69 6d 70 6c 65  custom VFS imple
25100 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 53  mentation]..** S
25110 51 4c 69 74 65 20 61 6e 64 20 69 74 73 20 62 75  QLite and its bu
25120 69 6c 74 2d 69 6e 20 5b 56 46 53 65 73 5d 20 69  ilt-in [VFSes] i
25130 6e 74 65 72 70 72 65 74 20 74 68 65 0a 2a 2a 20  nterpret the.** 
25140 66 6f 6c 6c 6f 77 69 6e 67 20 71 75 65 72 79 20  following query 
25150 70 61 72 61 6d 65 74 65 72 73 3a 0a 2a 2a 0a 2a  parameters:.**.*
25160 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e  * <ul>.**   <li>
25170 20 3c 62 3e 76 66 73 3c 2f 62 3e 3a 20 5e 54 68   <b>vfs</b>: ^Th
25180 65 20 22 76 66 73 22 20 70 61 72 61 6d 65 74 65  e "vfs" paramete
25190 72 20 6d 61 79 20 62 65 20 75 73 65 64 20 74 6f  r may be used to
251a0 20 73 70 65 63 69 66 79 20 74 68 65 20 6e 61 6d   specify the nam
251b0 65 20 6f 66 0a 2a 2a 20 20 20 20 20 61 20 56 46  e of.**     a VF
251c0 53 20 6f 62 6a 65 63 74 20 74 68 61 74 20 70 72  S object that pr
251d0 6f 76 69 64 65 73 20 74 68 65 20 6f 70 65 72 61  ovides the opera
251e0 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65  ting system inte
251f0 72 66 61 63 65 20 74 68 61 74 20 73 68 6f 75 6c  rface that shoul
25200 64 0a 2a 2a 20 20 20 20 20 62 65 20 75 73 65 64  d.**     be used
25210 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 64   to access the d
25220 61 74 61 62 61 73 65 20 66 69 6c 65 20 6f 6e 20  atabase file on 
25230 64 69 73 6b 2e 20 5e 49 66 20 74 68 69 73 20 6f  disk. ^If this o
25240 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 0a  ption is set to.
25250 2a 2a 20 20 20 20 20 61 6e 20 65 6d 70 74 79 20  **     an empty 
25260 73 74 72 69 6e 67 20 74 68 65 20 64 65 66 61 75  string the defau
25270 6c 74 20 56 46 53 20 6f 62 6a 65 63 74 20 69 73  lt VFS object is
25280 20 75 73 65 64 2e 20 5e 53 70 65 63 69 66 79 69   used. ^Specifyi
25290 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a  ng an unknown.**
252a0 20 20 20 20 20 56 46 53 20 69 73 20 61 6e 20 65       VFS is an e
252b0 72 72 6f 72 2e 20 5e 49 66 20 73 71 6c 69 74 65  rror. ^If sqlite
252c0 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75  3_open_v2() is u
252d0 73 65 64 20 61 6e 64 20 74 68 65 20 76 66 73 20  sed and the vfs 
252e0 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20  option is.**    
252f0 20 70 72 65 73 65 6e 74 2c 20 74 68 65 6e 20 74   present, then t
25300 68 65 20 56 46 53 20 73 70 65 63 69 66 69 65 64  he VFS specified
25310 20 62 79 20 74 68 65 20 6f 70 74 69 6f 6e 20 74   by the option t
25320 61 6b 65 73 20 70 72 65 63 65 64 65 6e 63 65 20  akes precedence 
25330 6f 76 65 72 0a 2a 2a 20 20 20 20 20 74 68 65 20  over.**     the 
25340 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20  value passed as 
25350 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
25360 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
25370 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a  open_v2()..**.**
25380 20 20 20 3c 6c 69 3e 20 3c 62 3e 6d 6f 64 65 3c     <li> <b>mode<
25390 2f 62 3e 3a 20 5e 28 54 68 65 20 6d 6f 64 65 20  /b>: ^(The mode 
253a0 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65  parameter may be
253b0 20 73 65 74 20 74 6f 20 65 69 74 68 65 72 20 22   set to either "
253c0 72 6f 22 2c 20 22 72 77 22 2c 0a 2a 2a 20 20 20  ro", "rw",.**   
253d0 20 20 22 72 77 63 22 2c 20 6f 72 20 22 6d 65 6d    "rwc", or "mem
253e0 6f 72 79 22 2e 20 41 74 74 65 6d 70 74 69 6e 67  ory". Attempting
253f0 20 74 6f 20 73 65 74 20 69 74 20 74 6f 20 61 6e   to set it to an
25400 79 20 6f 74 68 65 72 20 76 61 6c 75 65 20 69 73  y other value is
25410 0a 2a 2a 20 20 20 20 20 61 6e 20 65 72 72 6f 72  .**     an error
25420 29 5e 2e 20 0a 2a 2a 20 20 20 20 20 5e 49 66 20  )^. .**     ^If 
25430 22 72 6f 22 20 69 73 20 73 70 65 63 69 66 69 65  "ro" is specifie
25440 64 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  d, then the data
25450 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66  base is opened f
25460 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 0a 2a 2a  or read-only .**
25470 20 20 20 20 20 61 63 63 65 73 73 2c 20 6a 75 73       access, jus
25480 74 20 61 73 20 69 66 20 74 68 65 20 5b 53 51 4c  t as if the [SQL
25490 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
254a0 59 5d 20 66 6c 61 67 20 68 61 64 20 62 65 65 6e  Y] flag had been
254b0 20 73 65 74 20 69 6e 20 74 68 65 20 0a 2a 2a 20   set in the .** 
254c0 20 20 20 20 74 68 69 72 64 20 61 72 67 75 6d 65      third argume
254d0 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  nt to sqlite3_op
254e0 65 6e 5f 76 32 28 29 2e 20 5e 49 66 20 74 68 65  en_v2(). ^If the
254f0 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 20   mode option is 
25500 73 65 74 20 74 6f 20 0a 2a 2a 20 20 20 20 20 22  set to .**     "
25510 72 77 22 2c 20 74 68 65 6e 20 74 68 65 20 64 61  rw", then the da
25520 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
25530 20 66 6f 72 20 72 65 61 64 2d 77 72 69 74 65 20   for read-write 
25540 28 62 75 74 20 6e 6f 74 20 63 72 65 61 74 65 29  (but not create)
25550 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c   .**     access,
25560 20 61 73 20 69 66 20 53 51 4c 49 54 45 5f 4f 50   as if SQLITE_OP
25570 45 4e 5f 52 45 41 44 57 52 49 54 45 20 28 62 75  EN_READWRITE (bu
25580 74 20 6e 6f 74 20 53 51 4c 49 54 45 5f 4f 50 45  t not SQLITE_OPE
25590 4e 5f 43 52 45 41 54 45 29 20 68 61 64 20 0a 2a  N_CREATE) had .*
255a0 2a 20 20 20 20 20 62 65 65 6e 20 73 65 74 2e 20  *     been set. 
255b0 5e 56 61 6c 75 65 20 22 72 77 63 22 20 69 73 20  ^Value "rwc" is 
255c0 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65  equivalent to se
255d0 74 74 69 6e 67 20 62 6f 74 68 20 0a 2a 2a 20 20  tting both .**  
255e0 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52     SQLITE_OPEN_R
255f0 45 41 44 57 52 49 54 45 20 61 6e 64 20 53 51 4c  EADWRITE and SQL
25600 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2e  ITE_OPEN_CREATE.
25610 20 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20 6f    ^If the mode o
25620 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20  ption is.**     
25630 73 65 74 20 74 6f 20 22 6d 65 6d 6f 72 79 22 20  set to "memory" 
25640 74 68 65 6e 20 61 20 70 75 72 65 20 5b 69 6e 2d  then a pure [in-
25650 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 5d  memory database]
25660 20 74 68 61 74 20 6e 65 76 65 72 20 72 65 61 64   that never read
25670 73 0a 2a 2a 20 20 20 20 20 6f 72 20 77 72 69 74  s.**     or writ
25680 65 73 20 66 72 6f 6d 20 64 69 73 6b 20 69 73 20  es from disk is 
25690 75 73 65 64 2e 20 5e 49 74 20 69 73 20 61 6e 20  used. ^It is an 
256a0 65 72 72 6f 72 20 74 6f 20 73 70 65 63 69 66 79  error to specify
256b0 20 61 20 76 61 6c 75 65 20 66 6f 72 0a 2a 2a 20   a value for.** 
256c0 20 20 20 20 74 68 65 20 6d 6f 64 65 20 70 61 72      the mode par
256d0 61 6d 65 74 65 72 20 74 68 61 74 20 69 73 20 6c  ameter that is l
256e0 65 73 73 20 72 65 73 74 72 69 63 74 69 76 65 20  ess restrictive 
256f0 74 68 61 6e 20 74 68 61 74 20 73 70 65 63 69 66  than that specif
25700 69 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 74 68  ied by.**     th
25710 65 20 66 6c 61 67 73 20 70 61 73 73 65 64 20 69  e flags passed i
25720 6e 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  n the third para
25730 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
25740 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a  _open_v2()..**.*
25750 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 63 61 63 68  *   <li> <b>cach
25760 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 63 61 63 68  e</b>: ^The cach
25770 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  e parameter may 
25780 62 65 20 73 65 74 20 74 6f 20 65 69 74 68 65 72  be set to either
25790 20 22 73 68 61 72 65 64 22 20 6f 72 0a 2a 2a 20   "shared" or.** 
257a0 20 20 20 20 22 70 72 69 76 61 74 65 22 2e 20 5e      "private". ^
257b0 53 65 74 74 69 6e 67 20 69 74 20 74 6f 20 22 73  Setting it to "s
257c0 68 61 72 65 64 22 20 69 73 20 65 71 75 69 76 61  hared" is equiva
257d0 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20  lent to setting 
257e0 74 68 65 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54  the.**     SQLIT
257f0 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
25800 48 45 20 62 69 74 20 69 6e 20 74 68 65 20 66 6c  HE bit in the fl
25810 61 67 73 20 61 72 67 75 6d 65 6e 74 20 70 61 73  ags argument pas
25820 73 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20 73 71  sed to.**     sq
25830 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
25840 20 5e 53 65 74 74 69 6e 67 20 74 68 65 20 63 61   ^Setting the ca
25850 63 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f  che parameter to
25860 20 22 70 72 69 76 61 74 65 22 20 69 73 20 0a 2a   "private" is .*
25870 2a 20 20 20 20 20 65 71 75 69 76 61 6c 65 6e 74  *     equivalent
25880 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65 20   to setting the 
25890 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56  SQLITE_OPEN_PRIV
258a0 41 54 45 43 41 43 48 45 20 62 69 74 2e 0a 2a 2a  ATECACHE bit..**
258b0 20 20 20 20 20 5e 49 66 20 73 71 6c 69 74 65 33       ^If sqlite3
258c0 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73  _open_v2() is us
258d0 65 64 20 61 6e 64 20 74 68 65 20 22 63 61 63 68  ed and the "cach
258e0 65 22 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  e" parameter is 
258f0 70 72 65 73 65 6e 74 20 69 6e 0a 2a 2a 20 20 20  present in.**   
25900 20 20 61 20 55 52 49 20 66 69 6c 65 6e 61 6d 65    a URI filename
25910 2c 20 69 74 73 20 76 61 6c 75 65 20 6f 76 65 72  , its value over
25920 72 69 64 65 73 20 61 6e 79 20 62 65 68 61 76 69  rides any behavi
25930 6f 72 20 72 65 71 75 65 73 74 65 64 20 62 79 20  or requested by 
25940 73 65 74 74 69 6e 67 0a 2a 2a 20 20 20 20 20 53  setting.**     S
25950 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41  QLITE_OPEN_PRIVA
25960 54 45 43 41 43 48 45 20 6f 72 20 53 51 4c 49 54  TECACHE or SQLIT
25970 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
25980 48 45 20 66 6c 61 67 2e 0a 2a 2a 0a 2a 2a 20 20  HE flag..**.**  
25990 3c 6c 69 3e 20 3c 62 3e 70 73 6f 77 3c 2f 62 3e  <li> <b>psow</b>
259a0 3a 20 5e 54 68 65 20 70 73 6f 77 20 70 61 72 61  : ^The psow para
259b0 6d 65 74 65 72 20 69 6e 64 69 63 61 74 65 73 20  meter indicates 
259c0 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
259d0 68 65 0a 2a 2a 20 20 20 20 20 5b 70 6f 77 65 72  he.**     [power
259e0 73 61 66 65 20 6f 76 65 72 77 72 69 74 65 5d 20  safe overwrite] 
259f0 70 72 6f 70 65 72 74 79 20 64 6f 65 73 20 6f 72  property does or
25a00 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 6c 79 20   does not apply 
25a10 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 73 74  to the.**     st
25a20 6f 72 61 67 65 20 6d 65 64 69 61 20 6f 6e 20 77  orage media on w
25a30 68 69 63 68 20 74 68 65 20 64 61 74 61 62 61 73  hich the databas
25a40 65 20 66 69 6c 65 20 72 65 73 69 64 65 73 2e 0a  e file resides..
25a50 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 6e  **.**  <li> <b>n
25a60 6f 6c 6f 63 6b 3c 2f 62 3e 3a 20 5e 54 68 65 20  olock</b>: ^The 
25a70 6e 6f 6c 6f 63 6b 20 70 61 72 61 6d 65 74 65 72  nolock parameter
25a80 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 20 71 75   is a boolean qu
25a90 65 72 79 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  ery parameter.**
25aa0 20 20 20 20 20 77 68 69 63 68 20 69 66 20 73 65       which if se
25ab0 74 20 64 69 73 61 62 6c 65 73 20 66 69 6c 65 20  t disables file 
25ac0 6c 6f 63 6b 69 6e 67 20 69 6e 20 72 6f 6c 6c 62  locking in rollb
25ad0 61 63 6b 20 6a 6f 75 72 6e 61 6c 20 6d 6f 64 65  ack journal mode
25ae0 73 2e 20 20 54 68 69 73 0a 2a 2a 20 20 20 20 20  s.  This.**     
25af0 69 73 20 75 73 65 66 75 6c 20 66 6f 72 20 61 63  is useful for ac
25b00 63 65 73 73 69 6e 67 20 61 20 64 61 74 61 62 61  cessing a databa
25b10 73 65 20 6f 6e 20 61 20 66 69 6c 65 73 79 73 74  se on a filesyst
25b20 65 6d 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74  em that does not
25b30 0a 2a 2a 20 20 20 20 20 73 75 70 70 6f 72 74 20  .**     support 
25b40 6c 6f 63 6b 69 6e 67 2e 20 20 43 61 75 74 69 6f  locking.  Cautio
25b50 6e 3a 20 20 44 61 74 61 62 61 73 65 20 63 6f 72  n:  Database cor
25b60 72 75 70 74 69 6f 6e 20 6d 69 67 68 74 20 72 65  ruption might re
25b70 73 75 6c 74 20 69 66 20 74 77 6f 0a 2a 2a 20 20  sult if two.**  
25b80 20 20 20 6f 72 20 6d 6f 72 65 20 70 72 6f 63 65     or more proce
25b90 73 73 65 73 20 77 72 69 74 65 20 74 6f 20 74 68  sses write to th
25ba0 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
25bb0 61 6e 64 20 61 6e 79 20 6f 6e 65 20 6f 66 20 74  and any one of t
25bc0 68 6f 73 65 0a 2a 2a 20 20 20 20 20 70 72 6f 63  hose.**     proc
25bd0 65 73 73 65 73 20 75 73 65 73 20 6e 6f 6c 6f 63  esses uses noloc
25be0 6b 3d 31 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e  k=1..**.**  <li>
25bf0 20 3c 62 3e 69 6d 6d 75 74 61 62 6c 65 3c 2f 62   <b>immutable</b
25c00 3e 3a 20 5e 54 68 65 20 69 6d 6d 75 74 61 62 6c  >: ^The immutabl
25c10 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  e parameter is a
25c20 20 62 6f 6f 6c 65 61 6e 20 71 75 65 72 79 0a 2a   boolean query.*
25c30 2a 20 20 20 20 20 70 61 72 61 6d 65 74 65 72 20  *     parameter 
25c40 74 68 61 74 20 69 6e 64 69 63 61 74 65 73 20 74  that indicates t
25c50 68 61 74 20 74 68 65 20 64 61 74 61 62 61 73 65  hat the database
25c60 20 66 69 6c 65 20 69 73 20 73 74 6f 72 65 64 20   file is stored 
25c70 6f 6e 0a 2a 2a 20 20 20 20 20 72 65 61 64 2d 6f  on.**     read-o
25c80 6e 6c 79 20 6d 65 64 69 61 2e 20 20 5e 57 68 65  nly media.  ^Whe
25c90 6e 20 69 6d 6d 75 74 61 62 6c 65 20 69 73 20 73  n immutable is s
25ca0 65 74 2c 20 53 51 4c 69 74 65 20 61 73 73 75 6d  et, SQLite assum
25cb0 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 20  es that the.**  
25cc0 20 20 20 64 61 74 61 62 61 73 65 20 66 69 6c 65     database file
25cd0 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67   cannot be chang
25ce0 65 64 2c 20 65 76 65 6e 20 62 79 20 61 20 70 72  ed, even by a pr
25cf0 6f 63 65 73 73 20 77 69 74 68 20 68 69 67 68 65  ocess with highe
25d00 72 0a 2a 2a 20 20 20 20 20 70 72 69 76 69 6c 65  r.**     privile
25d10 67 65 2c 20 61 6e 64 20 73 6f 20 74 68 65 20 64  ge, and so the d
25d20 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
25d30 64 20 72 65 61 64 2d 6f 6e 6c 79 20 61 6e 64 20  d read-only and 
25d40 61 6c 6c 20 6c 6f 63 6b 69 6e 67 0a 2a 2a 20 20  all locking.**  
25d50 20 20 20 61 6e 64 20 63 68 61 6e 67 65 20 64 65     and change de
25d60 74 65 63 74 69 6f 6e 20 69 73 20 64 69 73 61 62  tection is disab
25d70 6c 65 64 2e 20 20 43 61 75 74 69 6f 6e 3a 20 53  led.  Caution: S
25d80 65 74 74 69 6e 67 20 74 68 65 20 69 6d 6d 75 74  etting the immut
25d90 61 62 6c 65 0a 2a 2a 20 20 20 20 20 70 72 6f 70  able.**     prop
25da0 65 72 74 79 20 6f 6e 20 61 20 64 61 74 61 62 61  erty on a databa
25db0 73 65 20 66 69 6c 65 20 74 68 61 74 20 64 6f 65  se file that doe
25dc0 73 20 69 6e 20 66 61 63 74 20 63 68 61 6e 67 65  s in fact change
25dd0 20 63 61 6e 20 72 65 73 75 6c 74 0a 2a 2a 20 20   can result.**  
25de0 20 20 20 69 6e 20 69 6e 63 6f 72 72 65 63 74 20     in incorrect 
25df0 71 75 65 72 79 20 72 65 73 75 6c 74 73 20 61 6e  query results an
25e00 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 52  d/or [SQLITE_COR
25e10 52 55 50 54 5d 20 65 72 72 6f 72 73 2e 0a 2a 2a  RUPT] errors..**
25e20 20 20 20 20 20 53 65 65 20 61 6c 73 6f 3a 20 5b       See also: [
25e30 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d  SQLITE_IOCAP_IMM
25e40 55 54 41 42 4c 45 5d 2e 0a 2a 2a 20 20 20 20 20  UTABLE]..**     
25e50 20 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a    .** </ul>.**.*
25e60 2a 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e  * ^Specifying an
25e70 20 75 6e 6b 6e 6f 77 6e 20 70 61 72 61 6d 65 74   unknown paramet
25e80 65 72 20 69 6e 20 74 68 65 20 71 75 65 72 79 20  er in the query 
25e90 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55  component of a U
25ea0 52 49 20 69 73 20 6e 6f 74 20 61 6e 0a 2a 2a 20  RI is not an.** 
25eb0 65 72 72 6f 72 2e 20 20 46 75 74 75 72 65 20 76  error.  Future v
25ec0 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
25ed0 65 20 6d 69 67 68 74 20 75 6e 64 65 72 73 74 61  e might understa
25ee0 6e 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 71 75  nd additional qu
25ef0 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ery.** parameter
25f00 73 2e 20 20 53 65 65 20 22 5b 71 75 65 72 79 20  s.  See "[query 
25f10 70 61 72 61 6d 65 74 65 72 73 20 77 69 74 68 20  parameters with 
25f20 73 70 65 63 69 61 6c 20 6d 65 61 6e 69 6e 67 20  special meaning 
25f30 74 6f 20 53 51 4c 69 74 65 5d 22 20 66 6f 72 0a  to SQLite]" for.
25f40 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  ** additional in
25f50 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
25f60 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 20   [[URI filename 
25f70 65 78 61 6d 70 6c 65 73 5d 5d 20 3c 68 33 3e 55  examples]] <h3>U
25f80 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d  RI filename exam
25f90 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20  ples</h3>.**.** 
25fa0 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31  <table border="1
25fb0 22 20 61 6c 69 67 6e 3d 63 65 6e 74 65 72 20 63  " align=center c
25fc0 65 6c 6c 70 61 64 64 69 6e 67 3d 35 3e 0a 2a 2a  ellpadding=5>.**
25fd0 20 3c 74 72 3e 3c 74 68 3e 20 55 52 49 20 66 69   <tr><th> URI fi
25fe0 6c 65 6e 61 6d 65 73 20 3c 74 68 3e 20 52 65 73  lenames <th> Res
25ff0 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  ults.** <tr><td>
26000 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 20 3c 74   file:data.db <t
26010 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  d> .**          
26020 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22 64  Open the file "d
26030 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63  ata.db" in the c
26040 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79  urrent directory
26050 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  ..** <tr><td> fi
26060 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61  le:/home/fred/da
26070 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a 20 20 20 20  ta.db<br>.**    
26080 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 68 6f        file:///ho
26090 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20  me/fred/data.db 
260a0 3c 62 72 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  <br> .**        
260b0 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63 61 6c 68 6f    file://localho
260c0 73 74 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74  st/home/fred/dat
260d0 61 2e 64 62 20 3c 62 72 3e 20 3c 74 64 3e 20 0a  a.db <br> <td> .
260e0 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e  **          Open
260f0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
26100 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  le "/home/fred/d
26110 61 74 61 2e 64 62 22 2e 0a 2a 2a 20 3c 74 72 3e  ata.db"..** <tr>
26120 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f 64 61 72 6b  <td> file://dark
26130 73 74 61 72 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  star/home/fred/d
26140 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20  ata.db <td> .** 
26150 20 20 20 20 20 20 20 20 20 41 6e 20 65 72 72 6f           An erro
26160 72 2e 20 22 64 61 72 6b 73 74 61 72 22 20 69 73  r. "darkstar" is
26170 20 6e 6f 74 20 61 20 72 65 63 6f 67 6e 69 7a 65   not a recognize
26180 64 20 61 75 74 68 6f 72 69 74 79 2e 0a 2a 2a 20  d authority..** 
26190 3c 74 72 3e 3c 74 64 20 73 74 79 6c 65 3d 22 77  <tr><td style="w
261a0 68 69 74 65 2d 73 70 61 63 65 3a 6e 6f 77 72 61  hite-space:nowra
261b0 70 22 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  p"> .**         
261c0 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f 63 75   file:///C:/Docu
261d0 6d 65 6e 74 73 25 32 30 61 6e 64 25 32 30 53 65  ments%20and%20Se
261e0 74 74 69 6e 67 73 2f 66 72 65 64 2f 44 65 73 6b  ttings/fred/Desk
261f0 74 6f 70 2f 64 61 74 61 2e 64 62 0a 2a 2a 20 20  top/data.db.**  
26200 20 20 20 3c 74 64 3e 20 57 69 6e 64 6f 77 73 20     <td> Windows 
26210 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74 68 65 20 66  only: Open the f
26220 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 6f 6e  ile "data.db" on
26230 20 66 72 65 64 27 73 20 64 65 73 6b 74 6f 70 20   fred's desktop 
26240 6f 6e 20 64 72 69 76 65 0a 2a 2a 20 20 20 20 20  on drive.**     
26250 20 20 20 20 20 43 3a 2e 20 4e 6f 74 65 20 74 68       C:. Note th
26260 61 74 20 74 68 65 20 25 32 30 20 65 73 63 61 70  at the %20 escap
26270 69 6e 67 20 69 6e 20 74 68 69 73 20 65 78 61 6d  ing in this exam
26280 70 6c 65 20 69 73 20 6e 6f 74 20 73 74 72 69 63  ple is not stric
26290 74 6c 79 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  tly .**         
262a0 20 6e 65 63 65 73 73 61 72 79 20 2d 20 73 70 61   necessary - spa
262b0 63 65 20 63 68 61 72 61 63 74 65 72 73 20 63 61  ce characters ca
262c0 6e 20 62 65 20 75 73 65 64 20 6c 69 74 65 72 61  n be used litera
262d0 6c 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  lly.**          
262e0 69 6e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73  in URI filenames
262f0 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  ..** <tr><td> fi
26300 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d  le:data.db?mode=
26310 72 6f 26 63 61 63 68 65 3d 70 72 69 76 61 74 65  ro&cache=private
26320 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20   <td> .**       
26330 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 64 61     Open file "da
26340 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63 75  ta.db" in the cu
26350 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79 20  rrent directory 
26360 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 61 63  for read-only ac
26370 63 65 73 73 2e 0a 2a 2a 20 20 20 20 20 20 20 20  cess..**        
26380 20 20 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20    Regardless of 
26390 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73  whether or not s
263a0 68 61 72 65 64 2d 63 61 63 68 65 20 6d 6f 64 65  hared-cache mode
263b0 20 69 73 20 65 6e 61 62 6c 65 64 20 62 79 0a 2a   is enabled by.*
263c0 2a 20 20 20 20 20 20 20 20 20 20 64 65 66 61 75  *          defau
263d0 6c 74 2c 20 75 73 65 20 61 20 70 72 69 76 61 74  lt, use a privat
263e0 65 20 63 61 63 68 65 2e 0a 2a 2a 20 3c 74 72 3e  e cache..** <tr>
263f0 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f  <td> file:/home/
26400 66 72 65 64 2f 64 61 74 61 2e 64 62 3f 76 66 73  fred/data.db?vfs
26410 3d 75 6e 69 78 2d 64 6f 74 66 69 6c 65 20 3c 74  =unix-dotfile <t
26420 64 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f  d>.**          O
26430 70 65 6e 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f  pen file "/home/
26440 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 20 55  fred/data.db". U
26450 73 65 20 74 68 65 20 73 70 65 63 69 61 6c 20 56  se the special V
26460 46 53 20 22 75 6e 69 78 2d 64 6f 74 66 69 6c 65  FS "unix-dotfile
26470 22 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  ".**          th
26480 61 74 20 75 73 65 73 20 64 6f 74 2d 66 69 6c 65  at uses dot-file
26490 73 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 70 6f  s in place of po
264a0 73 69 78 20 61 64 76 69 73 6f 72 79 20 6c 6f 63  six advisory loc
264b0 6b 69 6e 67 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  king..** <tr><td
264c0 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d  > file:data.db?m
264d0 6f 64 65 3d 72 65 61 64 6f 6e 6c 79 20 3c 74 64  ode=readonly <td
264e0 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41  > .**          A
264f0 6e 20 65 72 72 6f 72 2e 20 22 72 65 61 64 6f 6e  n error. "readon
26500 6c 79 22 20 69 73 20 6e 6f 74 20 61 20 76 61 6c  ly" is not a val
26510 69 64 20 6f 70 74 69 6f 6e 20 66 6f 72 20 74 68  id option for th
26520 65 20 22 6d 6f 64 65 22 20 70 61 72 61 6d 65 74  e "mode" paramet
26530 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a  er..** </table>.
26540 2a 2a 0a 2a 2a 20 5e 55 52 49 20 68 65 78 61 64  **.** ^URI hexad
26550 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65  ecimal escape se
26560 71 75 65 6e 63 65 73 20 28 25 48 48 29 20 61 72  quences (%HH) ar
26570 65 20 73 75 70 70 6f 72 74 65 64 20 77 69 74 68  e supported with
26580 69 6e 20 74 68 65 20 70 61 74 68 20 61 6e 64 0a  in the path and.
26590 2a 2a 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65  ** query compone
265a0 6e 74 73 20 6f 66 20 61 20 55 52 49 2e 20 41 20  nts of a URI. A 
265b0 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61  hexadecimal esca
265c0 70 65 20 73 65 71 75 65 6e 63 65 20 63 6f 6e 73  pe sequence cons
265d0 69 73 74 73 20 6f 66 20 61 0a 2a 2a 20 70 65 72  ists of a.** per
265e0 63 65 6e 74 20 73 69 67 6e 20 2d 20 22 25 22 20  cent sign - "%" 
265f0 2d 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 65 78  - followed by ex
26600 61 63 74 6c 79 20 74 77 6f 20 68 65 78 61 64 65  actly two hexade
26610 63 69 6d 61 6c 20 64 69 67 69 74 73 20 0a 2a 2a  cimal digits .**
26620 20 73 70 65 63 69 66 79 69 6e 67 20 61 6e 20 6f   specifying an o
26630 63 74 65 74 20 76 61 6c 75 65 2e 20 5e 42 65 66  ctet value. ^Bef
26640 6f 72 65 20 74 68 65 20 70 61 74 68 20 6f 72 20  ore the path or 
26650 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73  query components
26660 20 6f 66 20 61 0a 2a 2a 20 55 52 49 20 66 69 6c   of a.** URI fil
26670 65 6e 61 6d 65 20 61 72 65 20 69 6e 74 65 72 70  ename are interp
26680 72 65 74 65 64 2c 20 74 68 65 79 20 61 72 65 20  reted, they are 
26690 65 6e 63 6f 64 65 64 20 75 73 69 6e 67 20 55 54  encoded using UT
266a0 46 2d 38 20 61 6e 64 20 61 6c 6c 20 0a 2a 2a 20  F-8 and all .** 
266b0 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61  hexadecimal esca
266c0 70 65 20 73 65 71 75 65 6e 63 65 73 20 72 65 70  pe sequences rep
266d0 6c 61 63 65 64 20 62 79 20 61 20 73 69 6e 67 6c  laced by a singl
266e0 65 20 62 79 74 65 20 63 6f 6e 74 61 69 6e 69 6e  e byte containin
266f0 67 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 73 70  g the.** corresp
26700 6f 6e 64 69 6e 67 20 6f 63 74 65 74 2e 20 49 66  onding octet. If
26710 20 74 68 69 73 20 70 72 6f 63 65 73 73 20 67 65   this process ge
26720 6e 65 72 61 74 65 73 20 61 6e 20 69 6e 76 61 6c  nerates an inval
26730 69 64 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e  id UTF-8 encodin
26740 67 2c 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74  g,.** the result
26750 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
26760 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74  .**.** <b>Note t
26770 6f 20 57 69 6e 64 6f 77 73 20 75 73 65 72 73 3a  o Windows users:
26780 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f 64 69  </b>  The encodi
26790 6e 67 20 75 73 65 64 20 66 6f 72 20 74 68 65 20  ng used for the 
267a0 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
267b0 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f  t.** of sqlite3_
267c0 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  open() and sqlit
267d0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73  e3_open_v2() mus
267e0 74 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20  t be UTF-8, not 
267f0 77 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65  whatever.** code
26800 70 61 67 65 20 69 73 20 63 75 72 72 65 6e 74 6c  page is currentl
26810 79 20 64 65 66 69 6e 65 64 2e 20 20 46 69 6c 65  y defined.  File
26820 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67  names containing
26830 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a   international.*
26840 2a 20 63 68 61 72 61 63 74 65 72 73 20 6d 75 73  * characters mus
26850 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20 74  t be converted t
26860 6f 20 55 54 46 2d 38 20 70 72 69 6f 72 20 74 6f  o UTF-8 prior to
26870 20 70 61 73 73 69 6e 67 20 74 68 65 6d 20 69 6e   passing them in
26880 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70  to.** sqlite3_op
26890 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  en() or sqlite3_
268a0 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a  open_v2()..**.**
268b0 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64   <b>Note to Wind
268c0 6f 77 73 20 52 75 6e 74 69 6d 65 20 75 73 65 72  ows Runtime user
268d0 73 3a 3c 2f 62 3e 20 20 54 68 65 20 74 65 6d 70  s:</b>  The temp
268e0 6f 72 61 72 79 20 64 69 72 65 63 74 6f 72 79 20  orary directory 
268f0 6d 75 73 74 20 62 65 20 73 65 74 0a 2a 2a 20 70  must be set.** p
26900 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20  rior to calling 
26910 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f  sqlite3_open() o
26920 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
26930 32 28 29 2e 20 20 4f 74 68 65 72 77 69 73 65 2c  2().  Otherwise,
26940 20 76 61 72 69 6f 75 73 0a 2a 2a 20 66 65 61 74   various.** feat
26950 75 72 65 73 20 74 68 61 74 20 72 65 71 75 69 72  ures that requir
26960 65 20 74 68 65 20 75 73 65 20 6f 66 20 74 65 6d  e the use of tem
26970 70 6f 72 61 72 79 20 66 69 6c 65 73 20 6d 61 79  porary files may
26980 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 65   fail..**.** See
26990 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
269a0 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 5d 0a  temp_directory].
269b0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
269c0 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
269d0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20   sqlite3_open(. 
269e0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c   const char *fil
269f0 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61  ename,   /* Data
26a00 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55  base filename (U
26a10 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74  TF-8) */.  sqlit
26a20 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20  e3 **ppDb       
26a30 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74     /* OUT: SQLit
26a40 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29  e db handle */.)
26a50 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
26a60 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
26a70 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a  sqlite3_open16(.
26a80 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69    const void *fi
26a90 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74  lename,   /* Dat
26aa0 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28  abase filename (
26ab0 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c  UTF-16) */.  sql
26ac0 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20  ite3 **ppDb     
26ad0 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c       /* OUT: SQL
26ae0 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f  ite db handle */
26af0 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .);.SQLITE_API i
26b00 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  nt SQLITE_STDCAL
26b10 4c 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  L sqlite3_open_v
26b20 32 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  2(.  const char 
26b30 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20  *filename,   /* 
26b40 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  Database filenam
26b50 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73  e (UTF-8) */.  s
26b60 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c 20 20  qlite3 **ppDb,  
26b70 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53         /* OUT: S
26b80 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20  QLite db handle 
26b90 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 20  */.  int flags, 
26ba0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
26bb0 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74  Flags */.  const
26bc0 20 63 68 61 72 20 2a 7a 56 66 73 20 20 20 20 20   char *zVfs     
26bd0 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46     /* Name of VF
26be0 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65 20  S module to use 
26bf0 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.);../*.** CAP
26c00 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 56 61  I3REF: Obtain Va
26c10 6c 75 65 73 20 46 6f 72 20 55 52 49 20 50 61 72  lues For URI Par
26c20 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68  ameters.**.** Th
26c30 65 73 65 20 61 72 65 20 75 74 69 6c 69 74 79 20  ese are utility 
26c40 72 6f 75 74 69 6e 65 73 2c 20 75 73 65 66 75 6c  routines, useful
26c50 20 74 6f 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e   to VFS implemen
26c60 74 61 74 69 6f 6e 73 2c 20 74 68 61 74 20 63 68  tations, that ch
26c70 65 63 6b 0a 2a 2a 20 74 6f 20 73 65 65 20 69 66  eck.** to see if
26c80 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65   a database file
26c90 20 77 61 73 20 61 20 55 52 49 20 74 68 61 74 20   was a URI that 
26ca0 63 6f 6e 74 61 69 6e 65 64 20 61 20 73 70 65 63  contained a spec
26cb0 69 66 69 63 20 71 75 65 72 79 20 0a 2a 2a 20 70  ific query .** p
26cc0 61 72 61 6d 65 74 65 72 2c 20 61 6e 64 20 69 66  arameter, and if
26cd0 20 73 6f 20 6f 62 74 61 69 6e 73 20 74 68 65 20   so obtains the 
26ce0 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20 71 75  value of that qu
26cf0 65 72 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  ery parameter..*
26d00 2a 0a 2a 2a 20 49 66 20 46 20 69 73 20 74 68 65  *.** If F is the
26d10 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   database filena
26d20 6d 65 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65  me pointer passe
26d30 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e  d into the xOpen
26d40 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 0a 2a 2a  () method of .**
26d50 20 61 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74   a VFS implement
26d60 61 74 69 6f 6e 20 77 68 65 6e 20 74 68 65 20 66  ation when the f
26d70 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 74  lags parameter t
26d80 6f 20 78 4f 70 65 6e 28 29 20 68 61 73 20 6f 6e  o xOpen() has on
26d90 65 20 6f 72 20 0a 2a 2a 20 6d 6f 72 65 20 6f 66  e or .** more of
26da0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   the [SQLITE_OPE
26db0 4e 5f 55 52 49 5d 20 6f 72 20 5b 53 51 4c 49 54  N_URI] or [SQLIT
26dc0 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 20  E_OPEN_MAIN_DB] 
26dd0 62 69 74 73 20 73 65 74 20 61 6e 64 0a 2a 2a 20  bits set and.** 
26de0 50 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  P is the name of
26df0 20 74 68 65 20 71 75 65 72 79 20 70 61 72 61 6d   the query param
26e00 65 74 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 73 71  eter, then.** sq
26e10 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65  lite3_uri_parame
26e20 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73  ter(F,P) returns
26e30 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
26e40 65 20 50 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  e P.** parameter
26e50 20 69 66 20 69 74 20 65 78 69 73 74 73 20 6f 72   if it exists or
26e60 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
26e70 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 20 61 70  if P does not ap
26e80 70 65 61 72 20 61 73 20 61 20 0a 2a 2a 20 71 75  pear as a .** qu
26e90 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f 6e  ery parameter on
26ea0 20 46 2e 20 20 49 66 20 50 20 69 73 20 61 20 71   F.  If P is a q
26eb0 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f  uery parameter o
26ec0 66 20 46 0a 2a 2a 20 68 61 73 20 6e 6f 20 65 78  f F.** has no ex
26ed0 70 6c 69 63 69 74 20 76 61 6c 75 65 2c 20 74 68  plicit value, th
26ee0 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70  en sqlite3_uri_p
26ef0 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65  arameter(F,P) re
26f00 74 75 72 6e 73 0a 2a 2a 20 61 20 70 6f 69 6e 74  turns.** a point
26f10 65 72 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73  er to an empty s
26f20 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tring..**.** The
26f30 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f   sqlite3_uri_boo
26f40 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74  lean(F,P,B) rout
26f50 69 6e 65 20 61 73 73 75 6d 65 73 20 74 68 61 74  ine assumes that
26f60 20 50 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 0a   P is a boolean.
26f70 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64  ** parameter and
26f80 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 31   returns true (1
26f90 29 20 6f 72 20 66 61 6c 73 65 20 28 30 29 20 61  ) or false (0) a
26fa0 63 63 6f 72 64 69 6e 67 20 74 6f 20 74 68 65 20  ccording to the 
26fb0 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 50 2e 20 20  value.** of P.  
26fc0 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  The sqlite3_uri_
26fd0 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72  boolean(F,P,B) r
26fe0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
26ff0 72 75 65 20 28 31 29 20 69 66 20 74 68 65 0a 2a  rue (1) if the.*
27000 2a 20 76 61 6c 75 65 20 6f 66 20 71 75 65 72 79  * value of query
27010 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20   parameter P is 
27020 6f 6e 65 20 6f 66 20 22 79 65 73 22 2c 20 22 74  one of "yes", "t
27030 72 75 65 22 2c 20 6f 72 20 22 6f 6e 22 20 69 6e  rue", or "on" in
27040 20 61 6e 79 0a 2a 2a 20 63 61 73 65 20 6f 72 20   any.** case or 
27050 69 66 20 74 68 65 20 76 61 6c 75 65 20 62 65 67  if the value beg
27060 69 6e 73 20 77 69 74 68 20 61 20 6e 6f 6e 2d 7a  ins with a non-z
27070 65 72 6f 20 6e 75 6d 62 65 72 2e 20 20 54 68 65  ero number.  The
27080 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69   .** sqlite3_uri
27090 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20  _boolean(F,P,B) 
270a0 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 73  routines returns
270b0 20 66 61 6c 73 65 20 28 30 29 20 69 66 20 74 68   false (0) if th
270c0 65 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 71 75  e value of.** qu
270d0 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 50 20  ery parameter P 
270e0 69 73 20 6f 6e 65 20 6f 66 20 22 6e 6f 22 2c 20  is one of "no", 
270f0 22 66 61 6c 73 65 22 2c 20 6f 72 20 22 6f 66 66  "false", or "off
27100 22 20 69 6e 20 61 6e 79 20 63 61 73 65 20 6f 72  " in any case or
27110 0a 2a 2a 20 69 66 20 74 68 65 20 76 61 6c 75 65  .** if the value
27120 20 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e   begins with a n
27130 75 6d 65 72 69 63 20 7a 65 72 6f 2e 20 20 49 66  umeric zero.  If
27140 20 50 20 69 73 20 6e 6f 74 20 61 20 71 75 65 72   P is not a quer
27150 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 6f  y.** parameter o
27160 6e 20 46 20 6f 72 20 69 66 20 74 68 65 20 76 61  n F or if the va
27170 6c 75 65 20 6f 66 20 50 20 69 73 20 64 6f 65 73  lue of P is does
27180 20 6e 6f 74 20 6d 61 74 63 68 20 61 6e 79 20 6f   not match any o
27190 66 20 74 68 65 0a 2a 2a 20 61 62 6f 76 65 2c 20  f the.** above, 
271a0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69  then sqlite3_uri
271b0 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20  _boolean(F,P,B) 
271c0 72 65 74 75 72 6e 73 20 28 42 21 3d 30 29 2e 0a  returns (B!=0)..
271d0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
271e0 33 5f 75 72 69 5f 69 6e 74 36 34 28 46 2c 50 2c  3_uri_int64(F,P,
271f0 44 29 20 72 6f 75 74 69 6e 65 20 63 6f 6e 76 65  D) routine conve
27200 72 74 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66  rts the value of
27210 20 50 20 69 6e 74 6f 20 61 0a 2a 2a 20 36 34 2d   P into a.** 64-
27220 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67  bit signed integ
27230 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 74  er and returns t
27240 68 61 74 20 69 6e 74 65 67 65 72 2c 20 6f 72 20  hat integer, or 
27250 44 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 0a  D if P does not.
27260 2a 2a 20 65 78 69 73 74 2e 20 20 49 66 20 74 68  ** exist.  If th
27270 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20  e value of P is 
27280 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20  something other 
27290 74 68 61 6e 20 61 6e 20 69 6e 74 65 67 65 72 2c  than an integer,
272a0 20 74 68 65 6e 0a 2a 2a 20 7a 65 72 6f 20 69 73   then.** zero is
272b0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 0a 2a   returned..** .*
272c0 2a 20 49 66 20 46 20 69 73 20 61 20 4e 55 4c 4c  * If F is a NULL
272d0 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 73   pointer, then s
272e0 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d  qlite3_uri_param
272f0 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e  eter(F,P) return
27300 73 20 4e 55 4c 4c 20 61 6e 64 0a 2a 2a 20 73 71  s NULL and.** sq
27310 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61  lite3_uri_boolea
27320 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73  n(F,P,B) returns
27330 20 42 2e 20 20 49 66 20 46 20 69 73 20 6e 6f 74   B.  If F is not
27340 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
27350 61 6e 64 0a 2a 2a 20 69 73 20 6e 6f 74 20 61 20  and.** is not a 
27360 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 70 61  database file pa
27370 74 68 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 74  thname pointer t
27380 68 61 74 20 53 51 4c 69 74 65 20 70 61 73 73 65  hat SQLite passe
27390 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e  d into the xOpen
273a0 0a 2a 2a 20 56 46 53 20 6d 65 74 68 6f 64 2c 20  .** VFS method, 
273b0 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
273c0 72 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e  r of this routin
273d0 65 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61  e is undefined a
273e0 6e 64 20 70 72 6f 62 61 62 6c 79 0a 2a 2a 20 75  nd probably.** u
273f0 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2f 0a 53  ndesirable..*/.S
27400 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
27410 63 68 61 72 20 2a 53 51 4c 49 54 45 5f 53 54 44  char *SQLITE_STD
27420 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 75 72 69  CALL sqlite3_uri
27430 5f 70 61 72 61 6d 65 74 65 72 28 63 6f 6e 73 74  _parameter(const
27440 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65   char *zFilename
27450 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50  , const char *zP
27460 61 72 61 6d 29 3b 0a 53 51 4c 49 54 45 5f 41 50  aram);.SQLITE_AP
27470 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  I int SQLITE_STD
27480 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 75 72 69  CALL sqlite3_uri
27490 5f 62 6f 6f 6c 65 61 6e 28 63 6f 6e 73 74 20 63  _boolean(const c
274a0 68 61 72 20 2a 7a 46 69 6c 65 2c 20 63 6f 6e 73  har *zFile, cons
274b0 74 20 63 68 61 72 20 2a 7a 50 61 72 61 6d 2c 20  t char *zParam, 
274c0 69 6e 74 20 62 44 65 66 61 75 6c 74 29 3b 0a 53  int bDefault);.S
274d0 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65  QLITE_API sqlite
274e0 33 5f 69 6e 74 36 34 20 53 51 4c 49 54 45 5f 53  3_int64 SQLITE_S
274f0 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 75  TDCALL sqlite3_u
27500 72 69 5f 69 6e 74 36 34 28 63 6f 6e 73 74 20 63  ri_int64(const c
27510 68 61 72 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  har*, const char
27520 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
27530 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  );.../*.** CAPI3
27540 52 45 46 3a 20 45 72 72 6f 72 20 43 6f 64 65 73  REF: Error Codes
27550 20 41 6e 64 20 4d 65 73 73 61 67 65 73 0a 2a 2a   And Messages.**
27560 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
27570 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d  .**.** ^If the m
27580 6f 73 74 20 72 65 63 65 6e 74 20 73 71 6c 69 74  ost recent sqlit
27590 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c 20 61 73  e3_* API call as
275a0 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 0a 2a  sociated with .*
275b0 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
275c0 65 63 74 69 6f 6e 5d 20 44 20 66 61 69 6c 65 64  ection] D failed
275d0 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74  , then the sqlit
275e0 65 33 5f 65 72 72 63 6f 64 65 28 44 29 20 69 6e  e3_errcode(D) in
275f0 74 65 72 66 61 63 65 0a 2a 2a 20 72 65 74 75 72  terface.** retur
27600 6e 73 20 74 68 65 20 6e 75 6d 65 72 69 63 20 5b  ns the numeric [
27610 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20  result code] or 
27620 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
27630 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 61 74 0a   code] for that.
27640 2a 2a 20 41 50 49 20 63 61 6c 6c 2e 0a 2a 2a 20  ** API call..** 
27650 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  If the most rece
27660 6e 74 20 41 50 49 20 63 61 6c 6c 20 77 61 73 20  nt API call was 
27670 73 75 63 63 65 73 73 66 75 6c 2c 0a 2a 2a 20 74  successful,.** t
27680 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76  hen the return v
27690 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65  alue from sqlite
276a0 33 5f 65 72 72 63 6f 64 65 28 29 20 69 73 20 75  3_errcode() is u
276b0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 54 68  ndefined..** ^Th
276c0 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64  e sqlite3_extend
276d0 65 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20  ed_errcode().** 
276e0 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 65  interface is the
276f0 20 73 61 6d 65 20 65 78 63 65 70 74 20 74 68 61   same except tha
27700 74 20 69 74 20 61 6c 77 61 79 73 20 72 65 74 75  t it always retu
27710 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65 78 74  rns the .** [ext
27720 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
27730 65 5d 20 65 76 65 6e 20 77 68 65 6e 20 65 78 74  e] even when ext
27740 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
27750 65 73 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c  es are.** disabl
27760 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
27770 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 20  qlite3_errmsg() 
27780 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 72 72 6d  and sqlite3_errm
27790 73 67 31 36 28 29 20 72 65 74 75 72 6e 20 45 6e  sg16() return En
277a0 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a  glish-language.*
277b0 2a 20 74 65 78 74 20 74 68 61 74 20 64 65 73 63  * text that desc
277c0 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2c  ribes the error,
277d0 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38   as either UTF-8
277e0 20 6f 72 20 55 54 46 2d 31 36 20 72 65 73 70 65   or UTF-16 respe
277f0 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65  ctively..** ^(Me
27800 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65  mory to hold the
27810 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73   error message s
27820 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64  tring is managed
27830 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20   internally..** 
27840 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
27850 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
27860 20 77 6f 72 72 79 20 61 62 6f 75 74 20 66 72 65   worry about fre
27870 65 69 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2e  eing the result.
27880 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65  .** However, the
27890 20 65 72 72 6f 72 20 73 74 72 69 6e 67 20 6d 69   error string mi
278a0 67 68 74 20 62 65 20 6f 76 65 72 77 72 69 74 74  ght be overwritt
278b0 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65  en or deallocate
278c0 64 20 62 79 0a 2a 2a 20 73 75 62 73 65 71 75 65  d by.** subseque
278d0 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65  nt calls to othe
278e0 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  r SQLite interfa
278f0 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a  ce functions.)^.
27900 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
27910 65 33 5f 65 72 72 73 74 72 28 29 20 69 6e 74 65  e3_errstr() inte
27920 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
27930 65 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61  e English-langua
27940 67 65 20 74 65 78 74 0a 2a 2a 20 74 68 61 74 20  ge text.** that 
27950 64 65 73 63 72 69 62 65 73 20 74 68 65 20 5b 72  describes the [r
27960 65 73 75 6c 74 20 63 6f 64 65 5d 2c 20 61 73 20  esult code], as 
27970 55 54 46 2d 38 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f  UTF-8..** ^(Memo
27980 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65  ry to hold the e
27990 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72  rror message str
279a0 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69  ing is managed i
279b0 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 61 6e 64  nternally.** and
279c0 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 66 72 65   must not be fre
279d0 65 64 20 62 79 20 74 68 65 20 61 70 70 6c 69 63  ed by the applic
279e0 61 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a 2a 2a 20 57  ation)^..**.** W
279f0 68 65 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a  hen the serializ
27a00 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ed [threading mo
27a10 64 65 5d 20 69 73 20 69 6e 20 75 73 65 2c 20 69  de] is in use, i
27a20 74 20 6d 69 67 68 74 20 62 65 20 74 68 65 0a 2a  t might be the.*
27a30 2a 20 63 61 73 65 20 74 68 61 74 20 61 20 73 65  * case that a se
27a40 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63 63 75 72  cond error occur
27a50 73 20 6f 6e 20 61 20 73 65 70 61 72 61 74 65 20  s on a separate 
27a60 74 68 72 65 61 64 20 69 6e 20 62 65 74 77 65 65  thread in betwee
27a70 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65 20 6f 66  n.** the time of
27a80 20 74 68 65 20 66 69 72 73 74 20 65 72 72 6f 72   the first error
27a90 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 20 74 6f   and the call to
27aa0 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   these interface
27ab0 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 61 74 20  s..** When that 
27ac0 68 61 70 70 65 6e 73 2c 20 74 68 65 20 73 65 63  happens, the sec
27ad0 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c 6c 20 62  ond error will b
27ae0 65 20 72 65 70 6f 72 74 65 64 20 73 69 6e 63 65  e reported since
27af0 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74 65 72 66   these.** interf
27b00 61 63 65 73 20 61 6c 77 61 79 73 20 72 65 70 6f  aces always repo
27b10 72 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  rt the most rece
27b20 6e 74 20 72 65 73 75 6c 74 2e 20 20 54 6f 20 61  nt result.  To a
27b30 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c 20 65 61  void.** this, ea
27b40 63 68 20 74 68 72 65 61 64 20 63 61 6e 20 6f 62  ch thread can ob
27b50 74 61 69 6e 20 65 78 63 6c 75 73 69 76 65 20 75  tain exclusive u
27b60 73 65 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62  se of the [datab
27b70 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
27b80 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e 67  D.** by invoking
27b90 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
27ba0 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74 65 33 5f  enter]([sqlite3_
27bb0 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 62 65  db_mutex](D)) be
27bc0 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a  fore beginning.*
27bd0 2a 20 74 6f 20 75 73 65 20 44 20 61 6e 64 20 69  * to use D and i
27be0 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33  nvoking [sqlite3
27bf0 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d 28 5b 73  _mutex_leave]([s
27c00 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d  qlite3_db_mutex]
27c10 28 44 29 29 20 61 66 74 65 72 0a 2a 2a 20 61 6c  (D)) after.** al
27c20 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 69  l calls to the i
27c30 6e 74 65 72 66 61 63 65 73 20 6c 69 73 74 65 64  nterfaces listed
27c40 20 68 65 72 65 20 61 72 65 20 63 6f 6d 70 6c 65   here are comple
27c50 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e  ted..**.** If an
27c60 20 69 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73   interface fails
27c70 20 77 69 74 68 20 53 51 4c 49 54 45 5f 4d 49 53   with SQLITE_MIS
27c80 55 53 45 2c 20 74 68 61 74 20 6d 65 61 6e 73 20  USE, that means 
27c90 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  the interface.**
27ca0 20 77 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e 63   was invoked inc
27cb0 6f 72 72 65 63 74 6c 79 20 62 79 20 74 68 65 20  orrectly by the 
27cc0 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49 6e  application.  In
27cd0 20 74 68 61 74 20 63 61 73 65 2c 20 74 68 65 0a   that case, the.
27ce0 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e  ** error code an
27cf0 64 20 6d 65 73 73 61 67 65 20 6d 61 79 20 6f 72  d message may or
27d00 20 6d 61 79 20 6e 6f 74 20 62 65 20 73 65 74 2e   may not be set.
27d10 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
27d20 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  nt SQLITE_STDCAL
27d30 4c 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64  L sqlite3_errcod
27d40 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a  e(sqlite3 *db);.
27d50 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53  SQLITE_API int S
27d60 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
27d70 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65  lite3_extended_e
27d80 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a  rrcode(sqlite3 *
27d90 64 62 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  db);.SQLITE_API 
27da0 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51 4c 49  const char *SQLI
27db0 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
27dc0 65 33 5f 65 72 72 6d 73 67 28 73 71 6c 69 74 65  e3_errmsg(sqlite
27dd0 33 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  3*);.SQLITE_API 
27de0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51 4c 49  const void *SQLI
27df0 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
27e00 65 33 5f 65 72 72 6d 73 67 31 36 28 73 71 6c 69  e3_errmsg16(sqli
27e10 74 65 33 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  te3*);.SQLITE_AP
27e20 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51  I const char *SQ
27e30 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
27e40 69 74 65 33 5f 65 72 72 73 74 72 28 69 6e 74 29  ite3_errstr(int)
27e50 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
27e60 46 3a 20 50 72 65 70 61 72 65 64 20 53 74 61 74  F: Prepared Stat
27e70 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20  ement Object.** 
27e80 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 65 70 61  KEYWORDS: {prepa
27e90 72 65 64 20 73 74 61 74 65 6d 65 6e 74 7d 20 7b  red statement} {
27ea0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
27eb0 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e  nts}.**.** An in
27ec0 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f  stance of this o
27ed0 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73  bject represents
27ee0 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74   a single SQL st
27ef0 61 74 65 6d 65 6e 74 20 74 68 61 74 0a 2a 2a 20  atement that.** 
27f00 68 61 73 20 62 65 65 6e 20 63 6f 6d 70 69 6c 65  has been compile
27f10 64 20 69 6e 74 6f 20 62 69 6e 61 72 79 20 66 6f  d into binary fo
27f20 72 6d 20 61 6e 64 20 69 73 20 72 65 61 64 79 20  rm and is ready 
27f30 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 2e  to be evaluated.
27f40 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 6b 20 6f 66 20  .**.** Think of 
27f50 65 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65  each SQL stateme
27f60 6e 74 20 61 73 20 61 20 73 65 70 61 72 61 74 65  nt as a separate
27f70 20 63 6f 6d 70 75 74 65 72 20 70 72 6f 67 72 61   computer progra
27f80 6d 2e 20 20 54 68 65 0a 2a 2a 20 6f 72 69 67 69  m.  The.** origi
27f90 6e 61 6c 20 53 51 4c 20 74 65 78 74 20 69 73 20  nal SQL text is 
27fa0 73 6f 75 72 63 65 20 63 6f 64 65 2e 20 20 41 20  source code.  A 
27fb0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
27fc0 6e 74 20 6f 62 6a 65 63 74 20 0a 2a 2a 20 69 73  nt object .** is
27fd0 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 20 6f 62   the compiled ob
27fe0 6a 65 63 74 20 63 6f 64 65 2e 20 20 41 6c 6c 20  ject code.  All 
27ff0 53 51 4c 20 6d 75 73 74 20 62 65 20 63 6f 6e 76  SQL must be conv
28000 65 72 74 65 64 20 69 6e 74 6f 20 61 0a 2a 2a 20  erted into a.** 
28010 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
28020 6e 74 20 62 65 66 6f 72 65 20 69 74 20 63 61 6e  nt before it can
28030 20 62 65 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20 54   be run..**.** T
28040 68 65 20 6c 69 66 65 2d 63 79 63 6c 65 20 6f 66  he life-cycle of
28050 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74   a prepared stat
28060 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 75 73 75  ement object usu
28070 61 6c 6c 79 20 67 6f 65 73 20 6c 69 6b 65 20 74  ally goes like t
28080 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a  his:.**.** <ol>.
28090 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74  ** <li> Create t
280a0 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74  he prepared stat
280b0 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 75 73 69  ement object usi
280c0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ng [sqlite3_prep
280d0 61 72 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20 3c 6c  are_v2()]..** <l
280e0 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74  i> Bind values t
280f0 6f 20 5b 70 61 72 61 6d 65 74 65 72 73 5d 20 75  o [parameters] u
28100 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33  sing the sqlite3
28110 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20  _bind_*().**    
28120 20 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a    interfaces..**
28130 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 51   <li> Run the SQ
28140 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71  L by calling [sq
28150 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e  lite3_step()] on
28160 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e  e or more times.
28170 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 74  .** <li> Reset t
28180 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74  he prepared stat
28190 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c  ement using [sql
281a0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 68  ite3_reset()] th
281b0 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20  en go back.**   
281c0 20 20 20 74 6f 20 73 74 65 70 20 32 2e 20 20 44     to step 2.  D
281d0 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d  o this zero or m
281e0 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c  ore times..** <l
281f0 69 3e 20 44 65 73 74 72 6f 79 20 74 68 65 20 6f  i> Destroy the o
28200 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c  bject using [sql
28210 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
28220 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 74 79  ..** </ol>.*/.ty
28230 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
28240 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69 74 65  ite3_stmt sqlite
28250 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43  3_stmt;../*.** C
28260 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d  API3REF: Run-tim
28270 65 20 4c 69 6d 69 74 73 0a 2a 2a 20 4d 45 54 48  e Limits.** METH
28280 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
28290 2a 20 5e 28 54 68 69 73 20 69 6e 74 65 72 66 61  * ^(This interfa
282a0 63 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 69  ce allows the si
282b0 7a 65 20 6f 66 20 76 61 72 69 6f 75 73 20 63 6f  ze of various co
282c0 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 6c  nstructs to be l
282d0 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63  imited.** on a c
282e0 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e  onnection by con
282f0 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 20  nection basis.  
28300 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
28310 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64  ter is the.** [d
28320 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
28330 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 20  on] whose limit 
28340 69 73 20 74 6f 20 62 65 20 73 65 74 20 6f 72 20  is to be set or 
28350 71 75 65 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a  queried.  The.**
28360 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
28370 72 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20  r is one of the 
28380 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65  [limit categorie
28390 73 5d 20 74 68 61 74 20 64 65 66 69 6e 65 20 61  s] that define a
283a0 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e  .** class of con
283b0 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 73 69  structs to be si
283c0 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 65  ze limited.  The
283d0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
283e0 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c   is the.** new l
283f0 69 6d 69 74 20 66 6f 72 20 74 68 61 74 20 63 6f  imit for that co
28400 6e 73 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a  nstruct.)^.**.**
28410 20 5e 49 66 20 74 68 65 20 6e 65 77 20 6c 69 6d   ^If the new lim
28420 69 74 20 69 73 20 61 20 6e 65 67 61 74 69 76 65  it is a negative
28430 20 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d   number, the lim
28440 69 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e  it is unchanged.
28450 0a 2a 2a 20 5e 28 46 6f 72 20 65 61 63 68 20 6c  .** ^(For each l
28460 69 6d 69 74 20 63 61 74 65 67 6f 72 79 20 53 51  imit category SQ
28470 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41  LITE_LIMIT_<i>NA
28480 4d 45 3c 2f 69 3e 20 74 68 65 72 65 20 69 73 20  ME</i> there is 
28490 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20  a .** [limits | 
284a0 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64  hard upper bound
284b0 5d 0a 2a 2a 20 73 65 74 20 61 74 20 63 6f 6d 70  ].** set at comp
284c0 69 6c 65 2d 74 69 6d 65 20 62 79 20 61 20 43 20  ile-time by a C 
284d0 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63  preprocessor mac
284e0 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69  ro called.** [li
284f0 6d 69 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41  mits | SQLITE_MA
28500 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a  X_<i>NAME</i>]..
28510 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f  ** (The "_LIMIT_
28520 22 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 73  " in the name is
28530 20 63 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41   changed to "_MA
28540 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65  X_".))^.** ^Atte
28550 6d 70 74 73 20 74 6f 20 69 6e 63 72 65 61 73 65  mpts to increase
28560 20 61 20 6c 69 6d 69 74 20 61 62 6f 76 65 20 69   a limit above i
28570 74 73 20 68 61 72 64 20 75 70 70 65 72 20 62 6f  ts hard upper bo
28580 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e  und are.** silen
28590 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20 74 6f  tly truncated to
285a0 20 74 68 65 20 68 61 72 64 20 75 70 70 65 72 20   the hard upper 
285b0 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65  bound..**.** ^Re
285c0 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74  gardless of whet
285d0 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 6c  her or not the l
285e0 69 6d 69 74 20 77 61 73 20 63 68 61 6e 67 65 64  imit was changed
285f0 2c 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74  , the .** [sqlit
28600 65 33 5f 6c 69 6d 69 74 28 29 5d 20 69 6e 74 65  e3_limit()] inte
28610 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
28620 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66  e prior value of
28630 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e   the limit..** ^
28640 48 65 6e 63 65 2c 20 74 6f 20 66 69 6e 64 20 74  Hence, to find t
28650 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65  he current value
28660 20 6f 66 20 61 20 6c 69 6d 69 74 20 77 69 74 68   of a limit with
28670 6f 75 74 20 63 68 61 6e 67 69 6e 67 20 69 74 2c  out changing it,
28680 0a 2a 2a 20 73 69 6d 70 6c 79 20 69 6e 76 6f 6b  .** simply invok
28690 65 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  e this interface
286a0 20 77 69 74 68 20 74 68 65 20 74 68 69 72 64 20   with the third 
286b0 70 61 72 61 6d 65 74 65 72 20 73 65 74 20 74 6f  parameter set to
286c0 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74   -1..**.** Run-t
286d0 69 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 20 69  ime limits are i
286e0 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20  ntended for use 
286f0 69 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  in applications 
28700 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62  that manage.** b
28710 6f 74 68 20 74 68 65 69 72 20 6f 77 6e 20 69 6e  oth their own in
28720 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 20  ternal database 
28730 61 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 61 73  and also databas
28740 65 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e 74  es that are cont
28750 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74  rolled.** by unt
28760 72 75 73 74 65 64 20 65 78 74 65 72 6e 61 6c 20  rusted external 
28770 73 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 78 61  sources.  An exa
28780 6d 70 6c 65 20 61 70 70 6c 69 63 61 74 69 6f 6e  mple application
28790 20 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a 20 77   might be a.** w
287a0 65 62 20 62 72 6f 77 73 65 72 20 74 68 61 74 20  eb browser that 
287b0 68 61 73 20 69 74 73 20 6f 77 6e 20 64 61 74 61  has its own data
287c0 62 61 73 65 73 20 66 6f 72 20 73 74 6f 72 69 6e  bases for storin
287d0 67 20 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a  g history and.**
287e0 20 73 65 70 61 72 61 74 65 20 64 61 74 61 62 61   separate databa
287f0 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62  ses controlled b
28800 79 20 4a 61 76 61 53 63 72 69 70 74 20 61 70 70  y JavaScript app
28810 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f  lications downlo
28820 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20  aded.** off the 
28830 49 6e 74 65 72 6e 65 74 2e 20 20 54 68 65 20 69  Internet.  The i
28840 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65  nternal database
28850 73 20 63 61 6e 20 62 65 20 67 69 76 65 6e 20 74  s can be given t
28860 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66  he.** large, def
28870 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44 61  ault limits.  Da
28880 74 61 62 61 73 65 73 20 6d 61 6e 61 67 65 64 20  tabases managed 
28890 62 79 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72  by external sour
288a0 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69  ces can.** be gi
288b0 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72  ven much smaller
288c0 20 6c 69 6d 69 74 73 20 64 65 73 69 67 6e 65 64   limits designed
288d0 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 64 65   to prevent a de
288e0 6e 69 61 6c 20 6f 66 20 73 65 72 76 69 63 65 0a  nial of service.
288f0 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44 65 76 65  ** attack.  Deve
28900 6c 6f 70 65 72 73 20 6d 69 67 68 74 20 61 6c 73  lopers might als
28910 6f 20 77 61 6e 74 20 74 6f 20 75 73 65 20 74 68  o want to use th
28920 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  e [sqlite3_set_a
28930 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20  uthorizer()].** 
28940 69 6e 74 65 72 66 61 63 65 20 74 6f 20 66 75 72  interface to fur
28950 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74  ther control unt
28960 72 75 73 74 65 64 20 53 51 4c 2e 20 20 54 68 65  rusted SQL.  The
28970 20 73 69 7a 65 20 6f 66 20 74 68 65 20 64 61 74   size of the dat
28980 61 62 61 73 65 0a 2a 2a 20 63 72 65 61 74 65 64  abase.** created
28990 20 62 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64   by an untrusted
289a0 20 73 63 72 69 70 74 20 63 61 6e 20 62 65 20 63   script can be c
289b0 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e 67 20 74  ontained using t
289c0 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f  he.** [max_page_
289d0 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e  count] [PRAGMA].
289e0 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74  .**.** New run-t
289f0 69 6d 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f  ime limit catego
28a00 72 69 65 73 20 6d 61 79 20 62 65 20 61 64 64 65  ries may be adde
28a10 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
28a20 61 73 65 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  ases..*/.SQLITE_
28a30 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  API int SQLITE_S
28a40 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6c  TDCALL sqlite3_l
28a50 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c 20 69  imit(sqlite3*, i
28a60 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 77 56 61  nt id, int newVa
28a70 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  l);../*.** CAPI3
28a80 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69  REF: Run-Time Li
28a90 6d 69 74 20 43 61 74 65 67 6f 72 69 65 73 0a 2a  mit Categories.*
28aa0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c 69 6d  * KEYWORDS: {lim
28ab0 69 74 20 63 61 74 65 67 6f 72 79 7d 20 7b 2a 6c  it category} {*l
28ac0 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 7d  imit categories}
28ad0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
28ae0 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 76 61  stants define va
28af0 72 69 6f 75 73 20 70 65 72 66 6f 72 6d 61 6e 63  rious performanc
28b00 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 68 61 74  e limits.** that
28b10 20 63 61 6e 20 62 65 20 6c 6f 77 65 72 65 64 20   can be lowered 
28b20 61 74 20 72 75 6e 2d 74 69 6d 65 20 75 73 69 6e  at run-time usin
28b30 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  g [sqlite3_limit
28b40 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 79 6e 6f  ()]..** The syno
28b50 70 73 69 73 20 6f 66 20 74 68 65 20 6d 65 61 6e  psis of the mean
28b60 69 6e 67 73 20 6f 66 20 74 68 65 20 76 61 72 69  ings of the vari
28b70 6f 75 73 20 6c 69 6d 69 74 73 20 69 73 20 73 68  ous limits is sh
28b80 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64  own below..** Ad
28b90 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
28ba0 74 69 6f 6e 20 69 73 20 61 76 61 69 6c 61 62 6c  tion is availabl
28bb0 65 20 61 74 20 5b 6c 69 6d 69 74 73 20 7c 20 4c  e at [limits | L
28bc0 69 6d 69 74 73 20 69 6e 20 53 51 4c 69 74 65 5d  imits in SQLite]
28bd0 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20  ..**.** <dl>.** 
28be0 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  [[SQLITE_LIMIT_L
28bf0 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51  ENGTH]] ^(<dt>SQ
28c00 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54  LITE_LIMIT_LENGT
28c10 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
28c20 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f  e maximum size o
28c30 66 20 61 6e 79 20 73 74 72 69 6e 67 20 6f 72 20  f any string or 
28c40 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20 72 6f  BLOB or table ro
28c50 77 2c 20 69 6e 20 62 79 74 65 73 2e 3c 64 64 3e  w, in bytes.<dd>
28c60 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
28c70 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47  E_LIMIT_SQL_LENG
28c80 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  TH]] ^(<dt>SQLIT
28c90 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47  E_LIMIT_SQL_LENG
28ca0 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
28cb0 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  he maximum lengt
28cc0 68 20 6f 66 20 61 6e 20 53 51 4c 20 73 74 61 74  h of an SQL stat
28cd0 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74 65 73 2e  ement, in bytes.
28ce0 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
28cf0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c  SQLITE_LIMIT_COL
28d00 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  UMN]] ^(<dt>SQLI
28d10 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c  TE_LIMIT_COLUMN<
28d20 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
28d30 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
28d40 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74  f columns in a t
28d50 61 62 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e 20  able definition 
28d60 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73  or in the.** res
28d70 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45  ult set of a [SE
28d80 4c 45 43 54 5d 20 6f 72 20 74 68 65 20 6d 61 78  LECT] or the max
28d90 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63  imum number of c
28da0 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64  olumns in an ind
28db0 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f  ex.** or in an O
28dc0 52 44 45 52 20 42 59 20 6f 72 20 47 52 4f 55 50  RDER BY or GROUP
28dd0 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e   BY clause.</dd>
28de0 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
28df0 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50  E_LIMIT_EXPR_DEP
28e00 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  TH]] ^(<dt>SQLIT
28e10 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50  E_LIMIT_EXPR_DEP
28e20 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
28e30 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68  he maximum depth
28e40 20 6f 66 20 74 68 65 20 70 61 72 73 65 20 74 72   of the parse tr
28e50 65 65 20 6f 6e 20 61 6e 79 20 65 78 70 72 65 73  ee on any expres
28e60 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  sion.</dd>)^.**.
28e70 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
28e80 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43  T_COMPOUND_SELEC
28e90 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  T]] ^(<dt>SQLITE
28ea0 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f  _LIMIT_COMPOUND_
28eb0 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c  SELECT</dt>.** <
28ec0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
28ed0 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69  umber of terms i
28ee0 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c  n a compound SEL
28ef0 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f  ECT statement.</
28f00 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
28f10 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f  LITE_LIMIT_VDBE_
28f20 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  OP]] ^(<dt>SQLIT
28f30 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c  E_LIMIT_VDBE_OP<
28f40 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
28f50 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
28f60 66 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 20 69  f instructions i
28f70 6e 20 61 20 76 69 72 74 75 61 6c 20 6d 61 63 68  n a virtual mach
28f80 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75  ine program.** u
28f90 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  sed to implement
28fa0 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
28fb0 74 2e 20 20 54 68 69 73 20 6c 69 6d 69 74 20 69  t.  This limit i
28fc0 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 0a  s not currently.
28fd0 2a 2a 20 65 6e 66 6f 72 63 65 64 2c 20 74 68 6f  ** enforced, tho
28fe0 75 67 68 20 74 68 61 74 20 6d 69 67 68 74 20 62  ugh that might b
28ff0 65 20 61 64 64 65 64 20 69 6e 20 73 6f 6d 65 20  e added in some 
29000 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f  future release o
29010 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 3c 2f 64 64  f.** SQLite.</dd
29020 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
29030 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f  TE_LIMIT_FUNCTIO
29040 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64 74 3e 53 51  N_ARG]] ^(<dt>SQ
29050 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54  LITE_LIMIT_FUNCT
29060 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20  ION_ARG</dt>.** 
29070 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
29080 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65  number of argume
29090 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63 74 69 6f  nts on a functio
290a0 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  n.</dd>)^.**.** 
290b0 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41  [[SQLITE_LIMIT_A
290c0 54 54 41 43 48 45 44 5d 5d 20 5e 28 3c 64 74 3e  TTACHED]] ^(<dt>
290d0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54  SQLITE_LIMIT_ATT
290e0 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ACHED</dt>.** <d
290f0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
29100 6d 62 65 72 20 6f 66 20 5b 41 54 54 41 43 48 20  mber of [ATTACH 
29110 7c 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62  | attached datab
29120 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a  ases].)^</dd>.**
29130 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
29140 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f  IT_LIKE_PATTERN_
29150 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e 28 3c 64  LENGTH]].** ^(<d
29160 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  t>SQLITE_LIMIT_L
29170 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47  IKE_PATTERN_LENG
29180 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
29190 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  he maximum lengt
291a0 68 20 6f 66 20 74 68 65 20 70 61 74 74 65 72 6e  h of the pattern
291b0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
291c0 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47   [LIKE] or.** [G
291d0 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 73 2e 3c  LOB] operators.<
291e0 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
291f0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49  QLITE_LIMIT_VARI
29200 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d 0a 2a 2a  ABLE_NUMBER]].**
29210 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
29220 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d  MIT_VARIABLE_NUM
29230 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  BER</dt>.** <dd>
29240 54 68 65 20 6d 61 78 69 6d 75 6d 20 69 6e 64 65  The maximum inde
29250 78 20 6e 75 6d 62 65 72 20 6f 66 20 61 6e 79 20  x number of any 
29260 5b 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 61  [parameter] in a
29270 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  n SQL statement.
29280 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
29290 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f  E_LIMIT_TRIGGER_
292a0 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51  DEPTH]] ^(<dt>SQ
292b0 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47  LITE_LIMIT_TRIGG
292c0 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a  ER_DEPTH</dt>.**
292d0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
292e0 20 64 65 70 74 68 20 6f 66 20 72 65 63 75 72 73   depth of recurs
292f0 69 6f 6e 20 66 6f 72 20 74 72 69 67 67 65 72 73  ion for triggers
29300 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
29310 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f  [SQLITE_LIMIT_WO
29320 52 4b 45 52 5f 54 48 52 45 41 44 53 5d 5d 20 5e  RKER_THREADS]] ^
29330 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
29340 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53  T_WORKER_THREADS
29350 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
29360 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
29370 6f 66 20 61 75 78 69 6c 69 61 72 79 20 77 6f 72  of auxiliary wor
29380 6b 65 72 20 74 68 72 65 61 64 73 20 74 68 61 74  ker threads that
29390 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 70 72   a single.** [pr
293a0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
293b0 5d 20 6d 61 79 20 73 74 61 72 74 2e 3c 2f 64 64  ] may start.</dd
293c0 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a  >)^.** </dl>.*/.
293d0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
293e0 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20 20 20 20  IMIT_LENGTH     
293f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
29400 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
29410 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48  LIMIT_SQL_LENGTH
29420 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
29430 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
29440 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20 20  _LIMIT_COLUMN   
29450 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
29460 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
29470 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50  E_LIMIT_EXPR_DEP
29480 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TH              
29490 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    3.#define SQLI
294a0 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e  TE_LIMIT_COMPOUN
294b0 44 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20  D_SELECT        
294c0 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c     4.#define SQL
294d0 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f  ITE_LIMIT_VDBE_O
294e0 50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  P               
294f0 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51      5.#define SQ
29500 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54  LITE_LIMIT_FUNCT
29510 49 4f 4e 5f 41 52 47 20 20 20 20 20 20 20 20 20  ION_ARG         
29520 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53       6.#define S
29530 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41  QLITE_LIMIT_ATTA
29540 43 48 45 44 20 20 20 20 20 20 20 20 20 20 20 20  CHED            
29550 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20        7.#define 
29560 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b  SQLITE_LIMIT_LIK
29570 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48  E_PATTERN_LENGTH
29580 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65         8.#define
29590 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41   SQLITE_LIMIT_VA
295a0 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20 20 20  RIABLE_NUMBER   
295b0 20 20 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e          9.#defin
295c0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54  e SQLITE_LIMIT_T
295d0 52 49 47 47 45 52 5f 44 45 50 54 48 20 20 20 20  RIGGER_DEPTH    
295e0 20 20 20 20 20 20 20 20 31 30 0a 23 64 65 66 69          10.#defi
295f0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
29600 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53 20 20  WORKER_THREADS  
29610 20 20 20 20 20 20 20 20 20 31 31 0a 0a 2f 2a 0a           11../*.
29620 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d  ** CAPI3REF: Com
29630 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53 74  piling An SQL St
29640 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45 59 57 4f  atement.** KEYWO
29650 52 44 53 3a 20 7b 53 51 4c 20 73 74 61 74 65 6d  RDS: {SQL statem
29660 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a  ent compiler}.**
29670 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
29680 0a 2a 2a 20 43 4f 4e 53 54 52 55 43 54 4f 52 3a  .** CONSTRUCTOR:
29690 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
296a0 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 65 20 61  .** To execute a
296b0 6e 20 53 51 4c 20 71 75 65 72 79 2c 20 69 74 20  n SQL query, it 
296c0 6d 75 73 74 20 66 69 72 73 74 20 62 65 20 63 6f  must first be co
296d0 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61 20 62 79  mpiled into a by
296e0 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f 67 72  te-code.** progr
296f0 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20  am using one of 
29700 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a  these routines..
29710 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
29720 61 72 67 75 6d 65 6e 74 2c 20 22 64 62 22 2c 20  argument, "db", 
29730 69 73 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  is a [database c
29740 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74 61 69  onnection] obtai
29750 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 70 72  ned from a.** pr
29760 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20 63  ior successful c
29770 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
29780 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
29790 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6f 72 0a  3_open_v2()] or.
297a0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ** [sqlite3_open
297b0 31 36 28 29 5d 2e 20 20 54 68 65 20 64 61 74 61  16()].  The data
297c0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
297d0 6d 75 73 74 20 6e 6f 74 20 68 61 76 65 20 62 65  must not have be
297e0 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a  en closed..**.**
297f0 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
29800 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20 69 73  ment, "zSql", is
29810 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74   the statement t
29820 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20 65  o be compiled, e
29830 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69 74  ncoded.** as eit
29840 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46  her UTF-8 or UTF
29850 2d 31 36 2e 20 20 54 68 65 20 73 71 6c 69 74 65  -16.  The sqlite
29860 33 5f 70 72 65 70 61 72 65 28 29 20 61 6e 64 20  3_prepare() and 
29870 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
29880 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  v2().** interfac
29890 65 73 20 75 73 65 20 55 54 46 2d 38 2c 20 61 6e  es use UTF-8, an
298a0 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  d sqlite3_prepar
298b0 65 31 36 28 29 20 61 6e 64 20 73 71 6c 69 74 65  e16() and sqlite
298c0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
298d0 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31 36 2e 0a  .** use UTF-16..
298e0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 42  **.** ^If the nB
298f0 79 74 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  yte argument is 
29900 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 7a  negative, then z
29910 53 71 6c 20 69 73 20 72 65 61 64 20 75 70 20 74  Sql is read up t
29920 6f 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 7a  o the.** first z
29930 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20  ero terminator. 
29940 5e 49 66 20 6e 42 79 74 65 20 69 73 20 70 6f 73  ^If nByte is pos
29950 69 74 69 76 65 2c 20 74 68 65 6e 20 69 74 20 69  itive, then it i
29960 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20  s the.** number 
29970 6f 66 20 62 79 74 65 73 20 72 65 61 64 20 66 72  of bytes read fr
29980 6f 6d 20 7a 53 71 6c 2e 20 20 5e 49 66 20 6e 42  om zSql.  ^If nB
29990 79 74 65 20 69 73 20 7a 65 72 6f 2c 20 74 68 65  yte is zero, the
299a0 6e 20 6e 6f 20 70 72 65 70 61 72 65 64 0a 2a 2a  n no prepared.**
299b0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 67 65   statement is ge
299c0 6e 65 72 61 74 65 64 2e 0a 2a 2a 20 49 66 20 74  nerated..** If t
299d0 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 20  he caller knows 
299e0 74 68 61 74 20 74 68 65 20 73 75 70 70 6c 69 65  that the supplie
299f0 64 20 73 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d  d string is nul-
29a00 74 65 72 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e  terminated, then
29a10 0a 2a 2a 20 74 68 65 72 65 20 69 73 20 61 20 73  .** there is a s
29a20 6d 61 6c 6c 20 70 65 72 66 6f 72 6d 61 6e 63 65  mall performance
29a30 20 61 64 76 61 6e 74 61 67 65 20 74 6f 20 70 61   advantage to pa
29a40 73 73 69 6e 67 20 61 6e 20 6e 42 79 74 65 20 70  ssing an nByte p
29a50 61 72 61 6d 65 74 65 72 20 74 68 61 74 0a 2a 2a  arameter that.**
29a60 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
29a70 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 69  f bytes in the i
29a80 6e 70 75 74 20 73 74 72 69 6e 67 20 3c 69 3e 69  nput string <i>i
29a90 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20  ncluding</i>.** 
29aa0 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74  the nul-terminat
29ab0 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a  or..**.** ^If pz
29ac0 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  Tail is not NULL
29ad0 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73   then *pzTail is
29ae0 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74   made to point t
29af0 6f 20 74 68 65 20 66 69 72 73 74 20 62 79 74 65  o the first byte
29b00 0a 2a 2a 20 70 61 73 74 20 74 68 65 20 65 6e 64  .** past the end
29b10 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 53 51   of the first SQ
29b20 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a  L statement in z
29b30 53 71 6c 2e 20 20 54 68 65 73 65 20 72 6f 75 74  Sql.  These rout
29b40 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d  ines only.** com
29b50 70 69 6c 65 20 74 68 65 20 66 69 72 73 74 20 73  pile the first s
29b60 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c  tatement in zSql
29b70 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20  , so *pzTail is 
29b80 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f  left pointing to
29b90 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61 69 6e 73  .** what remains
29ba0 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a   uncompiled..**.
29bb0 2a 2a 20 5e 2a 70 70 53 74 6d 74 20 69 73 20 6c  ** ^*ppStmt is l
29bc0 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20  eft pointing to 
29bd0 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70  a compiled [prep
29be0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
29bf0 74 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65  that can be.** e
29c00 78 65 63 75 74 65 64 20 75 73 69 6e 67 20 5b 73  xecuted using [s
29c10 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 20  qlite3_step()]. 
29c20 20 5e 49 66 20 74 68 65 72 65 20 69 73 20 61 6e   ^If there is an
29c30 20 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20   error, *ppStmt 
29c40 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c  is set.** to NUL
29c50 4c 2e 20 20 5e 49 66 20 74 68 65 20 69 6e 70 75  L.  ^If the inpu
29c60 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e 73 20  t text contains 
29c70 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 65 20 69  no SQL (if the i
29c80 6e 70 75 74 20 69 73 20 61 6e 20 65 6d 70 74 79  nput is an empty
29c90 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20 61 20  .** string or a 
29ca0 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70  comment) then *p
29cb0 70 53 74 6d 74 20 69 73 20 73 65 74 20 74 6f 20  pStmt is set to 
29cc0 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63 61 6c  NULL..** The cal
29cd0 6c 69 6e 67 20 70 72 6f 63 65 64 75 72 65 20 69  ling procedure i
29ce0 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f  s responsible fo
29cf0 72 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63  r deleting the c
29d00 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73  ompiled.** SQL s
29d10 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b  tatement using [
29d20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
29d30 28 29 5d 20 61 66 74 65 72 20 69 74 20 68 61 73  ()] after it has
29d40 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69   finished with i
29d50 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 6d 61 79  t..** ppStmt may
29d60 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a   not be NULL..**
29d70 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63 65 73 73 2c  .** ^On success,
29d80 20 74 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65   the sqlite3_pre
29d90 70 61 72 65 28 29 20 66 61 6d 69 6c 79 20 6f 66  pare() family of
29da0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
29db0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a   [SQLITE_OK];.**
29dc0 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65   otherwise an [e
29dd0 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65  rror code] is re
29de0 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  turned..**.** Th
29df0 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  e sqlite3_prepar
29e00 65 5f 76 32 28 29 20 61 6e 64 20 73 71 6c 69 74  e_v2() and sqlit
29e10 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
29e20 29 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  ) interfaces are
29e30 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20  .** recommended 
29e40 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67  for all new prog
29e50 72 61 6d 73 2e 20 54 68 65 20 74 77 6f 20 6f 6c  rams. The two ol
29e60 64 65 72 20 69 6e 74 65 72 66 61 63 65 73 20 61  der interfaces a
29e70 72 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a 20 66  re retained.** f
29e80 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d  or backwards com
29e90 70 61 74 69 62 69 6c 69 74 79 2c 20 62 75 74 20  patibility, but 
29ea0 74 68 65 69 72 20 75 73 65 20 69 73 20 64 69 73  their use is dis
29eb0 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e  couraged..** ^In
29ec0 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
29ed0 61 63 65 73 2c 20 74 68 65 20 70 72 65 70 61 72  aces, the prepar
29ee0 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  ed statement.** 
29ef0 74 68 61 74 20 69 73 20 72 65 74 75 72 6e 65 64  that is returned
29f00 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73   (the [sqlite3_s
29f10 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e  tmt] object) con
29f20 74 61 69 6e 73 20 61 20 63 6f 70 79 20 6f 66 20  tains a copy of 
29f30 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20  the.** original 
29f40 53 51 4c 20 74 65 78 74 2e 20 54 68 69 73 20 63  SQL text. This c
29f50 61 75 73 65 73 20 74 68 65 20 5b 73 71 6c 69 74  auses the [sqlit
29f60 65 33 5f 73 74 65 70 28 29 5d 20 69 6e 74 65 72  e3_step()] inter
29f70 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76  face to.** behav
29f80 65 20 64 69 66 66 65 72 65 6e 74 6c 79 20 69 6e  e differently in
29f90 20 74 68 72 65 65 20 77 61 79 73 3a 0a 2a 2a 0a   three ways:.**.
29fa0 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a  ** <ol>.** <li>.
29fb0 2a 2a 20 5e 49 66 20 74 68 65 20 64 61 74 61 62  ** ^If the datab
29fc0 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67  ase schema chang
29fd0 65 73 2c 20 69 6e 73 74 65 61 64 20 6f 66 20 72  es, instead of r
29fe0 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45  eturning [SQLITE
29ff0 5f 53 43 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a  _SCHEMA] as it.*
2a000 2a 20 61 6c 77 61 79 73 20 75 73 65 64 20 74 6f  * always used to
2a010 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74   do, [sqlite3_st
2a020 65 70 28 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d  ep()] will autom
2a030 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69  atically recompi
2a040 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74  le the SQL.** st
2a050 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 72 79 20  atement and try 
2a060 74 6f 20 72 75 6e 20 69 74 20 61 67 61 69 6e 2e  to run it again.
2a070 20 41 73 20 6d 61 6e 79 20 61 73 20 5b 53 51 4c   As many as [SQL
2a080 49 54 45 5f 4d 41 58 5f 53 43 48 45 4d 41 5f 52  ITE_MAX_SCHEMA_R
2a090 45 54 52 59 5d 0a 2a 2a 20 72 65 74 72 69 65 73  ETRY].** retries
2a0a0 20 77 69 6c 6c 20 6f 63 63 75 72 20 62 65 66 6f   will occur befo
2a0b0 72 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  re sqlite3_step(
2a0c0 29 20 67 69 76 65 73 20 75 70 20 61 6e 64 20 72  ) gives up and r
2a0d0 65 74 75 72 6e 73 20 61 6e 20 65 72 72 6f 72 2e  eturns an error.
2a0e0 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20  .** </li>.**.** 
2a0f0 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61 6e  <li>.** ^When an
2a100 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c 20 5b   error occurs, [
2a110 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2a120 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20  will return one 
2a130 6f 66 20 74 68 65 20 64 65 74 61 69 6c 65 64 0a  of the detailed.
2a140 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d  ** [error codes]
2a150 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72   or [extended er
2a160 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20 5e 54 68  ror codes].  ^Th
2a170 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f  e legacy behavio
2a180 72 20 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b 73  r was that.** [s
2a190 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77  qlite3_step()] w
2a1a0 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e  ould only return
2a1b0 20 61 20 67 65 6e 65 72 69 63 20 5b 53 51 4c 49   a generic [SQLI
2a1c0 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c 74  TE_ERROR] result
2a1d0 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 74 68 65   code.** and the
2a1e0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 77 6f 75   application wou
2a1f0 6c 64 20 68 61 76 65 20 74 6f 20 6d 61 6b 65 20  ld have to make 
2a200 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f  a second call to
2a210 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2a220 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 74  )].** in order t
2a230 6f 20 66 69 6e 64 20 74 68 65 20 75 6e 64 65 72  o find the under
2a240 6c 79 69 6e 67 20 63 61 75 73 65 20 6f 66 20 74  lying cause of t
2a250 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69 74 68  he problem. With
2a260 20 74 68 65 20 22 76 32 22 20 70 72 65 70 61 72   the "v2" prepar
2a270 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2c  e.** interfaces,
2a280 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20   the underlying 
2a290 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 65 20 65  reason for the e
2a2a0 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64  rror is returned
2a2b0 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a   immediately..**
2a2c0 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69   </li>.**.** <li
2a2d0 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 70 65  >.** ^If the spe
2a2e0 63 69 66 69 63 20 76 61 6c 75 65 20 62 6f 75 6e  cific value boun
2a2f0 64 20 74 6f 20 5b 70 61 72 61 6d 65 74 65 72 20  d to [parameter 
2a300 7c 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72  | host parameter
2a310 5d 20 69 6e 20 74 68 65 20 0a 2a 2a 20 57 48 45  ] in the .** WHE
2a320 52 45 20 63 6c 61 75 73 65 20 6d 69 67 68 74 20  RE clause might 
2a330 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 63 68  influence the ch
2a340 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c  oice of query pl
2a350 61 6e 20 66 6f 72 20 61 20 73 74 61 74 65 6d 65  an for a stateme
2a360 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  nt,.** then the 
2a370 73 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20 62  statement will b
2a380 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  e automatically 
2a390 72 65 63 6f 6d 70 69 6c 65 64 2c 20 61 73 20 69  recompiled, as i
2a3a0 66 20 74 68 65 72 65 20 68 61 64 20 62 65 65 6e  f there had been
2a3b0 20 0a 2a 2a 20 61 20 73 63 68 65 6d 61 20 63 68   .** a schema ch
2a3c0 61 6e 67 65 2c 20 6f 6e 20 74 68 65 20 66 69 72  ange, on the fir
2a3d0 73 74 20 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  st  [sqlite3_ste
2a3e0 70 28 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77  p()] call follow
2a3f0 69 6e 67 20 61 6e 79 20 63 68 61 6e 67 65 0a 2a  ing any change.*
2a400 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  * to the [sqlite
2a410 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 62 69  3_bind_text | bi
2a420 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68 61 74 20  ndings] of that 
2a430 5b 70 61 72 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a  [parameter]. .**
2a440 20 5e 54 68 65 20 73 70 65 63 69 66 69 63 20 76   ^The specific v
2a450 61 6c 75 65 20 6f 66 20 57 48 45 52 45 2d 63 6c  alue of WHERE-cl
2a460 61 75 73 65 20 5b 70 61 72 61 6d 65 74 65 72 5d  ause [parameter]
2a470 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65   might influence
2a480 20 74 68 65 20 0a 2a 2a 20 63 68 6f 69 63 65 20   the .** choice 
2a490 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20 69 66  of query plan if
2a4a0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69   the parameter i
2a4b0 73 20 74 68 65 20 6c 65 66 74 2d 68 61 6e 64 20  s the left-hand 
2a4c0 73 69 64 65 20 6f 66 20 61 20 5b 4c 49 4b 45 5d  side of a [LIKE]
2a4d0 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20 6f 70  .** or [GLOB] op
2a4e0 65 72 61 74 6f 72 20 6f 72 20 69 66 20 74 68 65  erator or if the
2a4f0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 63 6f   parameter is co
2a500 6d 70 61 72 65 64 20 74 6f 20 61 6e 20 69 6e 64  mpared to an ind
2a510 65 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61  exed column.** a
2a520 6e 64 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 45  nd the [SQLITE_E
2a530 4e 41 42 4c 45 5f 53 54 41 54 33 5d 20 63 6f 6d  NABLE_STAT3] com
2a540 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
2a550 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20   is enabled..** 
2a560 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a  </li>.** </ol>.*
2a570 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
2a580 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
2a590 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
2a5a0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
2a5b0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
2a5c0 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
2a5d0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
2a5e0 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
2a5f0 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
2a600 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  -8 encoded */.  
2a610 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
2a620 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
2a630 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
2a640 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
2a650 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
2a660 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
2a670 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
2a680 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
2a690 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  r **pzTail     /
2a6a0 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
2a6b0 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
2a6c0 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53   of zSql */.);.S
2a6d0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51  QLITE_API int SQ
2a6e0 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
2a6f0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2a700 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
2a710 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
2a720 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
2a730 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
2a740 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
2a750 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
2a760 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  -8 encoded */.  
2a770 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
2a780 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
2a790 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
2a7a0 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
2a7b0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
2a7c0 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
2a7d0 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
2a7e0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
2a7f0 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  r **pzTail     /
2a800 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
2a810 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
2a820 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53   of zSql */.);.S
2a830 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51  QLITE_API int SQ
2a840 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
2a850 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 0a  ite3_prepare16(.
2a860 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
2a870 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
2a880 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
2a890 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53    const void *zS
2a8a0 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
2a8b0 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
2a8c0 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  16 encoded */.  
2a8d0 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
2a8e0 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
2a8f0 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
2a900 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
2a910 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
2a920 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
2a930 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
2a940 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
2a950 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  d **pzTail     /
2a960 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
2a970 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
2a980 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53   of zSql */.);.S
2a990 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51  QLITE_API int SQ
2a9a0 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
2a9b0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
2a9c0 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  2(.  sqlite3 *db
2a9d0 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
2a9e0 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
2a9f0 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
2aa00 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
2aa10 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
2aa20 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f  TF-16 encoded */
2aa30 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
2aa40 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
2aa50 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
2aa60 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
2aa70 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
2aa80 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
2aa90 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
2aaa0 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
2aab0 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20  void **pzTail   
2aac0 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
2aad0 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
2aae0 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
2aaf0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2ab00 46 3a 20 52 65 74 72 69 65 76 69 6e 67 20 53 74  F: Retrieving St
2ab10 61 74 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a 20 4d  atement SQL.** M
2ab20 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
2ab30 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  tmt.**.** ^This 
2ab40 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65  interface can be
2ab50 20 75 73 65 64 20 74 6f 20 72 65 74 72 69 65 76   used to retriev
2ab60 65 20 61 20 73 61 76 65 64 20 63 6f 70 79 20 6f  e a saved copy o
2ab70 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a 2a  f the original.*
2ab80 2a 20 53 51 4c 20 74 65 78 74 20 75 73 65 64 20  * SQL text used 
2ab90 74 6f 20 63 72 65 61 74 65 20 61 20 5b 70 72 65  to create a [pre
2aba0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2abb0 20 69 66 20 74 68 61 74 20 73 74 61 74 65 6d 65   if that stateme
2abc0 6e 74 20 77 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c  nt was.** compil
2abd0 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 20  ed using either 
2abe0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2abf0 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  _v2()] or [sqlit
2ac00 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
2ac10 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  )]..*/.SQLITE_AP
2ac20 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51  I const char *SQ
2ac30 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
2ac40 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 74 65 33  ite3_sql(sqlite3
2ac50 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
2ac60 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2ac70 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20  Determine If An 
2ac80 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 57 72  SQL Statement Wr
2ac90 69 74 65 73 20 54 68 65 20 44 61 74 61 62 61 73  ites The Databas
2aca0 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  e.** METHOD: sql
2acb0 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
2acc0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d  ^The sqlite3_stm
2acd0 74 5f 72 65 61 64 6f 6e 6c 79 28 58 29 20 69 6e  t_readonly(X) in
2ace0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
2acf0 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20  true (non-zero) 
2ad00 69 66 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 69  if.** and only i
2ad10 66 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  f the [prepared 
2ad20 73 74 61 74 65 6d 65 6e 74 5d 20 58 20 6d 61 6b  statement] X mak
2ad30 65 73 20 6e 6f 20 64 69 72 65 63 74 20 63 68 61  es no direct cha
2ad40 6e 67 65 73 20 74 6f 0a 2a 2a 20 74 68 65 20 63  nges to.** the c
2ad50 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 64 61  ontent of the da
2ad60 74 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a  tabase file..**.
2ad70 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 61 70  ** Note that [ap
2ad80 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2ad90 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d  d SQL functions]
2ada0 20 6f 72 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20   or.** [virtual 
2adb0 74 61 62 6c 65 73 5d 20 6d 69 67 68 74 20 63 68  tables] might ch
2adc0 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 73  ange the databas
2add0 65 20 69 6e 64 69 72 65 63 74 6c 79 20 61 73 20  e indirectly as 
2ade0 61 20 73 69 64 65 20 65 66 66 65 63 74 2e 20 20  a side effect.  
2adf0 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c  .** ^(For exampl
2ae00 65 2c 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61  e, if an applica
2ae10 74 69 6f 6e 20 64 65 66 69 6e 65 73 20 61 20 66  tion defines a f
2ae20 75 6e 63 74 69 6f 6e 20 22 65 76 61 6c 28 29 22  unction "eval()"
2ae30 20 74 68 61 74 20 0a 2a 2a 20 63 61 6c 6c 73 20   that .** calls 
2ae40 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
2ae50 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 6c 6c 6f  , then the follo
2ae60 77 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65  wing SQL stateme
2ae70 6e 74 20 77 6f 75 6c 64 0a 2a 2a 20 63 68 61 6e  nt would.** chan
2ae80 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ge the database 
2ae90 66 69 6c 65 20 74 68 72 6f 75 67 68 20 73 69 64  file through sid
2aea0 65 2d 65 66 66 65 63 74 73 3a 0a 2a 2a 0a 2a 2a  e-effects:.**.**
2aeb0 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
2aec0 65 3e 0a 2a 2a 20 20 20 20 53 45 4c 45 43 54 20  e>.**    SELECT 
2aed0 65 76 61 6c 28 27 44 45 4c 45 54 45 20 46 52 4f  eval('DELETE FRO
2aee0 4d 20 74 31 27 29 20 46 52 4f 4d 20 74 32 3b 0a  M t1') FROM t2;.
2aef0 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
2af00 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 75 74  quote>.**.** But
2af10 20 62 65 63 61 75 73 65 20 74 68 65 20 5b 53 45   because the [SE
2af20 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20  LECT] statement 
2af30 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20  does not change 
2af40 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
2af50 65 0a 2a 2a 20 64 69 72 65 63 74 6c 79 2c 20 73  e.** directly, s
2af60 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64  qlite3_stmt_read
2af70 6f 6e 6c 79 28 29 20 77 6f 75 6c 64 20 73 74 69  only() would sti
2af80 6c 6c 20 72 65 74 75 72 6e 20 74 72 75 65 2e 29  ll return true.)
2af90 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72 61 6e 73 61 63  ^.**.** ^Transac
2afa0 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 20 73 74 61  tion control sta
2afb0 74 65 6d 65 6e 74 73 20 73 75 63 68 20 61 73 20  tements such as 
2afc0 5b 42 45 47 49 4e 5d 2c 20 5b 43 4f 4d 4d 49 54  [BEGIN], [COMMIT
2afd0 5d 2c 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a  ], [ROLLBACK],.*
2afe0 2a 20 5b 53 41 56 45 50 4f 49 4e 54 5d 2c 20 61  * [SAVEPOINT], a
2aff0 6e 64 20 5b 52 45 4c 45 41 53 45 5d 20 63 61 75  nd [RELEASE] cau
2b000 73 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  se sqlite3_stmt_
2b010 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65  readonly() to re
2b020 74 75 72 6e 20 74 72 75 65 2c 0a 2a 2a 20 73 69  turn true,.** si
2b030 6e 63 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e  nce the statemen
2b040 74 73 20 74 68 65 6d 73 65 6c 76 65 73 20 64 6f  ts themselves do
2b050 20 6e 6f 74 20 61 63 74 75 61 6c 6c 79 20 6d 6f   not actually mo
2b060 64 69 66 79 20 74 68 65 20 64 61 74 61 62 61 73  dify the databas
2b070 65 20 62 75 74 0a 2a 2a 20 72 61 74 68 65 72 20  e but.** rather 
2b080 74 68 65 79 20 63 6f 6e 74 72 6f 6c 20 74 68 65  they control the
2b090 20 74 69 6d 69 6e 67 20 6f 66 20 77 68 65 6e 20   timing of when 
2b0a0 6f 74 68 65 72 20 73 74 61 74 65 6d 65 6e 74 73  other statements
2b0b0 20 6d 6f 64 69 66 79 20 74 68 65 20 0a 2a 2a 20   modify the .** 
2b0c0 64 61 74 61 62 61 73 65 2e 20 20 5e 54 68 65 20  database.  ^The 
2b0d0 5b 41 54 54 41 43 48 5d 20 61 6e 64 20 5b 44 45  [ATTACH] and [DE
2b0e0 54 41 43 48 5d 20 73 74 61 74 65 6d 65 6e 74 73  TACH] statements
2b0f0 20 61 6c 73 6f 20 63 61 75 73 65 0a 2a 2a 20 73   also cause.** s
2b100 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64  qlite3_stmt_read
2b110 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e  only() to return
2b120 20 74 72 75 65 20 73 69 6e 63 65 2c 20 77 68 69   true since, whi
2b130 6c 65 20 74 68 6f 73 65 20 73 74 61 74 65 6d 65  le those stateme
2b140 6e 74 73 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68  nts.** change th
2b150 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  e configuration 
2b160 6f 66 20 61 20 64 61 74 61 62 61 73 65 20 63 6f  of a database co
2b170 6e 6e 65 63 74 69 6f 6e 2c 20 74 68 65 79 20 64  nnection, they d
2b180 6f 20 6e 6f 74 20 6d 61 6b 65 20 0a 2a 2a 20 63  o not make .** c
2b190 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 63 6f  hanges to the co
2b1a0 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74  ntent of the dat
2b1b0 61 62 61 73 65 20 66 69 6c 65 73 20 6f 6e 20 64  abase files on d
2b1c0 69 73 6b 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  isk..*/.SQLITE_A
2b1d0 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54  PI int SQLITE_ST
2b1e0 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 73 74  DCALL sqlite3_st
2b1f0 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69  mt_readonly(sqli
2b200 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
2b210 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2b220 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20  F: Determine If 
2b230 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
2b240 6d 65 6e 74 20 48 61 73 20 42 65 65 6e 20 52 65  ment Has Been Re
2b250 73 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  set.** METHOD: s
2b260 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
2b270 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73  * ^The sqlite3_s
2b280 74 6d 74 5f 62 75 73 79 28 53 29 20 69 6e 74 65  tmt_busy(S) inte
2b290 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 72  rface returns tr
2b2a0 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66  ue (non-zero) if
2b2b0 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
2b2c0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 68  d statement] S h
2b2d0 61 73 20 62 65 65 6e 20 73 74 65 70 70 65 64 20  as been stepped 
2b2e0 61 74 20 6c 65 61 73 74 20 6f 6e 63 65 20 75 73  at least once us
2b2f0 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ing .** [sqlite3
2b300 5f 73 74 65 70 28 53 29 5d 20 62 75 74 20 68 61  _step(S)] but ha
2b310 73 20 6e 65 69 74 68 65 72 20 72 75 6e 20 74 6f  s neither run to
2b320 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 28 72 65 74   completion (ret
2b330 75 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45  urned.** [SQLITE
2b340 5f 44 4f 4e 45 5d 20 66 72 6f 6d 20 5b 73 71 6c  _DONE] from [sql
2b350 69 74 65 33 5f 73 74 65 70 28 53 29 5d 29 20 6e  ite3_step(S)]) n
2b360 6f 72 0a 2a 2a 20 62 65 65 6e 20 72 65 73 65 74  or.** been reset
2b370 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
2b380 72 65 73 65 74 28 53 29 5d 2e 20 20 5e 54 68 65  reset(S)].  ^The
2b390 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75   sqlite3_stmt_bu
2b3a0 73 79 28 53 29 0a 2a 2a 20 69 6e 74 65 72 66 61  sy(S).** interfa
2b3b0 63 65 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65  ce returns false
2b3c0 20 69 66 20 53 20 69 73 20 61 20 4e 55 4c 4c 20   if S is a NULL 
2b3d0 70 6f 69 6e 74 65 72 2e 20 20 49 66 20 53 20 69  pointer.  If S i
2b3e0 73 20 6e 6f 74 20 61 20 0a 2a 2a 20 4e 55 4c 4c  s not a .** NULL
2b3f0 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 69 73 20   pointer and is 
2b400 6e 6f 74 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  not a pointer to
2b410 20 61 20 76 61 6c 69 64 20 5b 70 72 65 70 61 72   a valid [prepar
2b420 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a  ed statement].**
2b430 20 6f 62 6a 65 63 74 2c 20 74 68 65 6e 20 74 68   object, then th
2b440 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e  e behavior is un
2b450 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62  defined and prob
2b460 61 62 6c 79 20 75 6e 64 65 73 69 72 61 62 6c 65  ably undesirable
2b470 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74  ..**.** This int
2b480 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73  erface can be us
2b490 65 64 20 69 6e 20 63 6f 6d 62 69 6e 61 74 69 6f  ed in combinatio
2b4a0 6e 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f  n [sqlite3_next_
2b4b0 73 74 6d 74 28 29 5d 0a 2a 2a 20 74 6f 20 6c 6f  stmt()].** to lo
2b4c0 63 61 74 65 20 61 6c 6c 20 70 72 65 70 61 72 65  cate all prepare
2b4d0 64 20 73 74 61 74 65 6d 65 6e 74 73 20 61 73 73  d statements ass
2b4e0 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20 64  ociated with a d
2b4f0 61 74 61 62 61 73 65 20 0a 2a 2a 20 63 6f 6e 6e  atabase .** conn
2b500 65 63 74 69 6f 6e 20 74 68 61 74 20 61 72 65 20  ection that are 
2b510 69 6e 20 6e 65 65 64 20 6f 66 20 62 65 69 6e 67  in need of being
2b520 20 72 65 73 65 74 2e 20 20 54 68 69 73 20 63 61   reset.  This ca
2b530 6e 20 62 65 20 75 73 65 64 2c 0a 2a 2a 20 66 6f  n be used,.** fo
2b540 72 20 65 78 61 6d 70 6c 65 2c 20 69 6e 20 64 69  r example, in di
2b550 61 67 6e 6f 73 74 69 63 20 72 6f 75 74 69 6e 65  agnostic routine
2b560 73 20 74 6f 20 73 65 61 72 63 68 20 66 6f 72 20  s to search for 
2b570 70 72 65 70 61 72 65 64 20 0a 2a 2a 20 73 74 61  prepared .** sta
2b580 74 65 6d 65 6e 74 73 20 74 68 61 74 20 61 72 65  tements that are
2b590 20 68 6f 6c 64 69 6e 67 20 61 20 74 72 61 6e 73   holding a trans
2b5a0 61 63 74 69 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a  action open..*/.
2b5b0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53  SQLITE_API int S
2b5c0 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
2b5d0 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28  lite3_stmt_busy(
2b5e0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
2b5f0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2b600 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70   Dynamically Typ
2b610 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74 0a  ed Value Object.
2b620 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72  ** KEYWORDS: {pr
2b630 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2b640 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65 63  value} {unprotec
2b650 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2b660 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  e}.**.** SQLite 
2b670 75 73 65 73 20 74 68 65 20 73 71 6c 69 74 65 33  uses the sqlite3
2b680 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74 6f  _value object to
2b690 20 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20 76   represent all v
2b6a0 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 63 61  alues.** that ca
2b6b0 6e 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20 61  n be stored in a
2b6c0 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 2e   database table.
2b6d0 20 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e   SQLite uses dyn
2b6e0 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20 66  amic typing.** f
2b6f0 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20 69 74  or the values it
2b700 20 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c 75 65   stores.  ^Value
2b710 73 20 73 74 6f 72 65 64 20 69 6e 20 73 71 6c 69  s stored in sqli
2b720 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
2b730 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74 65  s.** can be inte
2b740 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70  gers, floating p
2b750 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74 72  oint values, str
2b760 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20  ings, BLOBs, or 
2b770 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73  NULL..**.** An s
2b780 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
2b790 65 63 74 20 6d 61 79 20 62 65 20 65 69 74 68 65  ect may be eithe
2b7a0 72 20 22 70 72 6f 74 65 63 74 65 64 22 20 6f 72  r "protected" or
2b7b0 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a   "unprotected"..
2b7c0 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 61 63  ** Some interfac
2b7d0 65 73 20 72 65 71 75 69 72 65 20 61 20 70 72 6f  es require a pro
2b7e0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2b7f0 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 6e 74  alue.  Other int
2b800 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20  erfaces.** will 
2b810 61 63 63 65 70 74 20 65 69 74 68 65 72 20 61 20  accept either a 
2b820 70 72 6f 74 65 63 74 65 64 20 6f 72 20 61 6e 20  protected or an 
2b830 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
2b840 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76  te3_value..** Ev
2b850 65 72 79 20 69 6e 74 65 72 66 61 63 65 20 74 68  ery interface th
2b860 61 74 20 61 63 63 65 70 74 73 20 73 71 6c 69 74  at accepts sqlit
2b870 65 33 5f 76 61 6c 75 65 20 61 72 67 75 6d 65 6e  e3_value argumen
2b880 74 73 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  ts specifies.** 
2b890 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 69  whether or not i
2b8a0 74 20 72 65 71 75 69 72 65 73 20 61 20 70 72 6f  t requires a pro
2b8b0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2b8c0 61 6c 75 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73  alue.  The.** [s
2b8d0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75 70  qlite3_value_dup
2b8e0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 61  ()] interface ca
2b8f0 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63 6f 6e  n be used to con
2b900 73 74 72 75 63 74 20 61 20 6e 65 77 20 0a 2a 2a  struct a new .**
2b910 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74   protected sqlit
2b920 65 33 5f 76 61 6c 75 65 20 66 72 6f 6d 20 61 6e  e3_value from an
2b930 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c   unprotected sql
2b940 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a  ite3_value..**.*
2b950 2a 20 54 68 65 20 74 65 72 6d 73 20 22 70 72 6f  * The terms "pro
2b960 74 65 63 74 65 64 22 20 61 6e 64 20 22 75 6e 70  tected" and "unp
2b970 72 6f 74 65 63 74 65 64 22 20 72 65 66 65 72 20  rotected" refer 
2b980 74 6f 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  to whether or no
2b990 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69 73 20  t.** a mutex is 
2b9a0 68 65 6c 64 2e 20 20 41 6e 20 69 6e 74 65 72 6e  held.  An intern
2b9b0 61 6c 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64  al mutex is held
2b9c0 20 66 6f 72 20 61 20 70 72 6f 74 65 63 74 65 64   for a protected
2b9d0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
2b9e0 65 20 6f 62 6a 65 63 74 20 62 75 74 20 6e 6f 20  e object but no 
2b9f0 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f  mutex is held fo
2ba00 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64  r an unprotected
2ba10 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
2ba20 65 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 53 51  e object.  If SQ
2ba30 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
2ba40 20 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d 74 68   to be single-th
2ba50 72 65 61 64 65 64 0a 2a 2a 20 28 77 69 74 68 20  readed.** (with 
2ba60 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
2ba70 46 45 3d 30 5d 20 61 6e 64 20 77 69 74 68 20 5b  FE=0] and with [
2ba80 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61  sqlite3_threadsa
2ba90 66 65 28 29 5d 20 72 65 74 75 72 6e 69 6e 67 20  fe()] returning 
2baa0 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53 51 4c 69  0).** or if SQLi
2bab0 74 65 20 69 73 20 72 75 6e 20 69 6e 20 6f 6e 65  te is run in one
2bac0 20 6f 66 20 72 65 64 75 63 65 64 20 6d 75 74 65   of reduced mute
2bad0 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53 51 4c  x modes .** [SQL
2bae0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
2baf0 45 54 48 52 45 41 44 5d 20 6f 72 20 5b 53 51 4c  ETHREAD] or [SQL
2bb00 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49  ITE_CONFIG_MULTI
2bb10 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68 65 6e 20  THREAD].** then 
2bb20 74 68 65 72 65 20 69 73 20 6e 6f 20 64 69 73 74  there is no dist
2bb30 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20  inction between 
2bb40 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e  protected and un
2bb50 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
2bb60 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
2bb70 74 73 20 61 6e 64 20 74 68 65 79 20 63 61 6e 20  ts and they can 
2bb80 62 65 20 75 73 65 64 20 69 6e 74 65 72 63 68 61  be used intercha
2bb90 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77 65 76 65  ngeably.  Howeve
2bba0 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 69 6d 75  r,.** for maximu
2bbb0 6d 20 63 6f 64 65 20 70 6f 72 74 61 62 69 6c 69  m code portabili
2bbc0 74 79 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65  ty it is recomme
2bbd0 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63  nded that applic
2bbe0 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20  ations.** still 
2bbf0 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e 63  make the distinc
2bc00 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f  tion between pro
2bc10 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f  tected and unpro
2bc20 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65  tected.** sqlite
2bc30 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20  3_value objects 
2bc40 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20 73 74  even when not st
2bc50 72 69 63 74 6c 79 20 72 65 71 75 69 72 65 64 2e  rictly required.
2bc60 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2bc70 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
2bc80 73 20 74 68 61 74 20 61 72 65 20 70 61 73 73 65  s that are passe
2bc90 64 20 61 73 20 70 61 72 61 6d 65 74 65 72 73 20  d as parameters 
2bca0 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 6c  into the.** impl
2bcb0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 61  ementation of [a
2bcc0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2bcd0 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
2bce0 5d 20 61 72 65 20 70 72 6f 74 65 63 74 65 64 2e  ] are protected.
2bcf0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2bd00 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 72 65  _value object re
2bd10 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71  turned by.** [sq
2bd20 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c  lite3_column_val
2bd30 75 65 28 29 5d 20 69 73 20 75 6e 70 72 6f 74 65  ue()] is unprote
2bd40 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65  cted..** Unprote
2bd50 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2bd60 75 65 20 6f 62 6a 65 63 74 73 20 6d 61 79 20 6f  ue objects may o
2bd70 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68  nly be used with
2bd80 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
2bd90 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64  ult_value()] and
2bda0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76   [sqlite3_bind_v
2bdb0 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  alue()]..** The 
2bdc0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
2bdd0 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 76 61  lob | sqlite3_va
2bde0 6c 75 65 5f 74 79 70 65 28 29 5d 20 66 61 6d 69  lue_type()] fami
2bdf0 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61  ly of.** interfa
2be00 63 65 73 20 72 65 71 75 69 72 65 20 70 72 6f 74  ces require prot
2be10 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2be20 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a  lue objects..*/.
2be30 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 4d  typedef struct M
2be40 65 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  em sqlite3_value
2be50 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2be60 46 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20  F: SQL Function 
2be70 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74 0a 2a  Context Object.*
2be80 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78 74  *.** The context
2be90 20 69 6e 20 77 68 69 63 68 20 61 6e 20 53 51 4c   in which an SQL
2bea0 20 66 75 6e 63 74 69 6f 6e 20 65 78 65 63 75 74   function execut
2beb0 65 73 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20  es is stored in 
2bec0 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  an.** sqlite3_co
2bed0 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e 20 20 5e  ntext object.  ^
2bee0 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  A pointer to an 
2bef0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20  sqlite3_context 
2bf00 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61 6c 77  object.** is alw
2bf10 61 79 73 20 66 69 72 73 74 20 70 61 72 61 6d 65  ays first parame
2bf20 74 65 72 20 74 6f 20 5b 61 70 70 6c 69 63 61 74  ter to [applicat
2bf30 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
2bf40 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54  functions]..** T
2bf50 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
2bf60 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
2bf70 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ion implementati
2bf80 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20 74 68 69  on will pass thi
2bf90 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 68 72  s.** pointer thr
2bfa0 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c 73 20  ough into calls 
2bfb0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  to [sqlite3_resu
2bfc0 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33  lt_int | sqlite3
2bfd0 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b  _result()],.** [
2bfe0 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
2bff0 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20 5b 73  e_context()], [s
2c000 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61  qlite3_user_data
2c010 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
2c020 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64  _context_db_hand
2c030 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  le()], [sqlite3_
2c040 67 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2c 0a  get_auxdata()],.
2c050 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c 69 74  ** and/or [sqlit
2c060 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29  e3_set_auxdata()
2c070 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  ]..*/.typedef st
2c080 72 75 63 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e  ruct sqlite3_con
2c090 74 65 78 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e  text sqlite3_con
2c0a0 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  text;../*.** CAP
2c0b0 49 33 52 45 46 3a 20 42 69 6e 64 69 6e 67 20 56  I3REF: Binding V
2c0c0 61 6c 75 65 73 20 54 6f 20 50 72 65 70 61 72 65  alues To Prepare
2c0d0 64 20 53 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  d Statements.** 
2c0e0 4b 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73 74 20  KEYWORDS: {host 
2c0f0 70 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f 73 74  parameter} {host
2c100 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 68 6f   parameters} {ho
2c110 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d  st parameter nam
2c120 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  e}.** KEYWORDS: 
2c130 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 7d 20  {SQL parameter} 
2c140 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 7d  {SQL parameters}
2c150 20 7b 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64   {parameter bind
2c160 69 6e 67 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ing}.** METHOD: 
2c170 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
2c180 2a 2a 20 5e 28 49 6e 20 74 68 65 20 53 51 4c 20  ** ^(In the SQL 
2c190 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 69  statement text i
2c1a0 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  nput to [sqlite3
2c1b0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
2c1c0 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 2c  nd its variants,
2c1d0 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61 79  .** literals may
2c1e0 20 62 65 20 72 65 70 6c 61 63 65 64 20 62 79 20   be replaced by 
2c1f0 61 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 74 68  a [parameter] th
2c200 61 74 20 6d 61 74 63 68 65 73 20 6f 6e 65 20 6f  at matches one o
2c210 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74  f following.** t
2c220 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20  emplates:.**.** 
2c230 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a  <ul>.** <li>  ?.
2c240 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a  ** <li>  ?NNN.**
2c250 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c   <li>  :VVV.** <
2c260 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69  li>  @VVV.** <li
2c270 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e  >  $VVV.** </ul>
2c280 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 74 65  .**.** In the te
2c290 6d 70 6c 61 74 65 73 20 61 62 6f 76 65 2c 20 4e  mplates above, N
2c2a0 4e 4e 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e  NN represents an
2c2b0 20 69 6e 74 65 67 65 72 20 6c 69 74 65 72 61 6c   integer literal
2c2c0 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20 72 65 70  ,.** and VVV rep
2c2d0 72 65 73 65 6e 74 73 20 61 6e 20 61 6c 70 68 61  resents an alpha
2c2e0 6e 75 6d 65 72 69 63 20 69 64 65 6e 74 69 66 69  numeric identifi
2c2f0 65 72 2e 29 5e 20 20 5e 54 68 65 20 76 61 6c 75  er.)^  ^The valu
2c300 65 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70  es of these.** p
2c310 61 72 61 6d 65 74 65 72 73 20 28 61 6c 73 6f 20  arameters (also 
2c320 63 61 6c 6c 65 64 20 22 68 6f 73 74 20 70 61 72  called "host par
2c330 61 6d 65 74 65 72 20 6e 61 6d 65 73 22 20 6f 72  ameter names" or
2c340 20 22 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73   "SQL parameters
2c350 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65 74  ").** can be set
2c360 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74   using the sqlit
2c370 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74  e3_bind_*() rout
2c380 69 6e 65 73 20 64 65 66 69 6e 65 64 20 68 65 72  ines defined her
2c390 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  e..**.** ^The fi
2c3a0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
2c3b0 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
2c3c0 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 69 73  _*() routines is
2c3d0 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69   always.** a poi
2c3e0 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c  nter to the [sql
2c3f0 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63  ite3_stmt] objec
2c400 74 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a  t returned from.
2c410 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
2c420 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 69 74 73  are_v2()] or its
2c430 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a   variants..**.**
2c440 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67   ^The second arg
2c450 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64  ument is the ind
2c460 65 78 20 6f 66 20 74 68 65 20 53 51 4c 20 70 61  ex of the SQL pa
2c470 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20 73 65  rameter to be se
2c480 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 6d  t..** ^The leftm
2c490 6f 73 74 20 53 51 4c 20 70 61 72 61 6d 65 74 65  ost SQL paramete
2c4a0 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f  r has an index o
2c4b0 66 20 31 2e 20 20 5e 57 68 65 6e 20 74 68 65 20  f 1.  ^When the 
2c4c0 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51  same named.** SQ
2c4d0 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 75  L parameter is u
2c4e0 73 65 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e  sed more than on
2c4f0 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20 73  ce, second and s
2c500 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63  ubsequent.** occ
2c510 75 72 72 65 6e 63 65 73 20 68 61 76 65 20 74 68  urrences have th
2c520 65 20 73 61 6d 65 20 69 6e 64 65 78 20 61 73 20  e same index as 
2c530 74 68 65 20 66 69 72 73 74 20 6f 63 63 75 72 72  the first occurr
2c540 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e  ence..** ^The in
2c550 64 65 78 20 66 6f 72 20 6e 61 6d 65 64 20 70 61  dex for named pa
2c560 72 61 6d 65 74 65 72 73 20 63 61 6e 20 62 65 20  rameters can be 
2c570 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e 67 20  looked up using 
2c580 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
2c590 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
2c5a0 6e 64 65 78 28 29 5d 20 41 50 49 20 69 66 20 64  ndex()] API if d
2c5b0 65 73 69 72 65 64 2e 20 20 5e 54 68 65 20 69 6e  esired.  ^The in
2c5c0 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e  dex.** for "?NNN
2c5d0 22 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20  " parameters is 
2c5e0 74 68 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e  the value of NNN
2c5f0 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20 76 61  ..** ^The NNN va
2c600 6c 75 65 20 6d 75 73 74 20 62 65 20 62 65 74 77  lue must be betw
2c610 65 65 6e 20 31 20 61 6e 64 20 74 68 65 20 5b 73  een 1 and the [s
2c620 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a  qlite3_limit()].
2c630 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 5b 53 51  ** parameter [SQ
2c640 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41  LITE_LIMIT_VARIA
2c650 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65 66  BLE_NUMBER] (def
2c660 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 39 39 29  ault value: 999)
2c670 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69  ..**.** ^The thi
2c680 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  rd argument is t
2c690 68 65 20 76 61 6c 75 65 20 74 6f 20 62 69 6e 64  he value to bind
2c6a0 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65   to the paramete
2c6b0 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74 68  r..** ^If the th
2c6c0 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
2c6d0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
2c6e0 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  xt() or sqlite3_
2c6f0 62 69 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a  bind_text16().**
2c700 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   or sqlite3_bind
2c710 5f 62 6c 6f 62 28 29 20 69 73 20 61 20 4e 55 4c  _blob() is a NUL
2c720 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74  L pointer then t
2c730 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
2c740 74 65 72 0a 2a 2a 20 69 73 20 69 67 6e 6f 72 65  ter.** is ignore
2c750 64 20 61 6e 64 20 74 68 65 20 65 6e 64 20 72 65  d and the end re
2c760 73 75 6c 74 20 69 73 20 74 68 65 20 73 61 6d 65  sult is the same
2c770 20 61 73 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   as sqlite3_bind
2c780 5f 6e 75 6c 6c 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  _null()..**.** ^
2c790 28 49 6e 20 74 68 6f 73 65 20 72 6f 75 74 69 6e  (In those routin
2c7a0 65 73 20 74 68 61 74 20 68 61 76 65 20 61 20 66  es that have a f
2c7b0 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c 20  ourth argument, 
2c7c0 69 74 73 20 76 61 6c 75 65 20 69 73 20 74 68 65  its value is the
2c7d0 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  .** number of by
2c7e0 74 65 73 20 69 6e 20 74 68 65 20 70 61 72 61 6d  tes in the param
2c7f0 65 74 65 72 2e 20 20 54 6f 20 62 65 20 63 6c 65  eter.  To be cle
2c800 61 72 3a 20 74 68 65 20 76 61 6c 75 65 20 69 73  ar: the value is
2c810 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
2c820 66 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e 20 69  f <u>bytes</u> i
2c830 6e 20 74 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74  n the value, not
2c840 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
2c850 68 61 72 61 63 74 65 72 73 2e 29 5e 0a 2a 2a 20  haracters.)^.** 
2c860 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70  ^If the fourth p
2c870 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
2c880 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 20  te3_bind_text() 
2c890 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  or sqlite3_bind_
2c8a0 74 65 78 74 31 36 28 29 0a 2a 2a 20 69 73 20 6e  text16().** is n
2c8b0 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68  egative, then th
2c8c0 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20  e length of the 
2c8d0 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65  string is.** the
2c8e0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
2c8f0 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74   up to the first
2c900 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
2c910 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 6f 75 72  ..** If the four
2c920 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
2c930 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
2c940 62 28 29 20 69 73 20 6e 65 67 61 74 69 76 65 2c  b() is negative,
2c950 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 62 65 68   then.** the beh
2c960 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e  avior is undefin
2c970 65 64 2e 0a 2a 2a 20 49 66 20 61 20 6e 6f 6e 2d  ed..** If a non-
2c980 6e 65 67 61 74 69 76 65 20 66 6f 75 72 74 68 20  negative fourth 
2c990 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 72 6f  parameter is pro
2c9a0 76 69 64 65 64 20 74 6f 20 73 71 6c 69 74 65 33  vided to sqlite3
2c9b0 5f 62 69 6e 64 5f 74 65 78 74 28 29 0a 2a 2a 20  _bind_text().** 
2c9c0 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  or sqlite3_bind_
2c9d0 74 65 78 74 31 36 28 29 20 6f 72 20 73 71 6c 69  text16() or sqli
2c9e0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28  te3_bind_text64(
2c9f0 29 20 74 68 65 6e 0a 2a 2a 20 74 68 61 74 20 70  ) then.** that p
2ca00 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62 65  arameter must be
2ca10 20 74 68 65 20 62 79 74 65 20 6f 66 66 73 65 74   the byte offset
2ca20 0a 2a 2a 20 77 68 65 72 65 20 74 68 65 20 4e 55  .** where the NU
2ca30 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f 75  L terminator wou
2ca40 6c 64 20 6f 63 63 75 72 20 61 73 73 75 6d 69 6e  ld occur assumin
2ca50 67 20 74 68 65 20 73 74 72 69 6e 67 20 77 65 72  g the string wer
2ca60 65 20 4e 55 4c 0a 2a 2a 20 74 65 72 6d 69 6e 61  e NUL.** termina
2ca70 74 65 64 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c  ted.  If any NUL
2ca80 20 63 68 61 72 61 63 74 65 72 73 20 6f 63 63 75   characters occu
2ca90 72 20 61 74 20 62 79 74 65 20 6f 66 66 73 65 74  r at byte offset
2caa0 73 20 6c 65 73 73 20 74 68 61 6e 20 0a 2a 2a 20  s less than .** 
2cab0 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65  the value of the
2cac0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
2cad0 72 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c  r then the resul
2cae0 74 69 6e 67 20 73 74 72 69 6e 67 20 76 61 6c 75  ting string valu
2caf0 65 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 61 69  e will.** contai
2cb00 6e 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 2e  n embedded NULs.
2cb10 20 20 54 68 65 20 72 65 73 75 6c 74 20 6f 66 20    The result of 
2cb20 65 78 70 72 65 73 73 69 6f 6e 73 20 69 6e 76 6f  expressions invo
2cb30 6c 76 69 6e 67 20 73 74 72 69 6e 67 73 0a 2a 2a  lving strings.**
2cb40 20 77 69 74 68 20 65 6d 62 65 64 64 65 64 20 4e   with embedded N
2cb50 55 4c 73 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ULs is undefined
2cb60 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66  ..**.** ^The fif
2cb70 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  th argument to t
2cb80 68 65 20 42 4c 4f 42 20 61 6e 64 20 73 74 72 69  he BLOB and stri
2cb90 6e 67 20 62 69 6e 64 69 6e 67 20 69 6e 74 65 72  ng binding inter
2cba0 66 61 63 65 73 0a 2a 2a 20 69 73 20 61 20 64 65  faces.** is a de
2cbb0 73 74 72 75 63 74 6f 72 20 75 73 65 64 20 74 6f  structor used to
2cbc0 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20   dispose of the 
2cbd0 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69 6e  BLOB or.** strin
2cbe0 67 20 61 66 74 65 72 20 53 51 4c 69 74 65 20 68  g after SQLite h
2cbf0 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68  as finished with
2cc00 20 69 74 2e 20 20 5e 54 68 65 20 64 65 73 74 72   it.  ^The destr
2cc10 75 63 74 6f 72 20 69 73 20 63 61 6c 6c 65 64 0a  uctor is called.
2cc20 2a 2a 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66  ** to dispose of
2cc30 20 74 68 65 20 42 4c 4f 42 20 6f 72 20 73 74 72   the BLOB or str
2cc40 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 20  ing even if the 
2cc50 63 61 6c 6c 20 74 6f 20 62 69 6e 64 20 41 50 49  call to bind API
2cc60 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 49 66 20 74   fails..** ^If t
2cc70 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e  he fifth argumen
2cc80 74 20 69 73 0a 2a 2a 20 74 68 65 20 73 70 65 63  t is.** the spec
2cc90 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49 54  ial value [SQLIT
2cca0 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 65 6e 20  E_STATIC], then 
2ccb0 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74  SQLite assumes t
2ccc0 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72  hat the.** infor
2ccd0 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20 73 74 61  mation is in sta
2cce0 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73  tic, unmanaged s
2ccf0 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f  pace and does no
2cd00 74 20 6e 65 65 64 20 74 6f 20 62 65 20 66 72 65  t need to be fre
2cd10 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  ed..** ^If the f
2cd20 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 68 61  ifth argument ha
2cd30 73 20 74 68 65 20 76 61 6c 75 65 20 5b 53 51 4c  s the value [SQL
2cd40 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20  ITE_TRANSIENT], 
2cd50 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d  then.** SQLite m
2cd60 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 70 72 69  akes its own pri
2cd70 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65  vate copy of the
2cd80 20 64 61 74 61 20 69 6d 6d 65 64 69 61 74 65 6c   data immediatel
2cd90 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65  y, before.** the
2cda0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
2cdb0 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
2cdc0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69  s..**.** ^The si
2cdd0 78 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  xth argument to 
2cde0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
2cdf0 74 36 34 28 29 20 6d 75 73 74 20 62 65 20 6f 6e  t64() must be on
2ce00 65 20 6f 66 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  e of.** [SQLITE_
2ce10 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55  UTF8], [SQLITE_U
2ce20 54 46 31 36 5d 2c 20 5b 53 51 4c 49 54 45 5f 55  TF16], [SQLITE_U
2ce30 54 46 31 36 42 45 5d 2c 20 6f 72 20 5b 53 51 4c  TF16BE], or [SQL
2ce40 49 54 45 5f 55 54 46 31 36 4c 45 5d 0a 2a 2a 20  ITE_UTF16LE].** 
2ce50 74 6f 20 73 70 65 63 69 66 79 20 74 68 65 20 65  to specify the e
2ce60 6e 63 6f 64 69 6e 67 20 6f 66 20 74 68 65 20 74  ncoding of the t
2ce70 65 78 74 20 69 6e 20 74 68 65 20 74 68 69 72 64  ext in the third
2ce80 20 70 61 72 61 6d 65 74 65 72 2e 20 20 49 66 0a   parameter.  If.
2ce90 2a 2a 20 74 68 65 20 73 69 78 74 68 20 61 72 67  ** the sixth arg
2cea0 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
2ceb0 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29 20 69  _bind_text64() i
2cec0 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65  s not one of the
2ced0 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20 76 61 6c 75  .** allowed valu
2cee0 65 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 2c 20  es shown above, 
2cef0 6f 72 20 69 66 20 74 68 65 20 74 65 78 74 20 65  or if the text e
2cf00 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66 66 65  ncoding is diffe
2cf10 72 65 6e 74 0a 2a 2a 20 66 72 6f 6d 20 74 68 65  rent.** from the
2cf20 20 65 6e 63 6f 64 69 6e 67 20 73 70 65 63 69 66   encoding specif
2cf30 69 65 64 20 62 79 20 74 68 65 20 73 69 78 74 68  ied by the sixth
2cf40 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e   parameter, then
2cf50 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a   the behavior.**
2cf60 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
2cf70 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2cf80 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28  3_bind_zeroblob(
2cf90 29 20 72 6f 75 74 69 6e 65 20 62 69 6e 64 73 20  ) routine binds 
2cfa0 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68  a BLOB of length
2cfb0 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20 66 69   N that.** is fi
2cfc0 6c 6c 65 64 20 77 69 74 68 20 7a 65 72 6f 65 73  lled with zeroes
2cfd0 2e 20 20 5e 41 20 7a 65 72 6f 62 6c 6f 62 20 75  .  ^A zeroblob u
2cfe0 73 65 73 20 61 20 66 69 78 65 64 20 61 6d 6f 75  ses a fixed amou
2cff0 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20  nt of memory.** 
2d000 28 6a 75 73 74 20 61 6e 20 69 6e 74 65 67 65 72  (just an integer
2d010 20 74 6f 20 68 6f 6c 64 20 69 74 73 20 73 69 7a   to hold its siz
2d020 65 29 20 77 68 69 6c 65 20 69 74 20 69 73 20 62  e) while it is b
2d030 65 69 6e 67 20 70 72 6f 63 65 73 73 65 64 2e 0a  eing processed..
2d040 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65  ** Zeroblobs are
2d050 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 73 65 72   intended to ser
2d060 76 65 20 61 73 20 70 6c 61 63 65 68 6f 6c 64 65  ve as placeholde
2d070 72 73 20 66 6f 72 20 42 4c 4f 42 73 20 77 68 6f  rs for BLOBs who
2d080 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 73  se.** content is
2d090 20 6c 61 74 65 72 20 77 72 69 74 74 65 6e 20 75   later written u
2d0a0 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
2d0b0 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63  _blob_open | inc
2d0c0 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f  remental BLOB I/
2d0d0 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20  O] routines..** 
2d0e0 5e 41 20 6e 65 67 61 74 69 76 65 20 76 61 6c 75  ^A negative valu
2d0f0 65 20 66 6f 72 20 74 68 65 20 7a 65 72 6f 62 6c  e for the zerobl
2d100 6f 62 20 72 65 73 75 6c 74 73 20 69 6e 20 61 20  ob results in a 
2d110 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42  zero-length BLOB
2d120 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79 20  ..**.** ^If any 
2d130 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  of the sqlite3_b
2d140 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73  ind_*() routines
2d150 20 61 72 65 20 63 61 6c 6c 65 64 20 77 69 74 68   are called with
2d160 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a   a NULL pointer.
2d170 2a 2a 20 66 6f 72 20 74 68 65 20 5b 70 72 65 70  ** for the [prep
2d180 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2d190 6f 72 20 77 69 74 68 20 61 20 70 72 65 70 61 72  or with a prepar
2d1a0 65 64 20 73 74 61 74 65 6d 65 6e 74 20 66 6f 72  ed statement for
2d1b0 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74   which.** [sqlit
2d1c0 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 62  e3_step()] has b
2d1d0 65 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20  een called more 
2d1e0 72 65 63 65 6e 74 6c 79 20 74 68 61 6e 20 5b 73  recently than [s
2d1f0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c  qlite3_reset()],
2d200 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 61 6c  .** then the cal
2d210 6c 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53  l will return [S
2d220 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20  QLITE_MISUSE].  
2d230 49 66 20 61 6e 79 20 73 71 6c 69 74 65 33 5f 62  If any sqlite3_b
2d240 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74 69 6e  ind_().** routin
2d250 65 20 69 73 20 70 61 73 73 65 64 20 61 20 5b 70  e is passed a [p
2d260 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2d270 74 5d 20 74 68 61 74 20 68 61 73 20 62 65 65 6e  t] that has been
2d280 20 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68 65 0a   finalized, the.
2d290 2a 2a 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64  ** result is und
2d2a0 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61  efined and proba
2d2b0 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a  bly harmful..**.
2d2c0 2a 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61 72 65  ** ^Bindings are
2d2d0 20 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 79 20   not cleared by 
2d2e0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  the [sqlite3_res
2d2f0 65 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a  et()] routine..*
2d300 2a 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d  * ^Unbound param
2d310 65 74 65 72 73 20 61 72 65 20 69 6e 74 65 72 70  eters are interp
2d320 72 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a  reted as NULL..*
2d330 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2d340 33 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69 6e 65  3_bind_* routine
2d350 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  s return [SQLITE
2d360 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20  _OK] on success 
2d370 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20  or an.** [error 
2d380 63 6f 64 65 5d 20 69 66 20 61 6e 79 74 68 69 6e  code] if anythin
2d390 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a  g goes wrong..**
2d3a0 20 5e 5b 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47   ^[SQLITE_TOOBIG
2d3b0 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72  ] might be retur
2d3c0 6e 65 64 20 69 66 20 74 68 65 20 73 69 7a 65 20  ned if the size 
2d3d0 6f 66 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42  of a string or B
2d3e0 4c 4f 42 0a 2a 2a 20 65 78 63 65 65 64 73 20 6c  LOB.** exceeds l
2d3f0 69 6d 69 74 73 20 69 6d 70 6f 73 65 64 20 62 79  imits imposed by
2d400 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d   [sqlite3_limit]
2d410 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  ([SQLITE_LIMIT_L
2d420 45 4e 47 54 48 5d 29 20 6f 72 0a 2a 2a 20 5b 53  ENGTH]) or.** [S
2d430 51 4c 49 54 45 5f 4d 41 58 5f 4c 45 4e 47 54 48  QLITE_MAX_LENGTH
2d440 5d 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 52  ]..** ^[SQLITE_R
2d450 41 4e 47 45 5d 20 69 73 20 72 65 74 75 72 6e 65  ANGE] is returne
2d460 64 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  d if the paramet
2d470 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f  er.** index is o
2d480 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 5e 5b  ut of range.  ^[
2d490 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73  SQLITE_NOMEM] is
2d4a0 20 72 65 74 75 72 6e 65 64 20 69 66 20 6d 61 6c   returned if mal
2d4b0 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a  loc() fails..**.
2d4c0 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
2d4d0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2d4e0 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a  eter_count()],.*
2d4f0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
2d500 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29  parameter_name()
2d510 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ], and [sqlite3_
2d520 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
2d530 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49  ndex()]..*/.SQLI
2d540 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54  TE_API int SQLIT
2d550 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
2d560 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69  3_bind_blob(sqli
2d570 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
2d580 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
2d590 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64   n, void(*)(void
2d5a0 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  *));.SQLITE_API 
2d5b0 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41  int SQLITE_STDCA
2d5c0 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  LL sqlite3_bind_
2d5d0 62 6c 6f 62 36 34 28 73 71 6c 69 74 65 33 5f 73  blob64(sqlite3_s
2d5e0 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
2d5f0 20 76 6f 69 64 2a 2c 20 73 71 6c 69 74 65 33 5f   void*, sqlite3_
2d600 75 69 6e 74 36 34 2c 0a 20 20 20 20 20 20 20 20  uint64,.        
2d610 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2d620 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
2d630 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2d640 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
2d650 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62  qlite3_bind_doub
2d660 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  le(sqlite3_stmt*
2d670 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a  , int, double);.
2d680 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53  SQLITE_API int S
2d690 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
2d6a0 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73  lite3_bind_int(s
2d6b0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2d6c0 74 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f  t, int);.SQLITE_
2d6d0 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  API int SQLITE_S
2d6e0 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62  TDCALL sqlite3_b
2d6f0 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 65  ind_int64(sqlite
2d700 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71  3_stmt*, int, sq
2d710 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 53 51  lite3_int64);.SQ
2d720 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c  LITE_API int SQL
2d730 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
2d740 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71  te3_bind_null(sq
2d750 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2d760 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
2d770 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
2d780 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
2d790 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  xt(sqlite3_stmt*
2d7a0 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a  ,int,const char*
2d7b0 2c 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69  ,int,void(*)(voi
2d7c0 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  d*));.SQLITE_API
2d7d0 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43   int SQLITE_STDC
2d7e0 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  ALL sqlite3_bind
2d7f0 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f  _text16(sqlite3_
2d800 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
2d810 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f  t void*, int, vo
2d820 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53  id(*)(void*));.S
2d830 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51  QLITE_API int SQ
2d840 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
2d850 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34  ite3_bind_text64
2d860 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2d870 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a  int, const char*
2d880 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  , sqlite3_uint64
2d890 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
2d8a0 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 28             void(
2d8b0 2a 29 28 76 6f 69 64 2a 29 2c 20 75 6e 73 69 67  *)(void*), unsig
2d8c0 6e 65 64 20 63 68 61 72 20 65 6e 63 6f 64 69 6e  ned char encodin
2d8d0 67 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  g);.SQLITE_API i
2d8e0 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  nt SQLITE_STDCAL
2d8f0 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76  L sqlite3_bind_v
2d900 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  alue(sqlite3_stm
2d910 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 73  t*, int, const s
2d920 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
2d930 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53  SQLITE_API int S
2d940 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
2d950 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62  lite3_bind_zerob
2d960 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lob(sqlite3_stmt
2d970 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a  *, int, int n);.
2d980 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53  SQLITE_API int S
2d990 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
2d9a0 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62  lite3_bind_zerob
2d9b0 6c 6f 62 36 34 28 73 71 6c 69 74 65 33 5f 73 74  lob64(sqlite3_st
2d9c0 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65  mt*, int, sqlite
2d9d0 33 5f 75 69 6e 74 36 34 29 3b 0a 0a 2f 2a 0a 2a  3_uint64);../*.*
2d9e0 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62  * CAPI3REF: Numb
2d9f0 65 72 20 4f 66 20 53 51 4c 20 50 61 72 61 6d 65  er Of SQL Parame
2da00 74 65 72 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ters.** METHOD: 
2da10 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
2da20 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65  ** ^This routine
2da30 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
2da40 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20  find the number 
2da50 6f 66 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65  of [SQL paramete
2da60 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 72 65  rs].** in a [pre
2da70 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2da80 2e 20 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  .  SQL parameter
2da90 73 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66 20  s are tokens of 
2daa0 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c  the.** form "?",
2dab0 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 2c   "?NNN", ":AAA",
2dac0 20 22 24 41 41 41 22 2c 20 6f 72 20 22 40 41 41   "$AAA", or "@AA
2dad0 41 22 20 74 68 61 74 20 73 65 72 76 65 20 61 73  A" that serve as
2dae0 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72 73  .** placeholders
2daf0 20 66 6f 72 20 76 61 6c 75 65 73 20 74 68 61 74   for values that
2db00 20 61 72 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   are [sqlite3_bi
2db10 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d  nd_blob | bound]
2db20 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61 72 61 6d  .** to the param
2db30 65 74 65 72 73 20 61 74 20 61 20 6c 61 74 65 72  eters at a later
2db40 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54   time..**.** ^(T
2db50 68 69 73 20 72 6f 75 74 69 6e 65 20 61 63 74 75  his routine actu
2db60 61 6c 6c 79 20 72 65 74 75 72 6e 73 20 74 68 65  ally returns the
2db70 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 6c 61   index of the la
2db80 72 67 65 73 74 20 28 72 69 67 68 74 6d 6f 73 74  rgest (rightmost
2db90 29 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 20  ).** parameter. 
2dba0 46 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78  For all forms ex
2dbb0 63 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20  cept ?NNN, this 
2dbc0 77 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20  will correspond 
2dbd0 74 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  to the.** number
2dbe0 20 6f 66 20 75 6e 69 71 75 65 20 70 61 72 61 6d   of unique param
2dbf0 65 74 65 72 73 2e 20 20 49 66 20 70 61 72 61 6d  eters.  If param
2dc00 65 74 65 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e  eters of the ?NN
2dc10 4e 20 66 6f 72 6d 20 61 72 65 20 75 73 65 64 2c  N form are used,
2dc20 0a 2a 2a 20 74 68 65 72 65 20 6d 61 79 20 62 65  .** there may be
2dc30 20 67 61 70 73 20 69 6e 20 74 68 65 20 6c 69 73   gaps in the lis
2dc40 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  t.)^.**.** See a
2dc50 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69  lso: [sqlite3_bi
2dc60 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f  nd_blob|sqlite3_
2dc70 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  bind()],.** [sql
2dc80 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
2dc90 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64  ter_name()], and
2dca0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
2dcb0 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
2dcc0 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  x()]..*/.SQLITE_
2dcd0 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  API int SQLITE_S
2dce0 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62  TDCALL sqlite3_b
2dcf0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f  ind_parameter_co
2dd00 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  unt(sqlite3_stmt
2dd10 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
2dd20 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48  REF: Name Of A H
2dd30 6f 73 74 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a  ost Parameter.**
2dd40 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
2dd50 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  _stmt.**.** ^The
2dd60 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61   sqlite3_bind_pa
2dd70 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 50 2c 4e  rameter_name(P,N
2dd80 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
2dd90 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20  rns.** the name 
2dda0 6f 66 20 74 68 65 20 4e 2d 74 68 20 5b 53 51 4c  of the N-th [SQL
2ddb0 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74   parameter] in t
2ddc0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
2ddd0 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28  tement] P..** ^(
2dde0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 6f  SQL parameters o
2ddf0 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e  f the form "?NNN
2de00 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22  " or ":AAA" or "
2de10 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a  @AAA" or "$AAA".
2de20 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d 65 20 77  ** have a name w
2de30 68 69 63 68 20 69 73 20 74 68 65 20 73 74 72 69  hich is the stri
2de40 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41  ng "?NNN" or ":A
2de50 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72  AA" or "@AAA" or
2de60 20 22 24 41 41 41 22 0a 2a 2a 20 72 65 73 70 65   "$AAA".** respe
2de70 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f  ctively..** In o
2de80 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20  ther words, the 
2de90 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 22  initial ":" or "
2dea0 24 22 20 6f 72 20 22 40 22 20 6f 72 20 22 3f 22  $" or "@" or "?"
2deb0 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65 64 20  .** is included 
2dec0 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 6e  as part of the n
2ded0 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d  ame.)^.** ^Param
2dee0 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72  eters of the for
2def0 6d 20 22 3f 22 20 77 69 74 68 6f 75 74 20 61 20  m "?" without a 
2df00 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65  following intege
2df10 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a  r have no name.*
2df20 2a 20 61 6e 64 20 61 72 65 20 72 65 66 65 72 72  * and are referr
2df30 65 64 20 74 6f 20 61 73 20 22 6e 61 6d 65 6c 65  ed to as "namele
2df40 73 73 22 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75  ss" or "anonymou
2df50 73 20 70 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a  s parameters"..*
2df60 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
2df70 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 68  host parameter h
2df80 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31  as an index of 1
2df90 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e  , not 0..**.** ^
2dfa0 49 66 20 74 68 65 20 76 61 6c 75 65 20 4e 20 69  If the value N i
2dfb0 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f  s out of range o
2dfc0 72 20 69 66 20 74 68 65 20 4e 2d 74 68 20 70 61  r if the N-th pa
2dfd0 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61  rameter is.** na
2dfe0 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c  meless, then NUL
2dff0 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  L is returned.  
2e000 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74  ^The returned st
2e010 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79  ring is.** alway
2e020 73 20 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64  s in UTF-8 encod
2e030 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 20  ing even if the 
2e040 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20  named parameter 
2e050 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c  was.** originall
2e060 79 20 73 70 65 63 69 66 69 65 64 20 61 73 20 55  y specified as U
2e070 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 65  TF-16 in [sqlite
2e080 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 6f  3_prepare16()] o
2e090 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  r.** [sqlite3_pr
2e0a0 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a  epare16_v2()]..*
2e0b0 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
2e0c0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
2e0d0 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29  b|sqlite3_bind()
2e0e0 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
2e0f0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f  ind_parameter_co
2e100 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b  unt()], and.** [
2e110 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
2e120 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e  ameter_index()].
2e130 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  .*/.SQLITE_API c
2e140 6f 6e 73 74 20 63 68 61 72 20 2a 53 51 4c 49 54  onst char *SQLIT
2e150 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
2e160 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2e170 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
2e180 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  mt*, int);../*.*
2e190 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65  * CAPI3REF: Inde
2e1a0 78 20 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72  x Of A Parameter
2e1b0 20 57 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61   With A Given Na
2e1c0 6d 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  me.** METHOD: sq
2e1d0 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
2e1e0 20 5e 52 65 74 75 72 6e 20 74 68 65 20 69 6e 64   ^Return the ind
2e1f0 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72  ex of an SQL par
2e200 61 6d 65 74 65 72 20 67 69 76 65 6e 20 69 74 73  ameter given its
2e210 20 6e 61 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a 20   name.  ^The.** 
2e220 69 6e 64 65 78 20 76 61 6c 75 65 20 72 65 74 75  index value retu
2e230 72 6e 65 64 20 69 73 20 73 75 69 74 61 62 6c 65  rned is suitable
2e240 20 66 6f 72 20 75 73 65 20 61 73 20 74 68 65 20   for use as the 
2e250 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65  second.** parame
2e260 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
2e270 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
2e280 33 5f 62 69 6e 64 28 29 5d 2e 20 20 5e 41 20 7a  3_bind()].  ^A z
2e290 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e  ero.** is return
2e2a0 65 64 20 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e  ed if no matchin
2e2b0 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 66  g parameter is f
2e2c0 6f 75 6e 64 2e 20 20 5e 54 68 65 20 70 61 72 61  ound.  ^The para
2e2d0 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75  meter.** name mu
2e2e0 73 74 20 62 65 20 67 69 76 65 6e 20 69 6e 20 55  st be given in U
2e2f0 54 46 2d 38 20 65 76 65 6e 20 69 66 20 74 68 65  TF-8 even if the
2e300 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d   original statem
2e310 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65 70 61  ent.** was prepa
2e320 72 65 64 20 66 72 6f 6d 20 55 54 46 2d 31 36 20  red from UTF-16 
2e330 74 65 78 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  text using [sqli
2e340 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
2e350 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ()]..**.** See a
2e360 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69  lso: [sqlite3_bi
2e370 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f  nd_blob|sqlite3_
2e380 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  bind()],.** [sql
2e390 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
2e3a0 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e  ter_count()], an
2e3b0 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  d.** [sqlite3_bi
2e3c0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
2e3d0 65 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  e()]..*/.SQLITE_
2e3e0 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  API int SQLITE_S
2e3f0 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62  TDCALL sqlite3_b
2e400 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
2e410 64 65 78 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  dex(sqlite3_stmt
2e420 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
2e430 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Name);../*.** CA
2e440 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 6c  PI3REF: Reset Al
2e450 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20  l Bindings On A 
2e460 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
2e470 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  nt.** METHOD: sq
2e480 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
2e490 20 5e 43 6f 6e 74 72 61 72 79 20 74 6f 20 74 68   ^Contrary to th
2e4a0 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d  e intuition of m
2e4b0 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65  any, [sqlite3_re
2e4c0 73 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20  set()] does not 
2e4d0 72 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71  reset.** the [sq
2e4e0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20  lite3_bind_blob 
2e4f0 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61  | bindings] on a
2e500 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2e510 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74  ment]..** ^Use t
2e520 68 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 72  his routine to r
2e530 65 73 65 74 20 61 6c 6c 20 68 6f 73 74 20 70 61  eset all host pa
2e540 72 61 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c  rameters to NULL
2e550 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
2e560 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41  int SQLITE_STDCA
2e570 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6c 65 61 72  LL sqlite3_clear
2e580 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65  _bindings(sqlite
2e590 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  3_stmt*);../*.**
2e5a0 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65   CAPI3REF: Numbe
2e5b0 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20  r Of Columns In 
2e5c0 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 20  A Result Set.** 
2e5d0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
2e5e0 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75  stmt.**.** ^Retu
2e5f0 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  rn the number of
2e600 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20   columns in the 
2e610 72 65 73 75 6c 74 20 73 65 74 20 72 65 74 75 72  result set retur
2e620 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70  ned by the.** [p
2e630 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2e640 74 5d 2e 20 5e 54 68 69 73 20 72 6f 75 74 69 6e  t]. ^This routin
2e650 65 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 70  e returns 0 if p
2e660 53 74 6d 74 20 69 73 20 61 6e 20 53 51 4c 0a 2a  Stmt is an SQL.*
2e670 2a 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74  * statement that
2e680 20 64 6f 65 73 20 6e 6f 74 20 72 65 74 75 72 6e   does not return
2e690 20 64 61 74 61 20 28 66 6f 72 20 65 78 61 6d 70   data (for examp
2e6a0 6c 65 20 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e  le an [UPDATE]).
2e6b0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
2e6c0 20 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63   [sqlite3_data_c
2e6d0 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 53 51 4c 49 54  ount()].*/.SQLIT
2e6e0 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45  E_API int SQLITE
2e6f0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
2e700 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71  _column_count(sq
2e710 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
2e720 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
2e730 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65  REF: Column Name
2e740 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65  s In A Result Se
2e750 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  t.** METHOD: sql
2e760 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
2e770 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
2e780 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20  return the name 
2e790 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20 70 61  assigned to a pa
2e7a0 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a  rticular column.
2e7b0 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74  ** in the result
2e7c0 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43   set of a [SELEC
2e7d0 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e  T] statement.  ^
2e7e0 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  The sqlite3_colu
2e7f0 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74  mn_name().** int
2e800 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
2e810 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65   pointer to a ze
2e820 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
2e830 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e  F-8 string.** an
2e840 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
2e850 5f 6e 61 6d 65 31 36 28 29 20 72 65 74 75 72 6e  _name16() return
2e860 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
2e870 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
2e880 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e  .** UTF-16 strin
2e890 67 2e 20 20 5e 54 68 65 20 66 69 72 73 74 20 70  g.  ^The first p
2e8a0 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
2e8b0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2e8c0 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70  ent].** that imp
2e8d0 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b 53 45 4c  lements the [SEL
2e8e0 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20  ECT] statement. 
2e8f0 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61  ^The second para
2e900 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20  meter is the.** 
2e910 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20  column number.  
2e920 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f  ^The leftmost co
2e930 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20 30  lumn is number 0
2e940 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74  ..**.** ^The ret
2e950 75 72 6e 65 64 20 73 74 72 69 6e 67 20 70 6f 69  urned string poi
2e960 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20 75 6e  nter is valid un
2e970 74 69 6c 20 65 69 74 68 65 72 20 74 68 65 20 5b  til either the [
2e980 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2e990 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f  nt].** is destro
2e9a0 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  yed by [sqlite3_
2e9b0 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75  finalize()] or u
2e9c0 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65  ntil the stateme
2e9d0 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61  nt is automatica
2e9e0 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65  lly.** reprepare
2e9f0 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 63  d by the first c
2ea00 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
2ea10 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61  step()] for a pa
2ea20 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20  rticular run.** 
2ea30 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78  or until the nex
2ea40 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c  t call to.** sql
2ea50 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
2ea60 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f  () or sqlite3_co
2ea70 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e  lumn_name16() on
2ea80 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e   the same column
2ea90 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c 69  ..**.** ^If sqli
2eaa0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69  te3_malloc() fai
2eab0 6c 73 20 64 75 72 69 6e 67 20 74 68 65 20 70 72  ls during the pr
2eac0 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 69 74 68  ocessing of eith
2ead0 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66  er routine.** (f
2eae0 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 72 69 6e  or example durin
2eaf0 67 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66  g a conversion f
2eb00 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 54 46  rom UTF-8 to UTF
2eb10 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e  -16) then a.** N
2eb20 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72  ULL pointer is r
2eb30 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  eturned..**.** ^
2eb40 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 72 65  The name of a re
2eb50 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74  sult column is t
2eb60 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  he value of the 
2eb70 22 41 53 22 20 63 6c 61 75 73 65 20 66 6f 72 0a  "AS" clause for.
2eb80 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20  ** that column, 
2eb90 69 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 41  if there is an A
2eba0 53 20 63 6c 61 75 73 65 2e 20 20 49 66 20 74 68  S clause.  If th
2ebb0 65 72 65 20 69 73 20 6e 6f 20 41 53 20 63 6c 61  ere is no AS cla
2ebc0 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  use.** then the 
2ebd0 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 75  name of the colu
2ebe0 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 66 69 65  mn is unspecifie
2ebf0 64 20 61 6e 64 20 6d 61 79 20 63 68 61 6e 67 65  d and may change
2ec00 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c   from.** one rel
2ec10 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20 74  ease of SQLite t
2ec20 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a 53  o the next..*/.S
2ec30 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
2ec40 63 68 61 72 20 2a 53 51 4c 49 54 45 5f 53 54 44  char *SQLITE_STD
2ec50 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c  CALL sqlite3_col
2ec60 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  umn_name(sqlite3
2ec70 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a  _stmt*, int N);.
2ec80 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
2ec90 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54   void *SQLITE_ST
2eca0 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f  DCALL sqlite3_co
2ecb0 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69  lumn_name16(sqli
2ecc0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e  te3_stmt*, int N
2ecd0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2ece0 45 46 3a 20 53 6f 75 72 63 65 20 4f 66 20 44 61  EF: Source Of Da
2ecf0 74 61 20 49 6e 20 41 20 51 75 65 72 79 20 52 65  ta In A Query Re
2ed00 73 75 6c 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  sult.** METHOD: 
2ed10 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
2ed20 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
2ed30 65 73 20 70 72 6f 76 69 64 65 20 61 20 6d 65 61  es provide a mea
2ed40 6e 73 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20  ns to determine 
2ed50 74 68 65 20 64 61 74 61 62 61 73 65 2c 20 74 61  the database, ta
2ed60 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74 61 62 6c  ble, and.** tabl
2ed70 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73  e column that is
2ed80 20 74 68 65 20 6f 72 69 67 69 6e 20 6f 66 20 61   the origin of a
2ed90 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 73 75   particular resu
2eda0 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20  lt column in.** 
2edb0 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
2edc0 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65  nt..** ^The name
2edd0 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
2ede0 20 6f 72 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c   or table or col
2edf0 75 6d 6e 20 63 61 6e 20 62 65 20 72 65 74 75 72  umn can be retur
2ee00 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74 68 65 72  ned as.** either
2ee10 20 61 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d   a UTF-8 or UTF-
2ee20 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65  16 string.  ^The
2ee30 20 5f 64 61 74 61 62 61 73 65 5f 20 72 6f 75 74   _database_ rout
2ee40 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74  ines return.** t
2ee50 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65  he database name
2ee60 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f  , the _table_ ro
2ee70 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68  utines return th
2ee80 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e  e table name, an
2ee90 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f  d.** the origin_
2eea0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
2eeb0 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65   the column name
2eec0 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e  ..** ^The return
2eed0 65 64 20 73 74 72 69 6e 67 20 69 73 20 76 61 6c  ed string is val
2eee0 69 64 20 75 6e 74 69 6c 20 74 68 65 20 5b 70 72  id until the [pr
2eef0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2ef00 5d 20 69 73 20 64 65 73 74 72 6f 79 65 64 0a 2a  ] is destroyed.*
2ef10 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  * using [sqlite3
2ef20 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20  _finalize()] or 
2ef30 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d  until the statem
2ef40 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63  ent is automatic
2ef50 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72  ally.** reprepar
2ef60 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20  ed by the first 
2ef70 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
2ef80 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70  _step()] for a p
2ef90 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a  articular run.**
2efa0 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 61   or until the sa
2efb0 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  me information i
2efc0 73 20 72 65 71 75 65 73 74 65 64 0a 2a 2a 20 61  s requested.** a
2efd0 67 61 69 6e 20 69 6e 20 61 20 64 69 66 66 65 72  gain in a differ
2efe0 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a  ent encoding..**
2eff0 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 73 20 72  .** ^The names r
2f000 65 74 75 72 6e 65 64 20 61 72 65 20 74 68 65 20  eturned are the 
2f010 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61  original un-alia
2f020 73 65 64 20 6e 61 6d 65 73 20 6f 66 20 74 68 65  sed names of the
2f030 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c 20 74 61  .** database, ta
2f040 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e  ble, and column.
2f050 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
2f060 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
2f070 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 69  ese interfaces i
2f080 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  s a [prepared st
2f090 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68  atement]..** ^Th
2f0a0 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65  ese functions re
2f0b0 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  turn information
2f0c0 20 61 62 6f 75 74 20 74 68 65 20 4e 74 68 20 72   about the Nth r
2f0d0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 72 65 74  esult column ret
2f0e0 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65 20  urned by.** the 
2f0f0 73 74 61 74 65 6d 65 6e 74 2c 20 77 68 65 72 65  statement, where
2f100 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64   N is the second
2f110 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65   function argume
2f120 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74  nt..** ^The left
2f130 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20  -most column is 
2f140 63 6f 6c 75 6d 6e 20 30 20 66 6f 72 20 74 68 65  column 0 for the
2f150 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a  se routines..**.
2f160 2a 2a 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63  ** ^If the Nth c
2f170 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62  olumn returned b
2f180 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  y the statement 
2f190 69 73 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e  is an expression
2f1a0 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72 79 20   or.** subquery 
2f1b0 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c  and is not a col
2f1c0 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e 20  umn value, then 
2f1d0 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 66 75 6e  all of these fun
2f1e0 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a 2a  ctions return.**
2f1f0 20 4e 55 4c 4c 2e 20 20 5e 54 68 65 73 65 20 72   NULL.  ^These r
2f200 6f 75 74 69 6e 65 20 6d 69 67 68 74 20 61 6c 73  outine might als
2f210 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66  o return NULL if
2f220 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
2f230 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f 63  tion error.** oc
2f240 63 75 72 73 2e 20 20 5e 4f 74 68 65 72 77 69 73  curs.  ^Otherwis
2f250 65 2c 20 74 68 65 79 20 72 65 74 75 72 6e 20 74  e, they return t
2f260 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 61  he name of the a
2f270 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65  ttached database
2f280 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63  , table,.** or c
2f290 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75 65 72 79  olumn that query
2f2a0 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77   result column w
2f2b0 61 73 20 65 78 74 72 61 63 74 65 64 20 66 72 6f  as extracted fro
2f2c0 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69 74  m..**.** ^As wit
2f2d0 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69  h all other SQLi
2f2e0 74 65 20 41 50 49 73 2c 20 74 68 6f 73 65 20 77  te APIs, those w
2f2f0 68 6f 73 65 20 6e 61 6d 65 73 20 65 6e 64 20 77  hose names end w
2f300 69 74 68 20 22 31 36 22 20 72 65 74 75 72 6e 0a  ith "16" return.
2f310 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65  ** UTF-16 encode
2f320 64 20 73 74 72 69 6e 67 73 20 61 6e 64 20 74 68  d strings and th
2f330 65 20 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e  e other function
2f340 73 20 72 65 74 75 72 6e 20 55 54 46 2d 38 2e 0a  s return UTF-8..
2f350 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 41 50 49  **.** ^These API
2f360 73 20 61 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c  s are only avail
2f370 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72  able if the libr
2f380 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64  ary was compiled
2f390 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51   with the.** [SQ
2f3a0 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55  LITE_ENABLE_COLU
2f3b0 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70  MN_METADATA] C-p
2f3c0 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62  reprocessor symb
2f3d0 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f  ol..**.** If two
2f3e0 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73   or more threads
2f3f0 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72   call one or mor
2f400 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  e of these routi
2f410 6e 65 73 20 61 67 61 69 6e 73 74 20 74 68 65 20  nes against the 
2f420 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65 64  same.** prepared
2f430 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63   statement and c
2f440 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20 73 61 6d  olumn at the sam
2f450 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20  e time then the 
2f460 72 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75  results are.** u
2f470 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
2f480 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74  If two or more t
2f490 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20  hreads call one 
2f4a0 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69  or more.** [sqli
2f4b0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62  te3_column_datab
2f4c0 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d  ase_name | colum
2f4d0 6e 20 6d 65 74 61 64 61 74 61 20 69 6e 74 65 72  n metadata inter
2f4e0 66 61 63 65 73 5d 0a 2a 2a 20 66 6f 72 20 74 68  faces].** for th
2f4f0 65 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64  e same [prepared
2f500 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20   statement] and 
2f510 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a  result column.**
2f520 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d   at the same tim
2f530 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c  e then the resul
2f540 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64  ts are undefined
2f550 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
2f560 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51 4c 49  const char *SQLI
2f570 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
2f580 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61  e3_column_databa
2f590 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f  se_name(sqlite3_
2f5a0 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49  stmt*,int);.SQLI
2f5b0 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69  TE_API const voi
2f5c0 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  d *SQLITE_STDCAL
2f5d0 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  L sqlite3_column
2f5e0 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36  _database_name16
2f5f0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
2f600 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  nt);.SQLITE_API 
2f610 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51 4c 49  const char *SQLI
2f620 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
2f630 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f  e3_column_table_
2f640 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
2f650 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f  t*,int);.SQLITE_
2f660 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  API const void *
2f670 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
2f680 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61  qlite3_column_ta
2f690 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  ble_name16(sqlit
2f6a0 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53  e3_stmt*,int);.S
2f6b0 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
2f6c0 63 68 61 72 20 2a 53 51 4c 49 54 45 5f 53 54 44  char *SQLITE_STD
2f6d0 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c  CALL sqlite3_col
2f6e0 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28  umn_origin_name(
2f6f0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
2f700 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  t);.SQLITE_API c
2f710 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51 4c 49 54  onst void *SQLIT
2f720 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
2f730 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f  3_column_origin_
2f740 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73  name16(sqlite3_s
2f750 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  tmt*,int);../*.*
2f760 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c  * CAPI3REF: Decl
2f770 61 72 65 64 20 44 61 74 61 74 79 70 65 20 4f 66  ared Datatype Of
2f780 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a   A Query Result.
2f790 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
2f7a0 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28  e3_stmt.**.** ^(
2f7b0 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
2f7c0 74 65 72 20 69 73 20 61 20 5b 70 72 65 70 61 72  ter is a [prepar
2f7d0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
2f7e0 2a 20 49 66 20 74 68 69 73 20 73 74 61 74 65 6d  * If this statem
2f7f0 65 6e 74 20 69 73 20 61 20 5b 53 45 4c 45 43 54  ent is a [SELECT
2f800 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20  ] statement and 
2f810 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f  the Nth column o
2f820 66 20 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65  f the.** returne
2f830 64 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  d result set of 
2f840 74 68 61 74 20 5b 53 45 4c 45 43 54 5d 20 69 73  that [SELECT] is
2f850 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20   a table column 
2f860 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65  (not an.** expre
2f870 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72  ssion or subquer
2f880 79 29 20 74 68 65 6e 20 74 68 65 20 64 65 63 6c  y) then the decl
2f890 61 72 65 64 20 74 79 70 65 20 6f 66 20 74 68 65  ared type of the
2f8a0 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e   table.** column
2f8b0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20   is returned.)^ 
2f8c0 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c   ^If the Nth col
2f8d0 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c  umn of the resul
2f8e0 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65  t set is an.** e
2f8f0 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62  xpression or sub
2f900 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e 55  query, then a NU
2f910 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65  LL pointer is re
2f920 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20  turned..** ^The 
2f930 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20  returned string 
2f940 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20  is always UTF-8 
2f950 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  encoded..**.** ^
2f960 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67 69  (For example, gi
2f970 76 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  ven the database
2f980 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43   schema:.**.** C
2f990 52 45 41 54 45 20 54 41 42 4c 45 20 74 31 28 63  REATE TABLE t1(c
2f9a0 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a  1 VARIANT);.**.*
2f9b0 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77  * and the follow
2f9c0 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  ing statement to
2f9d0 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a   be compiled:.**
2f9e0 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31 20 2b 20  .** SELECT c1 + 
2f9f0 31 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a  1, c1 FROM t1;.*
2fa00 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e  *.** this routin
2fa10 65 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20 74  e would return t
2fa20 68 65 20 73 74 72 69 6e 67 20 22 56 41 52 49 41  he string "VARIA
2fa30 4e 54 22 20 66 6f 72 20 74 68 65 20 73 65 63 6f  NT" for the seco
2fa40 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c  nd result.** col
2fa50 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20  umn (i==1), and 
2fa60 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66  a NULL pointer f
2fa70 6f 72 20 74 68 65 20 66 69 72 73 74 20 72 65 73  or the first res
2fa80 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30  ult column (i==0
2fa90 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69  ).)^.**.** ^SQLi
2faa0 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20  te uses dynamic 
2fab0 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e  run-time typing.
2fac0 20 20 5e 53 6f 20 6a 75 73 74 20 62 65 63 61 75    ^So just becau
2fad0 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69  se a column.** i
2fae0 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f  s declared to co
2faf0 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c  ntain a particul
2fb00 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74  ar type does not
2fb10 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a   mean that the.*
2fb20 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e  * data stored in
2fb30 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20   that column is 
2fb40 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65 64 20  of the declared 
2fb50 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73  type.  SQLite is
2fb60 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70  .** strongly typ
2fb70 65 64 2c 20 62 75 74 20 74 68 65 20 74 79 70 69  ed, but the typi
2fb80 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f  ng is dynamic no
2fb90 74 20 73 74 61 74 69 63 2e 20 20 5e 54 79 70 65  t static.  ^Type
2fba0 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65  .** is associate
2fbb0 64 20 77 69 74 68 20 69 6e 64 69 76 69 64 75 61  d with individua
2fbc0 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69  l values, not wi
2fbd0 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72  th the container
2fbe0 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c  s.** used to hol
2fbf0 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a  d those values..
2fc00 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  */.SQLITE_API co
2fc10 6e 73 74 20 63 68 61 72 20 2a 53 51 4c 49 54 45  nst char *SQLITE
2fc20 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
2fc30 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65  _column_decltype
2fc40 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
2fc50 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  nt);.SQLITE_API 
2fc60 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51 4c 49  const void *SQLI
2fc70 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
2fc80 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79  e3_column_declty
2fc90 70 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  pe16(sqlite3_stm
2fca0 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  t*,int);../*.** 
2fcb0 43 41 50 49 33 52 45 46 3a 20 45 76 61 6c 75 61  CAPI3REF: Evalua
2fcc0 74 65 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d  te An SQL Statem
2fcd0 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ent.** METHOD: s
2fce0 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
2fcf0 2a 20 41 66 74 65 72 20 61 20 5b 70 72 65 70 61  * After a [prepa
2fd00 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 68  red statement] h
2fd10 61 73 20 62 65 65 6e 20 70 72 65 70 61 72 65 64  as been prepared
2fd20 20 75 73 69 6e 67 20 65 69 74 68 65 72 0a 2a 2a   using either.**
2fd30 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2fd40 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69  e_v2()] or [sqli
2fd50 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
2fd60 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68  ()] or one of th
2fd70 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65  e legacy.** inte
2fd80 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f  rfaces [sqlite3_
2fd90 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 5b 73  prepare()] or [s
2fda0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2fdb0 28 29 5d 2c 20 74 68 69 73 20 66 75 6e 63 74 69  ()], this functi
2fdc0 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 20 63 61  on.** must be ca
2fdd0 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  lled one or more
2fde0 20 74 69 6d 65 73 20 74 6f 20 65 76 61 6c 75 61   times to evalua
2fdf0 74 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  te the statement
2fe00 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61  ..**.** The deta
2fe10 69 6c 73 20 6f 66 20 74 68 65 20 62 65 68 61 76  ils of the behav
2fe20 69 6f 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74  ior of the sqlit
2fe30 65 33 5f 73 74 65 70 28 29 20 69 6e 74 65 72 66  e3_step() interf
2fe40 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e  ace depend.** on
2fe50 20 77 68 65 74 68 65 72 20 74 68 65 20 73 74 61   whether the sta
2fe60 74 65 6d 65 6e 74 20 77 61 73 20 70 72 65 70 61  tement was prepa
2fe70 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 6e 65  red using the ne
2fe80 77 65 72 20 22 76 32 22 20 69 6e 74 65 72 66 61  wer "v2" interfa
2fe90 63 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  ce.** [sqlite3_p
2fea0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
2feb0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2fec0 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 74 68 65  e16_v2()] or the
2fed0 20 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a   older legacy.**
2fee0 20 69 6e 74 65 72 66 61 63 65 20 5b 73 71 6c 69   interface [sqli
2fef0 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61  te3_prepare()] a
2ff00 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  nd [sqlite3_prep
2ff10 61 72 65 31 36 28 29 5d 2e 20 20 54 68 65 20 75  are16()].  The u
2ff20 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77  se of the.** new
2ff30 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 20   "v2" interface 
2ff40 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66  is recommended f
2ff50 6f 72 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69  or new applicati
2ff60 6f 6e 73 20 62 75 74 20 74 68 65 20 6c 65 67 61  ons but the lega
2ff70 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  cy.** interface 
2ff80 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f  will continue to
2ff90 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a   be supported..*
2ffa0 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 6c 65 67  *.** ^In the leg
2ffb0 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74  acy interface, t
2ffc0 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
2ffd0 77 69 6c 6c 20 62 65 20 65 69 74 68 65 72 20 5b  will be either [
2ffe0 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a  SQLITE_BUSY],.**
2fff0 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20   [SQLITE_DONE], 
30000 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b 53  [SQLITE_ROW], [S
30010 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f 72  QLITE_ERROR], or
30020 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
30030 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 22  ..** ^With the "
30040 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 20 61  v2" interface, a
30050 6e 79 20 6f 66 20 74 68 65 20 6f 74 68 65 72 20  ny of the other 
30060 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6f  [result codes] o
30070 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72  r.** [extended r
30080 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6d 69 67  esult codes] mig
30090 68 74 20 62 65 20 72 65 74 75 72 6e 65 64 20 61  ht be returned a
300a0 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b  s well..**.** ^[
300b0 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65 61  SQLITE_BUSY] mea
300c0 6e 73 20 74 68 61 74 20 74 68 65 20 64 61 74 61  ns that the data
300d0 62 61 73 65 20 65 6e 67 69 6e 65 20 77 61 73 20  base engine was 
300e0 75 6e 61 62 6c 65 20 74 6f 20 61 63 71 75 69 72  unable to acquir
300f0 65 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  e the.** databas
30100 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64 73  e locks it needs
30110 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e 20   to do its job. 
30120 20 5e 49 66 20 74 68 65 20 73 74 61 74 65 6d 65   ^If the stateme
30130 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d 49 54 5d  nt is a [COMMIT]
30140 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f 75  .** or occurs ou
30150 74 73 69 64 65 20 6f 66 20 61 6e 20 65 78 70 6c  tside of an expl
30160 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e  icit transaction
30170 2c 20 74 68 65 6e 20 79 6f 75 20 63 61 6e 20 72  , then you can r
30180 65 74 72 79 20 74 68 65 0a 2a 2a 20 73 74 61 74  etry the.** stat
30190 65 6d 65 6e 74 2e 20 20 49 66 20 74 68 65 20 73  ement.  If the s
301a0 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20  tatement is not 
301b0 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f  a [COMMIT] and o
301c0 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 6e 0a  ccurs within an.
301d0 2a 2a 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e  ** explicit tran
301e0 73 61 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f 75  saction then you
301f0 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 6b   should rollback
30200 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   the transaction
30210 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69   before.** conti
30220 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53  nuing..**.** ^[S
30230 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e  QLITE_DONE] mean
30240 73 20 74 68 61 74 20 74 68 65 20 73 74 61 74 65  s that the state
30250 6d 65 6e 74 20 68 61 73 20 66 69 6e 69 73 68 65  ment has finishe
30260 64 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20 73  d executing.** s
30270 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 73 71  uccessfully.  sq
30280 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f  lite3_step() sho
30290 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65  uld not be calle
302a0 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 69 73 20  d again on this 
302b0 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69  virtual.** machi
302c0 6e 65 20 77 69 74 68 6f 75 74 20 66 69 72 73 74  ne without first
302d0 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
302e0 33 5f 72 65 73 65 74 28 29 5d 20 74 6f 20 72 65  3_reset()] to re
302f0 73 65 74 20 74 68 65 20 76 69 72 74 75 61 6c 0a  set the virtual.
30300 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61 63 6b 20  ** machine back 
30310 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73  to its initial s
30320 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  tate..**.** ^If 
30330 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
30340 74 20 62 65 69 6e 67 20 65 78 65 63 75 74 65 64  t being executed
30350 20 72 65 74 75 72 6e 73 20 61 6e 79 20 64 61 74   returns any dat
30360 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f  a, then [SQLITE_
30370 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72  ROW].** is retur
30380 6e 65 64 20 65 61 63 68 20 74 69 6d 65 20 61 20  ned each time a 
30390 6e 65 77 20 72 6f 77 20 6f 66 20 64 61 74 61 20  new row of data 
303a0 69 73 20 72 65 61 64 79 20 66 6f 72 20 70 72 6f  is ready for pro
303b0 63 65 73 73 69 6e 67 20 62 79 20 74 68 65 0a 2a  cessing by the.*
303c0 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65 20 76 61  * caller. The va
303d0 6c 75 65 73 20 6d 61 79 20 62 65 20 61 63 63 65  lues may be acce
303e0 73 73 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b  ssed using the [
303f0 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75  column access fu
30400 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c  nctions]..** sql
30410 69 74 65 33 5f 73 74 65 70 28 29 20 69 73 20 63  ite3_step() is c
30420 61 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f 20 72  alled again to r
30430 65 74 72 69 65 76 65 20 74 68 65 20 6e 65 78 74  etrieve the next
30440 20 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a   row of data..**
30450 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 45 52 52  .** ^[SQLITE_ERR
30460 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 61  OR] means that a
30470 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20   run-time error 
30480 28 73 75 63 68 20 61 73 20 61 20 63 6f 6e 73 74  (such as a const
30490 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69  raint.** violati
304a0 6f 6e 29 20 68 61 73 20 6f 63 63 75 72 72 65 64  on) has occurred
304b0 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  .  sqlite3_step(
304c0 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20  ) should not be 
304d0 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a  called again on.
304e0 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20  ** the VM. More 
304f0 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20  information may 
30500 62 65 20 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c  be found by call
30510 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  ing [sqlite3_err
30520 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57 69 74 68  msg()]..** ^With
30530 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65   the legacy inte
30540 72 66 61 63 65 2c 20 61 20 6d 6f 72 65 20 73 70  rface, a more sp
30550 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64  ecific error cod
30560 65 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a  e (for example,.
30570 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52  ** [SQLITE_INTER
30580 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53  RUPT], [SQLITE_S
30590 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f  CHEMA], [SQLITE_
305a0 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f  CORRUPT], and so
305b0 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62   forth).** can b
305c0 65 20 6f 62 74 61 69 6e 65 64 20 62 79 20 63 61  e obtained by ca
305d0 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  lling [sqlite3_r
305e0 65 73 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a  eset()] on the.*
305f0 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
30600 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20 74 68 65  ement].  ^In the
30610 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c   "v2" interface,
30620 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 70 65  .** the more spe
30630 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65  cific error code
30640 20 69 73 20 72 65 74 75 72 6e 65 64 20 64 69 72   is returned dir
30650 65 63 74 6c 79 20 62 79 20 73 71 6c 69 74 65 33  ectly by sqlite3
30660 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b  _step()..**.** [
30670 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d  SQLITE_MISUSE] m
30680 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 74 68  eans that the th
30690 69 73 20 72 6f 75 74 69 6e 65 20 77 61 73 20 63  is routine was c
306a0 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70 72 69  alled inappropri
306b0 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70  ately..** Perhap
306c0 73 20 69 74 20 77 61 73 20 63 61 6c 6c 65 64 20  s it was called 
306d0 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  on a [prepared s
306e0 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68  tatement] that h
306f0 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62 65  as.** already be
30700 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  en [sqlite3_fina
30710 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64  lize | finalized
30720 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74  ] or on one that
30730 20 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f 75 73   had.** previous
30740 6c 79 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c  ly returned [SQL
30750 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53  ITE_ERROR] or [S
30760 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72  QLITE_DONE].  Or
30770 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20   it could.** be 
30780 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68  the case that th
30790 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
307a0 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62 65  connection is be
307b0 69 6e 67 20 75 73 65 64 20 62 79 20 74 77 6f 20  ing used by two 
307c0 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61  or.** more threa
307d0 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 6d  ds at the same m
307e0 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a  oment in time..*
307f0 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20 76 65 72  *.** For all ver
30800 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20  sions of SQLite 
30810 75 70 20 74 6f 20 61 6e 64 20 69 6e 63 6c 75 64  up to and includ
30820 69 6e 67 20 33 2e 36 2e 32 33 2e 31 2c 20 61 20  ing 3.6.23.1, a 
30830 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
30840 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77 61 73  te3_reset()] was
30850 20 72 65 71 75 69 72 65 64 20 61 66 74 65 72 20   required after 
30860 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 72  sqlite3_step() r
30870 65 74 75 72 6e 65 64 20 61 6e 79 74 68 69 6e 67  eturned anything
30880 0a 2a 2a 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  .** other than [
30890 53 51 4c 49 54 45 5f 52 4f 57 5d 20 62 65 66 6f  SQLITE_ROW] befo
308a0 72 65 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e  re any subsequen
308b0 74 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 0a  t invocation of.
308c0 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  ** sqlite3_step(
308d0 29 2e 20 20 46 61 69 6c 75 72 65 20 74 6f 20 72  ).  Failure to r
308e0 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65  eset the prepare
308f0 64 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e  d statement usin
30900 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  g .** [sqlite3_r
30910 65 73 65 74 28 29 5d 20 77 6f 75 6c 64 20 72 65  eset()] would re
30920 73 75 6c 74 20 69 6e 20 61 6e 20 5b 53 51 4c 49  sult in an [SQLI
30930 54 45 5f 4d 49 53 55 53 45 5d 20 72 65 74 75 72  TE_MISUSE] retur
30940 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65  n from.** sqlite
30950 33 5f 73 74 65 70 28 29 2e 20 20 42 75 74 20 61  3_step().  But a
30960 66 74 65 72 20 76 65 72 73 69 6f 6e 20 33 2e 36  fter version 3.6
30970 2e 32 33 2e 31 2c 20 73 71 6c 69 74 65 33 5f 73  .23.1, sqlite3_s
30980 74 65 70 28 29 20 62 65 67 61 6e 0a 2a 2a 20 63  tep() began.** c
30990 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
309a0 72 65 73 65 74 28 29 5d 20 61 75 74 6f 6d 61 74  reset()] automat
309b0 69 63 61 6c 6c 79 20 69 6e 20 74 68 69 73 20 63  ically in this c
309c0 69 72 63 75 6d 73 74 61 6e 63 65 20 72 61 74 68  ircumstance rath
309d0 65 72 0a 2a 2a 20 74 68 61 6e 20 72 65 74 75 72  er.** than retur
309e0 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 4d 49 53  ning [SQLITE_MIS
309f0 55 53 45 5d 2e 20 20 54 68 69 73 20 69 73 20 6e  USE].  This is n
30a00 6f 74 20 63 6f 6e 73 69 64 65 72 65 64 20 61 20  ot considered a 
30a10 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 0a 2a 2a  compatibility.**
30a20 20 62 72 65 61 6b 20 62 65 63 61 75 73 65 20 61   break because a
30a30 6e 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74  ny application t
30a40 68 61 74 20 65 76 65 72 20 72 65 63 65 69 76 65  hat ever receive
30a50 73 20 61 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55  s an SQLITE_MISU
30a60 53 45 20 65 72 72 6f 72 0a 2a 2a 20 69 73 20 62  SE error.** is b
30a70 72 6f 6b 65 6e 20 62 79 20 64 65 66 69 6e 69 74  roken by definit
30a80 69 6f 6e 2e 20 20 54 68 65 20 5b 53 51 4c 49 54  ion.  The [SQLIT
30a90 45 5f 4f 4d 49 54 5f 41 55 54 4f 52 45 53 45 54  E_OMIT_AUTORESET
30aa0 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
30ab0 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20 62 65 20  ption.** can be 
30ac0 75 73 65 64 20 74 6f 20 72 65 73 74 6f 72 65 20  used to restore 
30ad0 74 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76  the legacy behav
30ae0 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f  ior..**.** <b>Go
30af0 6f 66 79 20 49 6e 74 65 72 66 61 63 65 20 41 6c  ofy Interface Al
30b00 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 20  ert:</b> In the 
30b10 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65  legacy interface
30b20 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74  , the sqlite3_st
30b30 65 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c 77 61  ep().** API alwa
30b40 79 73 20 72 65 74 75 72 6e 73 20 61 20 67 65 6e  ys returns a gen
30b50 65 72 69 63 20 65 72 72 6f 72 20 63 6f 64 65 2c  eric error code,
30b60 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c   [SQLITE_ERROR],
30b70 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a   following any.*
30b80 2a 20 65 72 72 6f 72 20 6f 74 68 65 72 20 74 68  * error other th
30b90 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  an [SQLITE_BUSY]
30ba0 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53   and [SQLITE_MIS
30bb0 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20  USE].  You must 
30bc0 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  call.** [sqlite3
30bd0 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71  _reset()] or [sq
30be0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
30bf0 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69  ] in order to fi
30c00 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a  nd one of the.**
30c10 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72   specific [error
30c20 20 63 6f 64 65 73 5d 20 74 68 61 74 20 62 65 74   codes] that bet
30c30 74 65 72 20 64 65 73 63 72 69 62 65 73 20 74 68  ter describes th
30c40 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61  e error..** We a
30c50 64 6d 69 74 20 74 68 61 74 20 74 68 69 73 20 69  dmit that this i
30c60 73 20 61 20 67 6f 6f 66 79 20 64 65 73 69 67 6e  s a goofy design
30c70 2e 20 20 54 68 65 20 70 72 6f 62 6c 65 6d 20 68  .  The problem h
30c80 61 73 20 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a  as been fixed.**
30c90 20 77 69 74 68 20 74 68 65 20 22 76 32 22 20 69   with the "v2" i
30ca0 6e 74 65 72 66 61 63 65 2e 20 20 49 66 20 79 6f  nterface.  If yo
30cb0 75 20 70 72 65 70 61 72 65 20 61 6c 6c 20 6f 66  u prepare all of
30cc0 20 79 6f 75 72 20 53 51 4c 20 73 74 61 74 65 6d   your SQL statem
30cd0 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20 65 69  ents.** using ei
30ce0 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ther [sqlite3_pr
30cf0 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b  epare_v2()] or [
30d00 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
30d10 36 5f 76 32 28 29 5d 20 69 6e 73 74 65 61 64 0a  6_v2()] instead.
30d20 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79  ** of the legacy
30d30 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
30d40 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
30d50 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 69  3_prepare16()] i
30d60 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20 74 68  nterfaces,.** th
30d70 65 6e 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63  en the more spec
30d80 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65  ific [error code
30d90 73 5d 20 61 72 65 20 72 65 74 75 72 6e 65 64 20  s] are returned 
30da0 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73  directly.** by s
30db0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20  qlite3_step().  
30dc0 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 22  The use of the "
30dd0 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 73  v2" interface is
30de0 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f   recommended..*/
30df0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
30e00 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
30e10 71 6c 69 74 65 33 5f 73 74 65 70 28 73 71 6c 69  qlite3_step(sqli
30e20 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
30e30 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d  ** CAPI3REF: Num
30e40 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
30e50 6e 20 61 20 72 65 73 75 6c 74 20 73 65 74 0a 2a  n a result set.*
30e60 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
30e70 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  3_stmt.**.** ^Th
30e80 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63  e sqlite3_data_c
30e90 6f 75 6e 74 28 50 29 20 69 6e 74 65 72 66 61 63  ount(P) interfac
30ea0 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
30eb0 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
30ec0 69 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e  in the.** curren
30ed0 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73  t row of the res
30ee0 75 6c 74 20 73 65 74 20 6f 66 20 5b 70 72 65 70  ult set of [prep
30ef0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
30f00 50 2e 0a 2a 2a 20 5e 49 66 20 70 72 65 70 61 72  P..** ^If prepar
30f10 65 64 20 73 74 61 74 65 6d 65 6e 74 20 50 20 64  ed statement P d
30f20 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 72 65 73  oes not have res
30f30 75 6c 74 73 20 72 65 61 64 79 20 74 6f 20 72 65  ults ready to re
30f40 74 75 72 6e 0a 2a 2a 20 28 76 69 61 20 63 61 6c  turn.** (via cal
30f50 6c 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  ls to the [sqlit
30f60 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20  e3_column_int | 
30f70 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a  sqlite3_column_*
30f80 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66  ()] of.** interf
30f90 61 63 65 73 29 20 74 68 65 6e 20 73 71 6c 69 74  aces) then sqlit
30fa0 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29  e3_data_count(P)
30fb0 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a 20 5e   returns 0..** ^
30fc0 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61  The sqlite3_data
30fd0 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e  _count(P) routin
30fe0 65 20 61 6c 73 6f 20 72 65 74 75 72 6e 73 20 30  e also returns 0
30ff0 20 69 66 20 50 20 69 73 20 61 20 4e 55 4c 4c 20   if P is a NULL 
31000 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 5e 54 68 65  pointer..** ^The
31010 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
31020 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20 72  unt(P) routine r
31030 65 74 75 72 6e 73 20 30 20 69 66 20 74 68 65 20  eturns 0 if the 
31040 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f  previous call to
31050 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  .** [sqlite3_ste
31060 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64 20 5b  p](P) returned [
31070 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 5e  SQLITE_DONE].  ^
31080 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61  The sqlite3_data
31090 5f 63 6f 75 6e 74 28 50 29 0a 2a 2a 20 77 69 6c  _count(P).** wil
310a0 6c 20 72 65 74 75 72 6e 20 6e 6f 6e 2d 7a 65 72  l return non-zer
310b0 6f 20 69 66 20 70 72 65 76 69 6f 75 73 20 63 61  o if previous ca
310c0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
310d0 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64  tep](P) returned
310e0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  .** [SQLITE_ROW]
310f0 2c 20 65 78 63 65 70 74 20 69 6e 20 74 68 65 20  , except in the 
31100 63 61 73 65 20 6f 66 20 74 68 65 20 5b 50 52 41  case of the [PRA
31110 47 4d 41 20 69 6e 63 72 65 6d 65 6e 74 61 6c 5f  GMA incremental_
31120 76 61 63 75 75 6d 5d 0a 2a 2a 20 77 68 65 72 65  vacuum].** where
31130 20 69 74 20 61 6c 77 61 79 73 20 72 65 74 75 72   it always retur
31140 6e 73 20 7a 65 72 6f 20 73 69 6e 63 65 20 65 61  ns zero since ea
31150 63 68 20 73 74 65 70 20 6f 66 20 74 68 61 74 20  ch step of that 
31160 6d 75 6c 74 69 2d 73 74 65 70 0a 2a 2a 20 70 72  multi-step.** pr
31170 61 67 6d 61 20 72 65 74 75 72 6e 73 20 30 20 63  agma returns 0 c
31180 6f 6c 75 6d 6e 73 20 6f 66 20 64 61 74 61 2e 0a  olumns of data..
31190 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
311a0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
311b0 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 53 51 4c 49  count()].*/.SQLI
311c0 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54  TE_API int SQLIT
311d0 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
311e0 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c  3_data_count(sql
311f0 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
31200 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
31210 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20  EF: Fundamental 
31220 44 61 74 61 74 79 70 65 73 0a 2a 2a 20 4b 45 59  Datatypes.** KEY
31230 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 45  WORDS: SQLITE_TE
31240 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72 79  XT.**.** ^(Every
31250 20 76 61 6c 75 65 20 69 6e 20 53 51 4c 69 74 65   value in SQLite
31260 20 68 61 73 20 6f 6e 65 20 6f 66 20 66 69 76 65   has one of five
31270 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74   fundamental dat
31280 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  atypes:.**.** <u
31290 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69  l>.** <li> 64-bi
312a0 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
312b0 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20  .** <li> 64-bit 
312c0 49 45 45 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f  IEEE floating po
312d0 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c  int number.** <l
312e0 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69  i> string.** <li
312f0 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e  > BLOB.** <li> N
31300 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a  ULL.** </ul>)^.*
31310 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
31320 61 6e 74 73 20 61 72 65 20 63 6f 64 65 73 20 66  ants are codes f
31330 6f 72 20 65 61 63 68 20 6f 66 20 74 68 6f 73 65  or each of those
31340 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f   types..**.** No
31350 74 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 49  te that the SQLI
31360 54 45 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e 74  TE_TEXT constant
31370 20 77 61 73 20 61 6c 73 6f 20 75 73 65 64 20 69   was also used i
31380 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  n SQLite version
31390 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70   2.** for a comp
313a0 6c 65 74 65 6c 79 20 64 69 66 66 65 72 65 6e 74  letely different
313b0 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77   meaning.  Softw
313c0 61 72 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 61  are that links a
313d0 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53  gainst both.** S
313e0 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 20  QLite version 2 
313f0 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73 69  and SQLite versi
31400 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75 73 65 20  on 3 should use 
31410 53 51 4c 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f  SQLITE3_TEXT, no
31420 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58 54  t.** SQLITE_TEXT
31430 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
31440 49 54 45 5f 49 4e 54 45 47 45 52 20 20 31 0a 23  ITE_INTEGER  1.#
31450 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c  define SQLITE_FL
31460 4f 41 54 20 20 20 20 32 0a 23 64 65 66 69 6e 65  OAT    2.#define
31470 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20   SQLITE_BLOB    
31480 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   4.#define SQLIT
31490 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69 66  E_NULL     5.#if
314a0 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a  def SQLITE_TEXT.
314b0 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 54  # undef SQLITE_T
314c0 45 58 54 0a 23 65 6c 73 65 0a 23 20 64 65 66 69  EXT.#else.# defi
314d0 6e 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 20  ne SQLITE_TEXT  
314e0 20 20 20 33 0a 23 65 6e 64 69 66 0a 23 64 65 66     3.#endif.#def
314f0 69 6e 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54  ine SQLITE3_TEXT
31500 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41       3../*.** CA
31510 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 56  PI3REF: Result V
31520 61 6c 75 65 73 20 46 72 6f 6d 20 41 20 51 75 65  alues From A Que
31530 72 79 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ry.** KEYWORDS: 
31540 7b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66  {column access f
31550 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 20 4d 45 54  unctions}.** MET
31560 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
31570 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  t.**.** ^These r
31580 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 69  outines return i
31590 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74  nformation about
315a0 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e   a single column
315b0 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a   of the current.
315c0 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 6f 66  ** result row of
315d0 20 61 20 71 75 65 72 79 2e 20 20 5e 49 6e 20 65   a query.  ^In e
315e0 76 65 72 79 20 63 61 73 65 20 74 68 65 20 66 69  very case the fi
315f0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20  rst argument is 
31600 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20  a pointer.** to 
31610 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
31620 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 73  atement] that is
31630 20 62 65 69 6e 67 20 65 76 61 6c 75 61 74 65 64   being evaluated
31640 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73   (the [sqlite3_s
31650 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61  tmt*].** that wa
31660 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20  s returned from 
31670 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
31680 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66  _v2()] or one of
31690 20 69 74 73 20 76 61 72 69 61 6e 74 73 29 0a 2a   its variants).*
316a0 2a 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64  * and the second
316b0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
316c0 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f   index of the co
316d0 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63 68 20 69  lumn for which i
316e0 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68  nformation.** sh
316f0 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64  ould be returned
31700 2e 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20  . ^The leftmost 
31710 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65  column of the re
31720 73 75 6c 74 20 73 65 74 20 68 61 73 20 74 68 65  sult set has the
31730 20 69 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e 54 68   index 0..** ^Th
31740 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  e number of colu
31750 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c  mns in the resul
31760 74 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69  t can be determi
31770 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  ned using.** [sq
31780 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75  lite3_column_cou
31790 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  nt()]..**.** If 
317a0 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
317b0 74 20 64 6f 65 73 20 6e 6f 74 20 63 75 72 72 65  t does not curre
317c0 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61 20  ntly point to a 
317d0 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69 66  valid row, or if
317e0 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69   the.** column i
317f0 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72  ndex is out of r
31800 61 6e 67 65 2c 20 74 68 65 20 72 65 73 75 6c 74  ange, the result
31810 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
31820 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
31830 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c   may only be cal
31840 6c 65 64 20 77 68 65 6e 20 74 68 65 20 6d 6f 73  led when the mos
31850 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f  t recent call to
31860 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  .** [sqlite3_ste
31870 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65  p()] has returne
31880 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61  d [SQLITE_ROW] a
31890 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73  nd neither.** [s
318a0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
318b0 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  nor [sqlite3_fin
318c0 61 6c 69 7a 65 28 29 5d 20 68 61 76 65 20 62 65  alize()] have be
318d0 65 6e 20 63 61 6c 6c 65 64 20 73 75 62 73 65 71  en called subseq
318e0 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e  uently..** If an
318f0 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  y of these routi
31900 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 61  nes are called a
31910 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  fter [sqlite3_re
31920 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  set()] or.** [sq
31930 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
31940 5d 20 6f 72 20 61 66 74 65 72 20 5b 73 71 6c 69  ] or after [sqli
31950 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20  te3_step()] has 
31960 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65  returned.** some
31970 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e  thing other than
31980 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74   [SQLITE_ROW], t
31990 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75  he results are u
319a0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20  ndefined..** If 
319b0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
319c0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   or [sqlite3_res
319d0 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  et()] or [sqlite
319e0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a  3_finalize()].**
319f0 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d   are called from
31a00 20 61 20 64 69 66 66 65 72 65 6e 74 20 74 68 72   a different thr
31a10 65 61 64 20 77 68 69 6c 65 20 61 6e 79 20 6f 66  ead while any of
31a20 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a   these routines.
31a30 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e 67 2c 20  ** are pending, 
31a40 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73  then the results
31a50 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a   are undefined..
31a60 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
31a70 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29  e3_column_type()
31a80 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
31a90 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
31aa0 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79  INTEGER | dataty
31ab0 70 65 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65  pe code] for the
31ac0 20 69 6e 69 74 69 61 6c 20 64 61 74 61 20 74 79   initial data ty
31ad0 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73  pe.** of the res
31ae0 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54 68  ult column.  ^Th
31af0 65 20 72 65 74 75 72 6e 65 64 20 76 61 6c 75 65  e returned value
31b00 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49   is one of [SQLI
31b10 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20  TE_INTEGER],.** 
31b20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20  [SQLITE_FLOAT], 
31b30 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b  [SQLITE_TEXT], [
31b40 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72  SQLITE_BLOB], or
31b50 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20   [SQLITE_NULL]. 
31b60 20 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65   The value.** re
31b70 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
31b80 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20  3_column_type() 
31b90 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66  is only meaningf
31ba0 75 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a 2a 2a  ul if no type.**
31bb0 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61 76   conversions hav
31bc0 65 20 6f 63 63 75 72 72 65 64 20 61 73 20 64 65  e occurred as de
31bd0 73 63 72 69 62 65 64 20 62 65 6c 6f 77 2e 20 20  scribed below.  
31be0 41 66 74 65 72 20 61 20 74 79 70 65 20 63 6f 6e  After a type con
31bf0 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20  version,.** the 
31c00 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
31c10 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
31c20 5f 74 79 70 65 28 29 20 69 73 20 75 6e 64 65 66  _type() is undef
31c30 69 6e 65 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a  ined.  Future.**
31c40 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
31c50 69 74 65 20 6d 61 79 20 63 68 61 6e 67 65 20 74  ite may change t
31c60 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 73  he behavior of s
31c70 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
31c80 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e  pe().** followin
31c90 67 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73  g a type convers
31ca0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ion..**.** ^If t
31cb0 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 42  he result is a B
31cc0 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20 73 74 72  LOB or UTF-8 str
31cd0 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c  ing then the sql
31ce0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
31cf0 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72  s().** routine r
31d00 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
31d10 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
31d20 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e  at BLOB or strin
31d30 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  g..** ^If the re
31d40 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d 31 36  sult is a UTF-16
31d50 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71   string, then sq
31d60 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
31d70 65 73 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a  es() converts.**
31d80 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55   the string to U
31d90 54 46 2d 38 20 61 6e 64 20 74 68 65 6e 20 72 65  TF-8 and then re
31da0 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
31db0 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49   of bytes..** ^I
31dc0 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
31dd0 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20  a numeric value 
31de0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
31df0 75 6d 6e 5f 62 79 74 65 73 28 29 20 75 73 65 73  umn_bytes() uses
31e00 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70  .** [sqlite3_snp
31e10 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76  rintf()] to conv
31e20 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74  ert that value t
31e30 6f 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67  o a UTF-8 string
31e40 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20   and returns.** 
31e50 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
31e60 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 69  tes in that stri
31e70 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  ng..** ^If the r
31e80 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74  esult is NULL, t
31e90 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
31ea0 6d 6e 5f 62 79 74 65 73 28 29 20 72 65 74 75 72  mn_bytes() retur
31eb0 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e  ns zero..**.** ^
31ec0 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
31ed0 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 31   a BLOB or UTF-1
31ee0 36 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68  6 string then th
31ef0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
31f00 5f 62 79 74 65 73 31 36 28 29 0a 2a 2a 20 72 6f  _bytes16().** ro
31f10 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
31f20 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
31f30 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f  s in that BLOB o
31f40 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66  r string..** ^If
31f50 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
31f60 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2c 20 74   UTF-8 string, t
31f70 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
31f80 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 63 6f 6e  mn_bytes16() con
31f90 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72  verts.** the str
31fa0 69 6e 67 20 74 6f 20 55 54 46 2d 31 36 20 61 6e  ing to UTF-16 an
31fb0 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74  d then returns t
31fc0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
31fd0 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  es..** ^If the r
31fe0 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72  esult is a numer
31ff0 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71  ic value then sq
32000 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
32010 65 73 31 36 28 29 20 75 73 65 73 0a 2a 2a 20 5b  es16() uses.** [
32020 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
32030 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74  ()] to convert t
32040 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55  hat value to a U
32050 54 46 2d 31 36 20 73 74 72 69 6e 67 20 61 6e 64  TF-16 string and
32060 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20   returns.** the 
32070 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
32080 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a  in that string..
32090 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
320a0 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20  t is NULL, then 
320b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
320c0 79 74 65 73 31 36 28 29 20 72 65 74 75 72 6e 73  ytes16() returns
320d0 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   zero..**.** ^Th
320e0 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65  e values returne
320f0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d by [sqlite3_co
32100 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e  lumn_bytes()] an
32110 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  d .** [sqlite3_c
32120 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d  olumn_bytes16()]
32130 20 64 6f 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20   do not include 
32140 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  the zero termina
32150 74 6f 72 73 20 61 74 20 74 68 65 20 65 6e 64 0a  tors at the end.
32160 2a 2a 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67  ** of the string
32170 2e 20 20 5e 46 6f 72 20 63 6c 61 72 69 74 79 3a  .  ^For clarity:
32180 20 74 68 65 20 76 61 6c 75 65 73 20 72 65 74 75   the values retu
32190 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  rned by.** [sqli
321a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
321b0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
321c0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
321d0 29 5d 20 61 72 65 20 74 68 65 20 6e 75 6d 62 65  )] are the numbe
321e0 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e  r of.** bytes in
321f0 20 74 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74   the string, not
32200 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
32210 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a  haracters..**.**
32220 20 5e 53 74 72 69 6e 67 73 20 72 65 74 75 72 6e   ^Strings return
32230 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
32240 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64 20  lumn_text() and 
32250 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
32260 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e  ext16(),.** even
32270 20 65 6d 70 74 79 20 73 74 72 69 6e 67 73 2c 20   empty strings, 
32280 61 72 65 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d  are always zero-
32290 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68  terminated.  ^Th
322a0 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75  e return.** valu
322b0 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63  e from sqlite3_c
322c0 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72  olumn_blob() for
322d0 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42   a zero-length B
322e0 4c 4f 42 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  LOB is a NULL po
322f0 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e  inter..**.** <b>
32300 57 61 72 6e 69 6e 67 3a 3c 2f 62 3e 20 5e 54 68  Warning:</b> ^Th
32310 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65  e object returne
32320 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d by [sqlite3_co
32330 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73  lumn_value()] is
32340 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63   an.** [unprotec
32350 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
32360 65 5d 20 6f 62 6a 65 63 74 2e 20 20 49 6e 20 61  e] object.  In a
32370 20 6d 75 6c 74 69 74 68 72 65 61 64 65 64 20 65   multithreaded e
32380 6e 76 69 72 6f 6e 6d 65 6e 74 2c 0a 2a 2a 20 61  nvironment,.** a
32390 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71  n unprotected sq
323a0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
323b0 63 74 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75  ct may only be u
323c0 73 65 64 20 73 61 66 65 6c 79 20 77 69 74 68 0a  sed safely with.
323d0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
323e0 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73  _value()] and [s
323f0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
32400 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68  lue()]..** If th
32410 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  e [unprotected s
32420 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
32430 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79  ject returned by
32440 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
32450 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20  umn_value()] is 
32460 75 73 65 64 20 69 6e 20 61 6e 79 20 6f 74 68 65  used in any othe
32470 72 20 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67  r way, including
32480 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75   calls.** to rou
32490 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69  tines like [sqli
324a0 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d  te3_value_int()]
324b0 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  , [sqlite3_value
324c0 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20  _text()],.** or 
324d0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
324e0 79 74 65 73 28 29 5d 2c 20 74 68 65 20 62 65 68  ytes()], the beh
324f0 61 76 69 6f 72 20 69 73 20 6e 6f 74 20 74 68 72  avior is not thr
32500 65 61 64 73 61 66 65 2e 0a 2a 2a 0a 2a 2a 20 54  eadsafe..**.** T
32510 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 74  hese routines at
32520 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72 74  tempt to convert
32530 20 74 68 65 20 76 61 6c 75 65 20 77 68 65 72 65   the value where
32540 20 61 70 70 72 6f 70 72 69 61 74 65 2e 20 20 5e   appropriate.  ^
32550 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20  For.** example, 
32560 69 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20  if the internal 
32570 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 69  representation i
32580 73 20 46 4c 4f 41 54 20 61 6e 64 20 61 20 74 65  s FLOAT and a te
32590 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20  xt result.** is 
325a0 72 65 71 75 65 73 74 65 64 2c 20 5b 73 71 6c 69  requested, [sqli
325b0 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20  te3_snprintf()] 
325c0 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c  is used internal
325d0 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d 20 74 68  ly to perform th
325e0 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20  e.** conversion 
325f0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20  automatically.  
32600 5e 28 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  ^(The following 
32610 74 61 62 6c 65 20 64 65 74 61 69 6c 73 20 74 68  table details th
32620 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a  e conversions.**
32630 20 74 68 61 74 20 61 72 65 20 61 70 70 6c 69 65   that are applie
32640 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  d:.**.** <blockq
32650 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20  uote>.** <table 
32660 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c  border="1">.** <
32670 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c  tr><th> Internal
32680 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 52 65  <br>Type <th> Re
32690 71 75 65 73 74 65 64 3c 62 72 3e 54 79 70 65 20  quested<br>Type 
326a0 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e  <th>  Conversion
326b0 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  .**.** <tr><td> 
326c0 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e   NULL    <td> IN
326d0 54 45 47 45 52 20 20 20 3c 74 64 3e 20 52 65 73  TEGER   <td> Res
326e0 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e  ult is 0.** <tr>
326f0 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74  <td>  NULL    <t
32700 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64  d>  FLOAT    <td
32710 3e 20 52 65 73 75 6c 74 20 69 73 20 30 2e 30 0a  > Result is 0.0.
32720 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c  ** <tr><td>  NUL
32730 4c 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54  L    <td>   TEXT
32740 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20      <td> Result 
32750 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
32760 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e  r.** <tr><td>  N
32770 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 42 4c  ULL    <td>   BL
32780 4f 42 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c  OB    <td> Resul
32790 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  t is a NULL poin
327a0 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ter.** <tr><td> 
327b0 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 46  INTEGER  <td>  F
327c0 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e  LOAT    <td> Con
327d0 76 65 72 74 20 66 72 6f 6d 20 69 6e 74 65 67 65  vert from intege
327e0 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74  r to float.** <t
327f0 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20  r><td> INTEGER  
32800 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c  <td>   TEXT    <
32810 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72  td> ASCII render
32820 69 6e 67 20 6f 66 20 74 68 65 20 69 6e 74 65 67  ing of the integ
32830 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49  er.** <tr><td> I
32840 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 42  NTEGER  <td>   B
32850 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65  LOB    <td> Same
32860 20 61 73 20 49 4e 54 45 47 45 52 2d 3e 54 45 58   as INTEGER->TEX
32870 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46  T.** <tr><td>  F
32880 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e 54 45  LOAT   <td> INTE
32890 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54  GER   <td> [CAST
328a0 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20  ] to INTEGER.** 
328b0 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20  <tr><td>  FLOAT 
328c0 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20    <td>   TEXT   
328d0 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64   <td> ASCII rend
328e0 65 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f  ering of the flo
328f0 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  at.** <tr><td>  
32900 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 42  FLOAT   <td>   B
32910 4c 4f 42 20 20 20 20 3c 74 64 3e 20 5b 43 41 53  LOB    <td> [CAS
32920 54 5d 20 74 6f 20 42 4c 4f 42 0a 2a 2a 20 3c 74  T] to BLOB.** <t
32930 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20  r><td>  TEXT    
32940 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c  <td> INTEGER   <
32950 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e  td> [CAST] to IN
32960 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64  TEGER.** <tr><td
32970 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20  >  TEXT    <td> 
32980 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 5b   FLOAT    <td> [
32990 43 41 53 54 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a  CAST] to REAL.**
329a0 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20   <tr><td>  TEXT 
329b0 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20     <td>   BLOB  
329c0 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65    <td> No change
329d0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c  .** <tr><td>  BL
329e0 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  OB    <td> INTEG
329f0 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d  ER   <td> [CAST]
32a00 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c   to INTEGER.** <
32a10 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20  tr><td>  BLOB   
32a20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20   <td>  FLOAT    
32a30 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 52  <td> [CAST] to R
32a40 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  EAL.** <tr><td> 
32a50 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 20   BLOB    <td>   
32a60 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 64 64  TEXT    <td> Add
32a70 20 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74   a zero terminat
32a80 6f 72 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20  or if needed.** 
32a90 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c  </table>.** </bl
32aa0 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a  ockquote>)^.**.*
32ab0 2a 20 4e 6f 74 65 20 74 68 61 74 20 77 68 65 6e  * Note that when
32ac0 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   type conversion
32ad0 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65 72  s occur, pointer
32ae0 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 70 72  s returned by pr
32af0 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20  ior.** calls to 
32b00 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
32b10 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 63  lob(), sqlite3_c
32b20 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e  olumn_text(), an
32b30 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  d/or.** sqlite3_
32b40 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
32b50 6d 61 79 20 62 65 20 69 6e 76 61 6c 69 64 61 74  may be invalidat
32b60 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76  ed..** Type conv
32b70 65 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e  ersions and poin
32b80 74 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e  ter invalidation
32b90 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a  s might occur.**
32ba0 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   in the followin
32bb0 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c  g cases:.**.** <
32bc0 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  ul>.** <li> The 
32bd0 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20  initial content 
32be0 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 73 71  is a BLOB and sq
32bf0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
32c00 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73  t() or.**      s
32c10 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
32c20 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64  xt16() is called
32c30 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  .  A zero-termin
32c40 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20  ator might.**   
32c50 20 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61 64     need to be ad
32c60 64 65 64 20 74 6f 20 74 68 65 20 73 74 72 69 6e  ded to the strin
32c70 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20  g.</li>.** <li> 
32c80 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74  The initial cont
32c90 65 6e 74 20 69 73 20 55 54 46 2d 38 20 74 65 78  ent is UTF-8 tex
32ca0 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  t and sqlite3_co
32cb0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 6f  lumn_bytes16() o
32cc0 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65  r.**      sqlite
32cd0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
32ce0 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68  ) is called.  Th
32cf0 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62  e content must b
32d00 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20  e converted.**  
32d10 20 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f      to UTF-16.</
32d20 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  li>.** <li> The 
32d30 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20  initial content 
32d40 69 73 20 55 54 46 2d 31 36 20 74 65 78 74 20 61  is UTF-16 text a
32d50 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
32d60 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20  n_bytes() or.** 
32d70 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c       sqlite3_col
32d80 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 63 61  umn_text() is ca
32d90 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65  lled.  The conte
32da0 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65  nt must be conve
32db0 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20  rted.**      to 
32dc0 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c  UTF-8.</li>.** <
32dd0 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76  /ul>.**.** ^Conv
32de0 65 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e 20  ersions between 
32df0 55 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54 46  UTF-16be and UTF
32e00 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79 73  -16le are always
32e10 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 61   done in place a
32e20 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76  nd do.** not inv
32e30 61 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72 20  alidate a prior 
32e40 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 20  pointer, though 
32e50 6f 66 20 63 6f 75 72 73 65 20 74 68 65 20 63 6f  of course the co
32e60 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75 66  ntent of the buf
32e70 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20  fer.** that the 
32e80 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 72 65  prior pointer re
32e90 66 65 72 65 6e 63 65 73 20 77 69 6c 6c 20 68 61  ferences will ha
32ea0 76 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 64  ve been modified
32eb0 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a  .  Other kinds.*
32ec0 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20  * of conversion 
32ed0 61 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63  are done in plac
32ee0 65 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f 73  e when it is pos
32ef0 73 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74  sible, but somet
32f00 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61 72 65  imes they.** are
32f10 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 6e   not possible an
32f20 64 20 69 6e 20 74 68 6f 73 65 20 63 61 73 65 73  d in those cases
32f30 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 20   prior pointers 
32f40 61 72 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e  are invalidated.
32f50 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65 73  .**.** The safes
32f60 74 20 70 6f 6c 69 63 79 20 69 73 20 74 6f 20 69  t policy is to i
32f70 6e 76 6f 6b 65 20 74 68 65 73 65 20 72 6f 75 74  nvoke these rout
32f80 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f  ines.** in one o
32f90 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  f the following 
32fa0 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ways:.**.** <ul>
32fb0 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33  .**  <li>sqlite3
32fc0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66  _column_text() f
32fd0 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74  ollowed by sqlit
32fe0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
32ff0 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73  )</li>.**  <li>s
33000 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
33010 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79  ob() followed by
33020 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
33030 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20  bytes()</li>.** 
33040 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c   <li>sqlite3_col
33050 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 6f 6c  umn_text16() fol
33060 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33  lowed by sqlite3
33070 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
33080 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a  )</li>.** </ul>.
33090 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77  **.** In other w
330a0 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64  ords, you should
330b0 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f   call sqlite3_co
330c0 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a 20  lumn_text(),.** 
330d0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
330e0 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c 69 74 65  lob(), or sqlite
330f0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
33100 29 20 66 69 72 73 74 20 74 6f 20 66 6f 72 63 65  ) first to force
33110 20 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20 69   the result.** i
33120 6e 74 6f 20 74 68 65 20 64 65 73 69 72 65 64 20  nto the desired 
33130 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76  format, then inv
33140 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  oke sqlite3_colu
33150 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a  mn_bytes() or.**
33160 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
33170 62 79 74 65 73 31 36 28 29 20 74 6f 20 66 69 6e  bytes16() to fin
33180 64 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  d the size of th
33190 65 20 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f  e result.  Do no
331a0 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 74  t mix calls.** t
331b0 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  o sqlite3_column
331c0 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74  _text() or sqlit
331d0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
331e0 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 0a 2a   with calls to.*
331f0 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
33200 5f 62 79 74 65 73 31 36 28 29 2c 20 61 6e 64 20  _bytes16(), and 
33210 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73  do not mix calls
33220 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
33230 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 77  mn_text16().** w
33240 69 74 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  ith calls to sql
33250 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
33260 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  s()..**.** ^The 
33270 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65  pointers returne
33280 64 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69  d are valid unti
33290 6c 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73  l a type convers
332a0 69 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a  ion occurs as.**
332b0 20 64 65 73 63 72 69 62 65 64 20 61 62 6f 76 65   described above
332c0 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69  , or until [sqli
332d0 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b  te3_step()] or [
332e0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
332f0 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
33300 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63  finalize()] is c
33310 61 6c 6c 65 64 2e 20 20 5e 54 68 65 20 6d 65 6d  alled.  ^The mem
33320 6f 72 79 20 73 70 61 63 65 20 75 73 65 64 20 74  ory space used t
33330 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a  o hold strings.*
33340 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69 73 20 66  * and BLOBs is f
33350 72 65 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c  reed automatical
33360 6c 79 2e 20 20 44 6f 20 3c 65 6d 3e 6e 6f 74 3c  ly.  Do <em>not<
33370 2f 65 6d 3e 20 70 61 73 73 20 74 68 65 20 70 6f  /em> pass the po
33380 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 0a  inters returned.
33390 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ** from [sqlite3
333a0 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c  _column_blob()],
333b0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
333c0 5f 74 65 78 74 28 29 5d 2c 20 65 74 63 2e 20 69  _text()], etc. i
333d0 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  nto.** [sqlite3_
333e0 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  free()]..**.** ^
333f0 28 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c  (If a memory all
33400 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63  ocation error oc
33410 63 75 72 73 20 64 75 72 69 6e 67 20 74 68 65 20  curs during the 
33420 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e  evaluation of an
33430 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 72 6f  y.** of these ro
33440 75 74 69 6e 65 73 2c 20 61 20 64 65 66 61 75 6c  utines, a defaul
33450 74 20 76 61 6c 75 65 20 69 73 20 72 65 74 75 72  t value is retur
33460 6e 65 64 2e 20 20 54 68 65 20 64 65 66 61 75 6c  ned.  The defaul
33470 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69  t value.** is ei
33480 74 68 65 72 20 74 68 65 20 69 6e 74 65 67 65 72  ther the integer
33490 20 30 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e 67   0, the floating
334a0 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e   point number 0.
334b0 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20  0, or a NULL.** 
334c0 70 6f 69 6e 74 65 72 2e 20 20 53 75 62 73 65 71  pointer.  Subseq
334d0 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73  uent calls to [s
334e0 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
334f0 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a  ] will return.**
33500 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e   [SQLITE_NOMEM].
33510 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  )^.*/.SQLITE_API
33520 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51 4c   const void *SQL
33530 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
33540 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
33550 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
33560 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45  nt iCol);.SQLITE
33570 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f  _API int SQLITE_
33580 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
33590 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c  column_bytes(sql
335a0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
335b0 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50  iCol);.SQLITE_AP
335c0 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  I int SQLITE_STD
335d0 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c  CALL sqlite3_col
335e0 75 6d 6e 5f 62 79 74 65 73 31 36 28 73 71 6c 69  umn_bytes16(sqli
335f0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
33600 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  Col);.SQLITE_API
33610 20 64 6f 75 62 6c 65 20 53 51 4c 49 54 45 5f 53   double SQLITE_S
33620 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63  TDCALL sqlite3_c
33630 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c  olumn_double(sql
33640 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
33650 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50  iCol);.SQLITE_AP
33660 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  I int SQLITE_STD
33670 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c  CALL sqlite3_col
33680 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f  umn_int(sqlite3_
33690 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
336a0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c  ;.SQLITE_API sql
336b0 69 74 65 33 5f 69 6e 74 36 34 20 53 51 4c 49 54  ite3_int64 SQLIT
336c0 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
336d0 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 73  3_column_int64(s
336e0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
336f0 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f  t iCol);.SQLITE_
33700 41 50 49 20 63 6f 6e 73 74 20 75 6e 73 69 67 6e  API const unsign
33710 65 64 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f  ed char *SQLITE_
33720 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
33730 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69  column_text(sqli
33740 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
33750 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  Col);.SQLITE_API
33760 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51 4c   const void *SQL
33770 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
33780 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
33790 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
337a0 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49   int iCol);.SQLI
337b0 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54  TE_API int SQLIT
337c0 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
337d0 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71  3_column_type(sq
337e0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
337f0 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41   iCol);.SQLITE_A
33800 50 49 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  PI sqlite3_value
33810 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c   *SQLITE_STDCALL
33820 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
33830 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74  value(sqlite3_st
33840 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
33850 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
33860 20 44 65 73 74 72 6f 79 20 41 20 50 72 65 70 61   Destroy A Prepa
33870 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62  red Statement Ob
33880 6a 65 63 74 0a 2a 2a 20 44 45 53 54 52 55 43 54  ject.** DESTRUCT
33890 4f 52 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OR: sqlite3_stmt
338a0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
338b0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66  te3_finalize() f
338c0 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65  unction is calle
338d0 64 20 74 6f 20 64 65 6c 65 74 65 20 61 20 5b 70  d to delete a [p
338e0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
338f0 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d  t]..** ^If the m
33900 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75  ost recent evalu
33910 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 74 61  ation of the sta
33920 74 65 6d 65 6e 74 20 65 6e 63 6f 75 6e 74 65 72  tement encounter
33930 65 64 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20  ed no errors.** 
33940 6f 72 20 69 66 20 74 68 65 20 73 74 61 74 65 6d  or if the statem
33950 65 6e 74 20 69 73 20 6e 65 76 65 72 20 62 65 65  ent is never bee
33960 6e 20 65 76 61 6c 75 61 74 65 64 2c 20 74 68 65  n evaluated, the
33970 6e 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  n sqlite3_finali
33980 7a 65 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20  ze() returns.** 
33990 53 51 4c 49 54 45 5f 4f 4b 2e 20 20 5e 49 66 20  SQLITE_OK.  ^If 
339a0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
339b0 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 73 74  evaluation of st
339c0 61 74 65 6d 65 6e 74 20 53 20 66 61 69 6c 65 64  atement S failed
339d0 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65  , then.** sqlite
339e0 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 65  3_finalize(S) re
339f0 74 75 72 6e 73 20 74 68 65 20 61 70 70 72 6f 70  turns the approp
33a00 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64  riate [error cod
33a10 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64  e] or.** [extend
33a20 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a  ed error code]..
33a30 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
33a40 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72  e3_finalize(S) r
33a50 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 63 61  outine can be ca
33a60 6c 6c 65 64 20 61 74 20 61 6e 79 20 70 6f 69 6e  lled at any poin
33a70 74 20 64 75 72 69 6e 67 0a 2a 2a 20 74 68 65 20  t during.** the 
33a80 6c 69 66 65 20 63 79 63 6c 65 20 6f 66 20 5b 70  life cycle of [p
33a90 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
33aa0 74 5d 20 53 3a 0a 2a 2a 20 62 65 66 6f 72 65 20  t] S:.** before 
33ab0 73 74 61 74 65 6d 65 6e 74 20 53 20 69 73 20 65  statement S is e
33ac0 76 65 72 20 65 76 61 6c 75 61 74 65 64 2c 20 61  ver evaluated, a
33ad0 66 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d  fter.** one or m
33ae0 6f 72 65 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  ore calls to [sq
33af0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 20  lite3_reset()], 
33b00 6f 72 20 61 66 74 65 72 20 61 6e 79 20 63 61 6c  or after any cal
33b10 6c 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33  l.** to [sqlite3
33b20 5f 73 74 65 70 28 29 5d 20 72 65 67 61 72 64 6c  _step()] regardl
33b30 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f  ess of whether o
33b40 72 20 6e 6f 74 20 74 68 65 20 73 74 61 74 65 6d  r not the statem
33b50 65 6e 74 20 68 61 73 0a 2a 2a 20 63 6f 6d 70 6c  ent has.** compl
33b60 65 74 65 64 20 65 78 65 63 75 74 69 6f 6e 2e 0a  eted execution..
33b70 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b 69 6e 67 20  **.** ^Invoking 
33b80 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
33b90 28 29 20 6f 6e 20 61 20 4e 55 4c 4c 20 70 6f 69  () on a NULL poi
33ba0 6e 74 65 72 20 69 73 20 61 20 68 61 72 6d 6c 65  nter is a harmle
33bb0 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20  ss no-op..**.** 
33bc0 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
33bd0 6d 75 73 74 20 66 69 6e 61 6c 69 7a 65 20 65 76  must finalize ev
33be0 65 72 79 20 5b 70 72 65 70 61 72 65 64 20 73 74  ery [prepared st
33bf0 61 74 65 6d 65 6e 74 5d 20 69 6e 20 6f 72 64 65  atement] in orde
33c00 72 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 72 65  r to avoid.** re
33c10 73 6f 75 72 63 65 20 6c 65 61 6b 73 2e 20 20 49  source leaks.  I
33c20 74 20 69 73 20 61 20 67 72 69 65 76 6f 75 73 20  t is a grievous 
33c30 65 72 72 6f 72 20 66 6f 72 20 74 68 65 20 61 70  error for the ap
33c40 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 74 72 79  plication to try
33c50 20 74 6f 20 75 73 65 0a 2a 2a 20 61 20 70 72 65   to use.** a pre
33c60 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
33c70 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65  after it has bee
33c80 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 20 20 41 6e  n finalized.  An
33c90 79 20 75 73 65 20 6f 66 20 61 20 70 72 65 70 61  y use of a prepa
33ca0 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  red.** statement
33cb0 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65   after it has be
33cc0 65 6e 20 66 69 6e 61 6c 69 7a 65 64 20 63 61 6e  en finalized can
33cd0 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66   result in undef
33ce0 69 6e 65 64 20 61 6e 64 0a 2a 2a 20 75 6e 64 65  ined and.** unde
33cf0 73 69 72 61 62 6c 65 20 62 65 68 61 76 69 6f 72  sirable behavior
33d00 20 73 75 63 68 20 61 73 20 73 65 67 66 61 75 6c   such as segfaul
33d10 74 73 20 61 6e 64 20 68 65 61 70 20 63 6f 72 72  ts and heap corr
33d20 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54  uption..*/.SQLIT
33d30 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45  E_API int SQLITE
33d40 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
33d50 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65  _finalize(sqlite
33d60 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
33d70 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
33d80 20 52 65 73 65 74 20 41 20 50 72 65 70 61 72 65   Reset A Prepare
33d90 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65  d Statement Obje
33da0 63 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ct.** METHOD: sq
33db0 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
33dc0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   The sqlite3_res
33dd0 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73  et() function is
33de0 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 65 74   called to reset
33df0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
33e00 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63  tement].** objec
33e10 74 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e  t back to its in
33e20 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72 65 61  itial state, rea
33e30 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78 65 63  dy to be re-exec
33e40 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51  uted..** ^Any SQ
33e50 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61 72 69  L statement vari
33e60 61 62 6c 65 73 20 74 68 61 74 20 68 61 64 20 76  ables that had v
33e70 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f 20 74  alues bound to t
33e80 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65  hem using.** the
33e90 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
33ea0 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69  lob | sqlite3_bi
33eb0 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 74 61  nd_*() API] reta
33ec0 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65 73 2e  in their values.
33ed0 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 65 33  .** Use [sqlite3
33ee0 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28  _clear_bindings(
33ef0 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20  )] to reset the 
33f00 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20  bindings..**.** 
33f10 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65  ^The [sqlite3_re
33f20 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63  set(S)] interfac
33f30 65 20 72 65 73 65 74 73 20 74 68 65 20 5b 70 72  e resets the [pr
33f40 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
33f50 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 74  ] S.** back to t
33f60 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20  he beginning of 
33f70 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a  its program..**.
33f80 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20  ** ^If the most 
33f90 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b  recent call to [
33fa0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
33fb0 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65   for the.** [pre
33fc0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
33fd0 20 53 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c   S returned [SQL
33fe0 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c  ITE_ROW] or [SQL
33ff0 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72  ITE_DONE],.** or
34000 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   if [sqlite3_ste
34010 70 28 53 29 5d 20 68 61 73 20 6e 65 76 65 72 20  p(S)] has never 
34020 62 65 66 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c  before been call
34030 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e  ed on S,.** then
34040 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
34050 53 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  S)] returns [SQL
34060 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  ITE_OK]..**.** ^
34070 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  If the most rece
34080 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  nt call to [sqli
34090 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72  te3_step(S)] for
340a0 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
340b0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69  d statement] S i
340c0 6e 64 69 63 61 74 65 64 20 61 6e 20 65 72 72 6f  ndicated an erro
340d0 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69  r, then.** [sqli
340e0 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65  te3_reset(S)] re
340f0 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 72  turns an appropr
34100 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65  iate [error code
34110 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73  ]..**.** ^The [s
34120 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
34130 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65 73 20   interface does 
34140 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76  not change the v
34150 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 6e 79 20  alues.** of any 
34160 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
34170 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20  ob|bindings] on 
34180 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
34190 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 53  atement] S..*/.S
341a0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51  QLITE_API int SQ
341b0 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
341c0 69 74 65 33 5f 72 65 73 65 74 28 73 71 6c 69 74  ite3_reset(sqlit
341d0 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
341e0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
341f0 3a 20 43 72 65 61 74 65 20 4f 72 20 52 65 64 65  : Create Or Rede
34200 66 69 6e 65 20 53 51 4c 20 46 75 6e 63 74 69 6f  fine SQL Functio
34210 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ns.** KEYWORDS: 
34220 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69  {function creati
34230 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20  on routines}.** 
34240 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69  KEYWORDS: {appli
34250 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
34260 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20  QL function}.** 
34270 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69  KEYWORDS: {appli
34280 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
34290 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a  QL functions}.**
342a0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
342b0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75  .**.** ^These fu
342c0 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 63 74  nctions (collect
342d0 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 22  ively known as "
342e0 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f  function creatio
342f0 6e 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a 2a 20  n routines").** 
34300 61 72 65 20 75 73 65 64 20 74 6f 20 61 64 64 20  are used to add 
34310 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72  SQL functions or
34320 20 61 67 67 72 65 67 61 74 65 73 20 6f 72 20 74   aggregates or t
34330 6f 20 72 65 64 65 66 69 6e 65 20 74 68 65 20 62  o redefine the b
34340 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 65 78  ehavior.** of ex
34350 69 73 74 69 6e 67 20 53 51 4c 20 66 75 6e 63 74  isting SQL funct
34360 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74  ions or aggregat
34370 65 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 64 69  es.  The only di
34380 66 66 65 72 65 6e 63 65 73 20 62 65 74 77 65 65  fferences betwee
34390 6e 0a 2a 2a 20 74 68 65 73 65 20 72 6f 75 74 69  n.** these routi
343a0 6e 65 73 20 61 72 65 20 74 68 65 20 74 65 78 74  nes are the text
343b0 20 65 6e 63 6f 64 69 6e 67 20 65 78 70 65 63 74   encoding expect
343c0 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 73 65  ed for.** the se
343d0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 28  cond parameter (
343e0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
343f0 66 75 6e 63 74 69 6f 6e 20 62 65 69 6e 67 20 63  function being c
34400 72 65 61 74 65 64 29 0a 2a 2a 20 61 6e 64 20 74  reated).** and t
34410 68 65 20 70 72 65 73 65 6e 63 65 20 6f 72 20 61  he presence or a
34420 62 73 65 6e 63 65 20 6f 66 20 61 20 64 65 73 74  bsence of a dest
34430 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20  ructor callback 
34440 66 6f 72 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69  for.** the appli
34450 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e  cation data poin
34460 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ter..**.** ^The 
34470 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
34480 69 73 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  is the [database
34490 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20   connection] to 
344a0 77 68 69 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a  which the SQL.**
344b0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20   function is to 
344c0 62 65 20 61 64 64 65 64 2e 20 20 5e 49 66 20 61  be added.  ^If a
344d0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73  n application us
344e0 65 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65  es more than one
344f0 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e   database.** con
34500 6e 65 63 74 69 6f 6e 20 74 68 65 6e 20 61 70 70  nection then app
34510 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
34520 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6d   SQL functions m
34530 75 73 74 20 62 65 20 61 64 64 65 64 0a 2a 2a 20  ust be added.** 
34540 74 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 65  to each database
34550 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 65 70 61   connection sepa
34560 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54  rately..**.** ^T
34570 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
34580 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20  ter is the name 
34590 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  of the SQL funct
345a0 69 6f 6e 20 74 6f 20 62 65 20 63 72 65 61 74 65  ion to be create
345b0 64 20 6f 72 0a 2a 2a 20 72 65 64 65 66 69 6e 65  d or.** redefine
345c0 64 2e 20 20 5e 54 68 65 20 6c 65 6e 67 74 68 20  d.  ^The length 
345d0 6f 66 20 74 68 65 20 6e 61 6d 65 20 69 73 20 6c  of the name is l
345e0 69 6d 69 74 65 64 20 74 6f 20 32 35 35 20 62 79  imited to 255 by
345f0 74 65 73 20 69 6e 20 61 20 55 54 46 2d 38 0a 2a  tes in a UTF-8.*
34600 2a 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e  * representation
34610 2c 20 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74  , exclusive of t
34620 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  he zero-terminat
34630 6f 72 2e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20  or.  ^Note that 
34640 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 6c 65 6e 67  the name.** leng
34650 74 68 20 6c 69 6d 69 74 20 69 73 20 69 6e 20 55  th limit is in U
34660 54 46 2d 38 20 62 79 74 65 73 2c 20 6e 6f 74 20  TF-8 bytes, not 
34670 63 68 61 72 61 63 74 65 72 73 20 6e 6f 72 20 55  characters nor U
34680 54 46 2d 31 36 20 62 79 74 65 73 2e 20 20 0a 2a  TF-16 bytes.  .*
34690 2a 20 5e 41 6e 79 20 61 74 74 65 6d 70 74 20 74  * ^Any attempt t
346a0 6f 20 63 72 65 61 74 65 20 61 20 66 75 6e 63 74  o create a funct
346b0 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67 65  ion with a longe
346c0 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72  r name.** will r
346d0 65 73 75 6c 74 20 69 6e 20 5b 53 51 4c 49 54 45  esult in [SQLITE
346e0 5f 4d 49 53 55 53 45 5d 20 62 65 69 6e 67 20 72  _MISUSE] being r
346f0 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  eturned..**.** ^
34700 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  The third parame
34710 74 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20 69 73  ter (nArg).** is
34720 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61   the number of a
34730 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 74 68  rguments that th
34740 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f  e SQL function o
34750 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 74  r.** aggregate t
34760 61 6b 65 73 2e 20 5e 49 66 20 74 68 69 73 20 70  akes. ^If this p
34770 61 72 61 6d 65 74 65 72 20 69 73 20 2d 31 2c 20  arameter is -1, 
34780 74 68 65 6e 20 74 68 65 20 53 51 4c 20 66 75 6e  then the SQL fun
34790 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72  ction or.** aggr
347a0 65 67 61 74 65 20 6d 61 79 20 74 61 6b 65 20 61  egate may take a
347b0 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67  ny number of arg
347c0 75 6d 65 6e 74 73 20 62 65 74 77 65 65 6e 20 30  uments between 0
347d0 20 61 6e 64 20 74 68 65 20 6c 69 6d 69 74 0a 2a   and the limit.*
347e0 2a 20 73 65 74 20 62 79 20 5b 73 71 6c 69 74 65  * set by [sqlite
347f0 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45  3_limit]([SQLITE
34800 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f  _LIMIT_FUNCTION_
34810 41 52 47 5d 29 2e 20 20 49 66 20 74 68 65 20 74  ARG]).  If the t
34820 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65  hird.** paramete
34830 72 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 2d  r is less than -
34840 31 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61  1 or greater tha
34850 6e 20 31 32 37 20 74 68 65 6e 20 74 68 65 20 62  n 127 then the b
34860 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75 6e  ehavior is.** un
34870 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  defined..**.** ^
34880 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  The fourth param
34890 65 74 65 72 2c 20 65 54 65 78 74 52 65 70 2c 20  eter, eTextRep, 
348a0 73 70 65 63 69 66 69 65 73 20 77 68 61 74 0a 2a  specifies what.*
348b0 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c  * [SQLITE_UTF8 |
348c0 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20   text encoding] 
348d0 74 68 69 73 20 53 51 4c 20 66 75 6e 63 74 69 6f  this SQL functio
348e0 6e 20 70 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a  n prefers for.**
348f0 20 69 74 73 20 70 61 72 61 6d 65 74 65 72 73 2e   its parameters.
34900 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f    The applicatio
34910 6e 20 73 68 6f 75 6c 64 20 73 65 74 20 74 68 69  n should set thi
34920 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  s parameter to.*
34930 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c  * [SQLITE_UTF16L
34940 45 5d 20 69 66 20 74 68 65 20 66 75 6e 63 74 69  E] if the functi
34950 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  on implementatio
34960 6e 20 69 6e 76 6f 6b 65 73 20 0a 2a 2a 20 5b 73  n invokes .** [s
34970 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
34980 74 31 36 6c 65 28 29 5d 20 6f 6e 20 61 6e 20 69  t16le()] on an i
34990 6e 70 75 74 2c 20 6f 72 20 5b 53 51 4c 49 54 45  nput, or [SQLITE
349a0 5f 55 54 46 31 36 42 45 5d 20 69 66 20 74 68 65  _UTF16BE] if the
349b0 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
349c0 6f 6e 20 69 6e 76 6f 6b 65 73 20 5b 73 71 6c 69  on invokes [sqli
349d0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
349e0 62 65 28 29 5d 20 6f 6e 20 61 6e 20 69 6e 70 75  be()] on an inpu
349f0 74 2c 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45  t, or.** [SQLITE
34a00 5f 55 54 46 31 36 5d 20 69 66 20 5b 73 71 6c 69  _UTF16] if [sqli
34a10 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
34a20 28 29 5d 20 69 73 20 75 73 65 64 2c 20 6f 72 20  ()] is used, or 
34a30 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 0a 2a 2a  [SQLITE_UTF8].**
34a40 20 6f 74 68 65 72 77 69 73 65 2e 20 20 5e 54 68   otherwise.  ^Th
34a50 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74  e same SQL funct
34a60 69 6f 6e 20 6d 61 79 20 62 65 20 72 65 67 69 73  ion may be regis
34a70 74 65 72 65 64 20 6d 75 6c 74 69 70 6c 65 20 74  tered multiple t
34a80 69 6d 65 73 20 75 73 69 6e 67 0a 2a 2a 20 64 69  imes using.** di
34a90 66 66 65 72 65 6e 74 20 70 72 65 66 65 72 72 65  fferent preferre
34aa0 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73  d text encodings
34ab0 2c 20 77 69 74 68 20 64 69 66 66 65 72 65 6e 74  , with different
34ac0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
34ad0 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 65 6e 63   for.** each enc
34ae0 6f 64 69 6e 67 2e 0a 2a 2a 20 5e 57 68 65 6e 20  oding..** ^When 
34af0 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65  multiple impleme
34b00 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ntations of the 
34b10 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 61 72  same function ar
34b20 65 20 61 76 61 69 6c 61 62 6c 65 2c 20 53 51 4c  e available, SQL
34b30 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 63 6b  ite.** will pick
34b40 20 74 68 65 20 6f 6e 65 20 74 68 61 74 20 69 6e   the one that in
34b50 76 6f 6c 76 65 73 20 74 68 65 20 6c 65 61 73 74  volves the least
34b60 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20   amount of data 
34b70 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a  conversion..**.*
34b80 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61  * ^The fourth pa
34b90 72 61 6d 65 74 65 72 20 6d 61 79 20 6f 70 74 69  rameter may opti
34ba0 6f 6e 61 6c 6c 79 20 62 65 20 4f 52 65 64 20 77  onally be ORed w
34bb0 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 45 54 45  ith [SQLITE_DETE
34bc0 52 4d 49 4e 49 53 54 49 43 5d 0a 2a 2a 20 74 6f  RMINISTIC].** to
34bd0 20 73 69 67 6e 61 6c 20 74 68 61 74 20 74 68 65   signal that the
34be0 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 61   function will a
34bf0 6c 77 61 79 73 20 72 65 74 75 72 6e 20 74 68 65  lways return the
34c00 20 73 61 6d 65 20 72 65 73 75 6c 74 20 67 69 76   same result giv
34c10 65 6e 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 69  en.** the same i
34c20 6e 70 75 74 73 20 77 69 74 68 69 6e 20 61 20 73  nputs within a s
34c30 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d  ingle SQL statem
34c40 65 6e 74 2e 20 20 4d 6f 73 74 20 53 51 4c 20 66  ent.  Most SQL f
34c50 75 6e 63 74 69 6f 6e 73 20 61 72 65 0a 2a 2a 20  unctions are.** 
34c60 64 65 74 65 72 6d 69 6e 69 73 74 69 63 2e 20 20  deterministic.  
34c70 54 68 65 20 62 75 69 6c 74 2d 69 6e 20 5b 72 61  The built-in [ra
34c80 6e 64 6f 6d 28 29 5d 20 53 51 4c 20 66 75 6e 63  ndom()] SQL func
34c90 74 69 6f 6e 20 69 73 20 61 6e 20 65 78 61 6d 70  tion is an examp
34ca0 6c 65 20 6f 66 20 61 0a 2a 2a 20 66 75 6e 63 74  le of a.** funct
34cb0 69 6f 6e 20 74 68 61 74 20 69 73 20 6e 6f 74 20  ion that is not 
34cc0 64 65 74 65 72 6d 69 6e 69 73 74 69 63 2e 20 20  deterministic.  
34cd0 54 68 65 20 53 51 4c 69 74 65 20 71 75 65 72 79  The SQLite query
34ce0 20 70 6c 61 6e 6e 65 72 20 69 73 20 61 62 6c 65   planner is able
34cf0 20 74 6f 0a 2a 2a 20 70 65 72 66 6f 72 6d 20 61   to.** perform a
34d00 64 64 69 74 69 6f 6e 61 6c 20 6f 70 74 69 6d 69  dditional optimi
34d10 7a 61 74 69 6f 6e 73 20 6f 6e 20 64 65 74 65 72  zations on deter
34d20 6d 69 6e 69 73 74 69 63 20 66 75 6e 63 74 69 6f  ministic functio
34d30 6e 73 2c 20 73 6f 20 75 73 65 0a 2a 2a 20 6f 66  ns, so use.** of
34d40 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 44 45 54   the [SQLITE_DET
34d50 45 52 4d 49 4e 49 53 54 49 43 5d 20 66 6c 61 67  ERMINISTIC] flag
34d60 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
34d70 77 68 65 72 65 20 70 6f 73 73 69 62 6c 65 2e 0a  where possible..
34d80 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 66 74  **.** ^(The fift
34d90 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  h parameter is a
34da0 6e 20 61 72 62 69 74 72 61 72 79 20 70 6f 69 6e  n arbitrary poin
34db0 74 65 72 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d  ter.  The implem
34dc0 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a  entation of the.
34dd0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20  ** function can 
34de0 67 61 69 6e 20 61 63 63 65 73 73 20 74 6f 20 74  gain access to t
34df0 68 69 73 20 70 6f 69 6e 74 65 72 20 75 73 69 6e  his pointer usin
34e00 67 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f  g [sqlite3_user_
34e10 64 61 74 61 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a  data()].)^.**.**
34e20 20 5e 54 68 65 20 73 69 78 74 68 2c 20 73 65 76   ^The sixth, sev
34e30 65 6e 74 68 20 61 6e 64 20 65 69 67 68 74 68 20  enth and eighth 
34e40 70 61 72 61 6d 65 74 65 72 73 2c 20 78 46 75 6e  parameters, xFun
34e50 63 2c 20 78 53 74 65 70 20 61 6e 64 20 78 46 69  c, xStep and xFi
34e60 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e  nal, are.** poin
34e70 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61  ters to C-langua
34e80 67 65 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61  ge functions tha
34e90 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20  t implement the 
34ea0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a  SQL function or.
34eb0 2a 2a 20 61 67 67 72 65 67 61 74 65 2e 20 5e 41  ** aggregate. ^A
34ec0 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63   scalar SQL func
34ed0 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e  tion requires an
34ee0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
34ef0 6f 66 20 74 68 65 20 78 46 75 6e 63 0a 2a 2a 20  of the xFunc.** 
34f00 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 3b 20 4e  callback only; N
34f10 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 6d 75 73  ULL pointers mus
34f20 74 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74  t be passed as t
34f30 68 65 20 78 53 74 65 70 20 61 6e 64 20 78 46 69  he xStep and xFi
34f40 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  nal.** parameter
34f50 73 2e 20 5e 41 6e 20 61 67 67 72 65 67 61 74 65  s. ^An aggregate
34f60 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65   SQL function re
34f70 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d  quires an implem
34f80 65 6e 74 61 74 69 6f 6e 20 6f 66 20 78 53 74 65  entation of xSte
34f90 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20  p.** and xFinal 
34fa0 61 6e 64 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  and NULL pointer
34fb0 20 6d 75 73 74 20 62 65 20 70 61 73 73 65 64 20   must be passed 
34fc0 66 6f 72 20 78 46 75 6e 63 2e 20 5e 54 6f 20 64  for xFunc. ^To d
34fd0 65 6c 65 74 65 20 61 6e 20 65 78 69 73 74 69 6e  elete an existin
34fe0 67 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f  g.** SQL functio
34ff0 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2c 20  n or aggregate, 
35000 70 61 73 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  pass NULL pointe
35010 72 73 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 65  rs for all three
35020 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c   function.** cal
35030 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28  lbacks..**.** ^(
35040 49 66 20 74 68 65 20 6e 69 6e 74 68 20 70 61 72  If the ninth par
35050 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
35060 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
35070 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 4e 55  n_v2() is not NU
35080 4c 4c 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69  LL,.** then it i
35090 73 20 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72  s destructor for
350a0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
350b0 20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e 20 0a   data pointer. .
350c0 2a 2a 20 54 68 65 20 64 65 73 74 72 75 63 74 6f  ** The destructo
350d0 72 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65  r is invoked whe
350e0 6e 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69  n the function i
350f0 73 20 64 65 6c 65 74 65 64 2c 20 65 69 74 68 65  s deleted, eithe
35100 72 20 62 79 20 62 65 69 6e 67 0a 2a 2a 20 6f 76  r by being.** ov
35110 65 72 6c 6f 61 64 65 64 20 6f 72 20 77 68 65 6e  erloaded or when
35120 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
35130 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e  nnection closes.
35140 29 5e 0a 2a 2a 20 5e 54 68 65 20 64 65 73 74 72  )^.** ^The destr
35150 75 63 74 6f 72 20 69 73 20 61 6c 73 6f 20 69 6e  uctor is also in
35160 76 6f 6b 65 64 20 69 66 20 74 68 65 20 63 61 6c  voked if the cal
35170 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  l to.** sqlite3_
35180 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f  create_function_
35190 76 32 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e  v2() fails..** ^
351a0 57 68 65 6e 20 74 68 65 20 64 65 73 74 72 75 63  When the destruc
351b0 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20  tor callback of 
351c0 74 68 65 20 74 65 6e 74 68 20 70 61 72 61 6d 65  the tenth parame
351d0 74 65 72 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20  ter is invoked, 
351e0 69 74 0a 2a 2a 20 69 73 20 70 61 73 73 65 64 20  it.** is passed 
351f0 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
35200 74 20 77 68 69 63 68 20 69 73 20 61 20 63 6f 70  t which is a cop
35210 79 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  y of the applica
35220 74 69 6f 6e 20 64 61 74 61 20 0a 2a 2a 20 70 6f  tion data .** po
35230 69 6e 74 65 72 20 77 68 69 63 68 20 77 61 73 20  inter which was 
35240 74 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65  the fifth parame
35250 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  ter to sqlite3_c
35260 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76  reate_function_v
35270 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69  2()..**.** ^It i
35280 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 72  s permitted to r
35290 65 67 69 73 74 65 72 20 6d 75 6c 74 69 70 6c 65  egister multiple
352a0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
352b0 20 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20   of the same.** 
352c0 66 75 6e 63 74 69 6f 6e 73 20 77 69 74 68 20 74  functions with t
352d0 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74  he same name but
352e0 20 77 69 74 68 20 65 69 74 68 65 72 20 64 69 66   with either dif
352f0 66 65 72 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f  fering numbers o
35300 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f  f.** arguments o
35310 72 20 64 69 66 66 65 72 69 6e 67 20 70 72 65 66  r differing pref
35320 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64  erred text encod
35330 69 6e 67 73 2e 20 20 5e 53 51 4c 69 74 65 20 77  ings.  ^SQLite w
35340 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20 69  ill use.** the i
35350 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74 68  mplementation th
35360 61 74 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20  at most closely 
35370 6d 61 74 63 68 65 73 20 74 68 65 20 77 61 79 20  matches the way 
35380 69 6e 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20  in which the.** 
35390 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  SQL function is 
353a0 75 73 65 64 2e 20 20 5e 41 20 66 75 6e 63 74 69  used.  ^A functi
353b0 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  on implementatio
353c0 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d 6e 65 67  n with a non-neg
353d0 61 74 69 76 65 0a 2a 2a 20 6e 41 72 67 20 70 61  ative.** nArg pa
353e0 72 61 6d 65 74 65 72 20 69 73 20 61 20 62 65 74  rameter is a bet
353f0 74 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61  ter match than a
35400 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
35410 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 0a 2a 2a  entation with.**
35420 20 61 20 6e 65 67 61 74 69 76 65 20 6e 41 72 67   a negative nArg
35430 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77  .  ^A function w
35440 68 65 72 65 20 74 68 65 20 70 72 65 66 65 72 72  here the preferr
35450 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  ed text encoding
35460 0a 2a 2a 20 6d 61 74 63 68 65 73 20 74 68 65 20  .** matches the 
35470 64 61 74 61 62 61 73 65 20 65 6e 63 6f 64 69 6e  database encodin
35480 67 20 69 73 20 61 20 62 65 74 74 65 72 0a 2a 2a  g is a better.**
35490 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75   match than a fu
354a0 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65  nction where the
354b0 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66   encoding is dif
354c0 66 65 72 65 6e 74 2e 20 20 0a 2a 2a 20 5e 41 20  ferent.  .** ^A 
354d0 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74  function where t
354e0 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66  he encoding diff
354f0 65 72 65 6e 63 65 20 69 73 20 62 65 74 77 65 65  erence is betwee
35500 6e 20 55 54 46 31 36 6c 65 20 61 6e 64 20 55 54  n UTF16le and UT
35510 46 31 36 62 65 0a 2a 2a 20 69 73 20 61 20 63 6c  F16be.** is a cl
35520 6f 73 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20  oser match than 
35530 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65  a function where
35540 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69   the encoding di
35550 66 66 65 72 65 6e 63 65 20 69 73 0a 2a 2a 20 62  fference is.** b
35560 65 74 77 65 65 6e 20 55 54 46 38 20 61 6e 64 20  etween UTF8 and 
35570 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75  UTF16..**.** ^Bu
35580 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73  ilt-in functions
35590 20 6d 61 79 20 62 65 20 6f 76 65 72 6c 6f 61 64   may be overload
355a0 65 64 20 62 79 20 6e 65 77 20 61 70 70 6c 69 63  ed by new applic
355b0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
355c0 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  nctions..**.** ^
355d0 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  An application-d
355e0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
355f0 69 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20  is permitted to 
35600 63 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 53 51  call other.** SQ
35610 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 2e  Lite interfaces.
35620 20 20 48 6f 77 65 76 65 72 2c 20 73 75 63 68 20    However, such 
35630 63 61 6c 6c 73 20 6d 75 73 74 20 6e 6f 74 0a 2a  calls must not.*
35640 2a 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61  * close the data
35650 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
35660 6e 6f 72 20 66 69 6e 61 6c 69 7a 65 20 6f 72 20  nor finalize or 
35670 72 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72  reset the prepar
35680 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  ed.** statement 
35690 69 6e 20 77 68 69 63 68 20 74 68 65 20 66 75 6e  in which the fun
356a0 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67  ction is running
356b0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
356c0 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41  int SQLITE_STDCA
356d0 4c 4c 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  LL sqlite3_creat
356e0 65 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71  e_function(.  sq
356f0 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e  lite3 *db,.  con
35700 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69  st char *zFuncti
35710 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41  onName,.  int nA
35720 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52  rg,.  int eTextR
35730 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70  ep,.  void *pApp
35740 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63  ,.  void (*xFunc
35750 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
35760 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
35770 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
35780 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33  (*xStep)(sqlite3
35790 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
357a0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
357b0 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29    void (*xFinal)
357c0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
357d0 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  *).);.SQLITE_API
357e0 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43   int SQLITE_STDC
357f0 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 72 65 61  ALL sqlite3_crea
35800 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20  te_function16(. 
35810 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20   sqlite3 *db,.  
35820 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e  const void *zFun
35830 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74  ctionName,.  int
35840 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65   nArg,.  int eTe
35850 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70  xtRep,.  void *p
35860 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  App,.  void (*xF
35870 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  unc)(sqlite3_con
35880 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
35890 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
358a0 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69  id (*xStep)(sqli
358b0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
358c0 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
358d0 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e  ),.  void (*xFin
358e0 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  al)(sqlite3_cont
358f0 65 78 74 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f  ext*).);.SQLITE_
35900 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  API int SQLITE_S
35910 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63  TDCALL sqlite3_c
35920 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76  reate_function_v
35930 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  2(.  sqlite3 *db
35940 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  ,.  const char *
35950 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20  zFunctionName,. 
35960 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74   int nArg,.  int
35970 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69   eTextRep,.  voi
35980 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20  d *pApp,.  void 
35990 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33  (*xFunc)(sqlite3
359a0 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
359b0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
359c0 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28    void (*xStep)(
359d0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
359e0 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
359f0 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
35a00 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f  xFinal)(sqlite3_
35a10 63 6f 6e 74 65 78 74 2a 29 2c 0a 20 20 76 6f 69  context*),.  voi
35a20 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69  d(*xDestroy)(voi
35a30 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  d*).);../*.** CA
35a40 50 49 33 52 45 46 3a 20 54 65 78 74 20 45 6e 63  PI3REF: Text Enc
35a50 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65  odings.**.** The
35a60 73 65 20 63 6f 6e 73 74 61 6e 74 20 64 65 66 69  se constant defi
35a70 6e 65 20 69 6e 74 65 67 65 72 20 63 6f 64 65 73  ne integer codes
35a80 20 74 68 61 74 20 72 65 70 72 65 73 65 6e 74 20   that represent 
35a90 74 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20 74  the various.** t
35aa0 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 20 73 75  ext encodings su
35ab0 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74  pported by SQLit
35ac0 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  e..*/.#define SQ
35ad0 4c 49 54 45 5f 55 54 46 38 20 20 20 20 20 20 20  LITE_UTF8       
35ae0 20 20 20 20 31 20 20 20 20 2f 2a 20 49 4d 50 3a      1    /* IMP:
35af0 20 52 2d 33 37 35 31 34 2d 33 35 35 36 36 20 2a   R-37514-35566 *
35b00 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
35b10 5f 55 54 46 31 36 4c 45 20 20 20 20 20 20 20 20  _UTF16LE        
35b20 32 20 20 20 20 2f 2a 20 49 4d 50 3a 20 52 2d 30  2    /* IMP: R-0
35b30 33 33 37 31 2d 33 37 36 33 37 20 2a 2f 0a 23 64  3371-37637 */.#d
35b40 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46  efine SQLITE_UTF
35b50 31 36 42 45 20 20 20 20 20 20 20 20 33 20 20 20  16BE        3   
35b60 20 2f 2a 20 49 4d 50 3a 20 52 2d 35 31 39 37 31   /* IMP: R-51971
35b70 2d 33 34 31 35 34 20 2a 2f 0a 23 64 65 66 69 6e  -34154 */.#defin
35b80 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 20 20  e SQLITE_UTF16  
35b90 20 20 20 20 20 20 20 20 34 20 20 20 20 2f 2a 20          4    /* 
35ba0 55 73 65 20 6e 61 74 69 76 65 20 62 79 74 65 20  Use native byte 
35bb0 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65  order */.#define
35bc0 20 53 51 4c 49 54 45 5f 41 4e 59 20 20 20 20 20   SQLITE_ANY     
35bd0 20 20 20 20 20 20 20 35 20 20 20 20 2f 2a 20 44         5    /* D
35be0 65 70 72 65 63 61 74 65 64 20 2a 2f 0a 23 64 65  eprecated */.#de
35bf0 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31  fine SQLITE_UTF1
35c00 36 5f 41 4c 49 47 4e 45 44 20 20 38 20 20 20 20  6_ALIGNED  8    
35c10 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  /* sqlite3_creat
35c20 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79  e_collation only
35c30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
35c40 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 46 6c  REF: Function Fl
35c50 61 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ags.**.** These 
35c60 63 6f 6e 73 74 61 6e 74 73 20 6d 61 79 20 62 65  constants may be
35c70 20 4f 52 65 64 20 74 6f 67 65 74 68 65 72 20 77   ORed together w
35c80 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c  ith the .** [SQL
35c90 49 54 45 5f 55 54 46 38 20 7c 20 70 72 65 66 65  ITE_UTF8 | prefe
35ca0 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69  rred text encodi
35cb0 6e 67 5d 20 61 73 20 74 68 65 20 66 6f 75 72 74  ng] as the fourt
35cc0 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f  h argument.** to
35cd0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
35ce0 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 5b 73  _function()], [s
35cf0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
35d00 6e 63 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a  nction16()], or.
35d10 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  ** [sqlite3_crea
35d20 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29  te_function_v2()
35d30 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ]..*/.#define SQ
35d40 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54  LITE_DETERMINIST
35d50 49 43 20 20 20 20 30 78 38 30 30 0a 0a 2f 2a 0a  IC    0x800../*.
35d60 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 70  ** CAPI3REF: Dep
35d70 72 65 63 61 74 65 64 20 46 75 6e 63 74 69 6f 6e  recated Function
35d80 73 0a 2a 2a 20 44 45 50 52 45 43 41 54 45 44 0a  s.** DEPRECATED.
35d90 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63  **.** These func
35da0 74 69 6f 6e 73 20 61 72 65 20 5b 64 65 70 72 65  tions are [depre
35db0 63 61 74 65 64 5d 2e 20 20 49 6e 20 6f 72 64 65  cated].  In orde
35dc0 72 20 74 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a  r to maintain.**
35dd0 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
35de0 74 69 62 69 6c 69 74 79 20 77 69 74 68 20 6f 6c  tibility with ol
35df0 64 65 72 20 63 6f 64 65 2c 20 74 68 65 73 65 20  der code, these 
35e00 66 75 6e 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e  functions contin
35e10 75 65 20 0a 2a 2a 20 74 6f 20 62 65 20 73 75 70  ue .** to be sup
35e20 70 6f 72 74 65 64 2e 20 20 48 6f 77 65 76 65 72  ported.  However
35e30 2c 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f  , new applicatio
35e40 6e 73 20 73 68 6f 75 6c 64 20 61 76 6f 69 64 0a  ns should avoid.
35e50 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20 74 68  ** the use of th
35e60 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20  ese functions.  
35e70 54 6f 20 65 6e 63 6f 75 72 61 67 65 20 70 72 6f  To encourage pro
35e80 67 72 61 6d 6d 65 72 73 20 74 6f 20 61 76 6f 69  grammers to avoi
35e90 64 0a 2a 2a 20 74 68 65 73 65 20 66 75 6e 63 74  d.** these funct
35ea0 69 6f 6e 73 2c 20 77 65 20 77 69 6c 6c 20 6e 6f  ions, we will no
35eb0 74 20 65 78 70 6c 61 69 6e 20 77 68 61 74 20 74  t explain what t
35ec0 68 65 79 20 64 6f 2e 0a 2a 2f 0a 23 69 66 6e 64  hey do..*/.#ifnd
35ed0 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 44  ef SQLITE_OMIT_D
35ee0 45 50 52 45 43 41 54 45 44 0a 53 51 4c 49 54 45  EPRECATED.SQLITE
35ef0 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52  _API SQLITE_DEPR
35f00 45 43 41 54 45 44 20 69 6e 74 20 53 51 4c 49 54  ECATED int SQLIT
35f10 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
35f20 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 75 6e  3_aggregate_coun
35f30 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t(sqlite3_contex
35f40 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  t*);.SQLITE_API 
35f50 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
35f60 44 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  D int SQLITE_STD
35f70 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 65 78 70  CALL sqlite3_exp
35f80 69 72 65 64 28 73 71 6c 69 74 65 33 5f 73 74 6d  ired(sqlite3_stm
35f90 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  t*);.SQLITE_API 
35fa0 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
35fb0 44 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  D int SQLITE_STD
35fc0 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 74 72 61  CALL sqlite3_tra
35fd0 6e 73 66 65 72 5f 62 69 6e 64 69 6e 67 73 28 73  nsfer_bindings(s
35fe0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71  qlite3_stmt*, sq
35ff0 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51  lite3_stmt*);.SQ
36000 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f  LITE_API SQLITE_
36010 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 53  DEPRECATED int S
36020 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
36030 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63  lite3_global_rec
36040 6f 76 65 72 28 76 6f 69 64 29 3b 0a 53 51 4c 49  over(void);.SQLI
36050 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45  TE_API SQLITE_DE
36060 50 52 45 43 41 54 45 44 20 76 6f 69 64 20 53 51  PRECATED void SQ
36070 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
36080 69 74 65 33 5f 74 68 72 65 61 64 5f 63 6c 65 61  ite3_thread_clea
36090 6e 75 70 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54  nup(void);.SQLIT
360a0 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50  E_API SQLITE_DEP
360b0 52 45 43 41 54 45 44 20 69 6e 74 20 53 51 4c 49  RECATED int SQLI
360c0 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
360d0 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28  e3_memory_alarm(
360e0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71  void(*)(void*,sq
360f0 6c 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29  lite3_int64,int)
36100 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
36110 20 20 20 20 20 20 20 20 76 6f 69 64 2a 2c 73 71          void*,sq
36120 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 23 65  lite3_int64);.#e
36130 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
36140 33 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20  3REF: Obtaining 
36150 53 51 4c 20 56 61 6c 75 65 73 0a 2a 2a 20 4d 45  SQL Values.** ME
36160 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 76 61  THOD: sqlite3_va
36170 6c 75 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d  lue.**.** The C-
36180 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d 65  language impleme
36190 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66  ntation of SQL f
361a0 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67  unctions and agg
361b0 72 65 67 61 74 65 73 20 75 73 65 73 0a 2a 2a 20  regates uses.** 
361c0 74 68 69 73 20 73 65 74 20 6f 66 20 69 6e 74 65  this set of inte
361d0 72 66 61 63 65 20 72 6f 75 74 69 6e 65 73 20 74  rface routines t
361e0 6f 20 61 63 63 65 73 73 20 74 68 65 20 70 61 72  o access the par
361f0 61 6d 65 74 65 72 20 76 61 6c 75 65 73 20 6f 6e  ameter values on
36200 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  .** the function
36210 20 6f 72 20 61 67 67 72 65 67 61 74 65 2e 20 20   or aggregate.  
36220 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63  .**.** The xFunc
36230 20 28 66 6f 72 20 73 63 61 6c 61 72 20 66 75 6e   (for scalar fun
36240 63 74 69 6f 6e 73 29 20 6f 72 20 78 53 74 65 70  ctions) or xStep
36250 20 28 66 6f 72 20 61 67 67 72 65 67 61 74 65 73   (for aggregates
36260 29 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20  ) parameters.** 
36270 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  to [sqlite3_crea
36280 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61  te_function()] a
36290 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  nd [sqlite3_crea
362a0 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d  te_function16()]
362b0 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c 62  .** define callb
362c0 61 63 6b 73 20 74 68 61 74 20 69 6d 70 6c 65 6d  acks that implem
362d0 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63  ent the SQL func
362e0 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67  tions and aggreg
362f0 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20 33 72 64  ates..** The 3rd
36300 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
36310 65 73 65 20 63 61 6c 6c 62 61 63 6b 73 20 69 73  ese callbacks is
36320 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
36330 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f  nters to.** [pro
36340 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
36350 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20  alue] objects.  
36360 54 68 65 72 65 20 69 73 20 6f 6e 65 20 5b 73 71  There is one [sq
36370 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
36380 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20  ect for.** each 
36390 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
363a0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20   SQL function.  
363b0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
363c0 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78  re used to.** ex
363d0 74 72 61 63 74 20 76 61 6c 75 65 73 20 66 72 6f  tract values fro
363e0 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  m the [sqlite3_v
363f0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  alue] objects..*
36400 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
36410 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69  nes work only wi
36420 74 68 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71  th [protected sq
36430 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
36440 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74  ects..** Any att
36450 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65 73  empt to use thes
36460 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e  e routines on an
36470 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
36480 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20  lite3_value].** 
36490 6f 62 6a 65 63 74 20 72 65 73 75 6c 74 73 20 69  object results i
364a0 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61  n undefined beha
364b0 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  vior..**.** ^The
364c0 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b  se routines work
364d0 20 6a 75 73 74 20 6c 69 6b 65 20 74 68 65 20 63   just like the c
364e0 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63 6f  orresponding [co
364f0 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63  lumn access func
36500 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 74  tions].** except
36510 20 74 68 61 74 20 74 68 65 73 65 20 72 6f 75 74   that these rout
36520 69 6e 65 73 20 74 61 6b 65 20 61 20 73 69 6e 67  ines take a sing
36530 6c 65 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71  le [protected sq
36540 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
36550 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69  ect.** pointer i
36560 6e 73 74 65 61 64 20 6f 66 20 61 20 5b 73 71 6c  nstead of a [sql
36570 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e  ite3_stmt*] poin
36580 74 65 72 20 61 6e 64 20 61 6e 20 69 6e 74 65 67  ter and an integ
36590 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72  er column number
365a0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
365b0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
365c0 36 28 29 20 69 6e 74 65 72 66 61 63 65 20 65 78  6() interface ex
365d0 74 72 61 63 74 73 20 61 20 55 54 46 2d 31 36 20  tracts a UTF-16 
365e0 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65  string.** in the
365f0 20 6e 61 74 69 76 65 20 62 79 74 65 2d 6f 72 64   native byte-ord
36600 65 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20 6d  er of the host m
36610 61 63 68 69 6e 65 2e 20 20 5e 54 68 65 0a 2a 2a  achine.  ^The.**
36620 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
36630 65 78 74 31 36 62 65 28 29 20 61 6e 64 20 73 71  ext16be() and sq
36640 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
36650 31 36 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65  16le() interface
36660 73 0a 2a 2a 20 65 78 74 72 61 63 74 20 55 54 46  s.** extract UTF
36670 2d 31 36 20 73 74 72 69 6e 67 73 20 61 73 20 62  -16 strings as b
36680 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69  ig-endian and li
36690 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73 70  ttle-endian resp
366a0 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ectively..**.** 
366b0 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61  ^(The sqlite3_va
366c0 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65  lue_numeric_type
366d0 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74  () interface att
366e0 65 6d 70 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a  empts to apply.*
366f0 2a 20 6e 75 6d 65 72 69 63 20 61 66 66 69 6e 69  * numeric affini
36700 74 79 20 74 6f 20 74 68 65 20 76 61 6c 75 65 2e  ty to the value.
36710 20 20 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61    This means tha
36720 74 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 0a  t an attempt is.
36730 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65  ** made to conve
36740 72 74 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20  rt the value to 
36750 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 20 66 6c  an integer or fl
36760 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49  oating point.  I
36770 66 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e 76  f.** such a conv
36780 65 72 73 69 6f 6e 20 69 73 20 70 6f 73 73 69 62  ersion is possib
36790 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f 73 73 20  le without loss 
367a0 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28  of information (
367b0 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64  in other.** word
367c0 73 2c 20 69 66 20 74 68 65 20 76 61 6c 75 65 20  s, if the value 
367d0 69 73 20 61 20 73 74 72 69 6e 67 20 74 68 61 74  is a string that
367e0 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75   looks like a nu
367f0 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68  mber).** then th
36800 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20  e conversion is 
36810 70 65 72 66 6f 72 6d 65 64 2e 20 20 4f 74 68 65  performed.  Othe
36820 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73  rwise no convers
36830 69 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a 20 54  ion occurs..** T
36840 68 65 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47  he [SQLITE_INTEG
36850 45 52 20 7c 20 64 61 74 61 74 79 70 65 5d 20 61  ER | datatype] a
36860 66 74 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20  fter conversion 
36870 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a  is returned.)^.*
36880 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61 79 20  *.** Please pay 
36890 70 61 72 74 69 63 75 6c 61 72 20 61 74 74 65 6e  particular atten
368a0 74 69 6f 6e 20 74 6f 20 74 68 65 20 66 61 63 74  tion to the fact
368b0 20 74 68 61 74 20 74 68 65 20 70 6f 69 6e 74 65   that the pointe
368c0 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72  r returned.** fr
368d0 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  om [sqlite3_valu
368e0 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69  e_blob()], [sqli
368f0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29  te3_value_text()
36900 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ], or.** [sqlite
36910 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29  3_value_text16()
36920 5d 20 63 61 6e 20 62 65 20 69 6e 76 61 6c 69 64  ] can be invalid
36930 61 74 65 64 20 62 79 20 61 20 73 75 62 73 65 71  ated by a subseq
36940 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  uent call to.** 
36950 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
36960 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65  ytes()], [sqlite
36970 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28  3_value_bytes16(
36980 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  )], [sqlite3_val
36990 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f  ue_text()],.** o
369a0 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  r [sqlite3_value
369b0 5f 74 65 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a  _text16()]..**.*
369c0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
369d0 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
369e0 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68  from the same th
369f0 72 65 61 64 20 61 73 0a 2a 2a 20 74 68 65 20 53  read as.** the S
36a00 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74  QL function that
36a10 20 73 75 70 70 6c 69 65 64 20 74 68 65 20 5b 73   supplied the [s
36a20 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70  qlite3_value*] p
36a30 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a 53 51  arameters..*/.SQ
36a40 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76  LITE_API const v
36a50 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43  oid *SQLITE_STDC
36a60 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ALL sqlite3_valu
36a70 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 76  e_blob(sqlite3_v
36a80 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41  alue*);.SQLITE_A
36a90 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54  PI int SQLITE_ST
36aa0 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61  DCALL sqlite3_va
36ab0 6c 75 65 5f 62 79 74 65 73 28 73 71 6c 69 74 65  lue_bytes(sqlite
36ac0 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54  3_value*);.SQLIT
36ad0 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45  E_API int SQLITE
36ae0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
36af0 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 73  _value_bytes16(s
36b00 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
36b10 53 51 4c 49 54 45 5f 41 50 49 20 64 6f 75 62 6c  SQLITE_API doubl
36b20 65 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  e SQLITE_STDCALL
36b30 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64   sqlite3_value_d
36b40 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 76 61  ouble(sqlite3_va
36b50 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  lue*);.SQLITE_AP
36b60 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  I int SQLITE_STD
36b70 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c  CALL sqlite3_val
36b80 75 65 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 76  ue_int(sqlite3_v
36b90 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41  alue*);.SQLITE_A
36ba0 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  PI sqlite3_int64
36bb0 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
36bc0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e  sqlite3_value_in
36bd0 74 36 34 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  t64(sqlite3_valu
36be0 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  e*);.SQLITE_API 
36bf0 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63  const unsigned c
36c00 68 61 72 20 2a 53 51 4c 49 54 45 5f 53 54 44 43  har *SQLITE_STDC
36c10 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ALL sqlite3_valu
36c20 65 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 76  e_text(sqlite3_v
36c30 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41  alue*);.SQLITE_A
36c40 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53  PI const void *S
36c50 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
36c60 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
36c70 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  16(sqlite3_value
36c80 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  *);.SQLITE_API c
36c90 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51 4c 49 54  onst void *SQLIT
36ca0 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
36cb0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65  3_value_text16le
36cc0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
36cd0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  ;.SQLITE_API con
36ce0 73 74 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f  st void *SQLITE_
36cf0 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
36d00 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 73  value_text16be(s
36d10 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
36d20 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53  SQLITE_API int S
36d30 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
36d40 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65  lite3_value_type
36d50 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
36d60 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
36d70 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
36d80 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75  sqlite3_value_nu
36d90 6d 65 72 69 63 5f 74 79 70 65 28 73 71 6c 69 74  meric_type(sqlit
36da0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a  e3_value*);../*.
36db0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6e  ** CAPI3REF: Fin
36dc0 64 69 6e 67 20 54 68 65 20 53 75 62 74 79 70 65  ding The Subtype
36dd0 20 4f 66 20 53 51 4c 20 56 61 6c 75 65 73 0a 2a   Of SQL Values.*
36de0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
36df0 33 5f 76 61 6c 75 65 0a 2a 2a 0a 2a 2a 20 54 68  3_value.**.** Th
36e00 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  e sqlite3_value_
36e10 73 75 62 74 79 70 65 28 56 29 20 66 75 6e 63 74  subtype(V) funct
36e20 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  ion returns the 
36e30 73 75 62 74 79 70 65 20 66 6f 72 0a 2a 2a 20 61  subtype for.** a
36e40 6e 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  n [application-d
36e50 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
36e60 69 6f 6e 5d 20 61 72 67 75 6d 65 6e 74 20 56 2e  ion] argument V.
36e70 20 20 54 68 65 20 73 75 62 74 79 70 65 0a 2a 2a    The subtype.**
36e80 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 63 61 6e   information can
36e90 20 62 65 20 75 73 65 64 20 74 6f 20 70 61 73 73   be used to pass
36ea0 20 61 20 6c 69 6d 69 74 65 64 20 61 6d 6f 75 6e   a limited amoun
36eb0 74 20 6f 66 20 63 6f 6e 74 65 78 74 20 66 72 6f  t of context fro
36ec0 6d 0a 2a 2a 20 6f 6e 65 20 53 51 4c 20 66 75 6e  m.** one SQL fun
36ed0 63 74 69 6f 6e 20 74 6f 20 61 6e 6f 74 68 65 72  ction to another
36ee0 2e 20 20 55 73 65 20 74 68 65 20 5b 73 71 6c 69  .  Use the [sqli
36ef0 74 65 33 5f 72 65 73 75 6c 74 5f 73 75 62 74 79  te3_result_subty
36f00 70 65 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65  pe()].** routine
36f10 20 74 6f 20 73 65 74 20 74 68 65 20 73 75 62 74   to set the subt
36f20 79 70 65 20 66 6f 72 20 74 68 65 20 72 65 74 75  ype for the retu
36f30 72 6e 20 76 61 6c 75 65 20 6f 66 20 61 6e 20 53  rn value of an S
36f40 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a  QL function..**.
36f50 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20  ** SQLite makes 
36f60 6e 6f 20 75 73 65 20 6f 66 20 73 75 62 74 79 70  no use of subtyp
36f70 65 20 69 74 73 65 6c 66 2e 20 20 49 74 20 6d 65  e itself.  It me
36f80 72 65 6c 79 20 70 61 73 73 65 73 20 74 68 65 20  rely passes the 
36f90 73 75 62 74 79 70 65 0a 2a 2a 20 66 72 6f 6d 20  subtype.** from 
36fa0 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20 6f 6e  the result of on
36fb0 65 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  e [application-d
36fc0 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
36fd0 69 6f 6e 5d 20 69 6e 74 6f 20 74 68 65 0a 2a 2a  ion] into the.**
36fe0 20 69 6e 70 75 74 20 6f 66 20 61 6e 6f 74 68 65   input of anothe
36ff0 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  r..*/.SQLITE_API
37000 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 20 53 51   unsigned int SQ
37010 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
37020 69 74 65 33 5f 76 61 6c 75 65 5f 73 75 62 74 79  ite3_value_subty
37030 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  pe(sqlite3_value
37040 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
37050 52 45 46 3a 20 43 6f 70 79 20 41 6e 64 20 46 72  REF: Copy And Fr
37060 65 65 20 53 51 4c 20 56 61 6c 75 65 73 0a 2a 2a  ee SQL Values.**
37070 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
37080 5f 76 61 6c 75 65 0a 2a 2a 0a 2a 2a 20 5e 54 68  _value.**.** ^Th
37090 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  e sqlite3_value_
370a0 64 75 70 28 56 29 20 69 6e 74 65 72 66 61 63 65  dup(V) interface
370b0 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66   makes a copy of
370c0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   the [sqlite3_va
370d0 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 44  lue].** object D
370e0 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70   and returns a p
370f0 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20 63  ointer to that c
37100 6f 70 79 2e 20 20 5e 54 68 65 20 5b 73 71 6c 69  opy.  ^The [sqli
37110 74 65 33 5f 76 61 6c 75 65 5d 20 72 65 74 75 72  te3_value] retur
37120 6e 65 64 0a 2a 2a 20 69 73 20 61 20 5b 70 72 6f  ned.** is a [pro
37130 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
37140 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 65 76 65  alue] object eve
37150 6e 20 69 66 20 74 68 65 20 69 6e 70 75 74 20 69  n if the input i
37160 73 20 6e 6f 74 2e 0a 2a 2a 20 5e 54 68 65 20 73  s not..** ^The s
37170 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75 70  qlite3_value_dup
37180 28 56 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  (V) interface re
37190 74 75 72 6e 73 20 4e 55 4c 4c 20 69 66 20 56 20  turns NULL if V 
371a0 69 73 20 4e 55 4c 4c 20 6f 72 20 69 66 20 61 0a  is NULL or if a.
371b0 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ** memory alloca
371c0 74 69 6f 6e 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a  tion fails..**.*
371d0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76  * ^The sqlite3_v
371e0 61 6c 75 65 5f 66 72 65 65 28 56 29 20 69 6e 74  alue_free(V) int
371f0 65 72 66 61 63 65 20 66 72 65 65 73 20 61 6e 20  erface frees an 
37200 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20  [sqlite3_value] 
37210 6f 62 6a 65 63 74 0a 2a 2a 20 70 72 65 76 69 6f  object.** previo
37220 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72  usly obtained fr
37230 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  om [sqlite3_valu
37240 65 5f 64 75 70 28 29 5d 2e 20 20 5e 49 66 20 56  e_dup()].  ^If V
37250 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
37260 65 72 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74  er.** then sqlit
37270 65 33 5f 76 61 6c 75 65 5f 66 72 65 65 28 56 29  e3_value_free(V)
37280 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e   is a harmless n
37290 6f 2d 6f 70 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  o-op..*/.SQLITE_
372a0 41 50 49 20 53 51 4c 49 54 45 5f 45 58 50 45 52  API SQLITE_EXPER
372b0 49 4d 45 4e 54 41 4c 20 73 71 6c 69 74 65 33 5f  IMENTAL sqlite3_
372c0 76 61 6c 75 65 20 2a 53 51 4c 49 54 45 5f 53 54  value *SQLITE_ST
372d0 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61  DCALL sqlite3_va
372e0 6c 75 65 5f 64 75 70 28 63 6f 6e 73 74 20 73 71  lue_dup(const sq
372f0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53  lite3_value*);.S
37300 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45  QLITE_API SQLITE
37310 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 76 6f  _EXPERIMENTAL vo
37320 69 64 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  id SQLITE_STDCAL
37330 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  L sqlite3_value_
37340 66 72 65 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  free(sqlite3_val
37350 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ue*);../*.** CAP
37360 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 41 67  I3REF: Obtain Ag
37370 67 72 65 67 61 74 65 20 46 75 6e 63 74 69 6f 6e  gregate Function
37380 20 43 6f 6e 74 65 78 74 0a 2a 2a 20 4d 45 54 48   Context.** METH
37390 4f 44 3a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  OD: sqlite3_cont
373a0 65 78 74 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c 65 6d  ext.**.** Implem
373b0 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 61 67 67  entations of agg
373c0 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74  regate SQL funct
373d0 69 6f 6e 73 20 75 73 65 20 74 68 69 73 0a 2a 2a  ions use this.**
373e0 20 72 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f   routine to allo
373f0 63 61 74 65 20 6d 65 6d 6f 72 79 20 66 6f 72 20  cate memory for 
37400 73 74 6f 72 69 6e 67 20 74 68 65 69 72 20 73 74  storing their st
37410 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ate..**.** ^The 
37420 66 69 72 73 74 20 74 69 6d 65 20 74 68 65 20 73  first time the s
37430 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
37440 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f  _context(C,N) ro
37450 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20  utine is called 
37460 0a 2a 2a 20 66 6f 72 20 61 20 70 61 72 74 69 63  .** for a partic
37470 75 6c 61 72 20 61 67 67 72 65 67 61 74 65 20 66  ular aggregate f
37480 75 6e 63 74 69 6f 6e 2c 20 53 51 4c 69 74 65 0a  unction, SQLite.
37490 2a 2a 20 61 6c 6c 6f 63 61 74 65 73 20 4e 20 6f  ** allocates N o
374a0 66 20 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f 65 73  f memory, zeroes
374b0 20 6f 75 74 20 74 68 61 74 20 6d 65 6d 6f 72 79   out that memory
374c0 2c 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20  , and returns a 
374d0 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68  pointer.** to th
374e0 65 20 6e 65 77 20 6d 65 6d 6f 72 79 2e 20 5e 4f  e new memory. ^O
374f0 6e 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62  n second and sub
37500 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
37510 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72  .** sqlite3_aggr
37520 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20  egate_context() 
37530 66 6f 72 20 74 68 65 20 73 61 6d 65 20 61 67 67  for the same agg
37540 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20  regate function 
37550 69 6e 73 74 61 6e 63 65 2c 0a 2a 2a 20 74 68 65  instance,.** the
37560 20 73 61 6d 65 20 62 75 66 66 65 72 20 69 73 20   same buffer is 
37570 72 65 74 75 72 6e 65 64 2e 20 20 53 71 6c 69 74  returned.  Sqlit
37580 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
37590 74 65 78 74 28 29 20 69 73 20 6e 6f 72 6d 61 6c  text() is normal
375a0 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 6f 6e 63  ly.** called onc
375b0 65 20 66 6f 72 20 65 61 63 68 20 69 6e 76 6f 63  e for each invoc
375c0 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 53 74  ation of the xSt
375d0 65 70 20 63 61 6c 6c 62 61 63 6b 20 61 6e 64 20  ep callback and 
375e0 74 68 65 6e 20 6f 6e 65 0a 2a 2a 20 6c 61 73 74  then one.** last
375f0 20 74 69 6d 65 20 77 68 65 6e 20 74 68 65 20 78   time when the x
37600 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 69  Final callback i
37610 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 28 57 68  s invoked.  ^(Wh
37620 65 6e 20 6e 6f 20 72 6f 77 73 20 6d 61 74 63 68  en no rows match
37630 0a 2a 2a 20 61 6e 20 61 67 67 72 65 67 61 74 65  .** an aggregate
37640 20 71 75 65 72 79 2c 20 74 68 65 20 78 53 74 65   query, the xSte
37650 70 28 29 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20  p() callback of 
37660 74 68 65 20 61 67 67 72 65 67 61 74 65 20 66 75  the aggregate fu
37670 6e 63 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d  nction.** implem
37680 65 6e 74 61 74 69 6f 6e 20 69 73 20 6e 65 76 65  entation is neve
37690 72 20 63 61 6c 6c 65 64 20 61 6e 64 20 78 46 69  r called and xFi
376a0 6e 61 6c 28 29 20 69 73 20 63 61 6c 6c 65 64 20  nal() is called 
376b0 65 78 61 63 74 6c 79 20 6f 6e 63 65 2e 0a 2a 2a  exactly once..**
376c0 20 49 6e 20 74 68 6f 73 65 20 63 61 73 65 73 2c   In those cases,
376d0 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
376e0 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 6d 69 67  te_context() mig
376f0 68 74 20 62 65 20 63 61 6c 6c 65 64 20 66 6f 72  ht be called for
37700 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 69   the.** first ti
37710 6d 65 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 78  me from within x
37720 46 69 6e 61 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a  Final().)^.**.**
37730 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 61 67   ^The sqlite3_ag
37740 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
37750 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20 72 65 74  C,N) routine ret
37760 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  urns a NULL poin
37770 74 65 72 20 0a 2a 2a 20 77 68 65 6e 20 66 69 72  ter .** when fir
37780 73 74 20 63 61 6c 6c 65 64 20 69 66 20 4e 20 69  st called if N i
37790 73 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65  s less than or e
377a0 71 75 61 6c 20 74 6f 20 7a 65 72 6f 20 6f 72 20  qual to zero or 
377b0 69 66 20 61 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61  if a memory.** a
377c0 6c 6c 6f 63 61 74 65 20 65 72 72 6f 72 20 6f 63  llocate error oc
377d0 63 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  curs..**.** ^(Th
377e0 65 20 61 6d 6f 75 6e 74 20 6f 66 20 73 70 61 63  e amount of spac
377f0 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73  e allocated by s
37800 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
37810 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 69 73  _context(C,N) is
37820 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 64 20 62  .** determined b
37830 79 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65  y the N paramete
37840 72 20 6f 6e 20 66 69 72 73 74 20 73 75 63 63 65  r on first succe
37850 73 73 66 75 6c 20 63 61 6c 6c 2e 20 20 43 68 61  ssful call.  Cha
37860 6e 67 69 6e 67 20 74 68 65 0a 2a 2a 20 76 61 6c  nging the.** val
37870 75 65 20 6f 66 20 4e 20 69 6e 20 73 75 62 73 65  ue of N in subse
37880 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71  quent call to sq
37890 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
378a0 63 6f 6e 74 65 78 74 28 29 20 77 69 74 68 69 6e  context() within
378b0 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 61 67 67  .** the same agg
378c0 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20  regate function 
378d0 69 6e 73 74 61 6e 63 65 20 77 69 6c 6c 20 6e 6f  instance will no
378e0 74 20 72 65 73 69 7a 65 20 74 68 65 20 6d 65 6d  t resize the mem
378f0 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f  ory.** allocatio
37900 6e 2e 29 5e 20 20 57 69 74 68 69 6e 20 74 68 65  n.)^  Within the
37910 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b   xFinal callback
37920 2c 20 69 74 20 69 73 20 63 75 73 74 6f 6d 61 72  , it is customar
37930 79 20 74 6f 20 73 65 74 0a 2a 2a 20 4e 3d 30 20  y to set.** N=0 
37940 69 6e 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  in calls to sqli
37950 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
37960 6e 74 65 78 74 28 43 2c 4e 29 20 73 6f 20 74 68  ntext(C,N) so th
37970 61 74 20 6e 6f 20 0a 2a 2a 20 70 6f 69 6e 74 6c  at no .** pointl
37980 65 73 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ess memory alloc
37990 61 74 69 6f 6e 73 20 6f 63 63 75 72 2e 0a 2a 2a  ations occur..**
379a0 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 61 75 74 6f  .** ^SQLite auto
379b0 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 65 73 20  matically frees 
379c0 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
379d0 61 74 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69  ated by .** sqli
379e0 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
379f0 6e 74 65 78 74 28 29 20 77 68 65 6e 20 74 68 65  ntext() when the
37a00 20 61 67 67 72 65 67 61 74 65 20 71 75 65 72 79   aggregate query
37a10 20 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a   concludes..**.*
37a20 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61  * The first para
37a30 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20 61 20  meter must be a 
37a40 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b  copy of the.** [
37a50 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20  sqlite3_context 
37a60 7c 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63  | SQL function c
37a70 6f 6e 74 65 78 74 5d 20 74 68 61 74 20 69 73 20  ontext] that is 
37a80 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
37a90 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 78 53  ter.** to the xS
37aa0 74 65 70 20 6f 72 20 78 46 69 6e 61 6c 20 63 61  tep or xFinal ca
37ab0 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 74  llback routine t
37ac0 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74  hat implements t
37ad0 68 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a 20  he aggregate.** 
37ae0 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  function..**.** 
37af0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73  This routine mus
37b00 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  t be called from
37b10 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
37b20 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65   in which.** the
37b30 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66   aggregate SQL f
37b40 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
37b50 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ng..*/.SQLITE_AP
37b60 49 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53  I void *SQLITE_S
37b70 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 61  TDCALL sqlite3_a
37b80 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
37b90 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
37ba0 2a 2c 20 69 6e 74 20 6e 42 79 74 65 73 29 3b 0a  *, int nBytes);.
37bb0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
37bc0 20 55 73 65 72 20 44 61 74 61 20 46 6f 72 20 46   User Data For F
37bd0 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48  unctions.** METH
37be0 4f 44 3a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  OD: sqlite3_cont
37bf0 65 78 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ext.**.** ^The s
37c00 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61  qlite3_user_data
37c10 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
37c20 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a  urns a copy of.*
37c30 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 68  * the pointer th
37c40 61 74 20 77 61 73 20 74 68 65 20 70 55 73 65 72  at was the pUser
37c50 44 61 74 61 20 70 61 72 61 6d 65 74 65 72 20 28  Data parameter (
37c60 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  the 5th paramete
37c70 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71  r).** of the [sq
37c80 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
37c90 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20  ction()].** and 
37ca0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
37cb0 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f  function16()] ro
37cc0 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67  utines that orig
37cd0 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74  inally.** regist
37ce0 65 72 65 64 20 74 68 65 20 61 70 70 6c 69 63 61  ered the applica
37cf0 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e  tion defined fun
37d00 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  ction..**.** Thi
37d10 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62  s routine 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 61 70   which.** the ap
37d50 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
37d60 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  d function is ru
37d70 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45  nning..*/.SQLITE
37d80 5f 41 50 49 20 76 6f 69 64 20 2a 53 51 4c 49 54  _API void *SQLIT
37d90 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
37da0 33 5f 75 73 65 72 5f 64 61 74 61 28 73 71 6c 69  3_user_data(sqli
37db0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a  te3_context*);..
37dc0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
37dd0 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
37de0 69 6f 6e 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e  ion For Function
37df0 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  s.** METHOD: sql
37e00 69 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a  ite3_context.**.
37e10 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
37e20 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c  context_db_handl
37e30 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  e() interface re
37e40 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a  turns a copy of.
37e50 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74  ** the pointer t
37e60 6f 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  o the [database 
37e70 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 68 65  connection] (the
37e80 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 29 0a   1st parameter).
37e90 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ** of the [sqlit
37ea0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
37eb0 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71  on()].** and [sq
37ec0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
37ed0 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69  ction16()] routi
37ee0 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61  nes that origina
37ef0 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65  lly.** registere
37f00 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  d the applicatio
37f10 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n defined functi
37f20 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  on..*/.SQLITE_AP
37f30 49 20 73 71 6c 69 74 65 33 20 2a 53 51 4c 49 54  I sqlite3 *SQLIT
37f40 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
37f50 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e  3_context_db_han
37f60 64 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  dle(sqlite3_cont
37f70 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ext*);../*.** CA
37f80 50 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e  PI3REF: Function
37f90 20 41 75 78 69 6c 69 61 72 79 20 44 61 74 61 0a   Auxiliary Data.
37fa0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
37fb0 65 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a  e3_context.**.**
37fc0 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   These functions
37fd0 20 6d 61 79 20 62 65 20 75 73 65 64 20 62 79 20   may be used by 
37fe0 28 6e 6f 6e 2d 61 67 67 72 65 67 61 74 65 29 20  (non-aggregate) 
37ff0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f  SQL functions to
38000 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 20 6d 65  .** associate me
38010 74 61 64 61 74 61 20 77 69 74 68 20 61 72 67 75  tadata with argu
38020 6d 65 6e 74 20 76 61 6c 75 65 73 2e 20 49 66 20  ment values. If 
38030 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65 20 69  the same value i
38040 73 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 6d  s passed to.** m
38050 75 6c 74 69 70 6c 65 20 69 6e 76 6f 63 61 74 69  ultiple invocati
38060 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ons of the same 
38070 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 64 75 72  SQL function dur
38080 69 6e 67 20 71 75 65 72 79 20 65 78 65 63 75 74  ing query execut
38090 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20 73 6f  ion, under.** so
380a0 6d 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73  me circumstances
380b0 20 74 68 65 20 61 73 73 6f 63 69 61 74 65 64 20   the associated 
380c0 6d 65 74 61 64 61 74 61 20 6d 61 79 20 62 65 20  metadata may be 
380d0 70 72 65 73 65 72 76 65 64 2e 20 20 41 6e 20 65  preserved.  An e
380e0 78 61 6d 70 6c 65 0a 2a 2a 20 6f 66 20 77 68 65  xample.** of whe
380f0 72 65 20 74 68 69 73 20 6d 69 67 68 74 20 62 65  re this might be
38100 20 75 73 65 66 75 6c 20 69 73 20 69 6e 20 61 20   useful is in a 
38110 72 65 67 75 6c 61 72 2d 65 78 70 72 65 73 73 69  regular-expressi
38120 6f 6e 20 6d 61 74 63 68 69 6e 67 0a 2a 2a 20 66  on matching.** f
38130 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f 6d  unction. The com
38140 70 69 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f 66  piled version of
38150 20 74 68 65 20 72 65 67 75 6c 61 72 20 65 78 70   the regular exp
38160 72 65 73 73 69 6f 6e 20 63 61 6e 20 62 65 20 73  ression can be s
38170 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61  tored as.** meta
38180 64 61 74 61 20 61 73 73 6f 63 69 61 74 65 64 20  data associated 
38190 77 69 74 68 20 74 68 65 20 70 61 74 74 65 72 6e  with the pattern
381a0 20 73 74 72 69 6e 67 2e 20 20 0a 2a 2a 20 54 68   string.  .** Th
381b0 65 6e 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68  en as long as th
381c0 65 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67  e pattern string
381d0 20 72 65 6d 61 69 6e 73 20 74 68 65 20 73 61 6d   remains the sam
381e0 65 2c 0a 2a 2a 20 74 68 65 20 63 6f 6d 70 69 6c  e,.** the compil
381f0 65 64 20 72 65 67 75 6c 61 72 20 65 78 70 72 65  ed regular expre
38200 73 73 69 6f 6e 20 63 61 6e 20 62 65 20 72 65 75  ssion can be reu
38210 73 65 64 20 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a  sed on multiple.
38220 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f  ** invocations o
38230 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74  f the same funct
38240 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ion..**.** ^The 
38250 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
38260 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20  ata() interface 
38270 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
38280 72 20 74 6f 20 74 68 65 20 6d 65 74 61 64 61 74  r to the metadat
38290 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20  a.** associated 
382a0 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73  by the sqlite3_s
382b0 65 74 5f 61 75 78 64 61 74 61 28 29 20 66 75 6e  et_auxdata() fun
382c0 63 74 69 6f 6e 20 77 69 74 68 20 74 68 65 20 4e  ction with the N
382d0 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76  th argument.** v
382e0 61 6c 75 65 20 74 6f 20 74 68 65 20 61 70 70 6c  alue to the appl
382f0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
38300 66 75 6e 63 74 69 6f 6e 2e 20 5e 49 66 20 74 68  function. ^If th
38310 65 72 65 20 69 73 20 6e 6f 20 6d 65 74 61 64 61  ere is no metada
38320 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64  ta.** associated
38330 20 77 69 74 68 20 74 68 65 20 66 75 6e 63 74 69   with the functi
38340 6f 6e 20 61 72 67 75 6d 65 6e 74 2c 20 74 68 69  on argument, thi
38350 73 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75  s sqlite3_get_au
38360 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63  xdata() interfac
38370 65 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 4e  e.** returns a N
38380 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ULL pointer..**.
38390 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
383a0 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c  set_auxdata(C,N,
383b0 50 2c 58 29 20 69 6e 74 65 72 66 61 63 65 20 73  P,X) interface s
383c0 61 76 65 73 20 50 20 61 73 20 6d 65 74 61 64 61  aves P as metada
383d0 74 61 20 66 6f 72 20 74 68 65 20 4e 2d 74 68 0a  ta for the N-th.
383e0 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74  ** argument of t
383f0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
38400 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e  efined function.
38410 20 20 5e 53 75 62 73 65 71 75 65 6e 74 0a 2a 2a    ^Subsequent.**
38420 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
38430 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 43 2c  3_get_auxdata(C,
38440 4e 29 20 72 65 74 75 72 6e 20 50 20 66 72 6f 6d  N) return P from
38450 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
38460 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  .** sqlite3_set_
38470 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29  auxdata(C,N,P,X)
38480 20 63 61 6c 6c 20 69 66 20 74 68 65 20 6d 65 74   call if the met
38490 61 64 61 74 61 20 69 73 20 73 74 69 6c 6c 20 76  adata is still v
384a0 61 6c 69 64 20 6f 72 0a 2a 2a 20 4e 55 4c 4c 20  alid or.** NULL 
384b0 69 66 20 74 68 65 20 6d 65 74 61 64 61 74 61 20  if the metadata 
384c0 68 61 73 20 62 65 65 6e 20 64 69 73 63 61 72 64  has been discard
384d0 65 64 2e 0a 2a 2a 20 5e 41 66 74 65 72 20 65 61  ed..** ^After ea
384e0 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  ch call to sqlit
384f0 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43  e3_set_auxdata(C
38500 2c 4e 2c 50 2c 58 29 20 77 68 65 72 65 20 58 20  ,N,P,X) where X 
38510 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20  is not NULL,.** 
38520 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f  SQLite will invo
38530 6b 65 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  ke the destructo
38540 72 20 66 75 6e 63 74 69 6f 6e 20 58 20 77 69 74  r function X wit
38550 68 20 70 61 72 61 6d 65 74 65 72 20 50 20 65 78  h parameter P ex
38560 61 63 74 6c 79 0a 2a 2a 20 6f 6e 63 65 2c 20 77  actly.** once, w
38570 68 65 6e 20 74 68 65 20 6d 65 74 61 64 61 74 61  hen the metadata
38580 20 69 73 20 64 69 73 63 61 72 64 65 64 2e 0a 2a   is discarded..*
38590 2a 20 53 51 4c 69 74 65 20 69 73 20 66 72 65 65  * SQLite is free
385a0 20 74 6f 20 64 69 73 63 61 72 64 20 74 68 65 20   to discard the 
385b0 6d 65 74 61 64 61 74 61 20 61 74 20 61 6e 79 20  metadata at any 
385c0 74 69 6d 65 2c 20 69 6e 63 6c 75 64 69 6e 67 3a  time, including:
385d0 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 77 68   <ul>.** <li> wh
385e0 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  en the correspon
385f0 64 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70 61  ding function pa
38600 72 61 6d 65 74 65 72 20 63 68 61 6e 67 65 73 2c  rameter changes,
38610 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 77 68 65 6e   or.** <li> when
38620 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
38630 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66  )] or [sqlite3_f
38640 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 61  inalize()] is ca
38650 6c 6c 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20  lled for the.** 
38660 20 20 20 20 20 53 51 4c 20 73 74 61 74 65 6d 65       SQL stateme
38670 6e 74 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 77  nt, or.** <li> w
38680 68 65 6e 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  hen sqlite3_set_
38690 61 75 78 64 61 74 61 28 29 20 69 73 20 69 6e 76  auxdata() is inv
386a0 6f 6b 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68  oked again on th
386b0 65 20 73 61 6d 65 20 70 61 72 61 6d 65 74 65 72  e same parameter
386c0 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 64 75 72  , or.** <li> dur
386d0 69 6e 67 20 74 68 65 20 6f 72 69 67 69 6e 61 6c  ing the original
386e0 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
386f0 64 61 74 61 28 29 20 63 61 6c 6c 20 77 68 65 6e  data() call when
38700 20 61 20 6d 65 6d 6f 72 79 20 0a 2a 2a 20 20 20   a memory .**   
38710 20 20 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72     allocation er
38720 72 6f 72 20 6f 63 63 75 72 73 2e 20 3c 2f 75 6c  ror occurs. </ul
38730 3e 29 5e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  >)^.**.** Note t
38740 68 65 20 6c 61 73 74 20 62 75 6c 6c 65 74 20 69  he last bullet i
38750 6e 20 70 61 72 74 69 63 75 6c 61 72 2e 20 20 54  n particular.  T
38760 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 58 20  he destructor X 
38770 69 6e 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73