System.Data.SQLite
Hex Artifact Content
Not logged in

Artifact 5741f47d1bc38aa0a8c38f09e60a5fe0031f272d:


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 37 2e 31 35 2e 32 2e  ersion 3.7.15.2.
00b0: 20 20 42 79 20 63 6f 6d 62 69 6e 69 6e 67 20 61    By combining a
00c0: 6c 6c 20 74 68 65 20 69 6e 64 69 76 69 64 75 61  ll the individua
00d0: 6c 20 43 20 63 6f 64 65 20 66 69 6c 65 73 20 69  l C code files i
00e0: 6e 74 6f 20 74 68 69 73 20 0a 2a 2a 20 73 69 6e  nto this .** sin
00f0: 67 6c 65 20 6c 61 72 67 65 20 66 69 6c 65 2c 20  gle large file, 
0100: 74 68 65 20 65 6e 74 69 72 65 20 63 6f 64 65 20  the entire code 
0110: 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c 65 64 20  can be compiled 
0120: 61 73 20 61 20 73 69 6e 67 6c 65 20 74 72 61 6e  as a single tran
0130: 73 6c 61 74 69 6f 6e 0a 2a 2a 20 75 6e 69 74 2e  slation.** unit.
0140: 20 20 54 68 69 73 20 61 6c 6c 6f 77 73 20 6d 61    This allows ma
0150: 6e 79 20 63 6f 6d 70 69 6c 65 72 73 20 74 6f 20  ny compilers to 
0160: 64 6f 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 73  do optimizations
0170: 20 74 68 61 74 20 77 6f 75 6c 64 20 6e 6f 74 20   that would not 
0180: 62 65 0a 2a 2a 20 70 6f 73 73 69 62 6c 65 20 69  be.** possible i
0190: 66 20 74 68 65 20 66 69 6c 65 73 20 77 65 72 65  f the files were
01a0: 20 63 6f 6d 70 69 6c 65 64 20 73 65 70 61 72 61   compiled separa
01b0: 74 65 6c 79 2e 20 20 50 65 72 66 6f 72 6d 61 6e  tely.  Performan
01c0: 63 65 20 69 6d 70 72 6f 76 65 6d 65 6e 74 73 0a  ce improvements.
01d0: 2a 2a 20 6f 66 20 35 25 20 6f 72 20 6d 6f 72 65  ** of 5% or more
01e0: 20 61 72 65 20 63 6f 6d 6d 6f 6e 6c 79 20 73 65   are commonly se
01f0: 65 6e 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69  en when SQLite i
0200: 73 20 63 6f 6d 70 69 6c 65 64 20 61 73 20 61 20  s compiled as a 
0210: 73 69 6e 67 6c 65 0a 2a 2a 20 74 72 61 6e 73 6c  single.** transl
0220: 61 74 69 6f 6e 20 75 6e 69 74 2e 0a 2a 2a 0a 2a  ation unit..**.*
0230: 2a 20 54 68 69 73 20 66 69 6c 65 20 69 73 20 61  * This file is a
0240: 6c 6c 20 79 6f 75 20 6e 65 65 64 20 74 6f 20 63  ll you need to c
0250: 6f 6d 70 69 6c 65 20 53 51 4c 69 74 65 2e 20 20  ompile SQLite.  
0260: 54 6f 20 75 73 65 20 53 51 4c 69 74 65 20 69 6e  To use SQLite in
0270: 20 6f 74 68 65 72 0a 2a 2a 20 70 72 6f 67 72 61   other.** progra
0280: 6d 73 2c 20 79 6f 75 20 6e 65 65 64 20 74 68 69  ms, you need thi
0290: 73 20 66 69 6c 65 20 61 6e 64 20 74 68 65 20 22  s file and the "
02a0: 73 71 6c 69 74 65 33 2e 68 22 20 68 65 61 64 65  sqlite3.h" heade
02b0: 72 20 66 69 6c 65 20 74 68 61 74 20 64 65 66 69  r file that defi
02c0: 6e 65 73 0a 2a 2a 20 74 68 65 20 70 72 6f 67 72  nes.** the progr
02d0: 61 6d 6d 69 6e 67 20 69 6e 74 65 72 66 61 63 65  amming interface
02e0: 20 74 6f 20 74 68 65 20 53 51 4c 69 74 65 20 6c   to the SQLite l
02f0: 69 62 72 61 72 79 2e 20 20 28 49 66 20 79 6f 75  ibrary.  (If you
0300: 20 64 6f 20 6e 6f 74 20 68 61 76 65 20 0a 2a 2a   do not have .**
0310: 20 74 68 65 20 22 73 71 6c 69 74 65 33 2e 68 22   the "sqlite3.h"
0320: 20 68 65 61 64 65 72 20 66 69 6c 65 20 61 74 20   header file at 
0330: 68 61 6e 64 2c 20 79 6f 75 20 77 69 6c 6c 20 66  hand, you will f
0340: 69 6e 64 20 61 20 63 6f 70 79 20 65 6d 62 65 64  ind a copy embed
0350: 64 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68  ded within.** th
0360: 65 20 74 65 78 74 20 6f 66 20 74 68 69 73 20 66  e text of this f
0370: 69 6c 65 2e 20 20 53 65 61 72 63 68 20 66 6f 72  ile.  Search for
0380: 20 22 42 65 67 69 6e 20 66 69 6c 65 20 73 71 6c   "Begin file sql
0390: 69 74 65 33 2e 68 22 20 74 6f 20 66 69 6e 64 20  ite3.h" to find 
03a0: 74 68 65 20 73 74 61 72 74 0a 2a 2a 20 6f 66 20  the start.** of 
03b0: 74 68 65 20 65 6d 62 65 64 64 65 64 20 73 71 6c  the embedded sql
03c0: 69 74 65 33 2e 68 20 68 65 61 64 65 72 20 66 69  ite3.h header fi
03d0: 6c 65 2e 29 20 41 64 64 69 74 69 6f 6e 61 6c 20  le.) Additional 
03e0: 63 6f 64 65 20 66 69 6c 65 73 20 6d 61 79 20 62  code files may b
03f0: 65 20 6e 65 65 64 65 64 0a 2a 2a 20 69 66 20 79  e needed.** if y
0400: 6f 75 20 77 61 6e 74 20 61 20 77 72 61 70 70 65  ou want a wrappe
0410: 72 20 74 6f 20 69 6e 74 65 72 66 61 63 65 20 53  r to interface S
0420: 51 4c 69 74 65 20 77 69 74 68 20 79 6f 75 72 20  QLite with your 
0430: 63 68 6f 69 63 65 20 6f 66 20 70 72 6f 67 72 61  choice of progra
0440: 6d 6d 69 6e 67 0a 2a 2a 20 6c 61 6e 67 75 61 67  mming.** languag
0450: 65 2e 20 54 68 65 20 63 6f 64 65 20 66 6f 72 20  e. The code for 
0460: 74 68 65 20 22 73 71 6c 69 74 65 33 22 20 63 6f  the "sqlite3" co
0470: 6d 6d 61 6e 64 2d 6c 69 6e 65 20 73 68 65 6c 6c  mmand-line shell
0480: 20 69 73 20 61 6c 73 6f 20 69 6e 20 61 0a 2a 2a   is also in a.**
0490: 20 73 65 70 61 72 61 74 65 20 66 69 6c 65 2e 20   separate file. 
04a0: 54 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 61 69  This file contai
04b0: 6e 73 20 6f 6e 6c 79 20 63 6f 64 65 20 66 6f 72  ns only code for
04c0: 20 74 68 65 20 63 6f 72 65 20 53 51 4c 69 74 65   the core SQLite
04d0: 20 6c 69 62 72 61 72 79 2e 0a 2a 2f 0a 23 64 65   library..*/.#de
04e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 45  fine SQLITE_CORE
04f0: 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
0500: 45 5f 41 4d 41 4c 47 41 4d 41 54 49 4f 4e 20 31  E_AMALGAMATION 1
0510: 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f  .#ifndef SQLITE_
0520: 50 52 49 56 41 54 45 0a 23 20 64 65 66 69 6e 65  PRIVATE.# define
0530: 20 53 51 4c 49 54 45 5f 50 52 49 56 41 54 45 20   SQLITE_PRIVATE 
0540: 73 74 61 74 69 63 0a 23 65 6e 64 69 66 0a 23 69  static.#endif.#i
0550: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 41 50 49  fndef SQLITE_API
0560: 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45  .# define SQLITE
0570: 5f 41 50 49 0a 23 65 6e 64 69 66 0a 2f 2a 2a 2a  _API.#endif./***
0580: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 42 65 67 69  *********** Begi
0590: 6e 20 66 69 6c 65 20 73 71 6c 69 74 65 49 6e 74  n file sqliteInt
05a0: 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  .h *************
05b0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
05c0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 0a 2a  **********/./*.*
05d0: 2a 20 32 30 30 31 20 53 65 70 74 65 6d 62 65 72  * 2001 September
05e0: 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75   15.**.** The au
05f0: 74 68 6f 72 20 64 69 73 63 6c 61 69 6d 73 20 63  thor disclaims c
0600: 6f 70 79 72 69 67 68 74 20 74 6f 20 74 68 69 73  opyright to this
0610: 20 73 6f 75 72 63 65 20 63 6f 64 65 2e 20 20 49   source code.  I
0620: 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 61 20  n place of.** a 
0630: 6c 65 67 61 6c 20 6e 6f 74 69 63 65 2c 20 68 65  legal notice, he
0640: 72 65 20 69 73 20 61 20 62 6c 65 73 73 69 6e 67  re is a blessing
0650: 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d 61 79 20 79  :.**.**    May y
0660: 6f 75 20 64 6f 20 67 6f 6f 64 20 61 6e 64 20 6e  ou do good and n
0670: 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20 20 20 20 4d  ot evil..**    M
0680: 61 79 20 79 6f 75 20 66 69 6e 64 20 66 6f 72 67  ay you find forg
0690: 69 76 65 6e 65 73 73 20 66 6f 72 20 79 6f 75 72  iveness for your
06a0: 73 65 6c 66 20 61 6e 64 20 66 6f 72 67 69 76 65  self and forgive
06b0: 20 6f 74 68 65 72 73 2e 0a 2a 2a 20 20 20 20 4d   others..**    M
06c0: 61 79 20 79 6f 75 20 73 68 61 72 65 20 66 72 65  ay you share fre
06d0: 65 6c 79 2c 20 6e 65 76 65 72 20 74 61 6b 69 6e  ely, never takin
06e0: 67 20 6d 6f 72 65 20 74 68 61 6e 20 79 6f 75 20  g more than you 
06f0: 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a  give..**.*******
0700: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0710: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0720: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0730: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0740: 2a 2a 0a 2a 2a 20 49 6e 74 65 72 6e 61 6c 20 69  **.** Internal i
0750: 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e 69 74  nterface definit
0760: 69 6f 6e 73 20 66 6f 72 20 53 51 4c 69 74 65 2e  ions for SQLite.
0770: 0a 2a 2a 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 5f  .**.*/.#ifndef _
0780: 53 51 4c 49 54 45 49 4e 54 5f 48 5f 0a 23 64 65  SQLITEINT_H_.#de
0790: 66 69 6e 65 20 5f 53 51 4c 49 54 45 49 4e 54 5f  fine _SQLITEINT_
07a0: 48 5f 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73 65 20  H_../*.** These 
07b0: 23 64 65 66 69 6e 65 73 20 73 68 6f 75 6c 64 20  #defines should 
07c0: 65 6e 61 62 6c 65 20 3e 32 47 42 20 66 69 6c 65  enable >2GB file
07d0: 20 73 75 70 70 6f 72 74 20 6f 6e 20 50 4f 53 49   support on POSI
07e0: 58 20 69 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65  X if the.** unde
07f0: 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67  rlying operating
0800: 20 73 79 73 74 65 6d 20 73 75 70 70 6f 72 74 73   system supports
0810: 20 69 74 2e 20 20 49 66 20 74 68 65 20 4f 53 20   it.  If the OS 
0820: 6c 61 63 6b 73 0a 2a 2a 20 6c 61 72 67 65 20 66  lacks.** large f
0830: 69 6c 65 20 73 75 70 70 6f 72 74 2c 20 6f 72 20  ile support, or 
0840: 69 66 20 74 68 65 20 4f 53 20 69 73 20 77 69 6e  if the OS is win
0850: 64 6f 77 73 2c 20 74 68 65 73 65 20 73 68 6f 75  dows, these shou
0860: 6c 64 20 62 65 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a  ld be no-ops..**
0870: 0a 2a 2a 20 54 69 63 6b 65 74 20 23 32 37 33 39  .** Ticket #2739
0880: 3a 20 20 54 68 65 20 5f 4c 41 52 47 45 46 49 4c  :  The _LARGEFIL
0890: 45 5f 53 4f 55 52 43 45 20 6d 61 63 72 6f 20 6d  E_SOURCE macro m
08a0: 75 73 74 20 61 70 70 65 61 72 20 62 65 66 6f 72  ust appear befor
08b0: 65 20 61 6e 79 0a 2a 2a 20 73 79 73 74 65 6d 20  e any.** system 
08c0: 23 69 6e 63 6c 75 64 65 73 2e 20 20 48 65 6e 63  #includes.  Henc
08d0: 65 2c 20 74 68 69 73 20 62 6c 6f 63 6b 20 6f 66  e, this block of
08e0: 20 63 6f 64 65 20 6d 75 73 74 20 62 65 20 74 68   code must be th
08f0: 65 20 76 65 72 79 20 66 69 72 73 74 0a 2a 2a 20  e very first.** 
0900: 63 6f 64 65 20 69 6e 20 61 6c 6c 20 73 6f 75 72  code in all sour
0910: 63 65 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20  ce files..**.** 
0920: 4c 61 72 67 65 20 66 69 6c 65 20 73 75 70 70 6f  Large file suppo
0930: 72 74 20 63 61 6e 20 62 65 20 64 69 73 61 62 6c  rt can be disabl
0940: 65 64 20 75 73 69 6e 67 20 74 68 65 20 2d 44 53  ed using the -DS
0950: 51 4c 49 54 45 5f 44 49 53 41 42 4c 45 5f 4c 46  QLITE_DISABLE_LF
0960: 53 20 73 77 69 74 63 68 0a 2a 2a 20 6f 6e 20 74  S switch.** on t
0970: 68 65 20 63 6f 6d 70 69 6c 65 72 20 63 6f 6d 6d  he compiler comm
0980: 61 6e 64 20 6c 69 6e 65 2e 20 20 54 68 69 73 20  and line.  This 
0990: 69 73 20 6e 65 63 65 73 73 61 72 79 20 69 66 20  is necessary if 
09a0: 79 6f 75 20 61 72 65 20 63 6f 6d 70 69 6c 69 6e  you are compilin
09b0: 67 0a 2a 2a 20 6f 6e 20 61 20 72 65 63 65 6e 74  g.** on a recent
09c0: 20 6d 61 63 68 69 6e 65 20 28 65 78 3a 20 52 65   machine (ex: Re
09d0: 64 20 48 61 74 20 37 2e 32 29 20 62 75 74 20 79  d Hat 7.2) but y
09e0: 6f 75 20 77 61 6e 74 20 79 6f 75 72 20 63 6f 64  ou want your cod
09f0: 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 6f 6e 20  e to work.** on 
0a00: 61 6e 20 6f 6c 64 65 72 20 6d 61 63 68 69 6e 65  an older machine
0a10: 20 28 65 78 3a 20 52 65 64 20 48 61 74 20 36 2e   (ex: Red Hat 6.
0a20: 30 29 2e 20 20 49 66 20 79 6f 75 20 63 6f 6d 70  0).  If you comp
0a30: 69 6c 65 20 6f 6e 20 52 65 64 20 48 61 74 20 37  ile on Red Hat 7
0a40: 2e 32 0a 2a 2a 20 77 69 74 68 6f 75 74 20 74 68  .2.** without th
0a50: 69 73 20 6f 70 74 69 6f 6e 2c 20 4c 46 53 20 69  is option, LFS i
0a60: 73 20 65 6e 61 62 6c 65 2e 20 20 42 75 74 20 4c  s enable.  But L
0a70: 46 53 20 64 6f 65 73 20 6e 6f 74 20 65 78 69 73  FS does not exis
0a80: 74 20 69 6e 20 74 68 65 20 6b 65 72 6e 65 6c 0a  t in the kernel.
0a90: 2a 2a 20 69 6e 20 52 65 64 20 48 61 74 20 36 2e  ** in Red Hat 6.
0aa0: 30 2c 20 73 6f 20 74 68 65 20 63 6f 64 65 20 77  0, so the code w
0ab0: 6f 6e 27 74 20 77 6f 72 6b 2e 20 20 48 65 6e 63  on't work.  Henc
0ac0: 65 2c 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 62  e, for maximum b
0ad0: 69 6e 61 72 79 0a 2a 2a 20 70 6f 72 74 61 62 69  inary.** portabi
0ae0: 6c 69 74 79 20 79 6f 75 20 73 68 6f 75 6c 64 20  lity you should 
0af0: 6f 6d 69 74 20 4c 46 53 2e 0a 2a 2a 0a 2a 2a 20  omit LFS..**.** 
0b00: 53 69 6d 69 6c 61 72 20 69 73 20 74 72 75 65 20  Similar is true 
0b10: 66 6f 72 20 4d 61 63 20 4f 53 20 58 2e 20 20 4c  for Mac OS X.  L
0b20: 46 53 20 69 73 20 6f 6e 6c 79 20 73 75 70 70 6f  FS is only suppo
0b30: 72 74 65 64 20 6f 6e 20 4d 61 63 20 4f 53 20 58  rted on Mac OS X
0b40: 20 39 20 61 6e 64 20 6c 61 74 65 72 2e 0a 2a 2f   9 and later..*/
0b50: 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f  .#ifndef SQLITE_
0b60: 44 49 53 41 42 4c 45 5f 4c 46 53 0a 23 20 64 65  DISABLE_LFS.# de
0b70: 66 69 6e 65 20 5f 4c 41 52 47 45 5f 46 49 4c 45  fine _LARGE_FILE
0b80: 20 20 20 20 20 20 20 31 0a 23 20 69 66 6e 64 65         1.# ifnde
0b90: 66 20 5f 46 49 4c 45 5f 4f 46 46 53 45 54 5f 42  f _FILE_OFFSET_B
0ba0: 49 54 53 0a 23 20 20 20 64 65 66 69 6e 65 20 5f  ITS.#   define _
0bb0: 46 49 4c 45 5f 4f 46 46 53 45 54 5f 42 49 54 53  FILE_OFFSET_BITS
0bc0: 20 36 34 0a 23 20 65 6e 64 69 66 0a 23 20 64 65   64.# endif.# de
0bd0: 66 69 6e 65 20 5f 4c 41 52 47 45 46 49 4c 45 5f  fine _LARGEFILE_
0be0: 53 4f 55 52 43 45 20 31 0a 23 65 6e 64 69 66 0a  SOURCE 1.#endif.
0bf0: 0a 2f 2a 0a 2a 2a 20 49 6e 63 6c 75 64 65 20 74  ./*.** Include t
0c00: 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  he configuration
0c10: 20 68 65 61 64 65 72 20 6f 75 74 70 75 74 20 62   header output b
0c20: 79 20 27 63 6f 6e 66 69 67 75 72 65 27 20 69 66  y 'configure' if
0c30: 20 77 65 27 72 65 20 75 73 69 6e 67 20 74 68 65   we're using the
0c40: 0a 2a 2a 20 61 75 74 6f 63 6f 6e 66 2d 62 61 73  .** autoconf-bas
0c50: 65 64 20 62 75 69 6c 64 0a 2a 2f 0a 23 69 66 64  ed build.*/.#ifd
0c60: 65 66 20 5f 48 41 56 45 5f 53 51 4c 49 54 45 5f  ef _HAVE_SQLITE_
0c70: 43 4f 4e 46 49 47 5f 48 0a 23 69 6e 63 6c 75 64  CONFIG_H.#includ
0c80: 65 20 22 63 6f 6e 66 69 67 2e 68 22 0a 23 65 6e  e "config.h".#en
0c90: 64 69 66 0a 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  dif../**********
0ca0: 2a 2a 2a 2a 20 49 6e 63 6c 75 64 65 20 73 71 6c  **** Include sql
0cb0: 69 74 65 4c 69 6d 69 74 2e 68 20 69 6e 20 74 68  iteLimit.h in th
0cc0: 65 20 6d 69 64 64 6c 65 20 6f 66 20 73 71 6c 69  e middle of sqli
0cd0: 74 65 49 6e 74 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a  teInt.h ********
0ce0: 2a 2a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ***/./**********
0cf0: 2a 2a 2a 2a 20 42 65 67 69 6e 20 66 69 6c 65 20  **** Begin file 
0d00: 73 71 6c 69 74 65 4c 69 6d 69 74 2e 68 20 2a 2a  sqliteLimit.h **
0d10: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0d20: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0d30: 2a 2a 2a 2f 0a 2f 2a 0a 2a 2a 20 32 30 30 37 20  ***/./*.** 2007 
0d40: 4d 61 79 20 37 0a 2a 2a 0a 2a 2a 20 54 68 65 20  May 7.**.** The 
0d50: 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69 6d 73  author disclaims
0d60: 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20 74 68   copyright to th
0d70: 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65 2e 20  is source code. 
0d80: 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20   In place of.** 
0d90: 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65 2c 20  a legal notice, 
0da0: 68 65 72 65 20 69 73 20 61 20 62 6c 65 73 73 69  here is a blessi
0db0: 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d 61 79  ng:.**.**    May
0dc0: 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61 6e 64   you do good and
0dd0: 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20 20 20   not evil..**   
0de0: 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20 66 6f   May you find fo
0df0: 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20 79 6f  rgiveness for yo
0e00: 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72 67 69  urself and forgi
0e10: 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20 20 20  ve others..**   
0e20: 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65 20 66   May you share f
0e30: 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74 61 6b  reely, never tak
0e40: 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20 79 6f  ing more than yo
0e50: 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a  u give..**.*****
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 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0e90: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0ea0: 2a 2a 2a 2a 0a 2a 2a 20 0a 2a 2a 20 54 68 69 73  ****.** .** This
0eb0: 20 66 69 6c 65 20 64 65 66 69 6e 65 73 20 76 61   file defines va
0ec0: 72 69 6f 75 73 20 6c 69 6d 69 74 73 20 6f 66 20  rious limits of 
0ed0: 77 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20  what SQLite can 
0ee0: 70 72 6f 63 65 73 73 2e 0a 2a 2f 0a 0a 2f 2a 0a  process..*/../*.
0ef0: 2a 2a 20 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c  ** The maximum l
0f00: 65 6e 67 74 68 20 6f 66 20 61 20 54 45 58 54 20  ength of a TEXT 
0f10: 6f 72 20 42 4c 4f 42 20 69 6e 20 62 79 74 65 73  or BLOB in bytes
0f20: 2e 20 20 20 54 68 69 73 20 61 6c 73 6f 0a 2a 2a  .   This also.**
0f30: 20 6c 69 6d 69 74 73 20 74 68 65 20 73 69 7a 65   limits the size
0f40: 20 6f 66 20 61 20 72 6f 77 20 69 6e 20 61 20 74   of a row in a t
0f50: 61 62 6c 65 20 6f 72 20 69 6e 64 65 78 2e 0a 2a  able or index..*
0f60: 2a 0a 2a 2a 20 54 68 65 20 68 61 72 64 20 6c 69  *.** The hard li
0f70: 6d 69 74 20 69 73 20 74 68 65 20 61 62 69 6c 69  mit is the abili
0f80: 74 79 20 6f 66 20 61 20 33 32 2d 62 69 74 20 73  ty of a 32-bit s
0f90: 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a  igned integer.**
0fa0: 20 74 6f 20 63 6f 75 6e 74 20 74 68 65 20 73 69   to count the si
0fb0: 7a 65 3a 20 32 5e 33 31 2d 31 20 6f 72 20 32 31  ze: 2^31-1 or 21
0fc0: 34 37 34 38 33 36 34 37 2e 0a 2a 2f 0a 23 69 66  47483647..*/.#if
0fd0: 6e 64 65 66 20 53 51 4c 49 54 45 5f 4d 41 58 5f  ndef SQLITE_MAX_
0fe0: 4c 45 4e 47 54 48 0a 23 20 64 65 66 69 6e 65 20  LENGTH.# define 
0ff0: 53 51 4c 49 54 45 5f 4d 41 58 5f 4c 45 4e 47 54  SQLITE_MAX_LENGT
1000: 48 20 31 30 30 30 30 30 30 30 30 30 0a 23 65 6e  H 1000000000.#en
1010: 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 69 73 20  dif../*.** This 
1020: 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e  is the maximum n
1030: 75 6d 62 65 72 20 6f 66 0a 2a 2a 0a 2a 2a 20 20  umber of.**.**  
1040: 20 20 2a 20 43 6f 6c 75 6d 6e 73 20 69 6e 20 61    * Columns in a
1050: 20 74 61 62 6c 65 0a 2a 2a 20 20 20 20 2a 20 43   table.**    * C
1060: 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64  olumns in an ind
1070: 65 78 0a 2a 2a 20 20 20 20 2a 20 43 6f 6c 75 6d  ex.**    * Colum
1080: 6e 73 20 69 6e 20 61 20 76 69 65 77 0a 2a 2a 20  ns in a view.** 
1090: 20 20 20 2a 20 54 65 72 6d 73 20 69 6e 20 74 68     * Terms in th
10a0: 65 20 53 45 54 20 63 6c 61 75 73 65 20 6f 66 20  e SET clause of 
10b0: 61 6e 20 55 50 44 41 54 45 20 73 74 61 74 65 6d  an UPDATE statem
10c0: 65 6e 74 0a 2a 2a 20 20 20 20 2a 20 54 65 72 6d  ent.**    * Term
10d0: 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20  s in the result 
10e0: 73 65 74 20 6f 66 20 61 20 53 45 4c 45 43 54 20  set of a SELECT 
10f0: 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 20 20 20  statement.**    
1100: 2a 20 54 65 72 6d 73 20 69 6e 20 74 68 65 20 47  * Terms in the G
1110: 52 4f 55 50 20 42 59 20 6f 72 20 4f 52 44 45 52  ROUP BY or ORDER
1120: 20 42 59 20 63 6c 61 75 73 65 73 20 6f 66 20 61   BY clauses of a
1130: 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e   SELECT statemen
1140: 74 2e 0a 2a 2a 20 20 20 20 2a 20 54 65 72 6d 73  t..**    * Terms
1150: 20 69 6e 20 74 68 65 20 56 41 4c 55 45 53 20 63   in the VALUES c
1160: 6c 61 75 73 65 20 6f 66 20 61 6e 20 49 4e 53 45  lause of an INSE
1170: 52 54 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a  RT statement.**.
1180: 2a 2a 20 54 68 65 20 68 61 72 64 20 75 70 70 65  ** The hard uppe
1190: 72 20 6c 69 6d 69 74 20 68 65 72 65 20 69 73 20  r limit here is 
11a0: 33 32 36 37 36 2e 20 20 4d 6f 73 74 20 64 61 74  32676.  Most dat
11b0: 61 62 61 73 65 20 70 65 6f 70 6c 65 20 77 69 6c  abase people wil
11c0: 6c 0a 2a 2a 20 74 65 6c 6c 20 79 6f 75 20 74 68  l.** tell you th
11d0: 61 74 20 69 6e 20 61 20 77 65 6c 6c 2d 6e 6f 72  at in a well-nor
11e0: 6d 61 6c 69 7a 65 64 20 64 61 74 61 62 61 73 65  malized database
11f0: 2c 20 79 6f 75 20 75 73 75 61 6c 6c 79 20 73 68  , you usually sh
1200: 6f 75 6c 64 0a 2a 2a 20 6e 6f 74 20 68 61 76 65  ould.** not have
1210: 20 6d 6f 72 65 20 74 68 61 6e 20 61 20 64 6f 7a   more than a doz
1220: 65 6e 20 6f 72 20 73 6f 20 63 6f 6c 75 6d 6e 73  en or so columns
1230: 20 69 6e 20 61 6e 79 20 74 61 62 6c 65 2e 20 20   in any table.  
1240: 41 6e 64 20 69 66 0a 2a 2a 20 74 68 61 74 20 69  And if.** that i
1250: 73 20 74 68 65 20 63 61 73 65 2c 20 74 68 65 72  s the case, ther
1260: 65 20 69 73 20 6e 6f 20 70 6f 69 6e 74 20 69 6e  e is no point in
1270: 20 68 61 76 69 6e 67 20 6d 6f 72 65 20 74 68 61   having more tha
1280: 6e 20 61 20 66 65 77 0a 2a 2a 20 64 6f 7a 65 6e  n a few.** dozen
1290: 20 76 61 6c 75 65 73 20 69 6e 20 61 6e 79 20 6f   values in any o
12a0: 66 20 74 68 65 20 6f 74 68 65 72 20 73 69 74 75  f the other situ
12b0: 61 74 69 6f 6e 73 20 64 65 73 63 72 69 62 65 64  ations described
12c0: 20 61 62 6f 76 65 2e 0a 2a 2f 0a 23 69 66 6e 64   above..*/.#ifnd
12d0: 65 66 20 53 51 4c 49 54 45 5f 4d 41 58 5f 43 4f  ef SQLITE_MAX_CO
12e0: 4c 55 4d 4e 0a 23 20 64 65 66 69 6e 65 20 53 51  LUMN.# define SQ
12f0: 4c 49 54 45 5f 4d 41 58 5f 43 4f 4c 55 4d 4e 20  LITE_MAX_COLUMN 
1300: 32 30 30 30 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a  2000.#endif../*.
1310: 2a 2a 20 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c  ** The maximum l
1320: 65 6e 67 74 68 20 6f 66 20 61 20 73 69 6e 67 6c  ength of a singl
1330: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
1340: 69 6e 20 62 79 74 65 73 2e 0a 2a 2a 0a 2a 2a 20  in bytes..**.** 
1350: 49 74 20 75 73 65 64 20 74 6f 20 62 65 20 74 68  It used to be th
1360: 65 20 63 61 73 65 20 74 68 61 74 20 73 65 74 74  e case that sett
1370: 69 6e 67 20 74 68 69 73 20 76 61 6c 75 65 20 74  ing this value t
1380: 6f 20 7a 65 72 6f 20 77 6f 75 6c 64 0a 2a 2a 20  o zero would.** 
1390: 74 75 72 6e 20 74 68 65 20 6c 69 6d 69 74 20 6f  turn the limit o
13a0: 66 66 2e 20 20 54 68 61 74 20 69 73 20 6e 6f 20  ff.  That is no 
13b0: 6c 6f 6e 67 65 72 20 74 72 75 65 2e 20 20 49 74  longer true.  It
13c0: 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65   is not possible
13d0: 0a 2a 2a 20 74 6f 20 74 75 72 6e 20 74 68 69 73  .** to turn this
13e0: 20 6c 69 6d 69 74 20 6f 66 66 2e 0a 2a 2f 0a 23   limit off..*/.#
13f0: 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4d 41  ifndef SQLITE_MA
1400: 58 5f 53 51 4c 5f 4c 45 4e 47 54 48 0a 23 20 64  X_SQL_LENGTH.# d
1410: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 41 58  efine SQLITE_MAX
1420: 5f 53 51 4c 5f 4c 45 4e 47 54 48 20 31 30 30 30  _SQL_LENGTH 1000
1430: 30 30 30 30 30 30 0a 23 65 6e 64 69 66 0a 0a 2f  000000.#endif../
1440: 2a 0a 2a 2a 20 54 68 65 20 6d 61 78 69 6d 75 6d  *.** The maximum
1450: 20 64 65 70 74 68 20 6f 66 20 61 6e 20 65 78 70   depth of an exp
1460: 72 65 73 73 69 6f 6e 20 74 72 65 65 2e 20 54 68  ression tree. Th
1470: 69 73 20 69 73 20 6c 69 6d 69 74 65 64 20 74 6f  is is limited to
1480: 20 0a 2a 2a 20 73 6f 6d 65 20 65 78 74 65 6e 74   .** some extent
1490: 20 62 79 20 53 51 4c 49 54 45 5f 4d 41 58 5f 53   by SQLITE_MAX_S
14a0: 51 4c 5f 4c 45 4e 47 54 48 2e 20 42 75 74 20 73  QL_LENGTH. But s
14b0: 6f 6d 65 74 69 6d 65 20 79 6f 75 20 6d 69 67 68  ometime you migh
14c0: 74 20 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 70 6c  t .** want to pl
14d0: 61 63 65 20 6d 6f 72 65 20 73 65 76 65 72 65 20  ace more severe 
14e0: 6c 69 6d 69 74 73 20 6f 6e 20 74 68 65 20 63 6f  limits on the co
14f0: 6d 70 6c 65 78 69 74 79 20 6f 66 20 61 6e 20 0a  mplexity of an .
1500: 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 2e 0a 2a  ** expression..*
1510: 2a 0a 2a 2a 20 41 20 76 61 6c 75 65 20 6f 66 20  *.** A value of 
1520: 30 20 75 73 65 64 20 74 6f 20 6d 65 61 6e 20 74  0 used to mean t
1530: 68 61 74 20 74 68 65 20 6c 69 6d 69 74 20 77 61  hat the limit wa
1540: 73 20 6e 6f 74 20 65 6e 66 6f 72 63 65 64 2e 0a  s not enforced..
1550: 2a 2a 20 42 75 74 20 74 68 61 74 20 69 73 20 6e  ** But that is n
1560: 6f 20 6c 6f 6e 67 65 72 20 74 72 75 65 2e 20 20  o longer true.  
1570: 54 68 65 20 6c 69 6d 69 74 20 69 73 20 6e 6f 77  The limit is now
1580: 20 73 74 72 69 63 74 6c 79 20 65 6e 66 6f 72 63   strictly enforc
1590: 65 64 0a 2a 2a 20 61 74 20 61 6c 6c 20 74 69 6d  ed.** at all tim
15a0: 65 73 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53  es..*/.#ifndef S
15b0: 51 4c 49 54 45 5f 4d 41 58 5f 45 58 50 52 5f 44  QLITE_MAX_EXPR_D
15c0: 45 50 54 48 0a 23 20 64 65 66 69 6e 65 20 53 51  EPTH.# define SQ
15d0: 4c 49 54 45 5f 4d 41 58 5f 45 58 50 52 5f 44 45  LITE_MAX_EXPR_DE
15e0: 50 54 48 20 31 30 30 30 0a 23 65 6e 64 69 66 0a  PTH 1000.#endif.
15f0: 0a 2f 2a 0a 2a 2a 20 54 68 65 20 6d 61 78 69 6d  ./*.** The maxim
1600: 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72  um number of ter
1610: 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64  ms in a compound
1620: 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e   SELECT statemen
1630: 74 2e 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 67  t..** The code g
1640: 65 6e 65 72 61 74 6f 72 20 66 6f 72 20 63 6f 6d  enerator for com
1650: 70 6f 75 6e 64 20 53 45 4c 45 43 54 20 73 74 61  pound SELECT sta
1660: 74 65 6d 65 6e 74 73 20 64 6f 65 73 20 6f 6e 65  tements does one
1670: 0a 2a 2a 20 6c 65 76 65 6c 20 6f 66 20 72 65 63  .** level of rec
1680: 75 72 73 69 6f 6e 20 66 6f 72 20 65 61 63 68 20  ursion for each 
1690: 74 65 72 6d 2e 20 20 41 20 73 74 61 63 6b 20 6f  term.  A stack o
16a0: 76 65 72 66 6c 6f 77 20 63 61 6e 20 72 65 73 75  verflow can resu
16b0: 6c 74 0a 2a 2a 20 69 66 20 74 68 65 20 6e 75 6d  lt.** if the num
16c0: 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69 73 20  ber of terms is 
16d0: 74 6f 6f 20 6c 61 72 67 65 2e 20 20 49 6e 20 70  too large.  In p
16e0: 72 61 63 74 69 63 65 2c 20 6d 6f 73 74 20 53 51  ractice, most SQ
16f0: 4c 0a 2a 2a 20 6e 65 76 65 72 20 68 61 73 20 6d  L.** never has m
1700: 6f 72 65 20 74 68 61 6e 20 33 20 6f 72 20 34 20  ore than 3 or 4 
1710: 74 65 72 6d 73 2e 20 20 55 73 65 20 61 20 76 61  terms.  Use a va
1720: 6c 75 65 20 6f 66 20 30 20 74 6f 20 64 69 73 61  lue of 0 to disa
1730: 62 6c 65 0a 2a 2a 20 61 6e 79 20 6c 69 6d 69 74  ble.** any limit
1740: 20 6f 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   on the number o
1750: 66 20 74 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d  f terms in a com
1760: 70 6f 75 6e 74 20 53 45 4c 45 43 54 2e 0a 2a 2f  pount SELECT..*/
1770: 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f  .#ifndef SQLITE_
1780: 4d 41 58 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c  MAX_COMPOUND_SEL
1790: 45 43 54 0a 23 20 64 65 66 69 6e 65 20 53 51 4c  ECT.# define SQL
17a0: 49 54 45 5f 4d 41 58 5f 43 4f 4d 50 4f 55 4e 44  ITE_MAX_COMPOUND
17b0: 5f 53 45 4c 45 43 54 20 35 30 30 0a 23 65 6e 64  _SELECT 500.#end
17c0: 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 6d 61  if../*.** The ma
17d0: 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
17e0: 6f 70 63 6f 64 65 73 20 69 6e 20 61 20 56 44 42  opcodes in a VDB
17f0: 45 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 20 4e 6f  E program..** No
1800: 74 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 66 6f  t currently enfo
1810: 72 63 65 64 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66  rced..*/.#ifndef
1820: 20 53 51 4c 49 54 45 5f 4d 41 58 5f 56 44 42 45   SQLITE_MAX_VDBE
1830: 5f 4f 50 0a 23 20 64 65 66 69 6e 65 20 53 51 4c  _OP.# define SQL
1840: 49 54 45 5f 4d 41 58 5f 56 44 42 45 5f 4f 50 20  ITE_MAX_VDBE_OP 
1850: 32 35 30 30 30 0a 23 65 6e 64 69 66 0a 0a 2f 2a  25000.#endif../*
1860: 0a 2a 2a 20 54 68 65 20 6d 61 78 69 6d 75 6d 20  .** The maximum 
1870: 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65  number of argume
1880: 6e 74 73 20 74 6f 20 61 6e 20 53 51 4c 20 66 75  nts to an SQL fu
1890: 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a 23 69 66 6e 64  nction..*/.#ifnd
18a0: 65 66 20 53 51 4c 49 54 45 5f 4d 41 58 5f 46 55  ef SQLITE_MAX_FU
18b0: 4e 43 54 49 4f 4e 5f 41 52 47 0a 23 20 64 65 66  NCTION_ARG.# def
18c0: 69 6e 65 20 53 51 4c 49 54 45 5f 4d 41 58 5f 46  ine SQLITE_MAX_F
18d0: 55 4e 43 54 49 4f 4e 5f 41 52 47 20 31 32 37 0a  UNCTION_ARG 127.
18e0: 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68  #endif../*.** Th
18f0: 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
1900: 20 6f 66 20 69 6e 2d 6d 65 6d 6f 72 79 20 70 61   of in-memory pa
1910: 67 65 73 20 74 6f 20 75 73 65 20 66 6f 72 20 74  ges to use for t
1920: 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65  he main database
1930: 0a 2a 2a 20 74 61 62 6c 65 20 61 6e 64 20 66 6f  .** table and fo
1940: 72 20 74 65 6d 70 6f 72 61 72 79 20 74 61 62 6c  r temporary tabl
1950: 65 73 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  es.  The SQLITE_
1960: 44 45 46 41 55 4c 54 5f 43 41 43 48 45 5f 53 49  DEFAULT_CACHE_SI
1970: 5a 45 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51  ZE.*/.#ifndef SQ
1980: 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 43 41 43  LITE_DEFAULT_CAC
1990: 48 45 5f 53 49 5a 45 0a 23 20 64 65 66 69 6e 65  HE_SIZE.# define
19a0: 20 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f   SQLITE_DEFAULT_
19b0: 43 41 43 48 45 5f 53 49 5a 45 20 20 32 30 30 30  CACHE_SIZE  2000
19c0: 0a 23 65 6e 64 69 66 0a 23 69 66 6e 64 65 66 20  .#endif.#ifndef 
19d0: 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 54  SQLITE_DEFAULT_T
19e0: 45 4d 50 5f 43 41 43 48 45 5f 53 49 5a 45 0a 23  EMP_CACHE_SIZE.#
19f0: 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44   define SQLITE_D
1a00: 45 46 41 55 4c 54 5f 54 45 4d 50 5f 43 41 43 48  EFAULT_TEMP_CACH
1a10: 45 5f 53 49 5a 45 20 20 35 30 30 0a 23 65 6e 64  E_SIZE  500.#end
1a20: 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 64 65  if../*.** The de
1a30: 66 61 75 6c 74 20 6e 75 6d 62 65 72 20 6f 66 20  fault number of 
1a40: 66 72 61 6d 65 73 20 74 6f 20 61 63 63 75 6d 75  frames to accumu
1a50: 6c 61 74 65 20 69 6e 20 74 68 65 20 6c 6f 67 20  late in the log 
1a60: 66 69 6c 65 20 62 65 66 6f 72 65 0a 2a 2a 20 63  file before.** c
1a70: 68 65 63 6b 70 6f 69 6e 74 69 6e 67 20 74 68 65  heckpointing the
1a80: 20 64 61 74 61 62 61 73 65 20 69 6e 20 57 41 4c   database in WAL
1a90: 20 6d 6f 64 65 2e 0a 2a 2f 0a 23 69 66 6e 64 65   mode..*/.#ifnde
1aa0: 66 20 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54  f SQLITE_DEFAULT
1ab0: 5f 57 41 4c 5f 41 55 54 4f 43 48 45 43 4b 50 4f  _WAL_AUTOCHECKPO
1ac0: 49 4e 54 0a 23 20 64 65 66 69 6e 65 20 53 51 4c  INT.# define SQL
1ad0: 49 54 45 5f 44 45 46 41 55 4c 54 5f 57 41 4c 5f  ITE_DEFAULT_WAL_
1ae0: 41 55 54 4f 43 48 45 43 4b 50 4f 49 4e 54 20 20  AUTOCHECKPOINT  
1af0: 31 30 30 30 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a  1000.#endif../*.
1b00: 2a 2a 20 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  ** The maximum n
1b10: 75 6d 62 65 72 20 6f 66 20 61 74 74 61 63 68 65  umber of attache
1b20: 64 20 64 61 74 61 62 61 73 65 73 2e 20 20 54 68  d databases.  Th
1b30: 69 73 20 6d 75 73 74 20 62 65 20 62 65 74 77 65  is must be betwe
1b40: 65 6e 20 30 0a 2a 2a 20 61 6e 64 20 36 32 2e 20  en 0.** and 62. 
1b50: 20 54 68 65 20 75 70 70 65 72 20 62 6f 75 6e 64   The upper bound
1b60: 20 6f 6e 20 36 32 20 69 73 20 62 65 63 61 75 73   on 62 is becaus
1b70: 65 20 61 20 36 34 2d 62 69 74 20 69 6e 74 65 67  e a 64-bit integ
1b80: 65 72 20 62 69 74 6d 61 70 0a 2a 2a 20 69 73 20  er bitmap.** is 
1b90: 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20  used internally 
1ba0: 74 6f 20 74 72 61 63 6b 20 61 74 74 61 63 68 65  to track attache
1bb0: 64 20 64 61 74 61 62 61 73 65 73 2e 0a 2a 2f 0a  d databases..*/.
1bc0: 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4d  #ifndef SQLITE_M
1bd0: 41 58 5f 41 54 54 41 43 48 45 44 0a 23 20 64 65  AX_ATTACHED.# de
1be0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 41 58 5f  fine SQLITE_MAX_
1bf0: 41 54 54 41 43 48 45 44 20 31 30 0a 23 65 6e 64  ATTACHED 10.#end
1c00: 69 66 0a 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 6d  if.../*.** The m
1c10: 61 78 69 6d 75 6d 20 76 61 6c 75 65 20 6f 66 20  aximum value of 
1c20: 61 20 3f 6e 6e 6e 20 77 69 6c 64 63 61 72 64 20  a ?nnn wildcard 
1c30: 74 68 61 74 20 74 68 65 20 70 61 72 73 65 72 20  that the parser 
1c40: 77 69 6c 6c 20 61 63 63 65 70 74 2e 0a 2a 2f 0a  will accept..*/.
1c50: 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4d  #ifndef SQLITE_M
1c60: 41 58 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42  AX_VARIABLE_NUMB
1c70: 45 52 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  ER.# define SQLI
1c80: 54 45 5f 4d 41 58 5f 56 41 52 49 41 42 4c 45 5f  TE_MAX_VARIABLE_
1c90: 4e 55 4d 42 45 52 20 39 39 39 0a 23 65 6e 64 69  NUMBER 999.#endi
1ca0: 66 0a 0a 2f 2a 20 4d 61 78 69 6d 75 6d 20 70 61  f../* Maximum pa
1cb0: 67 65 20 73 69 7a 65 2e 20 20 54 68 65 20 75 70  ge size.  The up
1cc0: 70 65 72 20 62 6f 75 6e 64 20 6f 6e 20 74 68 69  per bound on thi
1cd0: 73 20 76 61 6c 75 65 20 69 73 20 36 35 35 33 36  s value is 65536
1ce0: 2e 20 20 54 68 69 73 20 61 20 6c 69 6d 69 74 0a  .  This a limit.
1cf0: 2a 2a 20 69 6d 70 6f 73 65 64 20 62 79 20 74 68  ** imposed by th
1d00: 65 20 75 73 65 20 6f 66 20 31 36 2d 62 69 74 20  e use of 16-bit 
1d10: 6f 66 66 73 65 74 73 20 77 69 74 68 69 6e 20 65  offsets within e
1d20: 61 63 68 20 70 61 67 65 2e 0a 2a 2a 0a 2a 2a 20  ach page..**.** 
1d30: 45 61 72 6c 69 65 72 20 76 65 72 73 69 6f 6e 73  Earlier versions
1d40: 20 6f 66 20 53 51 4c 69 74 65 20 61 6c 6c 6f 77   of SQLite allow
1d50: 65 64 20 74 68 65 20 75 73 65 72 20 74 6f 20 63  ed the user to c
1d60: 68 61 6e 67 65 20 74 68 69 73 20 76 61 6c 75 65  hange this value
1d70: 20 61 74 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74   at.** compile t
1d80: 69 6d 65 2e 20 54 68 69 73 20 69 73 20 6e 6f 20  ime. This is no 
1d90: 6c 6f 6e 67 65 72 20 70 65 72 6d 69 74 74 65 64  longer permitted
1da0: 2c 20 6f 6e 20 74 68 65 20 67 72 6f 75 6e 64 73  , on the grounds
1db0: 20 74 68 61 74 20 69 74 20 63 72 65 61 74 65 73   that it creates
1dc0: 0a 2a 2a 20 61 20 6c 69 62 72 61 72 79 20 74 68  .** a library th
1dd0: 61 74 20 69 73 20 74 65 63 68 6e 69 63 61 6c 6c  at is technicall
1de0: 79 20 69 6e 63 6f 6d 70 61 74 69 62 6c 65 20 77  y incompatible w
1df0: 69 74 68 20 61 6e 20 53 51 4c 69 74 65 20 6c 69  ith an SQLite li
1e00: 62 72 61 72 79 20 0a 2a 2a 20 63 6f 6d 70 69 6c  brary .** compil
1e10: 65 64 20 77 69 74 68 20 61 20 64 69 66 66 65 72  ed with a differ
1e20: 65 6e 74 20 6c 69 6d 69 74 2e 20 49 66 20 61 20  ent limit. If a 
1e30: 70 72 6f 63 65 73 73 20 6f 70 65 72 61 74 69 6e  process operatin
1e40: 67 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20  g on a database 
1e50: 0a 2a 2a 20 77 69 74 68 20 61 20 70 61 67 65 2d  .** with a page-
1e60: 73 69 7a 65 20 6f 66 20 36 35 35 33 36 20 62 79  size of 65536 by
1e70: 74 65 73 20 63 72 61 73 68 65 73 2c 20 74 68 65  tes crashes, the
1e80: 6e 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  n an instance of
1e90: 20 53 51 4c 69 74 65 20 0a 2a 2a 20 63 6f 6d 70   SQLite .** comp
1ea0: 69 6c 65 64 20 77 69 74 68 20 74 68 65 20 64 65  iled with the de
1eb0: 66 61 75 6c 74 20 70 61 67 65 2d 73 69 7a 65 20  fault page-size 
1ec0: 6c 69 6d 69 74 20 77 69 6c 6c 20 6e 6f 74 20 62  limit will not b
1ed0: 65 20 61 62 6c 65 20 74 6f 20 72 6f 6c 6c 62 61  e able to rollba
1ee0: 63 6b 20 0a 2a 2a 20 74 68 65 20 61 62 6f 72 74  ck .** the abort
1ef0: 65 64 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20  ed transaction. 
1f00: 54 68 69 73 20 63 6f 75 6c 64 20 6c 65 61 64 20  This could lead 
1f10: 74 6f 20 64 61 74 61 62 61 73 65 20 63 6f 72 72  to database corr
1f20: 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 23 69 66 64 65  uption..*/.#ifde
1f30: 66 20 53 51 4c 49 54 45 5f 4d 41 58 5f 50 41 47  f SQLITE_MAX_PAG
1f40: 45 5f 53 49 5a 45 0a 23 20 75 6e 64 65 66 20 53  E_SIZE.# undef S
1f50: 51 4c 49 54 45 5f 4d 41 58 5f 50 41 47 45 5f 53  QLITE_MAX_PAGE_S
1f60: 49 5a 45 0a 23 65 6e 64 69 66 0a 23 64 65 66 69  IZE.#endif.#defi
1f70: 6e 65 20 53 51 4c 49 54 45 5f 4d 41 58 5f 50 41  ne SQLITE_MAX_PA
1f80: 47 45 5f 53 49 5a 45 20 36 35 35 33 36 0a 0a 0a  GE_SIZE 65536...
1f90: 2f 2a 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c  /*.** The defaul
1fa0: 74 20 73 69 7a 65 20 6f 66 20 61 20 64 61 74 61  t size of a data
1fb0: 62 61 73 65 20 70 61 67 65 2e 0a 2a 2f 0a 23 69  base page..*/.#i
1fc0: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 44 45 46  fndef SQLITE_DEF
1fd0: 41 55 4c 54 5f 50 41 47 45 5f 53 49 5a 45 0a 23  AULT_PAGE_SIZE.#
1fe0: 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44   define SQLITE_D
1ff0: 45 46 41 55 4c 54 5f 50 41 47 45 5f 53 49 5a 45  EFAULT_PAGE_SIZE
2000: 20 31 30 32 34 0a 23 65 6e 64 69 66 0a 23 69 66   1024.#endif.#if
2010: 20 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f   SQLITE_DEFAULT_
2020: 50 41 47 45 5f 53 49 5a 45 3e 53 51 4c 49 54 45  PAGE_SIZE>SQLITE
2030: 5f 4d 41 58 5f 50 41 47 45 5f 53 49 5a 45 0a 23  _MAX_PAGE_SIZE.#
2040: 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 44 45   undef SQLITE_DE
2050: 46 41 55 4c 54 5f 50 41 47 45 5f 53 49 5a 45 0a  FAULT_PAGE_SIZE.
2060: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
2070: 44 45 46 41 55 4c 54 5f 50 41 47 45 5f 53 49 5a  DEFAULT_PAGE_SIZ
2080: 45 20 53 51 4c 49 54 45 5f 4d 41 58 5f 50 41 47  E SQLITE_MAX_PAG
2090: 45 5f 53 49 5a 45 0a 23 65 6e 64 69 66 0a 0a 2f  E_SIZE.#endif../
20a0: 2a 0a 2a 2a 20 4f 72 64 69 6e 61 72 69 6c 79 2c  *.** Ordinarily,
20b0: 20 69 66 20 6e 6f 20 76 61 6c 75 65 20 69 73 20   if no value is 
20c0: 65 78 70 6c 69 63 69 74 6c 79 20 70 72 6f 76 69  explicitly provi
20d0: 64 65 64 2c 20 53 51 4c 69 74 65 20 63 72 65 61  ded, SQLite crea
20e0: 74 65 73 20 64 61 74 61 62 61 73 65 73 0a 2a 2a  tes databases.**
20f0: 20 77 69 74 68 20 70 61 67 65 20 73 69 7a 65 20   with page size 
2100: 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 50  SQLITE_DEFAULT_P
2110: 41 47 45 5f 53 49 5a 45 2e 20 48 6f 77 65 76 65  AGE_SIZE. Howeve
2120: 72 2c 20 62 61 73 65 64 20 6f 6e 20 63 65 72 74  r, based on cert
2130: 61 69 6e 0a 2a 2a 20 64 65 76 69 63 65 20 63 68  ain.** device ch
2140: 61 72 61 63 74 65 72 69 73 74 69 63 73 20 28 73  aracteristics (s
2150: 65 63 74 6f 72 2d 73 69 7a 65 20 61 6e 64 20 61  ector-size and a
2160: 74 6f 6d 69 63 20 77 72 69 74 65 28 29 20 73 75  tomic write() su
2170: 70 70 6f 72 74 29 2c 0a 2a 2a 20 53 51 4c 69 74  pport),.** SQLit
2180: 65 20 6d 61 79 20 63 68 6f 6f 73 65 20 61 20 6c  e may choose a l
2190: 61 72 67 65 72 20 76 61 6c 75 65 2e 20 54 68 69  arger value. Thi
21a0: 73 20 63 6f 6e 73 74 61 6e 74 20 69 73 20 74 68  s constant is th
21b0: 65 20 6d 61 78 69 6d 75 6d 20 76 61 6c 75 65 0a  e maximum value.
21c0: 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 63  ** SQLite will c
21d0: 68 6f 6f 73 65 20 6f 6e 20 69 74 73 20 6f 77 6e  hoose on its own
21e0: 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c  ..*/.#ifndef SQL
21f0: 49 54 45 5f 4d 41 58 5f 44 45 46 41 55 4c 54 5f  ITE_MAX_DEFAULT_
2200: 50 41 47 45 5f 53 49 5a 45 0a 23 20 64 65 66 69  PAGE_SIZE.# defi
2210: 6e 65 20 53 51 4c 49 54 45 5f 4d 41 58 5f 44 45  ne SQLITE_MAX_DE
2220: 46 41 55 4c 54 5f 50 41 47 45 5f 53 49 5a 45 20  FAULT_PAGE_SIZE 
2230: 38 31 39 32 0a 23 65 6e 64 69 66 0a 23 69 66 20  8192.#endif.#if 
2240: 53 51 4c 49 54 45 5f 4d 41 58 5f 44 45 46 41 55  SQLITE_MAX_DEFAU
2250: 4c 54 5f 50 41 47 45 5f 53 49 5a 45 3e 53 51 4c  LT_PAGE_SIZE>SQL
2260: 49 54 45 5f 4d 41 58 5f 50 41 47 45 5f 53 49 5a  ITE_MAX_PAGE_SIZ
2270: 45 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45  E.# undef SQLITE
2280: 5f 4d 41 58 5f 44 45 46 41 55 4c 54 5f 50 41 47  _MAX_DEFAULT_PAG
2290: 45 5f 53 49 5a 45 0a 23 20 64 65 66 69 6e 65 20  E_SIZE.# define 
22a0: 53 51 4c 49 54 45 5f 4d 41 58 5f 44 45 46 41 55  SQLITE_MAX_DEFAU
22b0: 4c 54 5f 50 41 47 45 5f 53 49 5a 45 20 53 51 4c  LT_PAGE_SIZE SQL
22c0: 49 54 45 5f 4d 41 58 5f 50 41 47 45 5f 53 49 5a  ITE_MAX_PAGE_SIZ
22d0: 45 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a 2a  E.#endif.../*.**
22e0: 20 4d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   Maximum number 
22f0: 6f 66 20 70 61 67 65 73 20 69 6e 20 6f 6e 65 20  of pages in one 
2300: 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a  database file..*
2310: 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 72 65 61  *.** This is rea
2320: 6c 6c 79 20 6a 75 73 74 20 74 68 65 20 64 65 66  lly just the def
2330: 61 75 6c 74 20 76 61 6c 75 65 20 66 6f 72 20 74  ault value for t
2340: 68 65 20 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e  he max_page_coun
2350: 74 20 70 72 61 67 6d 61 2e 0a 2a 2a 20 54 68 69  t pragma..** Thi
2360: 73 20 76 61 6c 75 65 20 63 61 6e 20 62 65 20 6c  s value can be l
2370: 6f 77 65 72 65 64 20 28 6f 72 20 72 61 69 73 65  owered (or raise
2380: 64 29 20 61 74 20 72 75 6e 2d 74 69 6d 65 20 75  d) at run-time u
2390: 73 69 6e 67 20 74 68 61 74 20 74 68 65 0a 2a 2a  sing that the.**
23a0: 20 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 20   max_page_count 
23b0: 6d 61 63 72 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65  macro..*/.#ifnde
23c0: 66 20 53 51 4c 49 54 45 5f 4d 41 58 5f 50 41 47  f SQLITE_MAX_PAG
23d0: 45 5f 43 4f 55 4e 54 0a 23 20 64 65 66 69 6e 65  E_COUNT.# define
23e0: 20 53 51 4c 49 54 45 5f 4d 41 58 5f 50 41 47 45   SQLITE_MAX_PAGE
23f0: 5f 43 4f 55 4e 54 20 31 30 37 33 37 34 31 38 32  _COUNT 107374182
2400: 33 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20  3.#endif../*.** 
2410: 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 28  Maximum length (
2420: 69 6e 20 62 79 74 65 73 29 20 6f 66 20 74 68 65  in bytes) of the
2430: 20 70 61 74 74 65 72 6e 20 69 6e 20 61 20 4c 49   pattern in a LI
2440: 4b 45 20 6f 72 20 47 4c 4f 42 0a 2a 2a 20 6f 70  KE or GLOB.** op
2450: 65 72 61 74 6f 72 2e 0a 2a 2f 0a 23 69 66 6e 64  erator..*/.#ifnd
2460: 65 66 20 53 51 4c 49 54 45 5f 4d 41 58 5f 4c 49  ef SQLITE_MAX_LI
2470: 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54  KE_PATTERN_LENGT
2480: 48 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54  H.# define SQLIT
2490: 45 5f 4d 41 58 5f 4c 49 4b 45 5f 50 41 54 54 45  E_MAX_LIKE_PATTE
24a0: 52 4e 5f 4c 45 4e 47 54 48 20 35 30 30 30 30 0a  RN_LENGTH 50000.
24b0: 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 4d 61  #endif../*.** Ma
24c0: 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 72  ximum depth of r
24d0: 65 63 75 72 73 69 6f 6e 20 66 6f 72 20 74 72 69  ecursion for tri
24e0: 67 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 76  ggers..**.** A v
24f0: 61 6c 75 65 20 6f 66 20 31 20 6d 65 61 6e 73 20  alue of 1 means 
2500: 74 68 61 74 20 61 20 74 72 69 67 67 65 72 20 70  that a trigger p
2510: 72 6f 67 72 61 6d 20 77 69 6c 6c 20 6e 6f 74 20  rogram will not 
2520: 62 65 20 61 62 6c 65 20 74 6f 20 69 74 73 65 6c  be able to itsel
2530: 66 0a 2a 2a 20 66 69 72 65 20 61 6e 79 20 74 72  f.** fire any tr
2540: 69 67 67 65 72 73 2e 20 41 20 76 61 6c 75 65 20  iggers. A value 
2550: 6f 66 20 30 20 6d 65 61 6e 73 20 74 68 61 74 20  of 0 means that 
2560: 6e 6f 20 74 72 69 67 67 65 72 20 70 72 6f 67 72  no trigger progr
2570: 61 6d 73 20 61 74 20 61 6c 6c 20 0a 2a 2a 20 6d  ams at all .** m
2580: 61 79 20 62 65 20 65 78 65 63 75 74 65 64 2e 0a  ay be executed..
2590: 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54  */.#ifndef SQLIT
25a0: 45 5f 4d 41 58 5f 54 52 49 47 47 45 52 5f 44 45  E_MAX_TRIGGER_DE
25b0: 50 54 48 0a 23 20 64 65 66 69 6e 65 20 53 51 4c  PTH.# define SQL
25c0: 49 54 45 5f 4d 41 58 5f 54 52 49 47 47 45 52 5f  ITE_MAX_TRIGGER_
25d0: 44 45 50 54 48 20 31 30 30 30 0a 23 65 6e 64 69  DEPTH 1000.#endi
25e0: 66 0a 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  f../************
25f0: 2a 2a 20 45 6e 64 20 6f 66 20 73 71 6c 69 74 65  ** End of sqlite
2600: 4c 69 6d 69 74 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a  Limit.h ********
2610: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
2620: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
2630: 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  */./************
2640: 2a 2a 20 43 6f 6e 74 69 6e 75 69 6e 67 20 77 68  ** Continuing wh
2650: 65 72 65 20 77 65 20 6c 65 66 74 20 6f 66 66 20  ere we left off 
2660: 69 6e 20 73 71 6c 69 74 65 49 6e 74 2e 68 20 2a  in sqliteInt.h *
2670: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
2680: 2a 2f 0a 0a 2f 2a 20 44 69 73 61 62 6c 65 20 6e  */../* Disable n
2690: 75 69 73 61 6e 63 65 20 77 61 72 6e 69 6e 67 73  uisance warnings
26a0: 20 6f 6e 20 42 6f 72 6c 61 6e 64 20 63 6f 6d 70   on Borland comp
26b0: 69 6c 65 72 73 20 2a 2f 0a 23 69 66 20 64 65 66  ilers */.#if def
26c0: 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f  ined(__BORLANDC_
26d0: 5f 29 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 20  _).#pragma warn 
26e0: 2d 72 63 68 20 2f 2a 20 75 6e 72 65 61 63 68 61  -rch /* unreacha
26f0: 62 6c 65 20 63 6f 64 65 20 2a 2f 0a 23 70 72 61  ble code */.#pra
2700: 67 6d 61 20 77 61 72 6e 20 2d 63 63 63 20 2f 2a  gma warn -ccc /*
2710: 20 43 6f 6e 64 69 74 69 6f 6e 20 69 73 20 61 6c   Condition is al
2720: 77 61 79 73 20 74 72 75 65 20 6f 72 20 66 61 6c  ways true or fal
2730: 73 65 20 2a 2f 0a 23 70 72 61 67 6d 61 20 77 61  se */.#pragma wa
2740: 72 6e 20 2d 61 75 73 20 2f 2a 20 41 73 73 69 67  rn -aus /* Assig
2750: 6e 65 64 20 76 61 6c 75 65 20 69 73 20 6e 65 76  ned value is nev
2760: 65 72 20 75 73 65 64 20 2a 2f 0a 23 70 72 61 67  er used */.#prag
2770: 6d 61 20 77 61 72 6e 20 2d 63 73 75 20 2f 2a 20  ma warn -csu /* 
2780: 43 6f 6d 70 61 72 69 6e 67 20 73 69 67 6e 65 64  Comparing signed
2790: 20 61 6e 64 20 75 6e 73 69 67 6e 65 64 20 2a 2f   and unsigned */
27a0: 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 20 2d 73  .#pragma warn -s
27b0: 70 61 20 2f 2a 20 53 75 73 70 69 63 69 6f 75 73  pa /* Suspicious
27c0: 20 70 6f 69 6e 74 65 72 20 61 72 69 74 68 6d 65   pointer arithme
27d0: 74 69 63 20 2a 2f 0a 23 65 6e 64 69 66 0a 0a 2f  tic */.#endif../
27e0: 2a 20 4e 65 65 64 65 64 20 66 6f 72 20 76 61 72  * Needed for var
27f0: 69 6f 75 73 20 64 65 66 69 6e 69 74 69 6f 6e 73  ious definitions
2800: 2e 2e 2e 20 2a 2f 0a 23 69 66 6e 64 65 66 20 5f  ... */.#ifndef _
2810: 47 4e 55 5f 53 4f 55 52 43 45 0a 23 20 64 65 66  GNU_SOURCE.# def
2820: 69 6e 65 20 5f 47 4e 55 5f 53 4f 55 52 43 45 0a  ine _GNU_SOURCE.
2830: 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 49 6e  #endif../*.** In
2840: 63 6c 75 64 65 20 73 74 61 6e 64 61 72 64 20 68  clude standard h
2850: 65 61 64 65 72 20 66 69 6c 65 73 20 61 73 20 6e  eader files as n
2860: 65 63 65 73 73 61 72 79 0a 2a 2f 0a 23 69 66 64  ecessary.*/.#ifd
2870: 65 66 20 48 41 56 45 5f 53 54 44 49 4e 54 5f 48  ef HAVE_STDINT_H
2880: 0a 23 69 6e 63 6c 75 64 65 20 3c 73 74 64 69 6e  .#include <stdin
2890: 74 2e 68 3e 0a 23 65 6e 64 69 66 0a 23 69 66 64  t.h>.#endif.#ifd
28a0: 65 66 20 48 41 56 45 5f 49 4e 54 54 59 50 45 53  ef HAVE_INTTYPES
28b0: 5f 48 0a 23 69 6e 63 6c 75 64 65 20 3c 69 6e 74  _H.#include <int
28c0: 74 79 70 65 73 2e 68 3e 0a 23 65 6e 64 69 66 0a  types.h>.#endif.
28d0: 0a 2f 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f  ./*.** The follo
28e0: 77 69 6e 67 20 6d 61 63 72 6f 73 20 61 72 65 20  wing macros are 
28f0: 75 73 65 64 20 74 6f 20 63 61 73 74 20 70 6f 69  used to cast poi
2900: 6e 74 65 72 73 20 74 6f 20 69 6e 74 65 67 65 72  nters to integer
2910: 73 20 61 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 72  s and.** integer
2920: 73 20 74 6f 20 70 6f 69 6e 74 65 72 73 2e 20 20  s to pointers.  
2930: 54 68 65 20 77 61 79 20 79 6f 75 20 64 6f 20 74  The way you do t
2940: 68 69 73 20 76 61 72 69 65 73 20 66 72 6f 6d 20  his varies from 
2950: 6f 6e 65 20 63 6f 6d 70 69 6c 65 72 0a 2a 2a 20  one compiler.** 
2960: 74 6f 20 74 68 65 20 6e 65 78 74 2c 20 73 6f 20  to the next, so 
2970: 77 65 20 68 61 76 65 20 64 65 76 65 6c 6f 70 65  we have develope
2980: 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  d the following 
2990: 73 65 74 20 6f 66 20 23 69 66 20 73 74 61 74 65  set of #if state
29a0: 6d 65 6e 74 73 0a 2a 2a 20 74 6f 20 67 65 6e 65  ments.** to gene
29b0: 72 61 74 65 20 61 70 70 72 6f 70 72 69 61 74 65  rate appropriate
29c0: 20 6d 61 63 72 6f 73 20 66 6f 72 20 61 20 77 69   macros for a wi
29d0: 64 65 20 72 61 6e 67 65 20 6f 66 20 63 6f 6d 70  de range of comp
29e0: 69 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ilers..**.** The
29f0: 20 63 6f 72 72 65 63 74 20 22 41 4e 53 49 22 20   correct "ANSI" 
2a00: 77 61 79 20 74 6f 20 64 6f 20 74 68 69 73 20 69  way to do this i
2a10: 73 20 74 6f 20 75 73 65 20 74 68 65 20 69 6e 74  s to use the int
2a20: 70 74 72 5f 74 20 74 79 70 65 2e 20 0a 2a 2a 20  ptr_t type. .** 
2a30: 55 6e 66 6f 72 74 75 6e 61 74 65 6c 79 2c 20 74  Unfortunately, t
2a40: 68 61 74 20 74 79 70 65 64 65 66 20 69 73 20 6e  hat typedef is n
2a50: 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 6f 6e 20  ot available on 
2a60: 61 6c 6c 20 63 6f 6d 70 69 6c 65 72 73 2c 20 6f  all compilers, o
2a70: 72 0a 2a 2a 20 69 66 20 69 74 20 69 73 20 61 76  r.** if it is av
2a80: 61 69 6c 61 62 6c 65 2c 20 69 74 20 72 65 71 75  ailable, it requ
2a90: 69 72 65 73 20 61 6e 20 23 69 6e 63 6c 75 64 65  ires an #include
2aa0: 20 6f 66 20 73 70 65 63 69 66 69 63 20 68 65 61   of specific hea
2ab0: 64 65 72 73 0a 2a 2a 20 74 68 61 74 20 76 61 72  ders.** that var
2ac0: 79 20 66 72 6f 6d 20 6f 6e 65 20 6d 61 63 68 69  y from one machi
2ad0: 6e 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a  ne to the next..
2ae0: 2a 2a 0a 2a 2a 20 54 69 63 6b 65 74 20 23 33 38  **.** Ticket #38
2af0: 36 30 3a 20 20 54 68 65 20 6c 6c 76 6d 2d 67 63  60:  The llvm-gc
2b00: 63 2d 34 2e 32 20 63 6f 6d 70 69 6c 65 72 20 66  c-4.2 compiler f
2b10: 72 6f 6d 20 41 70 70 6c 65 20 63 68 6f 6b 65 73  rom Apple chokes
2b20: 20 6f 6e 0a 2a 2a 20 74 68 65 20 28 28 76 6f 69   on.** the ((voi
2b30: 64 2a 29 26 28 28 63 68 61 72 2a 29 30 29 5b 58  d*)&((char*)0)[X
2b40: 5d 29 20 63 6f 6e 73 74 72 75 63 74 2e 20 20 42  ]) construct.  B
2b50: 75 74 20 4d 53 56 43 20 63 68 6f 6b 65 73 20 6f  ut MSVC chokes o
2b60: 6e 20 28 28 76 6f 69 64 2a 29 28 58 29 29 2e 0a  n ((void*)(X))..
2b70: 2a 2a 20 53 6f 20 77 65 20 68 61 76 65 20 74 6f  ** So we have to
2b80: 20 64 65 66 69 6e 65 20 74 68 65 20 6d 61 63 72   define the macr
2b90: 6f 73 20 69 6e 20 64 69 66 66 65 72 65 6e 74 20  os in different 
2ba0: 77 61 79 73 20 64 65 70 65 6e 64 69 6e 67 20 6f  ways depending o
2bb0: 6e 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65  n the.** compile
2bc0: 72 2e 0a 2a 2f 0a 23 69 66 20 64 65 66 69 6e 65  r..*/.#if define
2bd0: 64 28 5f 5f 50 54 52 44 49 46 46 5f 54 59 50 45  d(__PTRDIFF_TYPE
2be0: 5f 5f 29 20 20 2f 2a 20 54 68 69 73 20 63 61 73  __)  /* This cas
2bf0: 65 20 73 68 6f 75 6c 64 20 77 6f 72 6b 20 66 6f  e should work fo
2c00: 72 20 47 43 43 20 2a 2f 0a 23 20 64 65 66 69 6e  r GCC */.# defin
2c10: 65 20 53 51 4c 49 54 45 5f 49 4e 54 5f 54 4f 5f  e SQLITE_INT_TO_
2c20: 50 54 52 28 58 29 20 20 28 28 76 6f 69 64 2a 29  PTR(X)  ((void*)
2c30: 28 5f 5f 50 54 52 44 49 46 46 5f 54 59 50 45 5f  (__PTRDIFF_TYPE_
2c40: 5f 29 28 58 29 29 0a 23 20 64 65 66 69 6e 65 20  _)(X)).# define 
2c50: 53 51 4c 49 54 45 5f 50 54 52 5f 54 4f 5f 49 4e  SQLITE_PTR_TO_IN
2c60: 54 28 58 29 20 20 28 28 69 6e 74 29 28 5f 5f 50  T(X)  ((int)(__P
2c70: 54 52 44 49 46 46 5f 54 59 50 45 5f 5f 29 28 58  TRDIFF_TYPE__)(X
2c80: 29 29 0a 23 65 6c 69 66 20 21 64 65 66 69 6e 65  )).#elif !define
2c90: 64 28 5f 5f 47 4e 55 43 5f 5f 29 20 20 20 20 20  d(__GNUC__)     
2ca0: 20 20 2f 2a 20 57 6f 72 6b 73 20 66 6f 72 20 63    /* Works for c
2cb0: 6f 6d 70 69 6c 65 72 73 20 6f 74 68 65 72 20 74  ompilers other t
2cc0: 68 61 6e 20 4c 4c 56 4d 20 2a 2f 0a 23 20 64 65  han LLVM */.# de
2cd0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 5f  fine SQLITE_INT_
2ce0: 54 4f 5f 50 54 52 28 58 29 20 20 28 28 76 6f 69  TO_PTR(X)  ((voi
2cf0: 64 2a 29 26 28 28 63 68 61 72 2a 29 30 29 5b 58  d*)&((char*)0)[X
2d00: 5d 29 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  ]).# define SQLI
2d10: 54 45 5f 50 54 52 5f 54 4f 5f 49 4e 54 28 58 29  TE_PTR_TO_INT(X)
2d20: 20 20 28 28 69 6e 74 29 28 28 28 63 68 61 72 2a    ((int)(((char*
2d30: 29 58 29 2d 28 63 68 61 72 2a 29 30 29 29 0a 23  )X)-(char*)0)).#
2d40: 65 6c 69 66 20 64 65 66 69 6e 65 64 28 48 41 56  elif defined(HAV
2d50: 45 5f 53 54 44 49 4e 54 5f 48 29 20 20 20 2f 2a  E_STDINT_H)   /*
2d60: 20 55 73 65 20 74 68 69 73 20 63 61 73 65 20 69   Use this case i
2d70: 66 20 77 65 20 68 61 76 65 20 41 4e 53 49 20 68  f we have ANSI h
2d80: 65 61 64 65 72 73 20 2a 2f 0a 23 20 64 65 66 69  eaders */.# defi
2d90: 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 5f 54 4f  ne SQLITE_INT_TO
2da0: 5f 50 54 52 28 58 29 20 20 28 28 76 6f 69 64 2a  _PTR(X)  ((void*
2db0: 29 28 69 6e 74 70 74 72 5f 74 29 28 58 29 29 0a  )(intptr_t)(X)).
2dc0: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
2dd0: 50 54 52 5f 54 4f 5f 49 4e 54 28 58 29 20 20 28  PTR_TO_INT(X)  (
2de0: 28 69 6e 74 29 28 69 6e 74 70 74 72 5f 74 29 28  (int)(intptr_t)(
2df0: 58 29 29 0a 23 65 6c 73 65 20 20 20 20 20 20 20  X)).#else       
2e00: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2e10: 20 20 20 2f 2a 20 47 65 6e 65 72 61 74 65 73 20     /* Generates 
2e20: 61 20 77 61 72 6e 69 6e 67 20 2d 20 62 75 74 20  a warning - but 
2e30: 69 74 20 61 6c 77 61 79 73 20 77 6f 72 6b 73 20  it always works 
2e40: 2a 2f 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  */.# define SQLI
2e50: 54 45 5f 49 4e 54 5f 54 4f 5f 50 54 52 28 58 29  TE_INT_TO_PTR(X)
2e60: 20 20 28 28 76 6f 69 64 2a 29 28 58 29 29 0a 23    ((void*)(X)).#
2e70: 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50   define SQLITE_P
2e80: 54 52 5f 54 4f 5f 49 4e 54 28 58 29 20 20 28 28  TR_TO_INT(X)  ((
2e90: 69 6e 74 29 28 58 29 29 0a 23 65 6e 64 69 66 0a  int)(X)).#endif.
2ea0: 0a 2f 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54  ./*.** The SQLIT
2eb0: 45 5f 54 48 52 45 41 44 53 41 46 45 20 6d 61 63  E_THREADSAFE mac
2ec0: 72 6f 20 6d 75 73 74 20 62 65 20 64 65 66 69 6e  ro must be defin
2ed0: 65 64 20 61 73 20 30 2c 20 31 2c 20 6f 72 20 32  ed as 0, 1, or 2
2ee0: 2e 0a 2a 2a 20 30 20 6d 65 61 6e 73 20 6d 75 74  ..** 0 means mut
2ef0: 65 78 65 73 20 61 72 65 20 70 65 72 6d 61 6e 65  exes are permane
2f00: 6e 74 6c 79 20 64 69 73 61 62 6c 65 20 61 6e 64  ntly disable and
2f10: 20 74 68 65 20 6c 69 62 72 61 72 79 20 69 73 20   the library is 
2f20: 6e 65 76 65 72 0a 2a 2a 20 74 68 72 65 61 64 73  never.** threads
2f30: 61 66 65 2e 20 20 31 20 6d 65 61 6e 73 20 74 68  afe.  1 means th
2f40: 65 20 6c 69 62 72 61 72 79 20 69 73 20 73 65 72  e library is ser
2f50: 69 61 6c 69 7a 65 64 20 77 68 69 63 68 20 69 73  ialized which is
2f60: 20 74 68 65 20 68 69 67 68 65 73 74 0a 2a 2a 20   the highest.** 
2f70: 6c 65 76 65 6c 20 6f 66 20 74 68 72 65 61 64 73  level of threads
2f80: 61 66 65 74 79 2e 20 20 32 20 6d 65 61 6e 73 20  afety.  2 means 
2f90: 74 68 65 20 6c 69 62 61 72 79 20 69 73 20 6d 75  the libary is mu
2fa0: 6c 74 69 74 68 72 65 61 64 65 64 20 2d 20 6d 75  ltithreaded - mu
2fb0: 6c 74 69 70 6c 65 0a 2a 2a 20 74 68 72 65 61 64  ltiple.** thread
2fc0: 73 20 63 61 6e 20 75 73 65 20 53 51 4c 69 74 65  s can use SQLite
2fd0: 20 61 73 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74   as long as no t
2fe0: 77 6f 20 74 68 72 65 61 64 73 20 74 72 79 20 74  wo threads try t
2ff0: 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 0a 2a  o use the same.*
3000: 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
3010: 63 74 69 6f 6e 20 61 74 20 74 68 65 20 73 61 6d  ction at the sam
3020: 65 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 4f 6c  e time..**.** Ol
3030: 64 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  der versions of 
3040: 53 51 4c 69 74 65 20 75 73 65 64 20 61 6e 20 6f  SQLite used an o
3050: 70 74 69 6f 6e 61 6c 20 54 48 52 45 41 44 53 41  ptional THREADSA
3060: 46 45 20 6d 61 63 72 6f 2e 0a 2a 2a 20 57 65 20  FE macro..** We 
3070: 73 75 70 70 6f 72 74 20 74 68 61 74 20 66 6f 72  support that for
3080: 20 6c 65 67 61 63 79 2e 0a 2a 2f 0a 23 69 66 20   legacy..*/.#if 
3090: 21 64 65 66 69 6e 65 64 28 53 51 4c 49 54 45 5f  !defined(SQLITE_
30a0: 54 48 52 45 41 44 53 41 46 45 29 0a 23 69 66 20  THREADSAFE).#if 
30b0: 64 65 66 69 6e 65 64 28 54 48 52 45 41 44 53 41  defined(THREADSA
30c0: 46 45 29 0a 23 20 64 65 66 69 6e 65 20 53 51 4c  FE).# define SQL
30d0: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 54  ITE_THREADSAFE T
30e0: 48 52 45 41 44 53 41 46 45 0a 23 65 6c 73 65 0a  HREADSAFE.#else.
30f0: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
3100: 54 48 52 45 41 44 53 41 46 45 20 31 20 2f 2a 20  THREADSAFE 1 /* 
3110: 49 4d 50 3a 20 52 2d 30 37 32 37 32 2d 32 32 33  IMP: R-07272-223
3120: 30 39 20 2a 2f 0a 23 65 6e 64 69 66 0a 23 65 6e  09 */.#endif.#en
3130: 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 50 6f 77 65 72  dif../*.** Power
3140: 73 61 66 65 20 6f 76 65 72 77 72 69 74 65 20 69  safe overwrite i
3150: 73 20 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e  s on by default.
3160: 20 20 42 75 74 20 63 61 6e 20 62 65 20 74 75 72    But can be tur
3170: 6e 65 64 20 6f 66 66 20 75 73 69 6e 67 0a 2a 2a  ned off using.**
3180: 20 74 68 65 20 2d 44 53 51 4c 49 54 45 5f 50 4f   the -DSQLITE_PO
3190: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54  WERSAFE_OVERWRIT
31a0: 45 3d 30 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65  E=0 command-line
31b0: 20 6f 70 74 69 6f 6e 2e 0a 2a 2f 0a 23 69 66 6e   option..*/.#ifn
31c0: 64 65 66 20 53 51 4c 49 54 45 5f 50 4f 57 45 52  def SQLITE_POWER
31d0: 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 0a 23  SAFE_OVERWRITE.#
31e0: 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50   define SQLITE_P
31f0: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49  OWERSAFE_OVERWRI
3200: 54 45 20 31 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a  TE 1.#endif../*.
3210: 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 44 45  ** The SQLITE_DE
3220: 46 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 20  FAULT_MEMSTATUS 
3230: 6d 61 63 72 6f 20 6d 75 73 74 20 62 65 20 64 65  macro must be de
3240: 66 69 6e 65 64 20 61 73 20 65 69 74 68 65 72 20  fined as either 
3250: 30 20 6f 72 20 31 2e 0a 2a 2a 20 49 74 20 64 65  0 or 1..** It de
3260: 74 65 72 6d 69 6e 65 73 20 77 68 65 74 68 65 72  termines whether
3270: 20 6f 72 20 6e 6f 74 20 74 68 65 20 66 65 61 74   or not the feat
3280: 75 72 65 73 20 72 65 6c 61 74 65 64 20 74 6f 20  ures related to 
3290: 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  .** SQLITE_CONFI
32a0: 47 5f 4d 45 4d 53 54 41 54 55 53 20 61 72 65 20  G_MEMSTATUS are 
32b0: 61 76 61 69 6c 61 62 6c 65 20 62 79 20 64 65 66  available by def
32c0: 61 75 6c 74 20 6f 72 20 6e 6f 74 2e 20 54 68 69  ault or not. Thi
32d0: 73 20 76 61 6c 75 65 20 63 61 6e 0a 2a 2a 20 62  s value can.** b
32e0: 65 20 6f 76 65 72 72 69 64 64 65 6e 20 61 74 20  e overridden at 
32f0: 72 75 6e 74 69 6d 65 20 75 73 69 6e 67 20 74 68  runtime using th
3300: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  e sqlite3_config
3310: 28 29 20 41 50 49 2e 0a 2a 2f 0a 23 69 66 20 21  () API..*/.#if !
3320: 64 65 66 69 6e 65 64 28 53 51 4c 49 54 45 5f 44  defined(SQLITE_D
3330: 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53  EFAULT_MEMSTATUS
3340: 29 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54  ).# define SQLIT
3350: 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41  E_DEFAULT_MEMSTA
3360: 54 55 53 20 31 0a 23 65 6e 64 69 66 0a 0a 2f 2a  TUS 1.#endif../*
3370: 0a 2a 2a 20 45 78 61 63 74 6c 79 20 6f 6e 65 20  .** Exactly one 
3380: 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  of the following
3390: 20 6d 61 63 72 6f 73 20 6d 75 73 74 20 62 65 20   macros must be 
33a0: 64 65 66 69 6e 65 64 20 69 6e 20 6f 72 64 65 72  defined in order
33b0: 20 74 6f 0a 2a 2a 20 73 70 65 63 69 66 79 20 77   to.** specify w
33c0: 68 69 63 68 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  hich memory allo
33d0: 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d  cation subsystem
33e0: 20 74 6f 20 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 20   to use..**.**  
33f0: 20 20 20 53 51 4c 49 54 45 5f 53 59 53 54 45 4d     SQLITE_SYSTEM
3400: 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 20  _MALLOC         
3410: 20 2f 2f 20 55 73 65 20 6e 6f 72 6d 61 6c 20 73   // Use normal s
3420: 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 0a 2a  ystem malloc().*
3430: 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 57 49 4e  *     SQLITE_WIN
3440: 33 32 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20  32_MALLOC       
3450: 20 20 20 20 2f 2f 20 55 73 65 20 57 69 6e 33 32      // Use Win32
3460: 20 6e 61 74 69 76 65 20 68 65 61 70 20 41 50 49   native heap API
3470: 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 5a  .**     SQLITE_Z
3480: 45 52 4f 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20  ERO_MALLOC      
3490: 20 20 20 20 20 20 2f 2f 20 55 73 65 20 61 20 73        // Use a s
34a0: 74 75 62 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68  tub allocator th
34b0: 61 74 20 61 6c 77 61 79 73 20 66 61 69 6c 73 0a  at always fails.
34c0: 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4d 45  **     SQLITE_ME
34d0: 4d 44 45 42 55 47 20 20 20 20 20 20 20 20 20 20  MDEBUG          
34e0: 20 20 20 20 20 2f 2f 20 44 65 62 75 67 67 69 6e       // Debuggin
34f0: 67 20 76 65 72 73 69 6f 6e 20 6f 66 20 73 79 73  g version of sys
3500: 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 0a 2a 2a 0a  tem malloc().**.
3510: 2a 2a 20 4f 6e 20 57 69 6e 64 6f 77 73 2c 20 69  ** On Windows, i
3520: 66 20 74 68 65 20 53 51 4c 49 54 45 5f 57 49 4e  f the SQLITE_WIN
3530: 33 32 5f 4d 41 4c 4c 4f 43 5f 56 41 4c 49 44 41  32_MALLOC_VALIDA
3540: 54 45 20 6d 61 63 72 6f 20 69 73 20 64 65 66 69  TE macro is defi
3550: 6e 65 64 20 61 6e 64 20 74 68 65 0a 2a 2a 20 61  ned and the.** a
3560: 73 73 65 72 74 28 29 20 6d 61 63 72 6f 20 69 73  ssert() macro is
3570: 20 65 6e 61 62 6c 65 64 2c 20 65 61 63 68 20 63   enabled, each c
3580: 61 6c 6c 20 69 6e 74 6f 20 74 68 65 20 57 69 6e  all into the Win
3590: 33 32 20 6e 61 74 69 76 65 20 68 65 61 70 20 73  32 native heap s
35a0: 75 62 73 79 73 74 65 6d 0a 2a 2a 20 77 69 6c 6c  ubsystem.** will
35b0: 20 63 61 75 73 65 20 48 65 61 70 56 61 6c 69 64   cause HeapValid
35c0: 61 74 65 20 74 6f 20 62 65 20 63 61 6c 6c 65 64  ate to be called
35d0: 2e 20 20 49 66 20 68 65 61 70 20 76 61 6c 69 64  .  If heap valid
35e0: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 66 61 69  ation should fai
35f0: 6c 2c 20 61 6e 0a 2a 2a 20 61 73 73 65 72 74 69  l, an.** asserti
3600: 6f 6e 20 77 69 6c 6c 20 62 65 20 74 72 69 67 67  on will be trigg
3610: 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 28 48 69 73  ered..**.** (His
3620: 74 6f 72 69 63 61 6c 20 6e 6f 74 65 3a 20 20 54  torical note:  T
3630: 68 65 72 65 20 75 73 65 64 20 74 6f 20 62 65 20  here used to be 
3640: 73 65 76 65 72 61 6c 20 6f 74 68 65 72 20 6f 70  several other op
3650: 74 69 6f 6e 73 2c 20 62 75 74 20 77 65 27 76 65  tions, but we've
3660: 0a 2a 2a 20 70 61 72 65 64 20 69 74 20 64 6f 77  .** pared it dow
3670: 6e 20 74 6f 20 6a 75 73 74 20 74 68 65 73 65 20  n to just these 
3680: 74 68 72 65 65 2e 29 0a 2a 2a 0a 2a 2a 20 49 66  three.).**.** If
3690: 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20 61 62 6f   none of the abo
36a0: 76 65 20 61 72 65 20 64 65 66 69 6e 65 64 2c 20  ve are defined, 
36b0: 74 68 65 6e 20 73 65 74 20 53 51 4c 49 54 45 5f  then set SQLITE_
36c0: 53 59 53 54 45 4d 5f 4d 41 4c 4c 4f 43 20 61 73  SYSTEM_MALLOC as
36d0: 0a 2a 2a 20 74 68 65 20 64 65 66 61 75 6c 74 2e  .** the default.
36e0: 0a 2a 2f 0a 23 69 66 20 64 65 66 69 6e 65 64 28  .*/.#if defined(
36f0: 53 51 4c 49 54 45 5f 53 59 53 54 45 4d 5f 4d 41  SQLITE_SYSTEM_MA
3700: 4c 4c 4f 43 29 20 5c 0a 20 20 2b 20 64 65 66 69  LLOC) \.  + defi
3710: 6e 65 64 28 53 51 4c 49 54 45 5f 57 49 4e 33 32  ned(SQLITE_WIN32
3720: 5f 4d 41 4c 4c 4f 43 29 20 5c 0a 20 20 2b 20 64  _MALLOC) \.  + d
3730: 65 66 69 6e 65 64 28 53 51 4c 49 54 45 5f 5a 45  efined(SQLITE_ZE
3740: 52 4f 5f 4d 41 4c 4c 4f 43 29 20 5c 0a 20 20 2b  RO_MALLOC) \.  +
3750: 20 64 65 66 69 6e 65 64 28 53 51 4c 49 54 45 5f   defined(SQLITE_
3760: 4d 45 4d 44 45 42 55 47 29 3e 31 0a 23 20 65 72  MEMDEBUG)>1.# er
3770: 72 6f 72 20 22 54 77 6f 20 6f 72 20 6d 6f 72 65  ror "Two or more
3780: 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   of the followin
3790: 67 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 63  g compile-time c
37a0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
37b0: 69 6f 6e 73 5c 0a 20 61 72 65 20 64 65 66 69 6e  ions\. are defin
37c0: 65 64 20 62 75 74 20 61 74 20 6d 6f 73 74 20 6f  ed but at most o
37d0: 6e 65 20 69 73 20 61 6c 6c 6f 77 65 64 3a 5c 0a  ne is allowed:\.
37e0: 20 53 51 4c 49 54 45 5f 53 59 53 54 45 4d 5f 4d   SQLITE_SYSTEM_M
37f0: 41 4c 4c 4f 43 2c 20 53 51 4c 49 54 45 5f 57 49  ALLOC, SQLITE_WI
3800: 4e 33 32 5f 4d 41 4c 4c 4f 43 2c 20 53 51 4c 49  N32_MALLOC, SQLI
3810: 54 45 5f 4d 45 4d 44 45 42 55 47 2c 5c 0a 20 53  TE_MEMDEBUG,\. S
3820: 51 4c 49 54 45 5f 5a 45 52 4f 5f 4d 41 4c 4c 4f  QLITE_ZERO_MALLO
3830: 43 22 0a 23 65 6e 64 69 66 0a 23 69 66 20 64 65  C".#endif.#if de
3840: 66 69 6e 65 64 28 53 51 4c 49 54 45 5f 53 59 53  fined(SQLITE_SYS
3850: 54 45 4d 5f 4d 41 4c 4c 4f 43 29 20 5c 0a 20 20  TEM_MALLOC) \.  
3860: 2b 20 64 65 66 69 6e 65 64 28 53 51 4c 49 54 45  + defined(SQLITE
3870: 5f 57 49 4e 33 32 5f 4d 41 4c 4c 4f 43 29 20 5c  _WIN32_MALLOC) \
3880: 0a 20 20 2b 20 64 65 66 69 6e 65 64 28 53 51 4c  .  + defined(SQL
3890: 49 54 45 5f 5a 45 52 4f 5f 4d 41 4c 4c 4f 43 29  ITE_ZERO_MALLOC)
38a0: 20 5c 0a 20 20 2b 20 64 65 66 69 6e 65 64 28 53   \.  + defined(S
38b0: 51 4c 49 54 45 5f 4d 45 4d 44 45 42 55 47 29 3d  QLITE_MEMDEBUG)=
38c0: 3d 30 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  =0.# define SQLI
38d0: 54 45 5f 53 59 53 54 45 4d 5f 4d 41 4c 4c 4f 43  TE_SYSTEM_MALLOC
38e0: 20 31 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a   1.#endif../*.**
38f0: 20 49 66 20 53 51 4c 49 54 45 5f 4d 41 4c 4c 4f   If SQLITE_MALLO
3900: 43 5f 53 4f 46 54 5f 4c 49 4d 49 54 20 69 73 20  C_SOFT_LIMIT is 
3910: 6e 6f 74 20 7a 65 72 6f 2c 20 74 68 65 6e 20 74  not zero, then t
3920: 72 79 20 74 6f 20 6b 65 65 70 20 74 68 65 0a 2a  ry to keep the.*
3930: 2a 20 73 69 7a 65 73 20 6f 66 20 6d 65 6d 6f 72  * sizes of memor
3940: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 62 65  y allocations be
3950: 6c 6f 77 20 74 68 69 73 20 76 61 6c 75 65 20 77  low this value w
3960: 68 65 72 65 20 70 6f 73 73 69 62 6c 65 2e 0a 2a  here possible..*
3970: 2f 0a 23 69 66 20 21 64 65 66 69 6e 65 64 28 53  /.#if !defined(S
3980: 51 4c 49 54 45 5f 4d 41 4c 4c 4f 43 5f 53 4f 46  QLITE_MALLOC_SOF
3990: 54 5f 4c 49 4d 49 54 29 0a 23 20 64 65 66 69 6e  T_LIMIT).# defin
39a0: 65 20 53 51 4c 49 54 45 5f 4d 41 4c 4c 4f 43 5f  e SQLITE_MALLOC_
39b0: 53 4f 46 54 5f 4c 49 4d 49 54 20 31 30 32 34 0a  SOFT_LIMIT 1024.
39c0: 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 57 65  #endif../*.** We
39d0: 20 6e 65 65 64 20 74 6f 20 64 65 66 69 6e 65 20   need to define 
39e0: 5f 58 4f 50 45 4e 5f 53 4f 55 52 43 45 20 61 73  _XOPEN_SOURCE as
39f0: 20 66 6f 6c 6c 6f 77 73 20 69 6e 20 6f 72 64 65   follows in orde
3a00: 72 20 74 6f 20 65 6e 61 62 6c 65 0a 2a 2a 20 72  r to enable.** r
3a10: 65 63 75 72 73 69 76 65 20 6d 75 74 65 78 65 73  ecursive mutexes
3a20: 20 6f 6e 20 6d 6f 73 74 20 55 6e 69 78 20 73 79   on most Unix sy
3a30: 73 74 65 6d 73 2e 20 20 42 75 74 20 4d 61 63 20  stems.  But Mac 
3a40: 4f 53 20 58 20 69 73 20 64 69 66 66 65 72 65 6e  OS X is differen
3a50: 74 2e 0a 2a 2a 20 54 68 65 20 5f 58 4f 50 45 4e  t..** The _XOPEN
3a60: 5f 53 4f 55 52 43 45 20 64 65 66 69 6e 65 20 63  _SOURCE define c
3a70: 61 75 73 65 73 20 70 72 6f 62 6c 65 6d 73 20 66  auses problems f
3a80: 6f 72 20 4d 61 63 20 4f 53 20 58 20 77 65 20 61  or Mac OS X we a
3a90: 72 65 20 74 6f 6c 64 2c 0a 2a 2a 20 73 6f 20 69  re told,.** so i
3aa0: 74 20 69 73 20 6f 6d 69 74 74 65 64 20 74 68 65  t is omitted the
3ab0: 72 65 2e 20 20 53 65 65 20 74 69 63 6b 65 74 20  re.  See ticket 
3ac0: 23 32 36 37 33 2e 0a 2a 2a 0a 2a 2a 20 4c 61 74  #2673..**.** Lat
3ad0: 65 72 20 77 65 20 6c 65 61 72 6e 20 74 68 61 74  er we learn that
3ae0: 20 5f 58 4f 50 45 4e 5f 53 4f 55 52 43 45 20 69   _XOPEN_SOURCE i
3af0: 73 20 70 6f 6f 72 6c 79 20 6f 72 20 69 6e 63 6f  s poorly or inco
3b00: 72 72 65 63 74 6c 79 0a 2a 2a 20 69 6d 70 6c 65  rrectly.** imple
3b10: 6d 65 6e 74 65 64 20 6f 6e 20 73 6f 6d 65 20 73  mented on some s
3b20: 79 73 74 65 6d 73 2e 20 20 53 6f 20 77 65 20 61  ystems.  So we a
3b30: 76 6f 69 64 20 64 65 66 69 6e 69 6e 67 20 69 74  void defining it
3b40: 20 61 74 20 61 6c 6c 0a 2a 2a 20 69 66 20 69 74   at all.** if it
3b50: 20 69 73 20 61 6c 72 65 61 64 79 20 64 65 66 69   is already defi
3b60: 6e 65 64 20 6f 72 20 69 66 20 69 74 20 69 73 20  ned or if it is 
3b70: 75 6e 6e 65 65 64 65 64 20 62 65 63 61 75 73 65  unneeded because
3b80: 20 77 65 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 64   we are.** not d
3b90: 6f 69 6e 67 20 61 20 74 68 72 65 61 64 73 61 66  oing a threadsaf
3ba0: 65 20 62 75 69 6c 64 2e 20 20 54 69 63 6b 65 74  e build.  Ticket
3bb0: 20 23 32 36 38 31 2e 0a 2a 2a 0a 2a 2a 20 53 65   #2681..**.** Se
3bc0: 65 20 61 6c 73 6f 20 74 69 63 6b 65 74 20 23 32  e also ticket #2
3bd0: 37 34 31 2e 0a 2a 2f 0a 23 69 66 20 21 64 65 66  741..*/.#if !def
3be0: 69 6e 65 64 28 5f 58 4f 50 45 4e 5f 53 4f 55 52  ined(_XOPEN_SOUR
3bf0: 43 45 29 20 26 26 20 21 64 65 66 69 6e 65 64 28  CE) && !defined(
3c00: 5f 5f 44 41 52 57 49 4e 5f 5f 29 20 26 26 20 21  __DARWIN__) && !
3c10: 64 65 66 69 6e 65 64 28 5f 5f 41 50 50 4c 45 5f  defined(__APPLE_
3c20: 5f 29 20 26 26 20 53 51 4c 49 54 45 5f 54 48 52  _) && SQLITE_THR
3c30: 45 41 44 53 41 46 45 0a 23 20 20 64 65 66 69 6e  EADSAFE.#  defin
3c40: 65 20 5f 58 4f 50 45 4e 5f 53 4f 55 52 43 45 20  e _XOPEN_SOURCE 
3c50: 35 30 30 20 20 2f 2a 20 4e 65 65 64 65 64 20 74  500  /* Needed t
3c60: 6f 20 65 6e 61 62 6c 65 20 70 74 68 72 65 61 64  o enable pthread
3c70: 20 72 65 63 75 72 73 69 76 65 20 6d 75 74 65 78   recursive mutex
3c80: 65 73 20 2a 2f 0a 23 65 6e 64 69 66 0a 0a 2f 2a  es */.#endif../*
3c90: 0a 2a 2a 20 54 68 65 20 54 43 4c 20 68 65 61 64  .** The TCL head
3ca0: 65 72 73 20 61 72 65 20 6f 6e 6c 79 20 6e 65 65  ers are only nee
3cb0: 64 65 64 20 77 68 65 6e 20 63 6f 6d 70 69 6c 69  ded when compili
3cc0: 6e 67 20 74 68 65 20 54 43 4c 20 62 69 6e 64 69  ng the TCL bindi
3cd0: 6e 67 73 2e 0a 2a 2f 0a 23 69 66 20 64 65 66 69  ngs..*/.#if defi
3ce0: 6e 65 64 28 53 51 4c 49 54 45 5f 54 43 4c 29 20  ned(SQLITE_TCL) 
3cf0: 7c 7c 20 64 65 66 69 6e 65 64 28 54 43 4c 53 48  || defined(TCLSH
3d00: 29 0a 23 20 69 6e 63 6c 75 64 65 20 3c 74 63 6c  ).# include <tcl
3d10: 2e 68 3e 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a  .h>.#endif../*.*
3d20: 2a 20 4e 44 45 42 55 47 20 61 6e 64 20 53 51 4c  * NDEBUG and SQL
3d30: 49 54 45 5f 44 45 42 55 47 20 61 72 65 20 6f 70  ITE_DEBUG are op
3d40: 70 6f 73 69 74 65 73 2e 20 20 49 74 20 73 68 6f  posites.  It sho
3d50: 75 6c 64 20 61 6c 77 61 79 73 20 62 65 20 74 72  uld always be tr
3d60: 75 65 20 74 68 61 74 0a 2a 2a 20 64 65 66 69 6e  ue that.** defin
3d70: 65 64 28 4e 44 45 42 55 47 29 3d 3d 21 64 65 66  ed(NDEBUG)==!def
3d80: 69 6e 65 64 28 53 51 4c 49 54 45 5f 44 45 42 55  ined(SQLITE_DEBU
3d90: 47 29 2e 20 20 49 66 20 74 68 69 73 20 69 73 20  G).  If this is 
3da0: 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 74 72  not currently tr
3db0: 75 65 2c 0a 2a 2a 20 6d 61 6b 65 20 69 74 20 74  ue,.** make it t
3dc0: 72 75 65 20 62 79 20 64 65 66 69 6e 69 6e 67 20  rue by defining 
3dd0: 6f 72 20 75 6e 64 65 66 69 6e 69 6e 67 20 4e 44  or undefining ND
3de0: 45 42 55 47 2e 0a 2a 2a 0a 2a 2a 20 53 65 74 74  EBUG..**.** Sett
3df0: 69 6e 67 20 4e 44 45 42 55 47 20 6d 61 6b 65 73  ing NDEBUG makes
3e00: 20 74 68 65 20 63 6f 64 65 20 73 6d 61 6c 6c 65   the code smalle
3e10: 72 20 61 6e 64 20 72 75 6e 20 66 61 73 74 65 72  r and run faster
3e20: 20 62 79 20 64 69 73 61 62 6c 69 6e 67 20 74 68   by disabling th
3e30: 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 61 73 73 65  e.** number asse
3e40: 72 74 28 29 20 73 74 61 74 65 6d 65 6e 74 73 20  rt() statements 
3e50: 69 6e 20 74 68 65 20 63 6f 64 65 2e 20 20 53 6f  in the code.  So
3e60: 20 77 65 20 77 61 6e 74 20 74 68 65 20 64 65 66   we want the def
3e70: 61 75 6c 74 20 61 63 74 69 6f 6e 0a 2a 2a 20 74  ault action.** t
3e80: 6f 20 62 65 20 66 6f 72 20 4e 44 45 42 55 47 20  o be for NDEBUG 
3e90: 74 6f 20 62 65 20 73 65 74 20 61 6e 64 20 4e 44  to be set and ND
3ea0: 45 42 55 47 20 74 6f 20 62 65 20 75 6e 64 65 66  EBUG to be undef
3eb0: 69 6e 65 64 20 6f 6e 6c 79 20 69 66 20 53 51 4c  ined only if SQL
3ec0: 49 54 45 5f 44 45 42 55 47 0a 2a 2a 20 69 73 20  ITE_DEBUG.** is 
3ed0: 73 65 74 2e 20 20 54 68 75 73 20 4e 44 45 42 55  set.  Thus NDEBU
3ee0: 47 20 62 65 63 6f 6d 65 73 20 61 6e 20 6f 70 74  G becomes an opt
3ef0: 2d 69 6e 20 72 61 74 68 65 72 20 74 68 61 6e 20  -in rather than 
3f00: 61 6e 20 6f 70 74 2d 6f 75 74 0a 2a 2a 20 66 65  an opt-out.** fe
3f10: 61 74 75 72 65 2e 0a 2a 2f 0a 23 69 66 20 21 64  ature..*/.#if !d
3f20: 65 66 69 6e 65 64 28 4e 44 45 42 55 47 29 20 26  efined(NDEBUG) &
3f30: 26 20 21 64 65 66 69 6e 65 64 28 53 51 4c 49 54  & !defined(SQLIT
3f40: 45 5f 44 45 42 55 47 29 20 0a 23 20 64 65 66 69  E_DEBUG) .# defi
3f50: 6e 65 20 4e 44 45 42 55 47 20 31 0a 23 65 6e 64  ne NDEBUG 1.#end
3f60: 69 66 0a 23 69 66 20 64 65 66 69 6e 65 64 28 4e  if.#if defined(N
3f70: 44 45 42 55 47 29 20 26 26 20 64 65 66 69 6e 65  DEBUG) && define
3f80: 64 28 53 51 4c 49 54 45 5f 44 45 42 55 47 29 0a  d(SQLITE_DEBUG).
3f90: 23 20 75 6e 64 65 66 20 4e 44 45 42 55 47 0a 23  # undef NDEBUG.#
3fa0: 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65  endif../*.** The
3fb0: 20 74 65 73 74 63 61 73 65 28 29 20 6d 61 63 72   testcase() macr
3fc0: 6f 20 69 73 20 75 73 65 64 20 74 6f 20 61 69 64  o is used to aid
3fd0: 20 69 6e 20 63 6f 76 65 72 61 67 65 20 74 65 73   in coverage tes
3fe0: 74 69 6e 67 2e 20 20 57 68 65 6e 20 0a 2a 2a 20  ting.  When .** 
3ff0: 64 6f 69 6e 67 20 63 6f 76 65 72 61 67 65 20 74  doing coverage t
4000: 65 73 74 69 6e 67 2c 20 74 68 65 20 63 6f 6e 64  esting, the cond
4010: 69 74 69 6f 6e 20 69 6e 73 69 64 65 20 74 68 65  ition inside the
4020: 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
4030: 74 65 73 74 63 61 73 65 28 29 20 6d 75 73 74 20  testcase() must 
4040: 62 65 20 65 76 61 6c 75 61 74 65 64 20 62 6f 74  be evaluated bot
4050: 68 20 74 72 75 65 20 61 6e 64 20 66 61 6c 73 65  h true and false
4060: 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20   in order to.** 
4070: 67 65 74 20 66 75 6c 6c 20 62 72 61 6e 63 68 20  get full branch 
4080: 63 6f 76 65 72 61 67 65 2e 20 20 54 68 65 20 74  coverage.  The t
4090: 65 73 74 63 61 73 65 28 29 20 6d 61 63 72 6f 20  estcase() macro 
40a0: 69 73 20 69 6e 73 65 72 74 65 64 0a 2a 2a 20 74  is inserted.** t
40b0: 6f 20 68 65 6c 70 20 65 6e 73 75 72 65 20 61 64  o help ensure ad
40c0: 65 71 75 61 74 65 20 74 65 73 74 20 63 6f 76 65  equate test cove
40d0: 72 61 67 65 20 69 6e 20 70 6c 61 63 65 73 20 77  rage in places w
40e0: 68 65 72 65 20 73 69 6d 70 6c 65 0a 2a 2a 20 63  here simple.** c
40f0: 6f 6e 64 69 74 69 6f 6e 2f 64 65 63 69 73 69 6f  ondition/decisio
4100: 6e 20 63 6f 76 65 72 61 67 65 20 69 73 20 69 6e  n coverage is in
4110: 61 64 65 71 75 61 74 65 2e 20 20 46 6f 72 20 65  adequate.  For e
4120: 78 61 6d 70 6c 65 2c 20 74 65 73 74 63 61 73 65  xample, testcase
4130: 28 29 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65  ().** can be use
4140: 64 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 62  d to make sure b
4150: 6f 75 6e 64 61 72 79 20 76 61 6c 75 65 73 20 61  oundary values a
4160: 72 65 20 74 65 73 74 65 64 2e 20 20 46 6f 72 0a  re tested.  For.
4170: 2a 2a 20 62 69 74 6d 61 73 6b 20 74 65 73 74 73  ** bitmask tests
4180: 2c 20 74 65 73 74 63 61 73 65 28 29 20 63 61 6e  , testcase() can
4190: 20 62 65 20 75 73 65 64 20 74 6f 20 6d 61 6b 65   be used to make
41a0: 20 73 75 72 65 20 65 61 63 68 20 62 69 74 0a 2a   sure each bit.*
41b0: 2a 20 69 73 20 73 69 67 6e 69 66 69 63 61 6e 74  * is significant
41c0: 20 61 6e 64 20 75 73 65 64 20 61 74 20 6c 65 61   and used at lea
41d0: 73 74 20 6f 6e 63 65 2e 20 20 4f 6e 20 73 77 69  st once.  On swi
41e0: 74 63 68 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  tch statements.*
41f0: 2a 20 77 68 65 72 65 20 6d 75 6c 74 69 70 6c 65  * where multiple
4200: 20 63 61 73 65 73 20 67 6f 20 74 6f 20 74 68 65   cases go to the
4210: 20 73 61 6d 65 20 62 6c 6f 63 6b 20 6f 66 20 63   same block of c
4220: 6f 64 65 2c 20 74 65 73 74 63 61 73 65 28 29 0a  ode, testcase().
4230: 2a 2a 20 63 61 6e 20 69 6e 73 75 72 65 20 74 68  ** can insure th
4240: 61 74 20 61 6c 6c 20 63 61 73 65 73 20 61 72 65  at all cases are
4250: 20 65 76 61 6c 75 61 74 65 64 2e 0a 2a 2a 0a 2a   evaluated..**.*
4260: 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f  /.#ifdef SQLITE_
4270: 43 4f 56 45 52 41 47 45 5f 54 45 53 54 0a 53 51  COVERAGE_TEST.SQ
4280: 4c 49 54 45 5f 50 52 49 56 41 54 45 20 20 20 76  LITE_PRIVATE   v
4290: 6f 69 64 20 73 71 6c 69 74 65 33 43 6f 76 65 72  oid sqlite3Cover
42a0: 61 67 65 28 69 6e 74 29 3b 0a 23 20 64 65 66 69  age(int);.# defi
42b0: 6e 65 20 74 65 73 74 63 61 73 65 28 58 29 20 20  ne testcase(X)  
42c0: 69 66 28 20 58 20 29 7b 20 73 71 6c 69 74 65 33  if( X ){ sqlite3
42d0: 43 6f 76 65 72 61 67 65 28 5f 5f 4c 49 4e 45 5f  Coverage(__LINE_
42e0: 5f 29 3b 20 7d 0a 23 65 6c 73 65 0a 23 20 64 65  _); }.#else.# de
42f0: 66 69 6e 65 20 74 65 73 74 63 61 73 65 28 58 29  fine testcase(X)
4300: 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54  .#endif../*.** T
4310: 68 65 20 54 45 53 54 4f 4e 4c 59 20 6d 61 63 72  he TESTONLY macr
4320: 6f 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 63  o is used to enc
4330: 6c 6f 73 65 20 76 61 72 69 61 62 6c 65 20 64 65  lose variable de
4340: 63 6c 61 72 61 74 69 6f 6e 73 20 6f 72 0a 2a 2a  clarations or.**
4350: 20 6f 74 68 65 72 20 62 69 74 73 20 6f 66 20 63   other bits of c
4360: 6f 64 65 20 74 68 61 74 20 61 72 65 20 6e 65 65  ode that are nee
4370: 64 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20 74  ded to support t
4380: 68 65 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20  he arguments.** 
4390: 77 69 74 68 69 6e 20 74 65 73 74 63 61 73 65 28  within testcase(
43a0: 29 20 61 6e 64 20 61 73 73 65 72 74 28 29 20 6d  ) and assert() m
43b0: 61 63 72 6f 73 2e 0a 2a 2f 0a 23 69 66 20 21 64  acros..*/.#if !d
43c0: 65 66 69 6e 65 64 28 4e 44 45 42 55 47 29 20 7c  efined(NDEBUG) |
43d0: 7c 20 64 65 66 69 6e 65 64 28 53 51 4c 49 54 45  | defined(SQLITE
43e0: 5f 43 4f 56 45 52 41 47 45 5f 54 45 53 54 29 0a  _COVERAGE_TEST).
43f0: 23 20 64 65 66 69 6e 65 20 54 45 53 54 4f 4e 4c  # define TESTONL
4400: 59 28 58 29 20 20 58 0a 23 65 6c 73 65 0a 23 20  Y(X)  X.#else.# 
4410: 64 65 66 69 6e 65 20 54 45 53 54 4f 4e 4c 59 28  define TESTONLY(
4420: 58 29 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  X).#endif../*.**
4430: 20 53 6f 6d 65 74 69 6d 65 73 20 77 65 20 6e 65   Sometimes we ne
4440: 65 64 20 61 20 73 6d 61 6c 6c 20 61 6d 6f 75 6e  ed a small amoun
4450: 74 20 6f 66 20 63 6f 64 65 20 73 75 63 68 20 61  t of code such a
4460: 73 20 61 20 76 61 72 69 61 62 6c 65 20 69 6e 69  s a variable ini
4470: 74 69 61 6c 69 7a 61 74 69 6f 6e 0a 2a 2a 20 74  tialization.** t
4480: 6f 20 73 65 74 75 70 20 66 6f 72 20 61 20 6c 61  o setup for a la
4490: 74 65 72 20 61 73 73 65 72 74 28 29 20 73 74 61  ter assert() sta
44a0: 74 65 6d 65 6e 74 2e 20 20 57 65 20 64 6f 20 6e  tement.  We do n
44b0: 6f 74 20 77 61 6e 74 20 74 68 69 73 20 63 6f 64  ot want this cod
44c0: 65 20 74 6f 0a 2a 2a 20 61 70 70 65 61 72 20 77  e to.** appear w
44d0: 68 65 6e 20 61 73 73 65 72 74 28 29 20 69 73 20  hen assert() is 
44e0: 64 69 73 61 62 6c 65 64 2e 20 20 54 68 65 20 66  disabled.  The f
44f0: 6f 6c 6c 6f 77 69 6e 67 20 6d 61 63 72 6f 20 69  ollowing macro i
4500: 73 20 74 68 65 72 65 66 6f 72 65 0a 2a 2a 20 75  s therefore.** u
4510: 73 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20 74  sed to contain t
4520: 68 61 74 20 73 65 74 75 70 20 63 6f 64 65 2e 20  hat setup code. 
4530: 20 54 68 65 20 22 56 56 41 22 20 61 63 72 6f 6e   The "VVA" acron
4540: 79 6d 20 73 74 61 6e 64 73 20 66 6f 72 0a 2a 2a  ym stands for.**
4550: 20 22 56 65 72 69 66 69 63 61 74 69 6f 6e 2c 20   "Verification, 
4560: 56 61 6c 69 64 61 74 69 6f 6e 2c 20 61 6e 64 20  Validation, and 
4570: 41 63 63 72 65 64 69 74 61 74 69 6f 6e 22 2e 20  Accreditation". 
4580: 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
4590: 20 74 68 65 0a 2a 2a 20 63 6f 64 65 20 77 69 74   the.** code wit
45a0: 68 69 6e 20 56 56 41 5f 4f 4e 4c 59 28 29 20 77  hin VVA_ONLY() w
45b0: 69 6c 6c 20 6f 6e 6c 79 20 72 75 6e 20 64 75 72  ill only run dur
45c0: 69 6e 67 20 76 65 72 69 66 69 63 61 74 69 6f 6e  ing verification
45d0: 20 70 72 6f 63 65 73 73 65 73 2e 0a 2a 2f 0a 23   processes..*/.#
45e0: 69 66 6e 64 65 66 20 4e 44 45 42 55 47 0a 23 20  ifndef NDEBUG.# 
45f0: 64 65 66 69 6e 65 20 56 56 41 5f 4f 4e 4c 59 28  define VVA_ONLY(
4600: 58 29 20 20 58 0a 23 65 6c 73 65 0a 23 20 64 65  X)  X.#else.# de
4610: 66 69 6e 65 20 56 56 41 5f 4f 4e 4c 59 28 58 29  fine VVA_ONLY(X)
4620: 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54  .#endif../*.** T
4630: 68 65 20 41 4c 57 41 59 53 20 61 6e 64 20 4e 45  he ALWAYS and NE
4640: 56 45 52 20 6d 61 63 72 6f 73 20 73 75 72 72 6f  VER macros surro
4650: 75 6e 64 20 62 6f 6f 6c 65 61 6e 20 65 78 70 72  und boolean expr
4660: 65 73 73 69 6f 6e 73 20 77 68 69 63 68 20 0a 2a  essions which .*
4670: 2a 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74  * are intended t
4680: 6f 20 61 6c 77 61 79 73 20 62 65 20 74 72 75 65  o always be true
4690: 20 6f 72 20 66 61 6c 73 65 2c 20 72 65 73 70 65   or false, respe
46a0: 63 74 69 76 65 6c 79 2e 20 20 53 75 63 68 0a 2a  ctively.  Such.*
46b0: 2a 20 65 78 70 72 65 73 73 69 6f 6e 73 20 63 6f  * expressions co
46c0: 75 6c 64 20 62 65 20 6f 6d 69 74 74 65 64 20 66  uld be omitted f
46d0: 72 6f 6d 20 74 68 65 20 63 6f 64 65 20 63 6f 6d  rom the code com
46e0: 70 6c 65 74 65 6c 79 2e 20 20 42 75 74 20 74 68  pletely.  But th
46f0: 65 79 0a 2a 2a 20 61 72 65 20 69 6e 63 6c 75 64  ey.** are includ
4700: 65 64 20 69 6e 20 61 20 66 65 77 20 63 61 73 65  ed in a few case
4710: 73 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 65 6e  s in order to en
4720: 68 61 6e 63 65 20 74 68 65 20 72 65 73 69 6c 69  hance the resili
4730: 65 6e 63 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74  ence.** of SQLit
4740: 65 20 74 6f 20 75 6e 65 78 70 65 63 74 65 64 20  e to unexpected 
4750: 62 65 68 61 76 69 6f 72 20 2d 20 74 6f 20 6d 61  behavior - to ma
4760: 6b 65 20 74 68 65 20 63 6f 64 65 20 22 73 65 6c  ke the code "sel
4770: 66 2d 68 65 61 6c 69 6e 67 22 0a 2a 2a 20 6f 72  f-healing".** or
4780: 20 22 64 75 63 74 69 6c 65 22 20 72 61 74 68 65   "ductile" rathe
4790: 72 20 74 68 61 6e 20 62 65 69 6e 67 20 22 62 72  r than being "br
47a0: 69 74 74 6c 65 22 20 61 6e 64 20 63 72 61 73 68  ittle" and crash
47b0: 69 6e 67 20 61 74 20 74 68 65 20 66 69 72 73 74  ing at the first
47c0: 0a 2a 2a 20 68 69 6e 74 20 6f 66 20 75 6e 70 6c  .** hint of unpl
47d0: 61 6e 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a  anned behavior..
47e0: 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77  **.** In other w
47f0: 6f 72 64 73 2c 20 41 4c 57 41 59 53 20 61 6e 64  ords, ALWAYS and
4800: 20 4e 45 56 45 52 20 61 72 65 20 61 64 64 65 64   NEVER are added
4810: 20 66 6f 72 20 64 65 66 65 6e 73 69 76 65 20 63   for defensive c
4820: 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  ode..**.** When 
4830: 64 6f 69 6e 67 20 63 6f 76 65 72 61 67 65 20 74  doing coverage t
4840: 65 73 74 69 6e 67 20 41 4c 57 41 59 53 20 61 6e  esting ALWAYS an
4850: 64 20 4e 45 56 45 52 20 61 72 65 20 68 61 72 64  d NEVER are hard
4860: 2d 63 6f 64 65 64 20 74 6f 0a 2a 2a 20 62 65 20  -coded to.** be 
4870: 74 72 75 65 20 61 6e 64 20 66 61 6c 73 65 20 73  true and false s
4880: 6f 20 74 68 61 74 20 74 68 65 20 75 6e 72 65 61  o that the unrea
4890: 63 68 61 62 6c 65 20 63 6f 64 65 20 74 68 65 6e  chable code then
48a0: 20 73 70 65 63 69 66 79 20 77 69 6c 6c 0a 2a 2a   specify will.**
48b0: 20 6e 6f 74 20 62 65 20 63 6f 75 6e 74 65 64 20   not be counted 
48c0: 61 73 20 75 6e 74 65 73 74 65 64 20 63 6f 64 65  as untested code
48d0: 2e 0a 2a 2f 0a 23 69 66 20 64 65 66 69 6e 65 64  ..*/.#if defined
48e0: 28 53 51 4c 49 54 45 5f 43 4f 56 45 52 41 47 45  (SQLITE_COVERAGE
48f0: 5f 54 45 53 54 29 0a 23 20 64 65 66 69 6e 65 20  _TEST).# define 
4900: 41 4c 57 41 59 53 28 58 29 20 20 20 20 20 20 28  ALWAYS(X)      (
4910: 31 29 0a 23 20 64 65 66 69 6e 65 20 4e 45 56 45  1).# define NEVE
4920: 52 28 58 29 20 20 20 20 20 20 20 28 30 29 0a 23  R(X)       (0).#
4930: 65 6c 69 66 20 21 64 65 66 69 6e 65 64 28 4e 44  elif !defined(ND
4940: 45 42 55 47 29 0a 23 20 64 65 66 69 6e 65 20 41  EBUG).# define A
4950: 4c 57 41 59 53 28 58 29 20 20 20 20 20 20 28 28  LWAYS(X)      ((
4960: 58 29 3f 31 3a 28 61 73 73 65 72 74 28 30 29 2c  X)?1:(assert(0),
4970: 30 29 29 0a 23 20 64 65 66 69 6e 65 20 4e 45 56  0)).# define NEV
4980: 45 52 28 58 29 20 20 20 20 20 20 20 28 28 58 29  ER(X)       ((X)
4990: 3f 28 61 73 73 65 72 74 28 30 29 2c 31 29 3a 30  ?(assert(0),1):0
49a0: 29 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65  ).#else.# define
49b0: 20 41 4c 57 41 59 53 28 58 29 20 20 20 20 20 20   ALWAYS(X)      
49c0: 28 58 29 0a 23 20 64 65 66 69 6e 65 20 4e 45 56  (X).# define NEV
49d0: 45 52 28 58 29 20 20 20 20 20 20 20 28 58 29 0a  ER(X)       (X).
49e0: 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 52 65  #endif../*.** Re
49f0: 74 75 72 6e 20 74 72 75 65 20 28 6e 6f 6e 2d 7a  turn true (non-z
4a00: 65 72 6f 29 20 69 66 20 74 68 65 20 69 6e 70 75  ero) if the inpu
4a10: 74 20 69 73 20 61 20 69 6e 74 65 67 65 72 20 74  t is a integer t
4a20: 68 61 74 20 69 73 20 74 6f 6f 20 6c 61 72 67 65  hat is too large
4a30: 0a 2a 2a 20 74 6f 20 66 69 74 20 69 6e 20 33 32  .** to fit in 32
4a40: 2d 62 69 74 73 2e 20 20 54 68 69 73 20 6d 61 63  -bits.  This mac
4a50: 72 6f 20 69 73 20 75 73 65 64 20 69 6e 73 69 64  ro is used insid
4a60: 65 20 6f 66 20 76 61 72 69 6f 75 73 20 74 65 73  e of various tes
4a70: 74 63 61 73 65 28 29 0a 2a 2a 20 6d 61 63 72 6f  tcase().** macro
4a80: 73 20 74 6f 20 76 65 72 69 66 79 20 74 68 61 74  s to verify that
4a90: 20 77 65 20 68 61 76 65 20 74 65 73 74 65 64 20   we have tested 
4aa0: 53 51 4c 69 74 65 20 66 6f 72 20 6c 61 72 67 65  SQLite for large
4ab0: 2d 66 69 6c 65 20 73 75 70 70 6f 72 74 2e 0a 2a  -file support..*
4ac0: 2f 0a 23 64 65 66 69 6e 65 20 49 53 5f 42 49 47  /.#define IS_BIG
4ad0: 5f 49 4e 54 28 58 29 20 20 28 28 28 58 29 26 7e  _INT(X)  (((X)&~
4ae0: 28 69 36 34 29 30 78 66 66 66 66 66 66 66 66 29  (i64)0xffffffff)
4af0: 21 3d 30 29 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20  !=0)../*.** The 
4b00: 6d 61 63 72 6f 20 75 6e 6c 69 6b 65 6c 79 28 29  macro unlikely()
4b10: 20 69 73 20 61 20 68 69 6e 74 20 74 68 61 74 20   is a hint that 
4b20: 73 75 72 72 6f 75 6e 64 73 20 61 20 62 6f 6f 6c  surrounds a bool
4b30: 65 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f  ean.** expressio
4b40: 6e 20 74 68 61 74 20 69 73 20 75 73 75 61 6c 6c  n that is usuall
4b50: 79 20 66 61 6c 73 65 2e 20 20 4d 61 63 72 6f 20  y false.  Macro 
4b60: 6c 69 6b 65 6c 79 28 29 20 73 75 72 72 6f 75 6e  likely() surroun
4b70: 64 73 0a 2a 2a 20 61 20 62 6f 6f 6c 65 61 6e 20  ds.** a boolean 
4b80: 65 78 70 72 65 73 73 69 6f 6e 20 74 68 61 74 20  expression that 
4b90: 69 73 20 75 73 75 61 6c 6c 79 20 74 72 75 65 2e  is usually true.
4ba0: 20 20 47 43 43 20 69 73 20 61 62 6c 65 20 74 6f    GCC is able to
4bb0: 0a 2a 2a 20 75 73 65 20 74 68 65 73 65 20 68 69  .** use these hi
4bc0: 6e 74 73 20 74 6f 20 67 65 6e 65 72 61 74 65 20  nts to generate 
4bd0: 62 65 74 74 65 72 20 63 6f 64 65 2c 20 73 6f 6d  better code, som
4be0: 65 74 69 6d 65 73 2e 0a 2a 2f 0a 23 69 66 20 64  etimes..*/.#if d
4bf0: 65 66 69 6e 65 64 28 5f 5f 47 4e 55 43 5f 5f 29  efined(__GNUC__)
4c00: 20 26 26 20 30 0a 23 20 64 65 66 69 6e 65 20 6c   && 0.# define l
4c10: 69 6b 65 6c 79 28 58 29 20 20 20 20 5f 5f 62 75  ikely(X)    __bu
4c20: 69 6c 74 69 6e 5f 65 78 70 65 63 74 28 28 58 29  iltin_expect((X)
4c30: 2c 31 29 0a 23 20 64 65 66 69 6e 65 20 75 6e 6c  ,1).# define unl
4c40: 69 6b 65 6c 79 28 58 29 20 20 5f 5f 62 75 69 6c  ikely(X)  __buil
4c50: 74 69 6e 5f 65 78 70 65 63 74 28 28 58 29 2c 30  tin_expect((X),0
4c60: 29 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65  ).#else.# define
4c70: 20 6c 69 6b 65 6c 79 28 58 29 20 20 20 20 21 21   likely(X)    !!
4c80: 28 58 29 0a 23 20 64 65 66 69 6e 65 20 75 6e 6c  (X).# define unl
4c90: 69 6b 65 6c 79 28 58 29 20 20 21 21 28 58 29 0a  ikely(X)  !!(X).
4ca0: 23 65 6e 64 69 66 0a 0a 2f 2a 2a 2a 2a 2a 2a 2a  #endif../*******
4cb0: 2a 2a 2a 2a 2a 2a 2a 20 49 6e 63 6c 75 64 65 20  ******* Include 
4cc0: 73 71 6c 69 74 65 33 2e 68 20 69 6e 20 74 68 65  sqlite3.h in the
4cd0: 20 6d 69 64 64 6c 65 20 6f 66 20 73 71 6c 69 74   middle of sqlit
4ce0: 65 49 6e 74 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a  eInt.h *********
4cf0: 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a  ******/./*******
4d00: 2a 2a 2a 2a 2a 2a 2a 20 42 65 67 69 6e 20 66 69  ******* Begin fi
4d10: 6c 65 20 73 71 6c 69 74 65 33 2e 68 20 2a 2a 2a  le sqlite3.h ***
4d20: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
4d30: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
4d40: 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 0a 2a 2a 20 32 30  ******/./*.** 20
4d50: 30 31 20 53 65 70 74 65 6d 62 65 72 20 31 35 0a  01 September 15.
4d60: 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72  **.** The author
4d70: 20 64 69 73 63 6c 61 69 6d 73 20 63 6f 70 79 72   disclaims copyr
4d80: 69 67 68 74 20 74 6f 20 74 68 69 73 20 73 6f 75  ight to this sou
4d90: 72 63 65 20 63 6f 64 65 2e 20 20 49 6e 20 70 6c  rce code.  In pl
4da0: 61 63 65 20 6f 66 0a 2a 2a 20 61 20 6c 65 67 61  ace of.** a lega
4db0: 6c 20 6e 6f 74 69 63 65 2c 20 68 65 72 65 20 69  l notice, here i
4dc0: 73 20 61 20 62 6c 65 73 73 69 6e 67 3a 0a 2a 2a  s a blessing:.**
4dd0: 0a 2a 2a 20 20 20 20 4d 61 79 20 79 6f 75 20 64  .**    May you d
4de0: 6f 20 67 6f 6f 64 20 61 6e 64 20 6e 6f 74 20 65  o good and not e
4df0: 76 69 6c 2e 0a 2a 2a 20 20 20 20 4d 61 79 20 79  vil..**    May y
4e00: 6f 75 20 66 69 6e 64 20 66 6f 72 67 69 76 65 6e  ou find forgiven
4e10: 65 73 73 20 66 6f 72 20 79 6f 75 72 73 65 6c 66  ess for yourself
4e20: 20 61 6e 64 20 66 6f 72 67 69 76 65 20 6f 74 68   and forgive oth
4e30: 65 72 73 2e 0a 2a 2a 20 20 20 20 4d 61 79 20 79  ers..**    May y
4e40: 6f 75 20 73 68 61 72 65 20 66 72 65 65 6c 79 2c  ou share freely,
4e50: 20 6e 65 76 65 72 20 74 61 6b 69 6e 67 20 6d 6f   never taking mo
4e60: 72 65 20 74 68 61 6e 20 79 6f 75 20 67 69 76 65  re than you give
4e70: 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ..**.***********
4e80: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
4e90: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
4ea0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
4eb0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a  **************.*
4ec0: 2a 20 54 68 69 73 20 68 65 61 64 65 72 20 66 69  * This header fi
4ed0: 6c 65 20 64 65 66 69 6e 65 73 20 74 68 65 20 69  le defines the i
4ee0: 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 74 68  nterface that th
4ef0: 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  e SQLite library
4f00: 0a 2a 2a 20 70 72 65 73 65 6e 74 73 20 74 6f 20  .** presents to 
4f10: 63 6c 69 65 6e 74 20 70 72 6f 67 72 61 6d 73 2e  client programs.
4f20: 20 20 49 66 20 61 20 43 2d 66 75 6e 63 74 69 6f    If a C-functio
4f30: 6e 2c 20 73 74 72 75 63 74 75 72 65 2c 20 64 61  n, structure, da
4f40: 74 61 74 79 70 65 2c 0a 2a 2a 20 6f 72 20 63 6f  tatype,.** or co
4f50: 6e 73 74 61 6e 74 20 64 65 66 69 6e 69 74 69 6f  nstant definitio
4f60: 6e 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 65 61  n does not appea
4f70: 72 20 69 6e 20 74 68 69 73 20 66 69 6c 65 2c 20  r in this file, 
4f80: 74 68 65 6e 20 69 74 20 69 73 0a 2a 2a 20 6e 6f  then it is.** no
4f90: 74 20 61 20 70 75 62 6c 69 73 68 65 64 20 41 50  t a published AP
4fa0: 49 20 6f 66 20 53 51 4c 69 74 65 2c 20 69 73 20  I of SQLite, is 
4fb0: 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67  subject to chang
4fc0: 65 20 77 69 74 68 6f 75 74 0a 2a 2a 20 6e 6f 74  e without.** not
4fd0: 69 63 65 2c 20 61 6e 64 20 73 68 6f 75 6c 64 20  ice, and should 
4fe0: 6e 6f 74 20 62 65 20 72 65 66 65 72 65 6e 63 65  not be reference
4ff0: 64 20 62 79 20 70 72 6f 67 72 61 6d 73 20 74 68  d by programs th
5000: 61 74 20 75 73 65 20 53 51 4c 69 74 65 2e 0a 2a  at use SQLite..*
5010: 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68 65  *.** Some of the
5020: 20 64 65 66 69 6e 69 74 69 6f 6e 73 20 74 68 61   definitions tha
5030: 74 20 61 72 65 20 69 6e 20 74 68 69 73 20 66 69  t are in this fi
5040: 6c 65 20 61 72 65 20 6d 61 72 6b 65 64 20 61 73  le are marked as
5050: 0a 2a 2a 20 22 65 78 70 65 72 69 6d 65 6e 74 61  .** "experimenta
5060: 6c 22 2e 20 20 45 78 70 65 72 69 6d 65 6e 74 61  l".  Experimenta
5070: 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  l interfaces are
5080: 20 6e 6f 72 6d 61 6c 6c 79 20 6e 65 77 0a 2a 2a   normally new.**
5090: 20 66 65 61 74 75 72 65 73 20 72 65 63 65 6e 74   features recent
50a0: 6c 79 20 61 64 64 65 64 20 74 6f 20 53 51 4c 69  ly added to SQLi
50b0: 74 65 2e 20 20 57 65 20 64 6f 20 6e 6f 74 20 61  te.  We do not a
50c0: 6e 74 69 63 69 70 61 74 65 20 63 68 61 6e 67 65  nticipate change
50d0: 73 0a 2a 2a 20 74 6f 20 65 78 70 65 72 69 6d 65  s.** to experime
50e0: 6e 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20  ntal interfaces 
50f0: 62 75 74 20 72 65 73 65 72 76 65 20 74 68 65 20  but reserve the 
5100: 72 69 67 68 74 20 74 6f 20 6d 61 6b 65 20 6d 69  right to make mi
5110: 6e 6f 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20 69  nor changes.** i
5120: 66 20 65 78 70 65 72 69 65 6e 63 65 20 66 72 6f  f experience fro
5130: 6d 20 75 73 65 20 22 69 6e 20 74 68 65 20 77 69  m use "in the wi
5140: 6c 64 22 20 73 75 67 67 65 73 74 20 73 75 63 68  ld" suggest such
5150: 20 63 68 61 6e 67 65 73 20 61 72 65 20 70 72 75   changes are pru
5160: 64 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  dent..**.** The 
5170: 6f 66 66 69 63 69 61 6c 20 43 2d 6c 61 6e 67 75  official C-langu
5180: 61 67 65 20 41 50 49 20 64 6f 63 75 6d 65 6e 74  age API document
5190: 61 74 69 6f 6e 20 66 6f 72 20 53 51 4c 69 74 65  ation for SQLite
51a0: 20 69 73 20 64 65 72 69 76 65 64 0a 2a 2a 20 66   is derived.** f
51b0: 72 6f 6d 20 63 6f 6d 6d 65 6e 74 73 20 69 6e 20  rom comments in 
51c0: 74 68 69 73 20 66 69 6c 65 2e 20 20 54 68 69 73  this file.  This
51d0: 20 66 69 6c 65 20 69 73 20 74 68 65 20 61 75 74   file is the aut
51e0: 68 6f 72 69 74 61 74 69 76 65 20 73 6f 75 72 63  horitative sourc
51f0: 65 0a 2a 2a 20 6f 6e 20 68 6f 77 20 53 51 4c 69  e.** on how SQLi
5200: 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  te interfaces ar
5210: 65 20 73 75 70 70 6f 73 65 20 74 6f 20 6f 70 65  e suppose to ope
5220: 72 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  rate..**.** The 
5230: 6e 61 6d 65 20 6f 66 20 74 68 69 73 20 66 69 6c  name of this fil
5240: 65 20 75 6e 64 65 72 20 63 6f 6e 66 69 67 75 72  e under configur
5250: 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74  ation management
5260: 20 69 73 20 22 73 71 6c 69 74 65 2e 68 2e 69 6e   is "sqlite.h.in
5270: 22 2e 0a 2a 2a 20 54 68 65 20 6d 61 6b 65 66 69  "..** The makefi
5280: 6c 65 20 6d 61 6b 65 73 20 73 6f 6d 65 20 6d 69  le makes some mi
5290: 6e 6f 72 20 63 68 61 6e 67 65 73 20 74 6f 20 74  nor changes to t
52a0: 68 69 73 20 66 69 6c 65 20 28 73 75 63 68 20 61  his file (such a
52b0: 73 20 69 6e 73 65 72 74 69 6e 67 0a 2a 2a 20 74  s inserting.** t
52c0: 68 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65  he version numbe
52d0: 72 29 20 61 6e 64 20 63 68 61 6e 67 65 73 20 69  r) and changes i
52e0: 74 73 20 6e 61 6d 65 20 74 6f 20 22 73 71 6c 69  ts name to "sqli
52f0: 74 65 33 2e 68 22 20 61 73 0a 2a 2a 20 70 61 72  te3.h" as.** par
5300: 74 20 6f 66 20 74 68 65 20 62 75 69 6c 64 20 70  t of the build p
5310: 72 6f 63 65 73 73 2e 0a 2a 2f 0a 23 69 66 6e 64  rocess..*/.#ifnd
5320: 65 66 20 5f 53 51 4c 49 54 45 33 5f 48 5f 0a 23  ef _SQLITE3_H_.#
5330: 64 65 66 69 6e 65 20 5f 53 51 4c 49 54 45 33 5f  define _SQLITE3_
5340: 48 5f 0a 23 69 6e 63 6c 75 64 65 20 3c 73 74 64  H_.#include <std
5350: 61 72 67 2e 68 3e 20 20 20 20 20 2f 2a 20 4e 65  arg.h>     /* Ne
5360: 65 64 65 64 20 66 6f 72 20 74 68 65 20 64 65 66  eded for the def
5370: 69 6e 69 74 69 6f 6e 20 6f 66 20 76 61 5f 6c 69  inition of va_li
5380: 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 4d 61 6b  st */../*.** Mak
5390: 65 20 73 75 72 65 20 77 65 20 63 61 6e 20 63 61  e sure we can ca
53a0: 6c 6c 20 74 68 69 73 20 73 74 75 66 66 20 66 72  ll this stuff fr
53b0: 6f 6d 20 43 2b 2b 2e 0a 2a 2f 0a 23 69 66 20 30  om C++..*/.#if 0
53c0: 0a 65 78 74 65 72 6e 20 22 43 22 20 7b 0a 23 65  .extern "C" {.#e
53d0: 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a 2a 20 41 64 64  ndif.../*.** Add
53e0: 20 74 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20   the ability to 
53f0: 6f 76 65 72 72 69 64 65 20 27 65 78 74 65 72 6e  override 'extern
5400: 27 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c  '.*/.#ifndef SQL
5410: 49 54 45 5f 45 58 54 45 52 4e 0a 23 20 64 65 66  ITE_EXTERN.# def
5420: 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 54 45 52  ine SQLITE_EXTER
5430: 4e 20 65 78 74 65 72 6e 0a 23 65 6e 64 69 66 0a  N extern.#endif.
5440: 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f  .#ifndef SQLITE_
5450: 41 50 49 0a 23 20 64 65 66 69 6e 65 20 53 51 4c  API.# define SQL
5460: 49 54 45 5f 41 50 49 0a 23 65 6e 64 69 66 0a 0a  ITE_API.#endif..
5470: 0a 2f 2a 0a 2a 2a 20 54 68 65 73 65 20 6e 6f 2d  ./*.** These no-
5480: 6f 70 20 6d 61 63 72 6f 73 20 61 72 65 20 75 73  op macros are us
5490: 65 64 20 69 6e 20 66 72 6f 6e 74 20 6f 66 20 69  ed in front of i
54a0: 6e 74 65 72 66 61 63 65 73 20 74 6f 20 6d 61 72  nterfaces to mar
54b0: 6b 20 74 68 6f 73 65 0a 2a 2a 20 69 6e 74 65 72  k those.** inter
54c0: 66 61 63 65 73 20 61 73 20 65 69 74 68 65 72 20  faces as either 
54d0: 64 65 70 72 65 63 61 74 65 64 20 6f 72 20 65 78  deprecated or ex
54e0: 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20 4e 65 77  perimental.  New
54f0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   applications.**
5500: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 75 73 65 20   should not use 
5510: 64 65 70 72 65 63 61 74 65 64 20 69 6e 74 65 72  deprecated inter
5520: 66 61 63 65 73 20 2d 20 74 68 65 79 20 61 72 65  faces - they are
5530: 20 73 75 70 70 6f 72 74 20 66 6f 72 20 62 61 63   support for bac
5540: 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74  kwards.** compat
5550: 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 20 20 41  ibility only.  A
5560: 70 70 6c 69 63 61 74 69 6f 6e 20 77 72 69 74 65  pplication write
5570: 72 73 20 73 68 6f 75 6c 64 20 62 65 20 61 77 61  rs should be awa
5580: 72 65 20 74 68 61 74 0a 2a 2a 20 65 78 70 65 72  re that.** exper
5590: 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66 61 63  imental interfac
55a0: 65 73 20 61 72 65 20 73 75 62 6a 65 63 74 20 74  es are subject t
55b0: 6f 20 63 68 61 6e 67 65 20 69 6e 20 70 6f 69 6e  o change in poin
55c0: 74 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a  t releases..**.*
55d0: 2a 20 54 68 65 73 65 20 6d 61 63 72 6f 73 20 75  * These macros u
55e0: 73 65 64 20 74 6f 20 72 65 73 6f 6c 76 65 20 74  sed to resolve t
55f0: 6f 20 76 61 72 69 6f 75 73 20 6b 69 6e 64 73 20  o various kinds 
5600: 6f 66 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69  of compiler magi
5610: 63 20 74 68 61 74 0a 2a 2a 20 77 6f 75 6c 64 20  c that.** would 
5620: 67 65 6e 65 72 61 74 65 20 77 61 72 6e 69 6e 67  generate warning
5630: 20 6d 65 73 73 61 67 65 73 20 77 68 65 6e 20 74   messages when t
5640: 68 65 79 20 77 65 72 65 20 75 73 65 64 2e 20 20  hey were used.  
5650: 42 75 74 20 74 68 61 74 0a 2a 2a 20 63 6f 6d 70  But that.** comp
5660: 69 6c 65 72 20 6d 61 67 69 63 20 65 6e 64 65 64  iler magic ended
5670: 20 75 70 20 67 65 6e 65 72 61 74 69 6e 67 20 73   up generating s
5680: 75 63 68 20 61 20 66 6c 75 72 72 79 20 6f 66 20  uch a flurry of 
5690: 62 75 67 20 72 65 70 6f 72 74 73 0a 2a 2a 20 74  bug reports.** t
56a0: 68 61 74 20 77 65 20 68 61 76 65 20 74 61 6b 65  hat we have take
56b0: 6e 20 69 74 20 61 6c 6c 20 6f 75 74 20 61 6e 64  n it all out and
56c0: 20 67 6f 6e 65 20 62 61 63 6b 20 74 6f 20 75 73   gone back to us
56d0: 69 6e 67 20 73 69 6d 70 6c 65 0a 2a 2a 20 6e 6f  ing simple.** no
56e0: 6f 70 20 6d 61 63 72 6f 73 2e 0a 2a 2f 0a 23 64  op macros..*/.#d
56f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 50  efine SQLITE_DEP
5700: 52 45 43 41 54 45 44 0a 23 64 65 66 69 6e 65 20  RECATED.#define 
5710: 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e  SQLITE_EXPERIMEN
5720: 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20 45 6e 73 75 72  TAL../*.** Ensur
5730: 65 20 74 68 65 73 65 20 73 79 6d 62 6f 6c 73 20  e these symbols 
5740: 77 65 72 65 20 6e 6f 74 20 64 65 66 69 6e 65 64  were not defined
5750: 20 62 79 20 73 6f 6d 65 20 70 72 65 76 69 6f 75   by some previou
5760: 73 20 68 65 61 64 65 72 20 66 69 6c 65 2e 0a 2a  s header file..*
5770: 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f  /.#ifdef SQLITE_
5780: 56 45 52 53 49 4f 4e 0a 23 20 75 6e 64 65 66 20  VERSION.# undef 
5790: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23  SQLITE_VERSION.#
57a0: 65 6e 64 69 66 0a 23 69 66 64 65 66 20 53 51 4c  endif.#ifdef SQL
57b0: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
57c0: 45 52 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54  ER.# undef SQLIT
57d0: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
57e0: 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43  .#endif../*.** C
57f0: 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65  API3REF: Compile
5800: 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20 56 65  -Time Library Ve
5810: 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a  rsion Numbers.**
5820: 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49 54  .** ^(The [SQLIT
5830: 45 5f 56 45 52 53 49 4f 4e 5d 20 43 20 70 72 65  E_VERSION] C pre
5840: 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20  processor macro 
5850: 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 2e 68  in the sqlite3.h
5860: 20 68 65 61 64 65 72 0a 2a 2a 20 65 76 61 6c 75   header.** evalu
5870: 61 74 65 73 20 74 6f 20 61 20 73 74 72 69 6e 67  ates to a string
5880: 20 6c 69 74 65 72 61 6c 20 74 68 61 74 20 69 73   literal that is
5890: 20 74 68 65 20 53 51 4c 69 74 65 20 76 65 72 73   the SQLite vers
58a0: 69 6f 6e 20 69 6e 20 74 68 65 0a 2a 2a 20 66 6f  ion in the.** fo
58b0: 72 6d 61 74 20 22 58 2e 59 2e 5a 22 20 77 68 65  rmat "X.Y.Z" whe
58c0: 72 65 20 58 20 69 73 20 74 68 65 20 6d 61 6a 6f  re X is the majo
58d0: 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72  r version number
58e0: 20 28 61 6c 77 61 79 73 20 33 20 66 6f 72 0a 2a   (always 3 for.*
58f0: 2a 20 53 51 4c 69 74 65 33 29 20 61 6e 64 20 59  * SQLite3) and Y
5900: 20 69 73 20 74 68 65 20 6d 69 6e 6f 72 20 76 65   is the minor ve
5910: 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 61 6e 64  rsion number and
5920: 20 5a 20 69 73 20 74 68 65 20 72 65 6c 65 61 73   Z is the releas
5930: 65 20 6e 75 6d 62 65 72 2e 29 5e 0a 2a 2a 20 5e  e number.)^.** ^
5940: 28 54 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52  (The [SQLITE_VER
5950: 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 20 43 20 70  SION_NUMBER] C p
5960: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
5970: 6f 20 72 65 73 6f 6c 76 65 73 20 74 6f 20 61 6e  o resolves to an
5980: 20 69 6e 74 65 67 65 72 0a 2a 2a 20 77 69 74 68   integer.** with
5990: 20 74 68 65 20 76 61 6c 75 65 20 28 58 2a 31 30   the value (X*10
59a0: 30 30 30 30 30 20 2b 20 59 2a 31 30 30 30 20 2b  00000 + Y*1000 +
59b0: 20 5a 29 20 77 68 65 72 65 20 58 2c 20 59 2c 20   Z) where X, Y, 
59c0: 61 6e 64 20 5a 20 61 72 65 20 74 68 65 20 73 61  and Z are the sa
59d0: 6d 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 75 73  me.** numbers us
59e0: 65 64 20 69 6e 20 5b 53 51 4c 49 54 45 5f 56 45  ed in [SQLITE_VE
59f0: 52 53 49 4f 4e 5d 2e 29 5e 0a 2a 2a 20 54 68 65  RSION].)^.** The
5a00: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f   SQLITE_VERSION_
5a10: 4e 55 4d 42 45 52 20 66 6f 72 20 61 6e 79 20 67  NUMBER for any g
5a20: 69 76 65 6e 20 72 65 6c 65 61 73 65 20 6f 66 20  iven release of 
5a30: 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f  SQLite will also
5a40: 0a 2a 2a 20 62 65 20 6c 61 72 67 65 72 20 74 68  .** be larger th
5a50: 61 6e 20 74 68 65 20 72 65 6c 65 61 73 65 20 66  an the release f
5a60: 72 6f 6d 20 77 68 69 63 68 20 69 74 20 69 73 20  rom which it is 
5a70: 64 65 72 69 76 65 64 2e 20 20 45 69 74 68 65 72  derived.  Either
5a80: 20 59 20 77 69 6c 6c 0a 2a 2a 20 62 65 20 68 65   Y will.** be he
5a90: 6c 64 20 63 6f 6e 73 74 61 6e 74 20 61 6e 64 20  ld constant and 
5aa0: 5a 20 77 69 6c 6c 20 62 65 20 69 6e 63 72 65 6d  Z will be increm
5ab0: 65 6e 74 65 64 20 6f 72 20 65 6c 73 65 20 59 20  ented or else Y 
5ac0: 77 69 6c 6c 20 62 65 20 69 6e 63 72 65 6d 65 6e  will be incremen
5ad0: 74 65 64 0a 2a 2a 20 61 6e 64 20 5a 20 77 69 6c  ted.** and Z wil
5ae0: 6c 20 62 65 20 72 65 73 65 74 20 74 6f 20 7a 65  l be reset to ze
5af0: 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 69 6e 63 65 20  ro..**.** Since 
5b00: 76 65 72 73 69 6f 6e 20 33 2e 36 2e 31 38 2c 20  version 3.6.18, 
5b10: 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20 63 6f  SQLite source co
5b20: 64 65 20 68 61 73 20 62 65 65 6e 20 73 74 6f 72  de has been stor
5b30: 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20 3c 61 20  ed in the.** <a 
5b40: 68 72 65 66 3d 22 68 74 74 70 3a 2f 2f 77 77 77  href="http://www
5b50: 2e 66 6f 73 73 69 6c 2d 73 63 6d 2e 6f 72 67 2f  .fossil-scm.org/
5b60: 22 3e 46 6f 73 73 69 6c 20 63 6f 6e 66 69 67 75  ">Fossil configu
5b70: 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e  ration managemen
5b80: 74 0a 2a 2a 20 73 79 73 74 65 6d 3c 2f 61 3e 2e  t.** system</a>.
5b90: 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 53 4f    ^The SQLITE_SO
5ba0: 55 52 43 45 5f 49 44 20 6d 61 63 72 6f 20 65 76  URCE_ID macro ev
5bb0: 61 6c 75 61 74 65 73 20 74 6f 0a 2a 2a 20 61 20  aluates to.** a 
5bc0: 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 64 65  string which ide
5bd0: 6e 74 69 66 69 65 73 20 61 20 70 61 72 74 69 63  ntifies a partic
5be0: 75 6c 61 72 20 63 68 65 63 6b 2d 69 6e 20 6f 66  ular check-in of
5bf0: 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 74 68 69   SQLite.** withi
5c00: 6e 20 69 74 73 20 63 6f 6e 66 69 67 75 72 61 74  n its configurat
5c10: 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 20 73  ion management s
5c20: 79 73 74 65 6d 2e 20 20 5e 54 68 65 20 53 51 4c  ystem.  ^The SQL
5c30: 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 0a 2a 2a  ITE_SOURCE_ID.**
5c40: 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 73   string contains
5c50: 20 74 68 65 20 64 61 74 65 20 61 6e 64 20 74 69   the date and ti
5c60: 6d 65 20 6f 66 20 74 68 65 20 63 68 65 63 6b 2d  me of the check-
5c70: 69 6e 20 28 55 54 43 29 20 61 6e 64 20 61 6e 20  in (UTC) and an 
5c80: 53 48 41 31 0a 2a 2a 20 68 61 73 68 20 6f 66 20  SHA1.** hash of 
5c90: 74 68 65 20 65 6e 74 69 72 65 20 73 6f 75 72 63  the entire sourc
5ca0: 65 20 74 72 65 65 2e 0a 2a 2a 0a 2a 2a 20 53 65  e tree..**.** Se
5cb0: 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
5cc0: 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 5d 2c 0a  _libversion()],.
5cd0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76  ** [sqlite3_libv
5ce0: 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 5d  ersion_number()]
5cf0: 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  , [sqlite3_sourc
5d00: 65 69 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  eid()],.** [sqli
5d10: 74 65 5f 76 65 72 73 69 6f 6e 28 29 5d 20 61 6e  te_version()] an
5d20: 64 20 5b 73 71 6c 69 74 65 5f 73 6f 75 72 63 65  d [sqlite_source
5d30: 5f 69 64 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69  _id()]..*/.#defi
5d40: 6e 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  ne SQLITE_VERSIO
5d50: 4e 20 20 20 20 20 20 20 20 22 33 2e 37 2e 31 35  N        "3.7.15
5d60: 2e 32 22 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .2".#define SQLI
5d70: 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45  TE_VERSION_NUMBE
5d80: 52 20 33 30 30 37 30 31 35 0a 23 64 65 66 69 6e  R 3007015.#defin
5d90: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  e SQLITE_SOURCE_
5da0: 49 44 20 20 20 20 20 20 22 32 30 31 33 2d 30 31  ID      "2013-01
5db0: 2d 30 39 20 31 31 3a 35 33 3a 30 35 20 63 30 65  -09 11:53:05 c0e
5dc0: 30 39 35 36 30 64 32 36 66 30 61 36 34 35 36 62  09560d26f0a6456b
5dd0: 65 39 64 64 33 34 34 37 66 35 33 31 31 65 62 34  e9dd3447f5311eb4
5de0: 66 32 33 38 66 22 0a 0a 2f 2a 0a 2a 2a 20 43 41  f238f"../*.** CA
5df0: 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65  PI3REF: Run-Time
5e00: 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f 6e   Library Version
5e10: 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b 45 59 57   Numbers.** KEYW
5e20: 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76 65  ORDS: sqlite3_ve
5e30: 72 73 69 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 73  rsion, sqlite3_s
5e40: 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a 20 54 68  ourceid.**.** Th
5e50: 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 70  ese interfaces p
5e60: 72 6f 76 69 64 65 20 74 68 65 20 73 61 6d 65 20  rovide the same 
5e70: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20 74  information as t
5e80: 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49  he [SQLITE_VERSI
5e90: 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ON],.** [SQLITE_
5ea0: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2c  VERSION_NUMBER],
5eb0: 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 53 4f 55   and [SQLITE_SOU
5ec0: 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72 6f  RCE_ID] C prepro
5ed0: 63 65 73 73 6f 72 20 6d 61 63 72 6f 73 0a 2a 2a  cessor macros.**
5ee0: 20 62 75 74 20 61 72 65 20 61 73 73 6f 63 69 61   but are associa
5ef0: 74 65 64 20 77 69 74 68 20 74 68 65 20 6c 69 62  ted with the lib
5f00: 72 61 72 79 20 69 6e 73 74 65 61 64 20 6f 66 20  rary instead of 
5f10: 74 68 65 20 68 65 61 64 65 72 20 66 69 6c 65 2e  the header file.
5f20: 20 20 5e 28 43 61 75 74 69 6f 75 73 0a 2a 2a 20    ^(Cautious.** 
5f30: 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68  programmers migh
5f40: 74 20 69 6e 63 6c 75 64 65 20 61 73 73 65 72 74  t include assert
5f50: 28 29 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e  () statements in
5f60: 20 74 68 65 69 72 20 61 70 70 6c 69 63 61 74 69   their applicati
5f70: 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69 66 79 20  on to.** verify 
5f80: 74 68 61 74 20 76 61 6c 75 65 73 20 72 65 74 75  that values retu
5f90: 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 69 6e  rned by these in
5fa0: 74 65 72 66 61 63 65 73 20 6d 61 74 63 68 20 74  terfaces match t
5fb0: 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a 2a 2a 20  he macros in.** 
5fc0: 74 68 65 20 68 65 61 64 65 72 2c 20 61 6e 64 20  the header, and 
5fd0: 74 68 75 73 20 69 6e 73 75 72 65 20 74 68 61 74  thus insure that
5fe0: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
5ff0: 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20   is.** compiled 
6000: 77 69 74 68 20 6d 61 74 63 68 69 6e 67 20 6c 69  with matching li
6010: 62 72 61 72 79 20 61 6e 64 20 68 65 61 64 65 72  brary and header
6020: 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62   files..**.** <b
6030: 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
6040: 2a 2a 20 61 73 73 65 72 74 28 20 73 71 6c 69 74  ** assert( sqlit
6050: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75  e3_libversion_nu
6060: 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54 45 5f 56  mber()==SQLITE_V
6070: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 29 3b  ERSION_NUMBER );
6080: 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72 63  .** assert( strc
6090: 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  mp(sqlite3_sourc
60a0: 65 69 64 28 29 2c 53 51 4c 49 54 45 5f 53 4f 55  eid(),SQLITE_SOU
60b0: 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b 0a 2a 2a  RCE_ID)==0 );.**
60c0: 20 61 73 73 65 72 74 28 20 73 74 72 63 6d 70 28   assert( strcmp(
60d0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
60e0: 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56 45 52 53  on(),SQLITE_VERS
60f0: 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a 20 3c 2f  ION)==0 );.** </
6100: 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
6110: 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  >)^.**.** ^The s
6120: 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d  qlite3_version[]
6130: 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74   string constant
6140: 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 74 65   contains the te
6150: 78 74 20 6f 66 20 5b 53 51 4c 49 54 45 5f 56 45  xt of [SQLITE_VE
6160: 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63 72 6f 2e  RSION].** macro.
6170: 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6c    ^The sqlite3_l
6180: 69 62 76 65 72 73 69 6f 6e 28 29 20 66 75 6e 63  ibversion() func
6190: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 20 70  tion returns a p
61a0: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a  ointer to the.**
61b0: 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
61c0: 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e 67  version[] string
61d0: 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65 20   constant.  The 
61e0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
61f0: 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  on().** function
6200: 20 69 73 20 70 72 6f 76 69 64 65 64 20 66 6f 72   is provided for
6210: 20 75 73 65 20 69 6e 20 44 4c 4c 73 20 73 69 6e   use in DLLs sin
6220: 63 65 20 44 4c 4c 20 75 73 65 72 73 20 75 73 75  ce DLL users usu
6230: 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76 65  ally do not have
6240: 0a 2a 2a 20 64 69 72 65 63 74 20 61 63 63 65 73  .** direct acces
6250: 73 20 74 6f 20 73 74 72 69 6e 67 20 63 6f 6e 73  s to string cons
6260: 74 61 6e 74 73 20 77 69 74 68 69 6e 20 74 68 65  tants within the
6270: 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a 2a 20 73   DLL.  ^The.** s
6280: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
6290: 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75 6e 63 74  n_number() funct
62a0: 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 6e 20 69  ion returns an i
62b0: 6e 74 65 67 65 72 20 65 71 75 61 6c 20 74 6f 0a  nteger equal to.
62c0: 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49  ** [SQLITE_VERSI
62d0: 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20 5e 54 68  ON_NUMBER].  ^Th
62e0: 65 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65  e sqlite3_source
62f0: 69 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65  id() function re
6300: 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70 6f 69 6e  turns .** a poin
6310: 74 65 72 20 74 6f 20 61 20 73 74 72 69 6e 67 20  ter to a string 
6320: 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73 65 20 76  constant whose v
6330: 61 6c 75 65 20 69 73 20 74 68 65 20 73 61 6d 65  alue is the same
6340: 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c   as the .** [SQL
6350: 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20 43  ITE_SOURCE_ID] C
6360: 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
6370: 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  cro..**.** See a
6380: 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65 72  lso: [sqlite_ver
6390: 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c  sion()] and [sql
63a0: 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29 5d  ite_source_id()]
63b0: 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
63c0: 63 6f 6e 73 74 20 63 68 61 72 20 73 71 6c 69 74  const char sqlit
63d0: 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 3d 20 53  e3_version[] = S
63e0: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 3b 0a 53  QLITE_VERSION;.S
63f0: 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
6400: 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6c 69  char *sqlite3_li
6410: 62 76 65 72 73 69 6f 6e 28 76 6f 69 64 29 3b 0a  bversion(void);.
6420: 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
6430: 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73   char *sqlite3_s
6440: 6f 75 72 63 65 69 64 28 76 6f 69 64 29 3b 0a 53  ourceid(void);.S
6450: 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
6460: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
6470: 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a 0a  _number(void);..
6480: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
6490: 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 79  Run-Time Library
64a0: 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f 70 74   Compilation Opt
64b0: 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69 63 73  ions Diagnostics
64c0: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
64d0: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
64e0: 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74 69 6f  n_used() functio
64f0: 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72 20 31  n returns 0 or 1
6500: 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 20   .** indicating 
6510: 77 68 65 74 68 65 72 20 74 68 65 20 73 70 65 63  whether the spec
6520: 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77 61 73  ified option was
6530: 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a 2a 20   defined at .** 
6540: 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 20 5e  compile time.  ^
6550: 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72 65 66  The SQLITE_ pref
6560: 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74 74 65  ix may be omitte
6570: 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a 20 6f  d from the .** o
6580: 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73 73 65  ption name passe
6590: 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d  d to sqlite3_com
65a0: 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28  pileoption_used(
65b0: 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ).  .**.** ^The 
65c0: 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f  sqlite3_compileo
65d0: 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75 6e 63  ption_get() func
65e0: 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74 65 72  tion allows iter
65f0: 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20 74 68  ating.** over th
6600: 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69 6f 6e  e list of option
6610: 73 20 74 68 61 74 20 77 65 72 65 20 64 65 66 69  s that were defi
6620: 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 20 74  ned at compile t
6630: 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75 72 6e  ime by.** return
6640: 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63 6f 6d  ing the N-th com
6650: 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69 6f 6e  pile time option
6660: 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20 4e 20   string.  ^If N 
6670: 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c  is out of range,
6680: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  .** sqlite3_comp
6690: 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20  ileoption_get() 
66a0: 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70  returns a NULL p
66b0: 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 53 51  ointer.  ^The SQ
66c0: 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66 69 78  LITE_ .** prefix
66d0: 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d   is omitted from
66e0: 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72 65 74   any strings ret
66f0: 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c  urned by .** sql
6700: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
6710: 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a 2a 20  on_get()..**.** 
6720: 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74 68 65  ^Support for the
6730: 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75 6e 63   diagnostic func
6740: 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f 63 6f  tions sqlite3_co
6750: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64  mpileoption_used
6760: 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65  ().** and sqlite
6770: 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  3_compileoption_
6780: 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f 6d 69  get() may be omi
6790: 74 74 65 64 20 62 79 20 73 70 65 63 69 66 79 69  tted by specifyi
67a0: 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49  ng the .** [SQLI
67b0: 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45 4f  TE_OMIT_COMPILEO
67c0: 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f 70 74  PTION_DIAGS] opt
67d0: 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65 20 74  ion at compile t
67e0: 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ime..**.** See a
67f0: 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74 69 6f  lso: SQL functio
6800: 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70 69  ns [sqlite_compi
6810: 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 5d  leoption_used()]
6820: 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f   and.** [sqlite_
6830: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65  compileoption_ge
6840: 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b 63 6f  t()] and the [co
6850: 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20 70 72  mpile_options pr
6860: 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e 64 65  agma]..*/.#ifnde
6870: 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f  f SQLITE_OMIT_CO
6880: 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41 47  MPILEOPTION_DIAG
6890: 53 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  S.SQLITE_API int
68a0: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
68b0: 6f 70 74 69 6f 6e 5f 75 73 65 64 28 63 6f 6e 73  option_used(cons
68c0: 74 20 63 68 61 72 20 2a 7a 4f 70 74 4e 61 6d 65  t char *zOptName
68d0: 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
68e0: 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
68f0: 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  3_compileoption_
6900: 67 65 74 28 69 6e 74 20 4e 29 3b 0a 23 65 6e 64  get(int N);.#end
6910: 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  if../*.** CAPI3R
6920: 45 46 3a 20 54 65 73 74 20 54 6f 20 53 65 65 20  EF: Test To See 
6930: 49 66 20 54 68 65 20 4c 69 62 72 61 72 79 20 49  If The Library I
6940: 73 20 54 68 72 65 61 64 73 61 66 65 0a 2a 2a 0a  s Threadsafe.**.
6950: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
6960: 74 68 72 65 61 64 73 61 66 65 28 29 20 66 75 6e  threadsafe() fun
6970: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 7a 65  ction returns ze
6980: 72 6f 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69  ro if and only i
6990: 66 0a 2a 2a 20 53 51 4c 69 74 65 20 77 61 73 20  f.** SQLite was 
69a0: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6d 75  compiled with mu
69b0: 74 65 78 69 6e 67 20 63 6f 64 65 20 6f 6d 69 74  texing code omit
69c0: 74 65 64 20 64 75 65 20 74 6f 20 74 68 65 0a 2a  ted due to the.*
69d0: 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  * [SQLITE_THREAD
69e0: 53 41 46 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  SAFE] compile-ti
69f0: 6d 65 20 6f 70 74 69 6f 6e 20 62 65 69 6e 67 20  me option being 
6a00: 73 65 74 20 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20  set to 0..**.** 
6a10: 53 51 4c 69 74 65 20 63 61 6e 20 62 65 20 63 6f  SQLite can be co
6a20: 6d 70 69 6c 65 64 20 77 69 74 68 20 6f 72 20 77  mpiled with or w
6a30: 69 74 68 6f 75 74 20 6d 75 74 65 78 65 73 2e 20  ithout mutexes. 
6a40: 20 57 68 65 6e 0a 2a 2a 20 74 68 65 20 5b 53 51   When.** the [SQ
6a50: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d  LITE_THREADSAFE]
6a60: 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20   C preprocessor 
6a70: 6d 61 63 72 6f 20 69 73 20 31 20 6f 72 20 32 2c  macro is 1 or 2,
6a80: 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20   mutexes.** are 
6a90: 65 6e 61 62 6c 65 64 20 61 6e 64 20 53 51 4c 69  enabled and SQLi
6aa0: 74 65 20 69 73 20 74 68 72 65 61 64 73 61 66 65  te is threadsafe
6ab0: 2e 20 20 57 68 65 6e 20 74 68 65 0a 2a 2a 20 5b  .  When the.** [
6ac0: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
6ad0: 45 5d 20 6d 61 63 72 6f 20 69 73 20 30 2c 20 0a  E] macro is 0, .
6ae0: 2a 2a 20 74 68 65 20 6d 75 74 65 78 65 73 20 61  ** the mutexes a
6af0: 72 65 20 6f 6d 69 74 74 65 64 2e 20 20 57 69 74  re omitted.  Wit
6b00: 68 6f 75 74 20 74 68 65 20 6d 75 74 65 78 65 73  hout the mutexes
6b10: 2c 20 69 74 20 69 73 20 6e 6f 74 20 73 61 66 65  , it is not safe
6b20: 0a 2a 2a 20 74 6f 20 75 73 65 20 53 51 4c 69 74  .** to use SQLit
6b30: 65 20 63 6f 6e 63 75 72 72 65 6e 74 6c 79 20 66  e concurrently f
6b40: 72 6f 6d 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e  rom more than on
6b50: 65 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20  e thread..**.** 
6b60: 45 6e 61 62 6c 69 6e 67 20 6d 75 74 65 78 65 73  Enabling mutexes
6b70: 20 69 6e 63 75 72 73 20 61 20 6d 65 61 73 75 72   incurs a measur
6b80: 61 62 6c 65 20 70 65 72 66 6f 72 6d 61 6e 63 65  able performance
6b90: 20 70 65 6e 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20   penalty..** So 
6ba0: 69 66 20 73 70 65 65 64 20 69 73 20 6f 66 20 75  if speed is of u
6bb0: 74 6d 6f 73 74 20 69 6d 70 6f 72 74 61 6e 63 65  tmost importance
6bc0: 2c 20 69 74 20 6d 61 6b 65 73 20 73 65 6e 73 65  , it makes sense
6bd0: 20 74 6f 20 64 69 73 61 62 6c 65 0a 2a 2a 20 74   to disable.** t
6be0: 68 65 20 6d 75 74 65 78 65 73 2e 20 20 42 75 74  he mutexes.  But
6bf0: 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 73 61 66   for maximum saf
6c00: 65 74 79 2c 20 6d 75 74 65 78 65 73 20 73 68 6f  ety, mutexes sho
6c10: 75 6c 64 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a  uld be enabled..
6c20: 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20  ** ^The default 
6c30: 62 65 68 61 76 69 6f 72 20 69 73 20 66 6f 72 20  behavior is for 
6c40: 6d 75 74 65 78 65 73 20 74 6f 20 62 65 20 65 6e  mutexes to be en
6c50: 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  abled..**.** Thi
6c60: 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20  s interface can 
6c70: 62 65 20 75 73 65 64 20 62 79 20 61 6e 20 61 70  be used by an ap
6c80: 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 6d 61 6b  plication to mak
6c90: 65 20 73 75 72 65 20 74 68 61 74 20 74 68 65 0a  e sure that the.
6ca0: 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20 53 51  ** version of SQ
6cb0: 4c 69 74 65 20 74 68 61 74 20 69 74 20 69 73 20  Lite that it is 
6cc0: 6c 69 6e 6b 69 6e 67 20 61 67 61 69 6e 73 74 20  linking against 
6cd0: 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74  was compiled wit
6ce0: 68 0a 2a 2a 20 74 68 65 20 64 65 73 69 72 65 64  h.** the desired
6cf0: 20 73 65 74 74 69 6e 67 20 6f 66 20 74 68 65 20   setting of the 
6d00: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
6d10: 46 45 5d 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a  FE] macro..**.**
6d20: 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   This interface 
6d30: 6f 6e 6c 79 20 72 65 70 6f 72 74 73 20 6f 6e 20  only reports on 
6d40: 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  the compile-time
6d50: 20 6d 75 74 65 78 20 73 65 74 74 69 6e 67 0a 2a   mutex setting.*
6d60: 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45  * of the [SQLITE
6d70: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 66 6c 61  _THREADSAFE] fla
6d80: 67 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69 73  g.  If SQLite is
6d90: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
6da0: 2a 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  * SQLITE_THREADS
6db0: 41 46 45 3d 31 20 6f 72 20 3d 32 20 74 68 65 6e  AFE=1 or =2 then
6dc0: 20 6d 75 74 65 78 65 73 20 61 72 65 20 65 6e 61   mutexes are ena
6dd0: 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20  bled by default 
6de0: 62 75 74 0a 2a 2a 20 63 61 6e 20 62 65 20 66 75  but.** can be fu
6df0: 6c 6c 79 20 6f 72 20 70 61 72 74 69 61 6c 6c 79  lly or partially
6e00: 20 64 69 73 61 62 6c 65 64 20 75 73 69 6e 67 20   disabled using 
6e10: 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  a call to [sqlit
6e20: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20  e3_config()].** 
6e30: 77 69 74 68 20 74 68 65 20 76 65 72 62 73 20 5b  with the verbs [
6e40: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
6e50: 4e 47 4c 45 54 48 52 45 41 44 5d 2c 20 5b 53 51  NGLETHREAD], [SQ
6e60: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
6e70: 49 54 48 52 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20  ITHREAD],.** or 
6e80: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
6e90: 55 54 45 58 5d 2e 20 20 5e 28 54 68 65 20 72 65  UTEX].  ^(The re
6ea0: 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
6eb0: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 74 68 72  e.** sqlite3_thr
6ec0: 65 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69  eadsafe() functi
6ed0: 6f 6e 20 73 68 6f 77 73 20 6f 6e 6c 79 20 74 68  on shows only th
6ee0: 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 73  e compile-time s
6ef0: 65 74 74 69 6e 67 20 6f 66 0a 2a 2a 20 74 68 72  etting of.** thr
6f00: 65 61 64 20 73 61 66 65 74 79 2c 20 6e 6f 74 20  ead safety, not 
6f10: 61 6e 79 20 72 75 6e 2d 74 69 6d 65 20 63 68 61  any run-time cha
6f20: 6e 67 65 73 20 74 6f 20 74 68 61 74 20 73 65 74  nges to that set
6f30: 74 69 6e 67 20 6d 61 64 65 20 62 79 0a 2a 2a 20  ting made by.** 
6f40: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
6f50: 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  . In other words
6f60: 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  , the return val
6f70: 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ue from sqlite3_
6f80: 74 68 72 65 61 64 73 61 66 65 28 29 0a 2a 2a 20  threadsafe().** 
6f90: 69 73 20 75 6e 63 68 61 6e 67 65 64 20 62 79 20  is unchanged by 
6fa0: 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
6fb0: 5f 63 6f 6e 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a  _config().)^.**.
6fc0: 2a 2a 20 53 65 65 20 74 68 65 20 5b 74 68 72 65  ** See the [thre
6fd0: 61 64 69 6e 67 20 6d 6f 64 65 5d 20 64 6f 63 75  ading mode] docu
6fe0: 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64  mentation for ad
6ff0: 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
7000: 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  tion..*/.SQLITE_
7010: 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
7020: 74 68 72 65 61 64 73 61 66 65 28 76 6f 69 64 29  threadsafe(void)
7030: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
7040: 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e  F: Database Conn
7050: 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 0a 2a 2a  ection Handle.**
7060: 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64 61 74 61   KEYWORDS: {data
7070: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 7d  base connection}
7080: 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   {database conne
7090: 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45 61  ctions}.**.** Ea
70a0: 63 68 20 6f 70 65 6e 20 53 51 4c 69 74 65 20 64  ch open SQLite d
70b0: 61 74 61 62 61 73 65 20 69 73 20 72 65 70 72 65  atabase is repre
70c0: 73 65 6e 74 65 64 20 62 79 20 61 20 70 6f 69 6e  sented by a poin
70d0: 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e  ter to an instan
70e0: 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f 70 61  ce of.** the opa
70f0: 71 75 65 20 73 74 72 75 63 74 75 72 65 20 6e 61  que structure na
7100: 6d 65 64 20 22 73 71 6c 69 74 65 33 22 2e 20 20  med "sqlite3".  
7110: 49 74 20 69 73 20 75 73 65 66 75 6c 20 74 6f 20  It is useful to 
7120: 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73 71 6c 69  think of an sqli
7130: 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 61  te3.** pointer a
7140: 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20 20 54 68  s an object.  Th
7150: 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  e [sqlite3_open(
7160: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
7170: 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b  n16()], and.** [
7180: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
7190: 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  )] interfaces ar
71a0: 65 20 69 74 73 20 63 6f 6e 73 74 72 75 63 74 6f  e its constructo
71b0: 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  rs, and [sqlite3
71c0: 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 61 6e 64  _close()].** and
71d0: 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f   [sqlite3_close_
71e0: 76 32 28 29 5d 20 61 72 65 20 69 74 73 20 64 65  v2()] are its de
71f0: 73 74 72 75 63 74 6f 72 73 2e 20 20 54 68 65 72  structors.  Ther
7200: 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65 72  e are many other
7210: 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 28  .** interfaces (
7220: 73 75 63 68 20 61 73 0a 2a 2a 20 5b 73 71 6c 69  such as.** [sqli
7230: 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
7240: 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  ], [sqlite3_crea
7250: 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20  te_function()], 
7260: 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
7270: 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20  busy_timeout()] 
7280: 74 6f 20 6e 61 6d 65 20 62 75 74 20 74 68 72 65  to name but thre
7290: 65 29 20 74 68 61 74 20 61 72 65 20 6d 65 74 68  e) that are meth
72a0: 6f 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c  ods on an.** sql
72b0: 69 74 65 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a  ite3 object..*/.
72c0: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
72d0: 71 6c 69 74 65 33 20 73 71 6c 69 74 65 33 3b 0a  qlite3 sqlite3;.
72e0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
72f0: 20 36 34 2d 42 69 74 20 49 6e 74 65 67 65 72 20   64-Bit Integer 
7300: 54 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  Types.** KEYWORD
7310: 53 3a 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20  S: sqlite_int64 
7320: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 0a 2a 2a  sqlite_uint64.**
7330: 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65 72  .** Because ther
7340: 65 20 69 73 20 6e 6f 20 63 72 6f 73 73 2d 70 6c  e is no cross-pl
7350: 61 74 66 6f 72 6d 20 77 61 79 20 74 6f 20 73 70  atform way to sp
7360: 65 63 69 66 79 20 36 34 2d 62 69 74 20 69 6e 74  ecify 64-bit int
7370: 65 67 65 72 20 74 79 70 65 73 0a 2a 2a 20 53 51  eger types.** SQ
7380: 4c 69 74 65 20 69 6e 63 6c 75 64 65 73 20 74 79  Lite includes ty
7390: 70 65 64 65 66 73 20 66 6f 72 20 36 34 2d 62 69  pedefs for 64-bi
73a0: 74 20 73 69 67 6e 65 64 20 61 6e 64 20 75 6e 73  t signed and uns
73b0: 69 67 6e 65 64 20 69 6e 74 65 67 65 72 73 2e 0a  igned integers..
73c0: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
73d0: 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69  3_int64 and sqli
73e0: 74 65 33 5f 75 69 6e 74 36 34 20 61 72 65 20 74  te3_uint64 are t
73f0: 68 65 20 70 72 65 66 65 72 72 65 64 20 74 79 70  he preferred typ
7400: 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a  e definitions..*
7410: 2a 20 54 68 65 20 73 71 6c 69 74 65 5f 69 6e 74  * The sqlite_int
7420: 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 69  64 and sqlite_ui
7430: 6e 74 36 34 20 74 79 70 65 73 20 61 72 65 20 73  nt64 types are s
7440: 75 70 70 6f 72 74 65 64 20 66 6f 72 20 62 61 63  upported for bac
7450: 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74  kwards.** compat
7460: 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a  ibility only..**
7470: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
7480: 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74  _int64 and sqlit
7490: 65 5f 69 6e 74 36 34 20 74 79 70 65 73 20 63 61  e_int64 types ca
74a0: 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20  n store integer 
74b0: 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65  values.** betwee
74c0: 6e 20 2d 39 32 32 33 33 37 32 30 33 36 38 35 34  n -9223372036854
74d0: 37 37 35 38 30 38 20 61 6e 64 20 2b 39 32 32 33  775808 and +9223
74e0: 33 37 32 30 33 36 38 35 34 37 37 35 38 30 37 20  372036854775807 
74f0: 69 6e 63 6c 75 73 69 76 65 2e 20 20 5e 54 68 65  inclusive.  ^The
7500: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 69 6e 74  .** sqlite3_uint
7510: 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 69  64 and sqlite_ui
7520: 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20 73  nt64 types can s
7530: 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61 6c  tore integer val
7540: 75 65 73 20 0a 2a 2a 20 62 65 74 77 65 65 6e 20  ues .** between 
7550: 30 20 61 6e 64 20 2b 31 38 34 34 36 37 34 34 30  0 and +184467440
7560: 37 33 37 30 39 35 35 31 36 31 35 20 69 6e 63 6c  73709551615 incl
7570: 75 73 69 76 65 2e 0a 2a 2f 0a 23 69 66 64 65 66  usive..*/.#ifdef
7580: 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59   SQLITE_INT64_TY
7590: 50 45 0a 20 20 74 79 70 65 64 65 66 20 53 51 4c  PE.  typedef SQL
75a0: 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73  ITE_INT64_TYPE s
75b0: 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74  qlite_int64;.  t
75c0: 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20  ypedef unsigned 
75d0: 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50  SQLITE_INT64_TYP
75e0: 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b  E sqlite_uint64;
75f0: 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64 28 5f  .#elif defined(_
7600: 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65 66 69  MSC_VER) || defi
7610: 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f  ned(__BORLANDC__
7620: 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f 69 6e  ).  typedef __in
7630: 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  t64 sqlite_int64
7640: 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73 69  ;.  typedef unsi
7650: 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73 71 6c  gned __int64 sql
7660: 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 73  ite_uint64;.#els
7670: 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f 6e 67  e.  typedef long
7680: 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65   long int sqlite
7690: 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65  _int64;.  typede
76a0: 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 20  f unsigned long 
76b0: 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f  long int sqlite_
76c0: 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a 74  uint64;.#endif.t
76d0: 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 69 6e  ypedef sqlite_in
76e0: 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  t64 sqlite3_int6
76f0: 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74  4;.typedef sqlit
7700: 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e_uint64 sqlite3
7710: 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20  _uint64;../*.** 
7720: 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72  If compiling for
7730: 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74 68 61   a processor tha
7740: 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e 67  t lacks floating
7750: 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c 0a   point support,.
7760: 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20 69 6e  ** substitute in
7770: 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61 74 69  teger for floati
7780: 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 66  ng-point..*/.#if
7790: 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  def SQLITE_OMIT_
77a0: 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23  FLOATING_POINT.#
77b0: 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65 20 73   define double s
77c0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23 65 6e  qlite3_int64.#en
77d0: 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  dif../*.** CAPI3
77e0: 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20 44  REF: Closing A D
77f0: 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
7800: 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  on.**.** ^The sq
7810: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 61 6e  lite3_close() an
7820: 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f  d sqlite3_close_
7830: 76 32 28 29 20 72 6f 75 74 69 6e 65 73 20 61 72  v2() routines ar
7840: 65 20 64 65 73 74 72 75 63 74 6f 72 73 0a 2a 2a  e destructors.**
7850: 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65   for the [sqlite
7860: 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 43  3] object..** ^C
7870: 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
7880: 63 6c 6f 73 65 28 29 20 61 6e 64 20 73 71 6c 69  close() and sqli
7890: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72  te3_close_v2() r
78a0: 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20  eturn SQLITE_OK 
78b0: 69 66 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74  if.** the [sqlit
78c0: 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 73 75  e3] object is su
78d0: 63 63 65 73 73 66 75 6c 6c 79 20 64 65 73 74 72  ccessfully destr
78e0: 6f 79 65 64 20 61 6e 64 20 61 6c 6c 20 61 73 73  oyed and all ass
78f0: 6f 63 69 61 74 65 64 0a 2a 2a 20 72 65 73 6f 75  ociated.** resou
7900: 72 63 65 73 20 61 72 65 20 64 65 61 6c 6c 6f 63  rces are dealloc
7910: 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ated..**.** ^If 
7920: 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
7930: 6e 65 63 74 69 6f 6e 20 69 73 20 61 73 73 6f 63  nection is assoc
7940: 69 61 74 65 64 20 77 69 74 68 20 75 6e 66 69 6e  iated with unfin
7950: 61 6c 69 7a 65 64 20 70 72 65 70 61 72 65 64 0a  alized prepared.
7960: 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 72  ** statements or
7970: 20 75 6e 66 69 6e 69 73 68 65 64 20 73 71 6c 69   unfinished sqli
7980: 74 65 33 5f 62 61 63 6b 75 70 20 6f 62 6a 65 63  te3_backup objec
7990: 74 73 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  ts then sqlite3_
79a0: 63 6c 6f 73 65 28 29 0a 2a 2a 20 77 69 6c 6c 20  close().** will 
79b0: 6c 65 61 76 65 20 74 68 65 20 64 61 74 61 62 61  leave the databa
79c0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70  se connection op
79d0: 65 6e 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53  en and return [S
79e0: 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 20  QLITE_BUSY]..** 
79f0: 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  ^If sqlite3_clos
7a00: 65 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64  e_v2() is called
7a10: 20 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a 65   with unfinalize
7a20: 64 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  d prepared state
7a30: 6d 65 6e 74 73 0a 2a 2a 20 61 6e 64 20 75 6e 66  ments.** and unf
7a40: 69 6e 69 73 68 65 64 20 73 71 6c 69 74 65 33 5f  inished sqlite3_
7a50: 62 61 63 6b 75 70 73 2c 20 74 68 65 6e 20 74 68  backups, then th
7a60: 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
7a70: 63 74 69 6f 6e 20 62 65 63 6f 6d 65 73 0a 2a 2a  ction becomes.**
7a80: 20 61 6e 20 75 6e 75 73 61 62 6c 65 20 22 7a 6f   an unusable "zo
7a90: 6d 62 69 65 22 20 77 68 69 63 68 20 77 69 6c 6c  mbie" which will
7aa0: 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62   automatically b
7ab0: 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 77 68  e deallocated wh
7ac0: 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 73 74 20 70  en the.** last p
7ad0: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
7ae0: 74 20 69 73 20 66 69 6e 61 6c 69 7a 65 64 20 6f  t is finalized o
7af0: 72 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74  r the last sqlit
7b00: 65 33 5f 62 61 63 6b 75 70 20 69 73 0a 2a 2a 20  e3_backup is.** 
7b10: 66 69 6e 69 73 68 65 64 2e 20 20 54 68 65 20 73  finished.  The s
7b20: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28  qlite3_close_v2(
7b30: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 69  ) interface is i
7b40: 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20  ntended for use 
7b50: 77 69 74 68 0a 2a 2a 20 68 6f 73 74 20 6c 61 6e  with.** host lan
7b60: 67 75 61 67 65 73 20 74 68 61 74 20 61 72 65 20  guages that are 
7b70: 67 61 72 62 61 67 65 20 63 6f 6c 6c 65 63 74 65  garbage collecte
7b80: 64 2c 20 61 6e 64 20 77 68 65 72 65 20 74 68 65  d, and where the
7b90: 20 6f 72 64 65 72 20 69 6e 20 77 68 69 63 68 0a   order in which.
7ba0: 2a 2a 20 64 65 73 74 72 75 63 74 6f 72 73 20 61  ** destructors a
7bb0: 72 65 20 63 61 6c 6c 65 64 20 69 73 20 61 72 62  re called is arb
7bc0: 69 74 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 41 70  itrary..**.** Ap
7bd0: 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c  plications shoul
7be0: 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  d [sqlite3_final
7bf0: 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 5d 20  ize | finalize] 
7c00: 61 6c 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74  all [prepared st
7c10: 61 74 65 6d 65 6e 74 73 5d 2c 0a 2a 2a 20 5b 73  atements],.** [s
7c20: 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73  qlite3_blob_clos
7c30: 65 20 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b  e | close] all [
7c40: 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61  BLOB handles], a
7c50: 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  nd .** [sqlite3_
7c60: 62 61 63 6b 75 70 5f 66 69 6e 69 73 68 20 7c 20  backup_finish | 
7c70: 66 69 6e 69 73 68 5d 20 61 6c 6c 20 5b 73 71 6c  finish] all [sql
7c80: 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a  ite3_backup] obj
7c90: 65 63 74 73 20 61 73 73 6f 63 69 61 74 65 64 0a  ects associated.
7ca0: 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 73 71 6c  ** with the [sql
7cb0: 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 72 69  ite3] object pri
7cc0: 6f 72 20 74 6f 20 61 74 74 65 6d 70 74 69 6e 67  or to attempting
7cd0: 20 74 6f 20 63 6c 6f 73 65 20 74 68 65 20 6f 62   to close the ob
7ce0: 6a 65 63 74 2e 20 20 5e 49 66 0a 2a 2a 20 73 71  ject.  ^If.** sq
7cf0: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 69 73  lite3_close() is
7d00: 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 64 61   called on a [da
7d10: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
7d20: 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c 20 68 61  n] that still ha
7d30: 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64 69 6e 67  s.** outstanding
7d40: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
7d50: 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 61  ments], [BLOB ha
7d60: 6e 64 6c 65 73 5d 2c 20 61 6e 64 2f 6f 72 0a 2a  ndles], and/or.*
7d70: 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75  * [sqlite3_backu
7d80: 70 5d 20 6f 62 6a 65 63 74 73 20 74 68 65 6e 20  p] objects then 
7d90: 69 74 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54  it returns SQLIT
7da0: 45 5f 4f 4b 20 62 75 74 20 74 68 65 20 64 65 61  E_OK but the dea
7db0: 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20  llocation.** of 
7dc0: 72 65 73 6f 75 72 63 65 73 20 69 73 20 64 65 66  resources is def
7dd0: 65 72 72 65 64 20 75 6e 74 69 6c 20 61 6c 6c 20  erred until all 
7de0: 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
7df0: 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 61 6e  ents], [BLOB han
7e00: 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e 64 20 5b 73  dles],.** and [s
7e10: 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f  qlite3_backup] o
7e20: 62 6a 65 63 74 73 20 61 72 65 20 61 6c 73 6f 20  bjects are also 
7e30: 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 0a 2a 2a  destroyed..**.**
7e40: 20 5e 49 66 20 61 6e 20 5b 73 71 6c 69 74 65 33   ^If an [sqlite3
7e50: 5d 20 6f 62 6a 65 63 74 20 69 73 20 64 65 73 74  ] object is dest
7e60: 72 6f 79 65 64 20 77 68 69 6c 65 20 61 20 74 72  royed while a tr
7e70: 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 6f 70 65  ansaction is ope
7e80: 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73 61  n,.** the transa
7e90: 63 74 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61 74  ction is automat
7ea0: 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61  ically rolled ba
7eb0: 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 20  ck..**.** The C 
7ec0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
7ed0: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20  lite3_close(C)] 
7ee0: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f  and [sqlite3_clo
7ef0: 73 65 5f 76 32 28 43 29 5d 0a 2a 2a 20 6d 75 73  se_v2(C)].** mus
7f00: 74 20 62 65 20 65 69 74 68 65 72 20 61 20 4e 55  t be either a NU
7f10: 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 6f 72  LL.** pointer or
7f20: 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62   an [sqlite3] ob
7f30: 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f 62 74  ject pointer obt
7f40: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73  ained.** from [s
7f50: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
7f60: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
7f70: 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  )], or.** [sqlit
7f80: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61  e3_open_v2()], a
7f90: 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75 73 6c  nd not previousl
7fa0: 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e 43 61  y closed..** ^Ca
7fb0: 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6c  lling sqlite3_cl
7fc0: 6f 73 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ose() or sqlite3
7fd0: 5f 63 6c 6f 73 65 5f 76 32 28 29 20 77 69 74 68  _close_v2() with
7fe0: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a   a NULL pointer.
7ff0: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  ** argument is a
8000: 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e   harmless no-op.
8010: 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
8020: 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  nt sqlite3_close
8030: 28 73 71 6c 69 74 65 33 2a 29 3b 0a 53 51 4c 49  (sqlite3*);.SQLI
8040: 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
8050: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 73 71 6c 69  e3_close_v2(sqli
8060: 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68  te3*);../*.** Th
8070: 65 20 74 79 70 65 20 66 6f 72 20 61 20 63 61 6c  e type for a cal
8080: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a  lback function..
8090: 2a 2a 20 54 68 69 73 20 69 73 20 6c 65 67 61 63  ** This is legac
80a0: 79 20 61 6e 64 20 64 65 70 72 65 63 61 74 65 64  y and deprecated
80b0: 2e 20 20 49 74 20 69 73 20 69 6e 63 6c 75 64 65  .  It is include
80c0: 64 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c  d for historical
80d0: 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  .** compatibilit
80e0: 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 64 6f 63  y and is not doc
80f0: 75 6d 65 6e 74 65 64 2e 0a 2a 2f 0a 74 79 70 65  umented..*/.type
8100: 64 65 66 20 69 6e 74 20 28 2a 73 71 6c 69 74 65  def int (*sqlite
8110: 33 5f 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64  3_callback)(void
8120: 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 20 63 68  *,int,char**, ch
8130: 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ar**);../*.** CA
8140: 50 49 33 52 45 46 3a 20 4f 6e 65 2d 53 74 65 70  PI3REF: One-Step
8150: 20 51 75 65 72 79 20 45 78 65 63 75 74 69 6f 6e   Query Execution
8160: 20 49 6e 74 65 72 66 61 63 65 0a 2a 2a 0a 2a 2a   Interface.**.**
8170: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65   The sqlite3_exe
8180: 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  c() interface is
8190: 20 61 20 63 6f 6e 76 65 6e 69 65 6e 63 65 20 77   a convenience w
81a0: 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a  rapper around.**
81b0: 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
81c0: 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65  e_v2()], [sqlite
81d0: 33 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b  3_step()], and [
81e0: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
81f0: 28 29 5d 2c 0a 2a 2a 20 74 68 61 74 20 61 6c 6c  ()],.** that all
8200: 6f 77 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69  ows an applicati
8210: 6f 6e 20 74 6f 20 72 75 6e 20 6d 75 6c 74 69 70  on to run multip
8220: 6c 65 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 66  le statements of
8230: 20 53 51 4c 0a 2a 2a 20 77 69 74 68 6f 75 74 20   SQL.** without 
8240: 68 61 76 69 6e 67 20 74 6f 20 75 73 65 20 61 20  having to use a 
8250: 6c 6f 74 20 6f 66 20 43 20 63 6f 64 65 2e 20 0a  lot of C code. .
8260: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
8270: 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66  e3_exec() interf
8280: 61 63 65 20 72 75 6e 73 20 7a 65 72 6f 20 6f 72  ace runs zero or
8290: 20 6d 6f 72 65 20 55 54 46 2d 38 20 65 6e 63 6f   more UTF-8 enco
82a0: 64 65 64 2c 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f  ded,.** semicolo
82b0: 6e 2d 73 65 70 61 72 61 74 65 20 53 51 4c 20 73  n-separate SQL s
82c0: 74 61 74 65 6d 65 6e 74 73 20 70 61 73 73 65 64  tatements passed
82d0: 20 69 6e 74 6f 20 69 74 73 20 32 6e 64 20 61 72   into its 2nd ar
82e0: 67 75 6d 65 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68  gument,.** in th
82f0: 65 20 63 6f 6e 74 65 78 74 20 6f 66 20 74 68 65  e context of the
8300: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
8310: 63 74 69 6f 6e 5d 20 70 61 73 73 65 64 20 69 6e  ction] passed in
8320: 20 61 73 20 69 74 73 20 31 73 74 0a 2a 2a 20 61   as its 1st.** a
8330: 72 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20 74 68  rgument.  ^If th
8340: 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
8350: 69 6f 6e 20 6f 66 20 74 68 65 20 33 72 64 20 61  ion of the 3rd a
8360: 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71  rgument to.** sq
8370: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
8380: 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 69  not NULL, then i
8390: 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 66 6f 72  t is invoked for
83a0: 20 65 61 63 68 20 72 65 73 75 6c 74 20 72 6f 77   each result row
83b0: 0a 2a 2a 20 63 6f 6d 69 6e 67 20 6f 75 74 20 6f  .** coming out o
83c0: 66 20 74 68 65 20 65 76 61 6c 75 61 74 65 64 20  f the evaluated 
83d0: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 20  SQL statements. 
83e0: 20 5e 54 68 65 20 34 74 68 20 61 72 67 75 6d 65   ^The 4th argume
83f0: 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  nt to.** sqlite3
8400: 5f 65 78 65 63 28 29 20 69 73 20 72 65 6c 61 79  _exec() is relay
8410: 65 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68  ed through to th
8420: 65 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 6f  e 1st argument o
8430: 66 20 65 61 63 68 0a 2a 2a 20 63 61 6c 6c 62 61  f each.** callba
8440: 63 6b 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 20 20  ck invocation.  
8450: 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  ^If the callback
8460: 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69   pointer to sqli
8470: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73  te3_exec().** is
8480: 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f 20 63   NULL, then no c
8490: 61 6c 6c 62 61 63 6b 20 69 73 20 65 76 65 72 20  allback is ever 
84a0: 69 6e 76 6f 6b 65 64 20 61 6e 64 20 72 65 73 75  invoked and resu
84b0: 6c 74 20 72 6f 77 73 20 61 72 65 0a 2a 2a 20 69  lt rows are.** i
84c0: 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  gnored..**.** ^I
84d0: 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  f an error occur
84e0: 73 20 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69  s while evaluati
84f0: 6e 67 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  ng the SQL state
8500: 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74  ments passed int
8510: 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65  o.** sqlite3_exe
8520: 63 28 29 2c 20 74 68 65 6e 20 65 78 65 63 75 74  c(), then execut
8530: 69 6f 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65  ion of the curre
8540: 6e 74 20 73 74 61 74 65 6d 65 6e 74 20 73 74 6f  nt statement sto
8550: 70 73 20 61 6e 64 0a 2a 2a 20 73 75 62 73 65 71  ps and.** subseq
8560: 75 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 73 20  uent statements 
8570: 61 72 65 20 73 6b 69 70 70 65 64 2e 20 20 5e 49  are skipped.  ^I
8580: 66 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65  f the 5th parame
8590: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
85a0: 78 65 63 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 20  xec().** is not 
85b0: 4e 55 4c 4c 20 74 68 65 6e 20 61 6e 79 20 65 72  NULL then any er
85c0: 72 6f 72 20 6d 65 73 73 61 67 65 20 69 73 20 77  ror message is w
85d0: 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f  ritten into memo
85e0: 72 79 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66  ry obtained.** f
85f0: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
8600: 6c 6f 63 28 29 5d 20 61 6e 64 20 70 61 73 73 65  loc()] and passe
8610: 64 20 62 61 63 6b 20 74 68 72 6f 75 67 68 20 74  d back through t
8620: 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
8630: 2e 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20 6d 65  ..** To avoid me
8640: 6d 6f 72 79 20 6c 65 61 6b 73 2c 20 74 68 65 20  mory leaks, the 
8650: 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
8660: 6c 64 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74  ld invoke [sqlit
8670: 65 33 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e  e3_free()].** on
8680: 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73   error message s
8690: 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20  trings returned 
86a0: 74 68 72 6f 75 67 68 20 74 68 65 20 35 74 68 20  through the 5th 
86b0: 70 61 72 61 6d 65 74 65 72 20 6f 66 0a 2a 2a 20  parameter of.** 
86c0: 6f 66 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  of sqlite3_exec(
86d0: 29 20 61 66 74 65 72 20 74 68 65 20 65 72 72 6f  ) after the erro
86e0: 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67  r message string
86f0: 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65   is no longer ne
8700: 65 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  eded..** ^If the
8710: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   5th parameter t
8720: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
8730: 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64   is not NULL and
8740: 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 63   no errors.** oc
8750: 63 75 72 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  cur, then sqlite
8760: 33 5f 65 78 65 63 28 29 20 73 65 74 73 20 74 68  3_exec() sets th
8770: 65 20 70 6f 69 6e 74 65 72 20 69 6e 20 69 74 73  e pointer in its
8780: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   5th parameter t
8790: 6f 0a 2a 2a 20 4e 55 4c 4c 20 62 65 66 6f 72 65  o.** NULL before
87a0: 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a   returning..**.*
87b0: 2a 20 5e 49 66 20 61 6e 20 73 71 6c 69 74 65 33  * ^If an sqlite3
87c0: 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b  _exec() callback
87d0: 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
87e0: 6f 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65  o, the sqlite3_e
87f0: 78 65 63 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  xec().** routine
8800: 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f   returns SQLITE_
8810: 41 42 4f 52 54 20 77 69 74 68 6f 75 74 20 69 6e  ABORT without in
8820: 76 6f 6b 69 6e 67 20 74 68 65 20 63 61 6c 6c 62  voking the callb
8830: 61 63 6b 20 61 67 61 69 6e 20 61 6e 64 0a 2a 2a  ack again and.**
8840: 20 77 69 74 68 6f 75 74 20 72 75 6e 6e 69 6e 67   without running
8850: 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20   any subsequent 
8860: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  SQL statements..
8870: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 32 6e 64 20 61  **.** ^The 2nd a
8880: 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73  rgument to the s
8890: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61  qlite3_exec() ca
88a0: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
88b0: 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  is the.** number
88c0: 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74   of columns in t
88d0: 68 65 20 72 65 73 75 6c 74 2e 20 20 5e 54 68 65  he result.  ^The
88e0: 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f   3rd argument to
88f0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65   the sqlite3_exe
8900: 63 28 29 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  c().** callback 
8910: 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
8920: 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e  ointers to strin
8930: 67 73 20 6f 62 74 61 69 6e 65 64 20 61 73 20 69  gs obtained as i
8940: 66 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74  f from.** [sqlit
8950: 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
8960: 5d 2c 20 6f 6e 65 20 66 6f 72 20 65 61 63 68 20  ], one for each 
8970: 63 6f 6c 75 6d 6e 2e 20 20 5e 49 66 20 61 6e 20  column.  ^If an 
8980: 65 6c 65 6d 65 6e 74 20 6f 66 20 61 0a 2a 2a 20  element of a.** 
8990: 72 65 73 75 6c 74 20 72 6f 77 20 69 73 20 4e 55  result row is NU
89a0: 4c 4c 20 74 68 65 6e 20 74 68 65 20 63 6f 72 72  LL then the corr
89b0: 65 73 70 6f 6e 64 69 6e 67 20 73 74 72 69 6e 67  esponding string
89c0: 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65   pointer for the
89d0: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63  .** sqlite3_exec
89e0: 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  () callback is a
89f0: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20   NULL pointer.  
8a00: 5e 54 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e  ^The 4th argumen
8a10: 74 20 74 6f 20 74 68 65 0a 2a 2a 20 73 71 6c 69  t to the.** sqli
8a20: 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62  te3_exec() callb
8a30: 61 63 6b 20 69 73 20 61 6e 20 61 72 72 61 79 20  ack is an array 
8a40: 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73  of pointers to s
8a50: 74 72 69 6e 67 73 20 77 68 65 72 65 20 65 61 63  trings where eac
8a60: 68 0a 2a 2a 20 65 6e 74 72 79 20 72 65 70 72 65  h.** entry repre
8a70: 73 65 6e 74 73 20 74 68 65 20 6e 61 6d 65 20 6f  sents the name o
8a80: 66 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  f corresponding 
8a90: 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 61 73  result column as
8aa0: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
8ab0: 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  m [sqlite3_colum
8ac0: 6e 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  n_name()]..**.**
8ad0: 20 5e 49 66 20 74 68 65 20 32 6e 64 20 70 61 72   ^If the 2nd par
8ae0: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
8af0: 33 5f 65 78 65 63 28 29 20 69 73 20 61 20 4e 55  3_exec() is a NU
8b00: 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 61 20 70 6f  LL pointer, a po
8b10: 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 61 6e 20 65  inter.** to an e
8b20: 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 6f 72 20  mpty string, or 
8b30: 61 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 63  a pointer that c
8b40: 6f 6e 74 61 69 6e 73 20 6f 6e 6c 79 20 77 68 69  ontains only whi
8b50: 74 65 73 70 61 63 65 20 61 6e 64 2f 6f 72 20 0a  tespace and/or .
8b60: 2a 2a 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c  ** SQL comments,
8b70: 20 74 68 65 6e 20 6e 6f 20 53 51 4c 20 73 74 61   then no SQL sta
8b80: 74 65 6d 65 6e 74 73 20 61 72 65 20 65 76 61 6c  tements are eval
8b90: 75 61 74 65 64 20 61 6e 64 20 74 68 65 20 64 61  uated and the da
8ba0: 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 6e 6f 74  tabase.** is not
8bb0: 20 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20   changed..**.** 
8bc0: 52 65 73 74 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a  Restrictions:.**
8bd0: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
8be0: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
8bf0: 20 6d 75 73 74 20 69 6e 73 75 72 65 20 74 68 61   must insure tha
8c00: 74 20 74 68 65 20 31 73 74 20 70 61 72 61 6d 65  t the 1st parame
8c10: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
8c20: 78 65 63 28 29 0a 2a 2a 20 20 20 20 20 20 69 73  xec().**      is
8c30: 20 61 20 76 61 6c 69 64 20 61 6e 64 20 6f 70 65   a valid and ope
8c40: 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
8c50: 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e  ection]..** <li>
8c60: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
8c70: 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20   must not close 
8c80: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
8c90: 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20  tion] specified 
8ca0: 62 79 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 31  by.**      the 1
8cb0: 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
8cc0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77  sqlite3_exec() w
8cd0: 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65  hile sqlite3_exe
8ce0: 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  c() is running..
8cf0: 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c  ** <li> The appl
8d00: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ication must not
8d10: 20 6d 6f 64 69 66 79 20 74 68 65 20 53 51 4c 20   modify the SQL 
8d20: 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 70  statement text p
8d30: 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 20 20  assed into.**   
8d40: 20 20 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d     the 2nd param
8d50: 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f  eter of sqlite3_
8d60: 65 78 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c  exec() while sql
8d70: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 72  ite3_exec() is r
8d80: 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e  unning..** </ul>
8d90: 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
8da0: 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  nt sqlite3_exec(
8db0: 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 20 20  .  sqlite3*,    
8dc0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
8dd0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
8de0: 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73   An open databas
8df0: 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
8e00: 72 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 20 20  r *sql,         
8e10: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
8e20: 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65    /* SQL to be e
8e30: 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69 6e  valuated */.  in
8e40: 74 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f  t (*callback)(vo
8e50: 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63  id*,int,char**,c
8e60: 68 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c  har**),  /* Call
8e70: 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f  back function */
8e80: 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20 20  .  void *,      
8e90: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
8ea0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
8eb0: 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f   1st argument to
8ec0: 20 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63   callback */.  c
8ed0: 68 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 20  har **errmsg    
8ee0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
8ef0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72            /* Err
8f00: 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68  or msg written h
8f10: 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  ere */.);../*.**
8f20: 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c   CAPI3REF: Resul
8f30: 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f  t Codes.** KEYWO
8f40: 52 44 53 3a 20 53 51 4c 49 54 45 5f 4f 4b 20 7b  RDS: SQLITE_OK {
8f50: 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 72 72  error code} {err
8f60: 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59  or codes}.** KEY
8f70: 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74 20 63  WORDS: {result c
8f80: 6f 64 65 7d 20 7b 72 65 73 75 6c 74 20 63 6f 64  ode} {result cod
8f90: 65 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53  es}.**.** Many S
8fa0: 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20  QLite functions 
8fb0: 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65  return an intege
8fc0: 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72  r result code fr
8fd0: 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e  om the set shown
8fe0: 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65  .** here in orde
8ff0: 72 20 74 6f 20 69 6e 64 69 63 61 74 65 20 73 75  r to indicate su
9000: 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65  ccess or failure
9010: 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f  ..**.** New erro
9020: 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20 61  r codes may be a
9030: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 76  dded in future v
9040: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
9050: 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  e..**.** See als
9060: 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  o: [SQLITE_IOERR
9070: 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64  _READ | extended
9080: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 2c 0a   result codes],.
9090: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 74 61 62  ** [sqlite3_vtab
90a0: 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20  _on_conflict()] 
90b0: 5b 53 51 4c 49 54 45 5f 52 4f 4c 4c 42 41 43 4b  [SQLITE_ROLLBACK
90c0: 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d   | result codes]
90d0: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
90e0: 49 54 45 5f 4f 4b 20 20 20 20 20 20 20 20 20 20  ITE_OK          
90f0: 20 30 20 20 20 2f 2a 20 53 75 63 63 65 73 73 66   0   /* Successf
9100: 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20  ul result */./* 
9110: 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72  beginning-of-err
9120: 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66  or-codes */.#def
9130: 69 6e 65 20 53 51 4c 49 54 45 5f 45 52 52 4f 52  ine SQLITE_ERROR
9140: 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 53          1   /* S
9150: 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d 69 73 73  QL error or miss
9160: 69 6e 67 20 64 61 74 61 62 61 73 65 20 2a 2f 0a  ing database */.
9170: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
9180: 4e 54 45 52 4e 41 4c 20 20 20 20 20 32 20 20 20  NTERNAL     2   
9190: 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69  /* Internal logi
91a0: 63 20 65 72 72 6f 72 20 69 6e 20 53 51 4c 69 74  c error in SQLit
91b0: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
91c0: 49 54 45 5f 50 45 52 4d 20 20 20 20 20 20 20 20  ITE_PERM        
91d0: 20 33 20 20 20 2f 2a 20 41 63 63 65 73 73 20 70   3   /* Access p
91e0: 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e 69 65 64  ermission denied
91f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
9200: 54 45 5f 41 42 4f 52 54 20 20 20 20 20 20 20 20  TE_ABORT        
9210: 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20  4   /* Callback 
9220: 72 6f 75 74 69 6e 65 20 72 65 71 75 65 73 74 65  routine requeste
9230: 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64  d an abort */.#d
9240: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53  efine SQLITE_BUS
9250: 59 20 20 20 20 20 20 20 20 20 35 20 20 20 2f 2a  Y         5   /*
9260: 20 54 68 65 20 64 61 74 61 62 61 73 65 20 66 69   The database fi
9270: 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a  le is locked */.
9280: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
9290: 4f 43 4b 45 44 20 20 20 20 20 20 20 36 20 20 20  OCKED       6   
92a0: 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e 20 74 68  /* A table in th
92b0: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6c 6f  e database is lo
92c0: 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  cked */.#define 
92d0: 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20  SQLITE_NOMEM    
92e0: 20 20 20 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c      7   /* A mal
92f0: 6c 6f 63 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a  loc() failed */.
9300: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
9310: 45 41 44 4f 4e 4c 59 20 20 20 20 20 38 20 20 20  EADONLY     8   
9320: 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f 20 77 72  /* Attempt to wr
9330: 69 74 65 20 61 20 72 65 61 64 6f 6e 6c 79 20 64  ite a readonly d
9340: 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 69  atabase */.#defi
9350: 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 52  ne SQLITE_INTERR
9360: 55 50 54 20 20 20 20 39 20 20 20 2f 2a 20 4f 70  UPT    9   /* Op
9370: 65 72 61 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74  eration terminat
9380: 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e  ed by sqlite3_in
9390: 74 65 72 72 75 70 74 28 29 2a 2f 0a 23 64 65 66  terrupt()*/.#def
93a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
93b0: 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 53         10   /* S
93c0: 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b  ome kind of disk
93d0: 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63 63 75 72   I/O error occur
93e0: 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  red */.#define S
93f0: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 20 20  QLITE_CORRUPT   
9400: 20 20 31 31 20 20 20 2f 2a 20 54 68 65 20 64 61    11   /* The da
9410: 74 61 62 61 73 65 20 64 69 73 6b 20 69 6d 61 67  tabase disk imag
9420: 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a  e is malformed *
9430: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
9440: 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20 31 32 20  _NOTFOUND    12 
9450: 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e 20 6f 70 63    /* Unknown opc
9460: 6f 64 65 20 69 6e 20 73 71 6c 69 74 65 33 5f 66  ode in sqlite3_f
9470: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 20 2a 2f  ile_control() */
9480: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
9490: 46 55 4c 4c 20 20 20 20 20 20 20 20 31 33 20 20  FULL        13  
94a0: 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 20 66 61   /* Insertion fa
94b0: 69 6c 65 64 20 62 65 63 61 75 73 65 20 64 61 74  iled because dat
94c0: 61 62 61 73 65 20 69 73 20 66 75 6c 6c 20 2a 2f  abase is full */
94d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
94e0: 43 41 4e 54 4f 50 45 4e 20 20 20 20 31 34 20 20  CANTOPEN    14  
94f0: 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 20 6f 70   /* Unable to op
9500: 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
9510: 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  file */.#define 
9520: 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43 4f 4c 20  SQLITE_PROTOCOL 
9530: 20 20 20 31 35 20 20 20 2f 2a 20 44 61 74 61 62     15   /* Datab
9540: 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f  ase lock protoco
9550: 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69  l error */.#defi
9560: 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50 54 59 20  ne SQLITE_EMPTY 
9570: 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 44 61        16   /* Da
9580: 74 61 62 61 73 65 20 69 73 20 65 6d 70 74 79 20  tabase is empty 
9590: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
95a0: 45 5f 53 43 48 45 4d 41 20 20 20 20 20 20 31 37  E_SCHEMA      17
95b0: 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61     /* The databa
95c0: 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65  se schema change
95d0: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
95e0: 49 54 45 5f 54 4f 4f 42 49 47 20 20 20 20 20 20  ITE_TOOBIG      
95f0: 31 38 20 20 20 2f 2a 20 53 74 72 69 6e 67 20 6f  18   /* String o
9600: 72 20 42 4c 4f 42 20 65 78 63 65 65 64 73 20 73  r BLOB exceeds s
9610: 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a 23 64 65  ize limit */.#de
9620: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
9630: 54 52 41 49 4e 54 20 20 31 39 20 20 20 2f 2a 20  TRAINT  19   /* 
9640: 41 62 6f 72 74 20 64 75 65 20 74 6f 20 63 6f 6e  Abort due to con
9650: 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f  straint violatio
9660: 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  n */.#define SQL
9670: 49 54 45 5f 4d 49 53 4d 41 54 43 48 20 20 20 20  ITE_MISMATCH    
9680: 32 30 20 20 20 2f 2a 20 44 61 74 61 20 74 79 70  20   /* Data typ
9690: 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f 0a 23 64  e mismatch */.#d
96a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53  efine SQLITE_MIS
96b0: 55 53 45 20 20 20 20 20 20 32 31 20 20 20 2f 2a  USE      21   /*
96c0: 20 4c 69 62 72 61 72 79 20 75 73 65 64 20 69 6e   Library used in
96d0: 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a 23 64 65  correctly */.#de
96e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4c 46  fine SQLITE_NOLF
96f0: 53 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20  S       22   /* 
9700: 55 73 65 73 20 4f 53 20 66 65 61 74 75 72 65 73  Uses OS features
9710: 20 6e 6f 74 20 73 75 70 70 6f 72 74 65 64 20 6f   not supported o
9720: 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65 66 69 6e  n host */.#defin
9730: 65 20 53 51 4c 49 54 45 5f 41 55 54 48 20 20 20  e SQLITE_AUTH   
9740: 20 20 20 20 20 32 33 20 20 20 2f 2a 20 41 75 74       23   /* Aut
9750: 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65 6e 69 65  horization denie
9760: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
9770: 49 54 45 5f 46 4f 52 4d 41 54 20 20 20 20 20 20  ITE_FORMAT      
9780: 32 34 20 20 20 2f 2a 20 41 75 78 69 6c 69 61 72  24   /* Auxiliar
9790: 79 20 64 61 74 61 62 61 73 65 20 66 6f 72 6d 61  y database forma
97a0: 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69  t error */.#defi
97b0: 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e 47 45 20  ne SQLITE_RANGE 
97c0: 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 32 6e        25   /* 2n
97d0: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
97e0: 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f 75 74 20  qlite3_bind out 
97f0: 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66  of range */.#def
9800: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44  ine SQLITE_NOTAD
9810: 42 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 46  B      26   /* F
9820: 69 6c 65 20 6f 70 65 6e 65 64 20 74 68 61 74 20  ile opened that 
9830: 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73  is not a databas
9840: 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e  e file */.#defin
9850: 65 20 53 51 4c 49 54 45 5f 52 4f 57 20 20 20 20  e SQLITE_ROW    
9860: 20 20 20 20 20 31 30 30 20 20 2f 2a 20 73 71 6c       100  /* sql
9870: 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73 20  ite3_step() has 
9880: 61 6e 6f 74 68 65 72 20 72 6f 77 20 72 65 61 64  another row read
9890: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
98a0: 49 54 45 5f 44 4f 4e 45 20 20 20 20 20 20 20 20  ITE_DONE        
98b0: 31 30 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f  101  /* sqlite3_
98c0: 73 74 65 70 28 29 20 68 61 73 20 66 69 6e 69 73  step() has finis
98d0: 68 65 64 20 65 78 65 63 75 74 69 6e 67 20 2a 2f  hed executing */
98e0: 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72  ./* end-of-error
98f0: 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  -codes */../*.**
9900: 20 43 41 50 49 33 52 45 46 3a 20 45 78 74 65 6e   CAPI3REF: Exten
9910: 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73  ded Result Codes
9920: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65  .** KEYWORDS: {e
9930: 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f  xtended error co
9940: 64 65 7d 20 7b 65 78 74 65 6e 64 65 64 20 65 72  de} {extended er
9950: 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45  ror codes}.** KE
9960: 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64 65  YWORDS: {extende
9970: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 7d 20 7b  d result code} {
9980: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
9990: 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20  codes}.**.** In 
99a0: 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  its default conf
99b0: 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74  iguration, SQLit
99c0: 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 72  e API routines r
99d0: 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 32 36 20  eturn one of 26 
99e0: 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c 49  integer.** [SQLI
99f0: 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63  TE_OK | result c
9a00: 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76 65 72 2c  odes].  However,
9a10: 20 65 78 70 65 72 69 65 6e 63 65 20 68 61 73 20   experience has 
9a20: 73 68 6f 77 6e 20 74 68 61 74 20 6d 61 6e 79 20  shown that many 
9a30: 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72 65 73 75  of.** these resu
9a40: 6c 74 20 63 6f 64 65 73 20 61 72 65 20 74 6f 6f  lt codes are too
9a50: 20 63 6f 61 72 73 65 2d 67 72 61 69 6e 65 64 2e   coarse-grained.
9a60: 20 20 54 68 65 79 20 64 6f 20 6e 6f 74 20 70 72    They do not pr
9a70: 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75 63 68  ovide as.** much
9a80: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f   information abo
9a90: 75 74 20 70 72 6f 62 6c 65 6d 73 20 61 73 20 70  ut problems as p
9aa0: 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68 74  rogrammers might
9ab0: 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20 65 66   like.  In an ef
9ac0: 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64 72 65  fort to.** addre
9ad0: 73 73 20 74 68 69 73 2c 20 6e 65 77 65 72 20 76  ss this, newer v
9ae0: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
9af0: 65 20 28 76 65 72 73 69 6f 6e 20 33 2e 33 2e 38  e (version 3.3.8
9b00: 20 61 6e 64 20 6c 61 74 65 72 29 20 69 6e 63 6c   and later) incl
9b10: 75 64 65 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66  ude.** support f
9b20: 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 72 65  or additional re
9b30: 73 75 6c 74 20 63 6f 64 65 73 20 74 68 61 74 20  sult codes that 
9b40: 70 72 6f 76 69 64 65 20 6d 6f 72 65 20 64 65 74  provide more det
9b50: 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f  ailed informatio
9b60: 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 72 72 6f 72  n.** about error
9b70: 73 2e 20 54 68 65 20 65 78 74 65 6e 64 65 64 20  s. The extended 
9b80: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
9b90: 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61   enabled or disa
9ba0: 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 65 72  bled.** on a per
9bb0: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
9bc0: 74 69 6f 6e 20 62 61 73 69 73 20 75 73 69 6e 67  tion basis using
9bd0: 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
9be0: 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74  _extended_result
9bf0: 5f 63 6f 64 65 73 28 29 5d 20 41 50 49 2e 0a 2a  _codes()] API..*
9c00: 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68 65  *.** Some of the
9c10: 20 61 76 61 69 6c 61 62 6c 65 20 65 78 74 65 6e   available exten
9c20: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
9c30: 20 61 72 65 20 6c 69 73 74 65 64 20 68 65 72 65   are listed here
9c40: 2e 0a 2a 2a 20 4f 6e 65 20 6d 61 79 20 65 78 70  ..** One may exp
9c50: 65 63 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ect the number o
9c60: 66 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  f extended resul
9c70: 74 20 63 6f 64 65 73 20 77 69 6c 6c 20 62 65 20  t codes will be 
9c80: 65 78 70 61 6e 64 0a 2a 2a 20 6f 76 65 72 20 74  expand.** over t
9c90: 69 6d 65 2e 20 20 53 6f 66 74 77 61 72 65 20 74  ime.  Software t
9ca0: 68 61 74 20 75 73 65 73 20 65 78 74 65 6e 64 65  hat uses extende
9cb0: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 73  d result codes s
9cc0: 68 6f 75 6c 64 20 65 78 70 65 63 74 0a 2a 2a 20  hould expect.** 
9cd0: 74 6f 20 73 65 65 20 6e 65 77 20 72 65 73 75 6c  to see new resul
9ce0: 74 20 63 6f 64 65 73 20 69 6e 20 66 75 74 75 72  t codes in futur
9cf0: 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
9d00: 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  Lite..**.** The 
9d10: 53 51 4c 49 54 45 5f 4f 4b 20 72 65 73 75 6c 74  SQLITE_OK result
9d20: 20 63 6f 64 65 20 77 69 6c 6c 20 6e 65 76 65 72   code will never
9d30: 20 62 65 20 65 78 74 65 6e 64 65 64 2e 20 20 49   be extended.  I
9d40: 74 20 77 69 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a  t will always.**
9d50: 20 62 65 20 65 78 61 63 74 6c 79 20 7a 65 72 6f   be exactly zero
9d60: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
9d70: 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 20  ITE_IOERR_READ  
9d80: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
9d90: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c  ITE_IOERR | (1<<
9da0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
9db0: 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52  TE_IOERR_SHORT_R
9dc0: 45 41 44 20 20 20 20 20 20 20 20 28 53 51 4c 49  EAD        (SQLI
9dd0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38  TE_IOERR | (2<<8
9de0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
9df0: 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20 20  E_IOERR_WRITE   
9e00: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
9e10: 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29  E_IOERR | (3<<8)
9e20: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
9e30: 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20 20  _IOERR_FSYNC    
9e40: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
9e50: 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29 29  _IOERR | (4<<8))
9e60: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
9e70: 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43 20  IOERR_DIR_FSYNC 
9e80: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
9e90: 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a  IOERR | (5<<8)).
9ea0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
9eb0: 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20 20  OERR_TRUNCATE   
9ec0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
9ed0: 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23  OERR | (6<<8)).#
9ee0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
9ef0: 45 52 52 5f 46 53 54 41 54 20 20 20 20 20 20 20  ERR_FSTAT       
9f00: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
9f10: 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64  ERR | (7<<8)).#d
9f20: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
9f30: 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20  RR_UNLOCK       
9f40: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
9f50: 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65  RR | (8<<8)).#de
9f60: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
9f70: 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20 20  R_RDLOCK        
9f80: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
9f90: 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66  R | (9<<8)).#def
9fa0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
9fb0: 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20  _DELETE         
9fc0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
9fd0: 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 66   | (10<<8)).#def
9fe0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
9ff0: 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 20  _BLOCKED        
a000: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
a010: 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65 66   | (11<<8)).#def
a020: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
a030: 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20 20  _NOMEM          
a040: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
a050: 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65 66   | (12<<8)).#def
a060: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
a070: 5f 41 43 43 45 53 53 20 20 20 20 20 20 20 20 20  _ACCESS         
a080: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
a090: 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65 66   | (13<<8)).#def
a0a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
a0b0: 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c 4f  _CHECKRESERVEDLO
a0c0: 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52  CK (SQLITE_IOERR
a0d0: 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65 66   | (14<<8)).#def
a0e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
a0f0: 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  _LOCK           
a100: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
a110: 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65 66   | (15<<8)).#def
a120: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
a130: 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 20  _CLOSE          
a140: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
a150: 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65 66   | (16<<8)).#def
a160: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
a170: 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20 20  _DIR_CLOSE      
a180: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
a190: 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65 66   | (17<<8)).#def
a1a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
a1b0: 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20 20 20 20  _SHMOPEN        
a1c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
a1d0: 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64 65 66   | (18<<8)).#def
a1e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
a1f0: 5f 53 48 4d 53 49 5a 45 20 20 20 20 20 20 20 20  _SHMSIZE        
a200: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
a210: 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64 65 66   | (19<<8)).#def
a220: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
a230: 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20  _SHMLOCK        
a240: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
a250: 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64 65 66   | (20<<8)).#def
a260: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
a270: 5f 53 48 4d 4d 41 50 20 20 20 20 20 20 20 20 20  _SHMMAP         
a280: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
a290: 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64 65 66   | (21<<8)).#def
a2a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
a2b0: 5f 53 45 45 4b 20 20 20 20 20 20 20 20 20 20 20  _SEEK           
a2c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
a2d0: 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64 65 66   | (22<<8)).#def
a2e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
a2f0: 5f 44 45 4c 45 54 45 5f 4e 4f 45 4e 54 20 20 20  _DELETE_NOENT   
a300: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
a310: 20 7c 20 28 32 33 3c 3c 38 29 29 0a 23 64 65 66   | (23<<8)).#def
a320: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45  ine SQLITE_LOCKE
a330: 44 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20  D_SHAREDCACHE   
a340: 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45     (SQLITE_LOCKE
a350: 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65  D |  (1<<8)).#de
a360: 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59  fine SQLITE_BUSY
a370: 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20  _RECOVERY       
a380: 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59      (SQLITE_BUSY
a390: 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64     |  (1<<8)).#d
a3a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e  efine SQLITE_CAN
a3b0: 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52 20  TOPEN_NOTEMPDIR 
a3c0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e       (SQLITE_CAN
a3d0: 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29 0a  TOPEN | (1<<8)).
a3e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
a3f0: 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52 20 20 20  ANTOPEN_ISDIR   
a400: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43         (SQLITE_C
a410: 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c 3c 38 29  ANTOPEN | (2<<8)
a420: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
a430: 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c 4c 50 41  _CANTOPEN_FULLPA
a440: 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  TH       (SQLITE
a450: 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 33 3c 3c  _CANTOPEN | (3<<
a460: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
a470: 54 45 5f 43 4f 52 52 55 50 54 5f 56 54 41 42 20  TE_CORRUPT_VTAB 
a480: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
a490: 54 45 5f 43 4f 52 52 55 50 54 20 7c 20 28 31 3c  TE_CORRUPT | (1<
a4a0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
a4b0: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 45 43  ITE_READONLY_REC
a4c0: 4f 56 45 52 59 20 20 20 20 20 20 20 28 53 51 4c  OVERY       (SQL
a4d0: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28  ITE_READONLY | (
a4e0: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
a4f0: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 43  QLITE_READONLY_C
a500: 41 4e 54 4c 4f 43 4b 20 20 20 20 20 20 20 28 53  ANTLOCK       (S
a510: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c  QLITE_READONLY |
a520: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (2<<8)).#define
a530: 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 5f 52 4f   SQLITE_ABORT_RO
a540: 4c 4c 42 41 43 4b 20 20 20 20 20 20 20 20 20 20  LLBACK          
a550: 28 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 7c 20  (SQLITE_ABORT | 
a560: 28 32 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43  (2<<8))../*.** C
a570: 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46  API3REF: Flags F
a580: 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65  or File Open Ope
a590: 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  rations.**.** Th
a5a0: 65 73 65 20 62 69 74 20 76 61 6c 75 65 73 20 61  ese bit values a
a5b0: 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  re intended for 
a5c0: 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72  use in the.** 3r
a5d0: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
a5e0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
a5f0: 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65  _v2()] interface
a600: 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34   and.** in the 4
a610: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
a620: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
a630: 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a  .xOpen] method..
a640: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
a650: 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20  E_OPEN_READONLY 
a660: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
a670: 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  01  /* Ok for sq
a680: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
a690: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
a6a0: 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
a6b0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
a6c0: 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  02  /* Ok for sq
a6d0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
a6e0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
a6f0: 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20  E_OPEN_CREATE   
a700: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
a710: 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  04  /* Ok for sq
a720: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
a730: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
a740: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
a750: 4c 4f 53 45 20 20 20 20 30 78 30 30 30 30 30 30  LOSE    0x000000
a760: 30 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  08  /* VFS only 
a770: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
a780: 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45  E_OPEN_EXCLUSIVE
a790: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
a7a0: 31 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  10  /* VFS only 
a7b0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
a7c0: 45 5f 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58 59  E_OPEN_AUTOPROXY
a7d0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
a7e0: 32 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  20  /* VFS only 
a7f0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
a800: 45 5f 4f 50 45 4e 5f 55 52 49 20 20 20 20 20 20  E_OPEN_URI      
a810: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
a820: 34 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  40  /* Ok for sq
a830: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
a840: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
a850: 45 5f 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20 20 20  E_OPEN_MEMORY   
a860: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
a870: 38 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  80  /* Ok for sq
a880: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
a890: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
a8a0: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20  E_OPEN_MAIN_DB  
a8b0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31          0x000001
a8c0: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
a8d0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
a8e0: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20  E_OPEN_TEMP_DB  
a8f0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32          0x000002
a900: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
a910: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
a920: 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54  E_OPEN_TRANSIENT
a930: 5f 44 42 20 20 20 20 20 30 78 30 30 30 30 30 34  _DB     0x000004
a940: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
a950: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
a960: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52  E_OPEN_MAIN_JOUR
a970: 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 30 38  NAL     0x000008
a980: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
a990: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
a9a0: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52  E_OPEN_TEMP_JOUR
a9b0: 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 31 30  NAL     0x000010
a9c0: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
a9d0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
a9e0: 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41  E_OPEN_SUBJOURNA
a9f0: 4c 20 20 20 20 20 20 20 30 78 30 30 30 30 32 30  L       0x000020
aa00: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
aa10: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
aa20: 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f  E_OPEN_MASTER_JO
aa30: 55 52 4e 41 4c 20 20 20 30 78 30 30 30 30 34 30  URNAL   0x000040
aa40: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
aa50: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
aa60: 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20  E_OPEN_NOMUTEX  
aa70: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 38 30          0x000080
aa80: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
aa90: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
aaa0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
aab0: 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58  E_OPEN_FULLMUTEX
aac0: 20 20 20 20 20 20 20 20 30 78 30 30 30 31 30 30          0x000100
aad0: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
aae0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
aaf0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
ab00: 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
ab10: 48 45 20 20 20 20 20 20 30 78 30 30 30 32 30 30  HE      0x000200
ab20: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
ab30: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
ab40: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
ab50: 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41  E_OPEN_PRIVATECA
ab60: 43 48 45 20 20 20 20 20 30 78 30 30 30 34 30 30  CHE     0x000400
ab70: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
ab80: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
ab90: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
aba0: 45 5f 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20 20  E_OPEN_WAL      
abb0: 20 20 20 20 20 20 20 20 30 78 30 30 30 38 30 30          0x000800
abc0: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
abd0: 2a 2f 0a 0a 2f 2a 20 52 65 73 65 72 76 65 64 3a  */../* Reserved:
abe0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
abf0: 20 20 20 20 20 20 20 20 20 30 78 30 30 46 30 30           0x00F00
ac00: 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  000 */../*.** CA
ac10: 50 49 33 52 45 46 3a 20 44 65 76 69 63 65 20 43  PI3REF: Device C
ac20: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 0a 2a  haracteristics.*
ac30: 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65  *.** The xDevice
ac40: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20  Characteristics 
ac50: 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 73  method of the [s
ac60: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
ac70: 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74  s].** object ret
ac80: 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20  urns an integer 
ac90: 77 68 69 63 68 20 69 73 20 61 20 76 65 63 74 6f  which is a vecto
aca0: 72 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 62 69  r of these.** bi
acb0: 74 20 76 61 6c 75 65 73 20 65 78 70 72 65 73 73  t values express
acc0: 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 74 65  ing I/O characte
acd0: 72 69 73 74 69 63 73 20 6f 66 20 74 68 65 20 6d  ristics of the m
ace0: 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64  ass storage.** d
acf0: 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c 64 73  evice that holds
ad00: 20 74 68 65 20 66 69 6c 65 20 74 68 61 74 20 74   the file that t
ad10: 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  he [sqlite3_io_m
ad20: 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72  ethods].** refer
ad30: 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  s to..**.** The 
ad40: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
ad50: 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61  MIC property mea
ad60: 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74  ns that all writ
ad70: 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a  es of.** any siz
ad80: 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  e are atomic.  T
ad90: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
ada0: 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73  ATOMICnnn values
adb0: 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72  .** mean that wr
adc0: 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74  ites of blocks t
add0: 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65  hat are nnn byte
ade0: 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a  s in size and.**
adf0: 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20   are aligned to 
ae00: 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68  an address which
ae10: 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d   is an integer m
ae20: 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e  ultiple of.** nn
ae30: 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  n are atomic.  T
ae40: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
ae50: 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75  SAFE_APPEND valu
ae60: 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20  e means.** that 
ae70: 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70  when data is app
ae80: 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c  ended to a file,
ae90: 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70   the data is app
aea0: 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74  ended.** first t
aeb0: 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20  hen the size of 
aec0: 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65  the file is exte
aed0: 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20  nded, never the 
aee0: 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f  other.** way aro
aef0: 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45  und.  The SQLITE
af00: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41  _IOCAP_SEQUENTIA
af10: 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  L property means
af20: 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61   that.** informa
af30: 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20  tion is written 
af40: 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73  to disk in the s
af50: 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c  ame order as cal
af60: 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28  ls.** to xWrite(
af70: 29 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  ).  The SQLITE_I
af80: 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f  OCAP_POWERSAFE_O
af90: 56 45 52 57 52 49 54 45 20 70 72 6f 70 65 72 74  VERWRITE propert
afa0: 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20  y means that.** 
afb0: 61 66 74 65 72 20 72 65 62 6f 6f 74 20 66 6f 6c  after reboot fol
afc0: 6c 6f 77 69 6e 67 20 61 20 63 72 61 73 68 20 6f  lowing a crash o
afd0: 72 20 70 6f 77 65 72 20 6c 6f 73 73 2c 20 74 68  r power loss, th
afe0: 65 20 6f 6e 6c 79 20 62 79 74 65 73 20 69 6e 20  e only bytes in 
aff0: 61 0a 2a 2a 20 66 69 6c 65 20 74 68 61 74 20 77  a.** file that w
b000: 65 72 65 20 77 72 69 74 74 65 6e 20 61 74 20 74  ere written at t
b010: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6c  he application l
b020: 65 76 65 6c 20 6d 69 67 68 74 20 68 61 76 65 20  evel might have 
b030: 63 68 61 6e 67 65 64 0a 2a 2a 20 61 6e 64 20 74  changed.** and t
b040: 68 61 74 20 61 64 6a 61 63 65 6e 74 20 62 79 74  hat adjacent byt
b050: 65 73 2c 20 65 76 65 6e 20 62 79 74 65 73 20 77  es, even bytes w
b060: 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 73  ithin the same s
b070: 65 63 74 6f 72 20 61 72 65 0a 2a 2a 20 67 75 61  ector are.** gua
b080: 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20 75 6e  ranteed to be un
b090: 63 68 61 6e 67 65 64 2e 0a 2a 2f 0a 23 64 65 66  changed..*/.#def
b0a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
b0b0: 5f 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20 20  _ATOMIC         
b0c0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
b0d0: 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  01.#define SQLIT
b0e0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31  E_IOCAP_ATOMIC51
b0f0: 32 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30  2              0
b100: 78 30 30 30 30 30 30 30 32 0a 23 64 65 66 69 6e  x00000002.#defin
b110: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
b120: 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 20 20  TOMIC1K         
b130: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34        0x00000004
b140: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
b150: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20 20  IOCAP_ATOMIC2K  
b160: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
b170: 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20  0000008.#define 
b180: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
b190: 4d 49 43 34 4b 20 20 20 20 20 20 20 20 20 20 20  MIC4K           
b1a0: 20 20 20 20 30 78 30 30 30 30 30 30 31 30 0a 23      0x00000010.#
b1b0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
b1c0: 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20 20  CAP_ATOMIC8K    
b1d0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
b1e0: 30 30 30 32 30 0a 23 64 65 66 69 6e 65 20 53 51  00020.#define SQ
b1f0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
b200: 43 31 36 4b 20 20 20 20 20 20 20 20 20 20 20 20  C16K            
b210: 20 20 30 78 30 30 30 30 30 30 34 30 0a 23 64 65    0x00000040.#de
b220: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
b230: 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20 20 20  P_ATOMIC32K     
b240: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
b250: 30 38 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  080.#define SQLI
b260: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36  TE_IOCAP_ATOMIC6
b270: 34 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  4K              
b280: 30 78 30 30 30 30 30 31 30 30 0a 23 64 65 66 69  0x00000100.#defi
b290: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
b2a0: 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20 20 20  SAFE_APPEND     
b2b0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30         0x0000020
b2c0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
b2d0: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41  _IOCAP_SEQUENTIA
b2e0: 4c 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78  L             0x
b2f0: 30 30 30 30 30 34 30 30 0a 23 64 65 66 69 6e 65  00000400.#define
b300: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e   SQLITE_IOCAP_UN
b310: 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f  DELETABLE_WHEN_O
b320: 50 45 4e 20 20 30 78 30 30 30 30 30 38 30 30 0a  PEN  0x00000800.
b330: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
b340: 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f  OCAP_POWERSAFE_O
b350: 56 45 52 57 52 49 54 45 20 20 20 20 30 78 30 30  VERWRITE    0x00
b360: 30 30 31 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41  001000../*.** CA
b370: 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63  PI3REF: File Loc
b380: 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a 2a  king Levels.**.*
b390: 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 6f 6e  * SQLite uses on
b3a0: 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67  e of these integ
b3b0: 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65  er values as the
b3c0: 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d   second.** argum
b3d0: 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69 74 20  ent to calls it 
b3e0: 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78 4c 6f  makes to the xLo
b3f0: 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b  ck() and xUnlock
b400: 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66  () methods.** of
b410: 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f   an [sqlite3_io_
b420: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e  methods] object.
b430: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
b440: 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20  TE_LOCK_NONE    
b450: 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20        0.#define 
b460: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52  SQLITE_LOCK_SHAR
b470: 45 44 20 20 20 20 20 20 20 20 31 0a 23 64 65 66  ED        1.#def
b480: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
b490: 52 45 53 45 52 56 45 44 20 20 20 20 20 20 32 0a  RESERVED      2.
b4a0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
b4b0: 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20 20  OCK_PENDING     
b4c0: 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    3.#define SQLI
b4d0: 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56  TE_LOCK_EXCLUSIV
b4e0: 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43  E     4../*.** C
b4f0: 41 50 49 33 52 45 46 3a 20 53 79 6e 63 68 72 6f  API3REF: Synchro
b500: 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 20 46 6c  nization Type Fl
b510: 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53  ags.**.** When S
b520: 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 74 68  QLite invokes th
b530: 65 20 78 53 79 6e 63 28 29 20 6d 65 74 68 6f 64  e xSync() method
b540: 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74   of an.** [sqlit
b550: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f  e3_io_methods] o
b560: 62 6a 65 63 74 20 69 74 20 75 73 65 73 20 61 20  bject it uses a 
b570: 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a  combination of.*
b580: 2a 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20  * these integer 
b590: 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 65  values as the se
b5a0: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  cond argument..*
b5b0: 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 53 51  *.** When the SQ
b5c0: 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e  LITE_SYNC_DATAON
b5d0: 4c 59 20 66 6c 61 67 20 69 73 20 75 73 65 64 2c  LY flag is used,
b5e0: 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74   it means that t
b5f0: 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61  he.** sync opera
b600: 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20  tion only needs 
b610: 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20 74 6f  to flush data to
b620: 20 6d 61 73 73 20 73 74 6f 72 61 67 65 2e 20 20   mass storage.  
b630: 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61  Inode.** informa
b640: 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65  tion need not be
b650: 20 66 6c 75 73 68 65 64 2e 20 49 66 20 74 68 65   flushed. If the
b660: 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73   lower four bits
b670: 20 6f 66 20 74 68 65 20 66 6c 61 67 0a 2a 2a 20   of the flag.** 
b680: 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e  equal SQLITE_SYN
b690: 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 74 20 6d  C_NORMAL, that m
b6a0: 65 61 6e 73 20 74 6f 20 75 73 65 20 6e 6f 72 6d  eans to use norm
b6b0: 61 6c 20 66 73 79 6e 63 28 29 20 73 65 6d 61 6e  al fsync() seman
b6c0: 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20  tics..** If the 
b6d0: 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73 20  lower four bits 
b6e0: 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e  equal SQLITE_SYN
b6f0: 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20 6d 65 61  C_FULL, that mea
b700: 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63  ns.** to use Mac
b710: 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c   OS X style full
b720: 73 79 6e 63 20 69 6e 73 74 65 61 64 20 6f 66 20  sync instead of 
b730: 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 44  fsync()..**.** D
b740: 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65 20 74 68  o not confuse th
b750: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f  e SQLITE_SYNC_NO
b760: 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f  RMAL and SQLITE_
b770: 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73 0a  SYNC_FULL flags.
b780: 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 50 52 41  ** with the [PRA
b790: 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d  GMA synchronous]
b7a0: 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b 50 52 41  =NORMAL and [PRA
b7b0: 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d  GMA synchronous]
b7c0: 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e 67  =FULL.** setting
b7d0: 73 2e 20 20 54 68 65 20 5b 73 79 6e 63 68 72 6f  s.  The [synchro
b7e0: 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20 64 65 74  nous pragma] det
b7f0: 65 72 6d 69 6e 65 73 20 77 68 65 6e 20 63 61 6c  ermines when cal
b800: 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 79  ls to the.** xSy
b810: 6e 63 20 56 46 53 20 6d 65 74 68 6f 64 20 6f 63  nc VFS method oc
b820: 63 75 72 20 61 6e 64 20 61 70 70 6c 69 65 73 20  cur and applies 
b830: 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72 6f 73 73  uniformly across
b840: 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d 73 2e 0a   all platforms..
b850: 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 53 59  ** The SQLITE_SY
b860: 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51  NC_NORMAL and SQ
b870: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66  LITE_SYNC_FULL f
b880: 6c 61 67 73 20 64 65 74 65 72 6d 69 6e 65 20 68  lags determine h
b890: 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74 69 63 20  ow.** energetic 
b8a0: 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f 72 20 66  or rigorous or f
b8b0: 6f 72 63 65 66 75 6c 20 74 68 65 20 73 79 6e 63  orceful the sync
b8c0: 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72 65 20   operations are 
b8d0: 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b 65  and.** only make
b8e0: 20 61 20 64 69 66 66 65 72 65 6e 63 65 20 6f 6e   a difference on
b8f0: 20 4d 61 63 20 4f 53 58 20 66 6f 72 20 74 68 65   Mac OSX for the
b900: 20 64 65 66 61 75 6c 74 20 53 51 4c 69 74 65 20   default SQLite 
b910: 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69 72 64 2d  code..** (Third-
b920: 70 61 72 74 79 20 56 46 53 20 69 6d 70 6c 65 6d  party VFS implem
b930: 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67 68 74 20  entations might 
b940: 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65 20 64 69  also make the di
b950: 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74  stinction.** bet
b960: 77 65 65 6e 20 53 51 4c 49 54 45 5f 53 59 4e 43  ween SQLITE_SYNC
b970: 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49  _NORMAL and SQLI
b980: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 62 75  TE_SYNC_FULL, bu
b990: 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20 6f  t among the.** o
b9a0: 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 73  perating systems
b9b0: 20 6e 61 74 69 76 65 6c 79 20 73 75 70 70 6f 72   natively suppor
b9c0: 74 65 64 20 62 79 20 53 51 4c 69 74 65 2c 20 6f  ted by SQLite, o
b9d0: 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a 2a 20 63  nly Mac OSX.** c
b9e0: 61 72 65 73 20 61 62 6f 75 74 20 74 68 65 20 64  ares about the d
b9f0: 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a 23  ifference.).*/.#
ba00: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59  define SQLITE_SY
ba10: 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20  NC_NORMAL       
ba20: 20 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e 65   0x00002.#define
ba30: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c   SQLITE_SYNC_FUL
ba40: 4c 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30  L          0x000
ba50: 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  03.#define SQLIT
ba60: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20  E_SYNC_DATAONLY 
ba70: 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a 2f 2a       0x00010../*
ba80: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53  .** CAPI3REF: OS
ba90: 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e 20   Interface Open 
baa0: 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a  File Handle.**.*
bab0: 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69  * An [sqlite3_fi
bac0: 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72 65  le] object repre
bad0: 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66 69  sents an open fi
bae0: 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b 73  le in the .** [s
baf0: 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f 53 20  qlite3_vfs | OS 
bb00: 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72 5d  interface layer]
bb10: 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f 53  .  Individual OS
bb20: 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 6d   interface.** im
bb30: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69  plementations wi
bb40: 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73 75  ll.** want to su
bb50: 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62 6a 65  bclass this obje
bb60: 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e 67 20  ct by appending 
bb70: 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64  additional field
bb80: 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72 20 6f  s.** for their o
bb90: 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70 4d 65  wn use.  The pMe
bba0: 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73 20 61  thods entry is a
bbb0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a   pointer to an.*
bbc0: 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  * [sqlite3_io_me
bbd0: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74 68  thods] object th
bbe0: 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74 68 6f  at defines metho
bbf0: 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d 69 6e  ds for performin
bc00: 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74 69  g.** I/O operati
bc10: 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e 20  ons on the open 
bc20: 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  file..*/.typedef
bc30: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
bc40: 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66 69 6c  file sqlite3_fil
bc50: 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  e;.struct sqlite
bc60: 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 74  3_file {.  const
bc70: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
bc80: 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65 74  io_methods *pMet
bc90: 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f 64  hods;  /* Method
bca0: 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66 69  s for an open fi
bcb0: 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  le */.};../*.** 
bcc0: 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74  CAPI3REF: OS Int
bcd0: 65 72 66 61 63 65 20 46 69 6c 65 20 56 69 72 74  erface File Virt
bce0: 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65  ual Methods Obje
bcf0: 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66  ct.**.** Every f
bd00: 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74 68  ile opened by th
bd10: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  e [sqlite3_vfs.x
bd20: 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 70 6f 70  Open] method pop
bd30: 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73 71  ulates an.** [sq
bd40: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
bd50: 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d  ct (or, more com
bd60: 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61 73  monly, a subclas
bd70: 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  s of the.** [sql
bd80: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
bd90: 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65  t) with a pointe
bda0: 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65  r to an instance
bdb0: 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 2e   of this object.
bdc0: 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20  .** This object 
bdd0: 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65 74 68  defines the meth
bde0: 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65 72 66  ods used to perf
bdf0: 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65 72  orm various oper
be00: 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e 73  ations.** agains
be10: 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 20  t the open file 
be20: 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 74  represented by t
be30: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
be40: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20  ] object..**.** 
be50: 49 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  If the [sqlite3_
be60: 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f  vfs.xOpen] metho
be70: 64 20 73 65 74 73 20 74 68 65 20 73 71 6c 69 74  d sets the sqlit
be80: 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73  e3_file.pMethods
be90: 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f 20   element .** to 
bea0: 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74  a non-NULL point
beb0: 65 72 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c  er, then the sql
bec0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 2e  ite3_io_methods.
bed0: 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a 2a 2a  xClose method.**
bee0: 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20   may be invoked 
bef0: 65 76 65 6e 20 69 66 20 74 68 65 20 5b 73 71 6c  even if the [sql
bf00: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20  ite3_vfs.xOpen] 
bf10: 72 65 70 6f 72 74 65 64 20 74 68 61 74 20 69 74  reported that it
bf20: 20 66 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a 2a   failed.  The.**
bf30: 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70 72 65   only way to pre
bf40: 76 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20 78  vent a call to x
bf50: 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  Close following 
bf60: 61 20 66 61 69 6c 65 64 20 5b 73 71 6c 69 74 65  a failed [sqlite
bf70: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a 20  3_vfs.xOpen].** 
bf80: 69 73 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69  is for the [sqli
bf90: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 74  te3_vfs.xOpen] t
bfa0: 6f 20 73 65 74 20 74 68 65 20 73 71 6c 69 74 65  o set the sqlite
bfb0: 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20  3_file.pMethods 
bfc0: 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e 55  element.** to NU
bfd0: 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c  LL..**.** The fl
bfe0: 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ags argument to 
bff0: 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65  xSync may be one
c000: 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43   of [SQLITE_SYNC
c010: 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b  _NORMAL] or.** [
c020: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
c030: 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 63 68  ].  The first ch
c040: 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f 72 6d  oice is the norm
c050: 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54  al fsync()..** T
c060: 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69 63 65  he second choice
c070: 20 69 73 20 61 20 4d 61 63 20 4f 53 20 58 20 73   is a Mac OS X s
c080: 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20  tyle fullsync.  
c090: 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43  The [SQLITE_SYNC
c0a0: 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c  _DATAONLY].** fl
c0b0: 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64 20 69  ag may be ORed i
c0c0: 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68  n to indicate th
c0d0: 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61 74 61  at only the data
c0e0: 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20   of the file.** 
c0f0: 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64  and not its inod
c100: 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 79  e needs to be sy
c110: 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  nced..**.** The 
c120: 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 74  integer values t
c130: 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55  o xLock() and xU
c140: 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65 20  nlock() are one 
c150: 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  of.** <ul>.** <l
c160: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
c170: 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  NONE],.** <li> [
c180: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52  SQLITE_LOCK_SHAR
c190: 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  ED],.** <li> [SQ
c1a0: 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56  LITE_LOCK_RESERV
c1b0: 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  ED],.** <li> [SQ
c1c0: 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e  LITE_LOCK_PENDIN
c1d0: 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b  G], or.** <li> [
c1e0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c  SQLITE_LOCK_EXCL
c1f0: 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e  USIVE]..** </ul>
c200: 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72  .** xLock() incr
c210: 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20  eases the lock. 
c220: 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65 61  xUnlock() decrea
c230: 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a  ses the lock..**
c240: 20 54 68 65 20 78 43 68 65 63 6b 52 65 73 65 72   The xCheckReser
c250: 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64  vedLock() method
c260: 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20   checks whether 
c270: 61 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f 6e  any database con
c280: 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68  nection,.** eith
c290: 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f 63 65  er in this proce
c2a0: 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74  ss or in some ot
c2b0: 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69 73 20  her process, is 
c2c0: 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45 52 56  holding a RESERV
c2d0: 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20  ED,.** PENDING, 
c2e0: 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c 6f 63  or EXCLUSIVE loc
c2f0: 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20 20  k on the file.  
c300: 49 74 20 72 65 74 75 72 6e 73 20 74 72 75 65 0a  It returns true.
c310: 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c 6f 63  ** if such a loc
c320: 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66 61 6c  k exists and fal
c330: 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a  se otherwise..**
c340: 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43 6f 6e  .** The xFileCon
c350: 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69 73  trol() method is
c360: 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74 65 72   a generic inter
c370: 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f 77 73  face that allows
c380: 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69   custom.** VFS i
c390: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74  mplementations t
c3a0: 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e 74 72  o directly contr
c3b0: 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20  ol an open file 
c3c0: 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71  using the.** [sq
c3d0: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
c3e0: 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ol()] interface.
c3f0: 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22 6f 70    The second "op
c400: 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e  " argument is an
c410: 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70 63 6f  .** integer opco
c420: 64 65 2e 20 20 54 68 65 20 74 68 69 72 64 20 61  de.  The third a
c430: 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67 65 6e  rgument is a gen
c440: 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69 6e 74  eric pointer int
c450: 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e  ended to.** poin
c460: 74 20 74 6f 20 61 20 73 74 72 75 63 74 75 72 65  t to a structure
c470: 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 61 69   that may contai
c480: 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 73  n arguments or s
c490: 70 61 63 65 20 69 6e 20 77 68 69 63 68 20 74 6f  pace in which to
c4a0: 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75 72 6e  .** write return
c4b0: 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74   values.  Potent
c4c0: 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78 46 69  ial uses for xFi
c4d0: 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68  leControl() migh
c4e0: 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  t be.** function
c4f0: 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63  s to enable bloc
c500: 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68 20  king locks with 
c510: 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68 61  timeouts, to cha
c520: 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69  nge the.** locki
c530: 6e 67 20 73 74 72 61 74 65 67 79 20 28 66 6f 72  ng strategy (for
c540: 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 65 20   example to use 
c550: 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c  dot-file locks),
c560: 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61   to inquire.** a
c570: 62 6f 75 74 20 74 68 65 20 73 74 61 74 75 73 20  bout the status 
c580: 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f  of a lock, or to
c590: 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63   break stale loc
c5a0: 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74 65 0a  ks.  The SQLite.
c5b0: 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76 65 73  ** core reserves
c5c0: 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73   all opcodes les
c5d0: 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72 20 69  s than 100 for i
c5e0: 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41  ts own use..** A
c5f0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c   [SQLITE_FCNTL_L
c600: 4f 43 4b 53 54 41 54 45 20 7c 20 6c 69 73 74 20  OCKSTATE | list 
c610: 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73  of opcodes] less
c620: 20 74 68 61 6e 20 31 30 30 20 69 73 20 61 76 61   than 100 is ava
c630: 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69  ilable..** Appli
c640: 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64 65 66  cations that def
c650: 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 46 69  ine a custom xFi
c660: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
c670: 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f   should use opco
c680: 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 72 20 74  des.** greater t
c690: 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f 69 64  han 100 to avoid
c6a0: 20 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56 46 53   conflicts.  VFS
c6b0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
c6c0: 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72   should.** retur
c6d0: 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55  n [SQLITE_NOTFOU
c6e0: 4e 44 5d 20 66 6f 72 20 66 69 6c 65 20 63 6f 6e  ND] for file con
c6f0: 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74 68 61  trol opcodes tha
c700: 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a  t they do not.**
c710: 20 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a   recognize..**.*
c720: 2a 20 54 68 65 20 78 53 65 63 74 6f 72 53 69 7a  * The xSectorSiz
c730: 65 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72  e() method retur
c740: 6e 73 20 74 68 65 20 73 65 63 74 6f 72 20 73 69  ns the sector si
c750: 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76  ze of the.** dev
c760: 69 63 65 20 74 68 61 74 20 75 6e 64 65 72 6c 69  ice that underli
c770: 65 73 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68  es the file.  Th
c780: 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 69 73  e sector size is
c790: 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20   the.** minimum 
c7a0: 77 72 69 74 65 20 74 68 61 74 20 63 61 6e 20 62  write that can b
c7b0: 65 20 70 65 72 66 6f 72 6d 65 64 20 77 69 74 68  e performed with
c7c0: 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67 0a 2a  out disturbing.*
c7d0: 2a 20 6f 74 68 65 72 20 62 79 74 65 73 20 69 6e  * other bytes in
c7e0: 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20   the file.  The 
c7f0: 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72  xDeviceCharacter
c800: 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68  istics().** meth
c810: 6f 64 20 72 65 74 75 72 6e 73 20 61 20 62 69 74  od returns a bit
c820: 20 76 65 63 74 6f 72 20 64 65 73 63 72 69 62 69   vector describi
c830: 6e 67 20 62 65 68 61 76 69 6f 72 73 20 6f 66 20  ng behaviors of 
c840: 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e  the.** underlyin
c850: 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20  g device:.**.** 
c860: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  <ul>.** <li> [SQ
c870: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
c880: 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  C].** <li> [SQLI
c890: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35  TE_IOCAP_ATOMIC5
c8a0: 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  12].** <li> [SQL
c8b0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
c8c0: 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  1K].** <li> [SQL
c8d0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
c8e0: 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  2K].** <li> [SQL
c8f0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
c900: 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  4K].** <li> [SQL
c910: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
c920: 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  8K].** <li> [SQL
c930: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
c940: 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  16K].** <li> [SQ
c950: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
c960: 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C32K].** <li> [S
c970: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
c980: 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC64K].** <li> [
c990: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46  SQLITE_IOCAP_SAF
c9a0: 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69  E_APPEND].** <li
c9b0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
c9c0: 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c  SEQUENTIAL].** <
c9d0: 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53  /ul>.**.** The S
c9e0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
c9f0: 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  IC property mean
ca00: 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65  s that all write
ca10: 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65  s of.** any size
ca20: 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68   are atomic.  Th
ca30: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
ca40: 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a  TOMICnnn values.
ca50: 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69  ** mean that wri
ca60: 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68  tes of blocks th
ca70: 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73  at are nnn bytes
ca80: 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20   in size and.** 
ca90: 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61  are aligned to a
caa0: 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20  n address which 
cab0: 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75  is an integer mu
cac0: 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e  ltiple of.** nnn
cad0: 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68   are atomic.  Th
cae0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
caf0: 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65  AFE_APPEND value
cb00: 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77   means.** that w
cb10: 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65  hen data is appe
cb20: 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20  nded to a file, 
cb30: 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65  the data is appe
cb40: 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68  nded.** first th
cb50: 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  en the size of t
cb60: 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e  he file is exten
cb70: 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f  ded, never the o
cb80: 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75  ther.** way arou
cb90: 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  nd.  The SQLITE_
cba0: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c  IOCAP_SEQUENTIAL
cbb0: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20   property means 
cbc0: 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  that.** informat
cbd0: 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74  ion is written t
cbe0: 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61  o disk in the sa
cbf0: 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c  me order as call
cc00: 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29  s.** to xWrite()
cc10: 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 65 61 64  ..**.** If xRead
cc20: 28 29 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54  () returns SQLIT
cc30: 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45  E_IOERR_SHORT_RE
cc40: 41 44 20 69 74 20 6d 75 73 74 20 61 6c 73 6f 20  AD it must also 
cc50: 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 75  fill.** in the u
cc60: 6e 72 65 61 64 20 70 6f 72 74 69 6f 6e 73 20 6f  nread portions o
cc70: 66 20 74 68 65 20 62 75 66 66 65 72 20 77 69 74  f the buffer wit
cc80: 68 20 7a 65 72 6f 73 2e 20 20 41 20 56 46 53 20  h zeros.  A VFS 
cc90: 74 68 61 74 0a 2a 2a 20 66 61 69 6c 73 20 74 6f  that.** fails to
cca0: 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74   zero-fill short
ccb0: 20 72 65 61 64 73 20 6d 69 67 68 74 20 73 65 65   reads might see
ccc0: 6d 20 74 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 65  m to work.  Howe
ccd0: 76 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 20  ver,.** failure 
cce0: 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f  to zero-fill sho
ccf0: 72 74 20 72 65 61 64 73 20 77 69 6c 6c 20 65 76  rt reads will ev
cd00: 65 6e 74 75 61 6c 6c 79 20 6c 65 61 64 20 74 6f  entually lead to
cd10: 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 72  .** database cor
cd20: 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65  ruption..*/.type
cd30: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
cd40: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71  e3_io_methods sq
cd50: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
cd60: 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  ;.struct sqlite3
cd70: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20  _io_methods {.  
cd80: 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20  int iVersion;.  
cd90: 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 71  int (*xClose)(sq
cda0: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20  lite3_file*);.  
cdb0: 69 6e 74 20 28 2a 78 52 65 61 64 29 28 73 71 6c  int (*xRead)(sql
cdc0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64  ite3_file*, void
cdd0: 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c  *, int iAmt, sql
cde0: 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74  ite3_int64 iOfst
cdf0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72 69 74  );.  int (*xWrit
ce00: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
ce10: 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
ce20: 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33  nt iAmt, sqlite3
ce30: 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20  _int64 iOfst);. 
ce40: 20 69 6e 74 20 28 2a 78 54 72 75 6e 63 61 74 65   int (*xTruncate
ce50: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
ce60: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73   sqlite3_int64 s
ce70: 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  ize);.  int (*xS
ce80: 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ync)(sqlite3_fil
ce90: 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a  e*, int flags);.
cea0: 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a    int (*xFileSiz
ceb0: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
cec0: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
ced0: 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28  *pSize);.  int (
cee0: 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f  *xLock)(sqlite3_
cef0: 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69  file*, int);.  i
cf00: 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71  nt (*xUnlock)(sq
cf10: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
cf20: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68 65 63  );.  int (*xChec
cf30: 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 29 28 73  kReservedLock)(s
cf40: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
cf50: 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69  t *pResOut);.  i
cf60: 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f  nt (*xFileContro
cf70: 6c 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  l)(sqlite3_file*
cf80: 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a  , int op, void *
cf90: 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78  pArg);.  int (*x
cfa0: 53 65 63 74 6f 72 53 69 7a 65 29 28 73 71 6c 69  SectorSize)(sqli
cfb0: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e  te3_file*);.  in
cfc0: 74 20 28 2a 78 44 65 76 69 63 65 43 68 61 72 61  t (*xDeviceChara
cfd0: 63 74 65 72 69 73 74 69 63 73 29 28 73 71 6c 69  cteristics)(sqli
cfe0: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a  te3_file*);.  /*
cff0: 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61   Methods above a
d000: 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72  re valid for ver
d010: 73 69 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e 74 20  sion 1 */.  int 
d020: 28 2a 78 53 68 6d 4d 61 70 29 28 73 71 6c 69 74  (*xShmMap)(sqlit
d030: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 69 50  e3_file*, int iP
d040: 67 2c 20 69 6e 74 20 70 67 73 7a 2c 20 69 6e 74  g, int pgsz, int
d050: 2c 20 76 6f 69 64 20 76 6f 6c 61 74 69 6c 65 2a  , void volatile*
d060: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d  *);.  int (*xShm
d070: 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69  Lock)(sqlite3_fi
d080: 6c 65 2a 2c 20 69 6e 74 20 6f 66 66 73 65 74 2c  le*, int offset,
d090: 20 69 6e 74 20 6e 2c 20 69 6e 74 20 66 6c 61 67   int n, int flag
d0a0: 73 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 53 68  s);.  void (*xSh
d0b0: 6d 42 61 72 72 69 65 72 29 28 73 71 6c 69 74 65  mBarrier)(sqlite
d0c0: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20  3_file*);.  int 
d0d0: 28 2a 78 53 68 6d 55 6e 6d 61 70 29 28 73 71 6c  (*xShmUnmap)(sql
d0e0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
d0f0: 64 65 6c 65 74 65 46 6c 61 67 29 3b 0a 20 20 2f  deleteFlag);.  /
d100: 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  * Methods above 
d110: 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65  are valid for ve
d120: 72 73 69 6f 6e 20 32 20 2a 2f 0a 20 20 2f 2a 20  rsion 2 */.  /* 
d130: 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f  Additional metho
d140: 64 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  ds may be added 
d150: 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
d160: 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  es */.};../*.** 
d170: 43 41 50 49 33 52 45 46 3a 20 53 74 61 6e 64 61  CAPI3REF: Standa
d180: 72 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20  rd File Control 
d190: 4f 70 63 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68  Opcodes.**.** Th
d1a0: 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73  ese integer cons
d1b0: 74 61 6e 74 73 20 61 72 65 20 6f 70 63 6f 64 65  tants are opcode
d1c0: 73 20 66 6f 72 20 74 68 65 20 78 46 69 6c 65 43  s for the xFileC
d1d0: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a  ontrol method.**
d1e0: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
d1f0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
d200: 65 63 74 20 61 6e 64 20 66 6f 72 20 74 68 65 20  ect and for the 
d210: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
d220: 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65  ntrol()].** inte
d230: 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rface..**.** The
d240: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c   [SQLITE_FCNTL_L
d250: 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64 65  OCKSTATE] opcode
d260: 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65 62   is used for deb
d270: 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a  ugging.  This.**
d280: 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20 74   opcode causes t
d290: 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  he xFileControl 
d2a0: 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74 65 20  method to write 
d2b0: 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61 74  the current stat
d2c0: 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b  e of.** the lock
d2d0: 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45   (one of [SQLITE
d2e0: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51  _LOCK_NONE], [SQ
d2f0: 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44  LITE_LOCK_SHARED
d300: 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f  ],.** [SQLITE_LO
d310: 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b 53  CK_RESERVED], [S
d320: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49  QLITE_LOCK_PENDI
d330: 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  NG], or [SQLITE_
d340: 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 29  LOCK_EXCLUSIVE])
d350: 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74 65  .** into an inte
d360: 67 65 72 20 74 68 61 74 20 74 68 65 20 70 41 72  ger that the pAr
d370: 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74  g argument point
d380: 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70 61 62  s to. This capab
d390: 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73 65 64  ility.** is used
d3a0: 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20   during testing 
d3b0: 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74  and only needs t
d3c0: 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 20 77  o be supported w
d3d0: 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 54 0a  hen SQLITE_TEST.
d3e0: 2a 2a 20 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a  ** is defined..*
d3f0: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 5b 5b  * <ul>.** <li>[[
d400: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a  SQLITE_FCNTL_SIZ
d410: 45 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 54 68 65 20  E_HINT]].** The 
d420: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49  [SQLITE_FCNTL_SI
d430: 5a 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65 20  ZE_HINT] opcode 
d440: 69 73 20 75 73 65 64 20 62 79 20 53 51 4c 69 74  is used by SQLit
d450: 65 20 74 6f 20 67 69 76 65 20 74 68 65 20 56 46  e to give the VF
d460: 53 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68 69 6e  S.** layer a hin
d470: 74 20 6f 66 20 68 6f 77 20 6c 61 72 67 65 20 74  t of how large t
d480: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
d490: 20 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62 65   will grow to be
d4a0: 20 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20 63   during the.** c
d4b0: 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74 69  urrent transacti
d4c0: 6f 6e 2e 20 20 54 68 69 73 20 68 69 6e 74 20 69  on.  This hint i
d4d0: 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 64  s not guaranteed
d4e0: 20 74 6f 20 62 65 20 61 63 63 75 72 61 74 65 20   to be accurate 
d4f0: 62 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66 74  but it.** is oft
d500: 65 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65 20 75  en close.  The u
d510: 6e 64 65 72 6c 79 69 6e 67 20 56 46 53 20 6d 69  nderlying VFS mi
d520: 67 68 74 20 63 68 6f 6f 73 65 20 74 6f 20 70 72  ght choose to pr
d530: 65 61 6c 6c 6f 63 61 74 65 20 64 61 74 61 62 61  eallocate databa
d540: 73 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63 65  se.** file space
d550: 20 62 61 73 65 64 20 6f 6e 20 74 68 69 73 20 68   based on this h
d560: 69 6e 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  int in order to 
d570: 68 65 6c 70 20 77 72 69 74 65 73 20 74 6f 20 74  help writes to t
d580: 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66  he database.** f
d590: 69 6c 65 20 72 75 6e 20 66 61 73 74 65 72 2e 0a  ile run faster..
d5a0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
d5b0: 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53  TE_FCNTL_CHUNK_S
d5c0: 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  IZE]].** The [SQ
d5d0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b  LITE_FCNTL_CHUNK
d5e0: 5f 53 49 5a 45 5d 20 6f 70 63 6f 64 65 20 69 73  _SIZE] opcode is
d5f0: 20 75 73 65 64 20 74 6f 20 72 65 71 75 65 73 74   used to request
d600: 20 74 68 61 74 20 74 68 65 20 56 46 53 0a 2a 2a   that the VFS.**
d610: 20 65 78 74 65 6e 64 73 20 61 6e 64 20 74 72 75   extends and tru
d620: 6e 63 61 74 65 73 20 74 68 65 20 64 61 74 61 62  ncates the datab
d630: 61 73 65 20 66 69 6c 65 20 69 6e 20 63 68 75 6e  ase file in chun
d640: 6b 73 20 6f 66 20 61 20 73 69 7a 65 20 73 70 65  ks of a size spe
d650: 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65  cified.** by the
d660: 20 75 73 65 72 2e 20 54 68 65 20 66 6f 75 72 74   user. The fourt
d670: 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73  h argument to [s
d680: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
d690: 72 6f 6c 28 29 5d 20 73 68 6f 75 6c 64 20 0a 2a  rol()] should .*
d6a0: 2a 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 69 6e  * point to an in
d6b0: 74 65 67 65 72 20 28 74 79 70 65 20 69 6e 74 29  teger (type int)
d6c0: 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
d6d0: 6e 65 77 20 63 68 75 6e 6b 2d 73 69 7a 65 20 74  new chunk-size t
d6e0: 6f 20 75 73 65 0a 2a 2a 20 66 6f 72 20 74 68 65  o use.** for the
d6f0: 20 6e 6f 6d 69 6e 61 74 65 64 20 64 61 74 61 62   nominated datab
d700: 61 73 65 2e 20 41 6c 6c 6f 63 61 74 69 6e 67 20  ase. Allocating 
d710: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 73 70  database file sp
d720: 61 63 65 20 69 6e 20 6c 61 72 67 65 0a 2a 2a 20  ace in large.** 
d730: 63 68 75 6e 6b 73 20 28 73 61 79 20 31 4d 42 20  chunks (say 1MB 
d740: 61 74 20 61 20 74 69 6d 65 29 2c 20 6d 61 79 20  at a time), may 
d750: 72 65 64 75 63 65 20 66 69 6c 65 2d 73 79 73 74  reduce file-syst
d760: 65 6d 20 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e  em fragmentation
d770: 20 61 6e 64 0a 2a 2a 20 69 6d 70 72 6f 76 65 20   and.** improve 
d780: 70 65 72 66 6f 72 6d 61 6e 63 65 20 6f 6e 20 73  performance on s
d790: 6f 6d 65 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 0a  ome systems..**.
d7a0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
d7b0: 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54  FCNTL_FILE_POINT
d7c0: 45 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ER]].** The [SQL
d7d0: 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50  ITE_FCNTL_FILE_P
d7e0: 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 69  OINTER] opcode i
d7f0: 73 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e  s used to obtain
d800: 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f   a pointer.** to
d810: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   the [sqlite3_fi
d820: 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f 63  le] object assoc
d830: 69 61 74 65 64 20 77 69 74 68 20 61 20 70 61 72  iated with a par
d840: 74 69 63 75 6c 61 72 20 64 61 74 61 62 61 73 65  ticular database
d850: 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  .** connection. 
d860: 20 53 65 65 20 74 68 65 20 5b 73 71 6c 69 74 65   See the [sqlite
d870: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
d880: 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20  ] documentation 
d890: 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61  for.** additiona
d8a0: 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  l information..*
d8b0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
d8c0: 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49  E_FCNTL_SYNC_OMI
d8d0: 54 54 45 44 5d 5d 0a 2a 2a 20 5e 28 54 68 65 20  TTED]].** ^(The 
d8e0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59  [SQLITE_FCNTL_SY
d8f0: 4e 43 5f 4f 4d 49 54 54 45 44 5d 20 6f 70 63 6f  NC_OMITTED] opco
d900: 64 65 20 69 73 20 67 65 6e 65 72 61 74 65 64 20  de is generated 
d910: 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 0a 2a 2a  internally by.**
d920: 20 53 51 4c 69 74 65 20 61 6e 64 20 73 65 6e 74   SQLite and sent
d930: 20 74 6f 20 61 6c 6c 20 56 46 53 65 73 20 69 6e   to all VFSes in
d940: 20 70 6c 61 63 65 20 6f 66 20 61 20 63 61 6c 6c   place of a call
d950: 20 74 6f 20 74 68 65 20 78 53 79 6e 63 20 6d 65   to the xSync me
d960: 74 68 6f 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65  thod.** when the
d970: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
d980: 74 69 6f 6e 20 68 61 73 20 5b 50 52 41 47 4d 41  tion has [PRAGMA
d990: 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 20 73 65   synchronous] se
d9a0: 74 20 74 6f 20 4f 46 46 2e 29 5e 0a 2a 2a 20 53  t to OFF.)^.** S
d9b0: 6f 6d 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20  ome specialized 
d9c0: 56 46 53 65 73 20 6e 65 65 64 20 74 68 69 73 20  VFSes need this 
d9d0: 73 69 67 6e 61 6c 20 69 6e 20 6f 72 64 65 72 20  signal in order 
d9e0: 74 6f 20 6f 70 65 72 61 74 65 20 63 6f 72 72 65  to operate corre
d9f0: 63 74 6c 79 0a 2a 2a 20 77 68 65 6e 20 5b 50 52  ctly.** when [PR
da00: 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73  AGMA synchronous
da10: 20 7c 20 50 52 41 47 4d 41 20 73 79 6e 63 68 72   | PRAGMA synchr
da20: 6f 6e 6f 75 73 3d 4f 46 46 5d 20 69 73 20 73 65  onous=OFF] is se
da30: 74 2c 20 62 75 74 20 6d 6f 73 74 20 0a 2a 2a 20  t, but most .** 
da40: 56 46 53 65 73 20 64 6f 20 6e 6f 74 20 6e 65 65  VFSes do not nee
da50: 64 20 74 68 69 73 20 73 69 67 6e 61 6c 20 61 6e  d this signal an
da60: 64 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c  d should silentl
da70: 79 20 69 67 6e 6f 72 65 20 74 68 69 73 20 6f 70  y ignore this op
da80: 63 6f 64 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61  code..** Applica
da90: 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74  tions should not
daa0: 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66   call [sqlite3_f
dab0: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77  ile_control()] w
dac0: 69 74 68 20 74 68 69 73 0a 2a 2a 20 6f 70 63 6f  ith this.** opco
dad0: 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d  de as doing so m
dae0: 61 79 20 64 69 73 72 75 70 74 20 74 68 65 20 6f  ay disrupt the o
daf0: 70 65 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  peration of the 
db00: 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65  specialized VFSe
db10: 73 0a 2a 2a 20 74 68 61 74 20 64 6f 20 72 65 71  s.** that do req
db20: 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a  uire it.  .**.**
db30: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
db40: 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54  NTL_WIN32_AV_RET
db50: 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  RY]].** ^The [SQ
db60: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32  LITE_FCNTL_WIN32
db70: 5f 41 56 5f 52 45 54 52 59 5d 20 6f 70 63 6f 64  _AV_RETRY] opcod
db80: 65 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f 6e  e is used to con
db90: 66 69 67 75 72 65 20 61 75 74 6f 6d 61 74 69 63  figure automatic
dba0: 0a 2a 2a 20 72 65 74 72 79 20 63 6f 75 6e 74 73  .** retry counts
dbb0: 20 61 6e 64 20 69 6e 74 65 72 76 61 6c 73 20 66   and intervals f
dbc0: 6f 72 20 63 65 72 74 61 69 6e 20 64 69 73 6b 20  or certain disk 
dbd0: 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 66  I/O operations f
dbe0: 6f 72 20 74 68 65 0a 2a 2a 20 77 69 6e 64 6f 77  or the.** window
dbf0: 73 20 5b 56 46 53 5d 20 69 6e 20 6f 72 64 65 72  s [VFS] in order
dc00: 20 74 6f 20 70 72 6f 76 69 64 65 20 72 6f 62 75   to provide robu
dc10: 73 74 6e 65 73 73 20 69 6e 20 74 68 65 20 70 72  stness in the pr
dc20: 65 73 65 6e 63 65 20 6f 66 0a 2a 2a 20 61 6e 74  esence of.** ant
dc30: 69 2d 76 69 72 75 73 20 70 72 6f 67 72 61 6d 73  i-virus programs
dc40: 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c 20 74  .  By default, t
dc50: 68 65 20 77 69 6e 64 6f 77 73 20 56 46 53 20 77  he windows VFS w
dc60: 69 6c 6c 20 72 65 74 72 79 20 66 69 6c 65 20 72  ill retry file r
dc70: 65 61 64 2c 0a 2a 2a 20 66 69 6c 65 20 77 72 69  ead,.** file wri
dc80: 74 65 2c 20 61 6e 64 20 66 69 6c 65 20 64 65 6c  te, and file del
dc90: 65 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20 75  ete operations u
dca0: 70 20 74 6f 20 31 30 20 74 69 6d 65 73 2c 20 77  p to 10 times, w
dcb0: 69 74 68 20 61 20 64 65 6c 61 79 0a 2a 2a 20 6f  ith a delay.** o
dcc0: 66 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  f 25 millisecond
dcd0: 73 20 62 65 66 6f 72 65 20 74 68 65 20 66 69 72  s before the fir
dce0: 73 74 20 72 65 74 72 79 20 61 6e 64 20 77 69 74  st retry and wit
dcf0: 68 20 74 68 65 20 64 65 6c 61 79 20 69 6e 63 72  h the delay incr
dd00: 65 61 73 69 6e 67 0a 2a 2a 20 62 79 20 61 6e 20  easing.** by an 
dd10: 61 64 64 69 74 69 6f 6e 61 6c 20 32 35 20 6d 69  additional 25 mi
dd20: 6c 6c 69 73 65 63 6f 6e 64 73 20 77 69 74 68 20  lliseconds with 
dd30: 65 61 63 68 20 73 75 62 73 65 71 75 65 6e 74 20  each subsequent 
dd40: 72 65 74 72 79 2e 20 20 54 68 69 73 0a 2a 2a 20  retry.  This.** 
dd50: 6f 70 63 6f 64 65 20 61 6c 6c 6f 77 73 20 74 68  opcode allows th
dd60: 65 73 65 20 74 77 6f 20 76 61 6c 75 65 73 20 28  ese two values (
dd70: 31 30 20 72 65 74 72 69 65 73 20 61 6e 64 20 32  10 retries and 2
dd80: 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f  5 milliseconds o
dd90: 66 20 64 65 6c 61 79 29 0a 2a 2a 20 74 6f 20 62  f delay).** to b
dda0: 65 20 61 64 6a 75 73 74 65 64 2e 20 20 54 68 65  e adjusted.  The
ddb0: 20 76 61 6c 75 65 73 20 61 72 65 20 63 68 61 6e   values are chan
ddc0: 67 65 64 20 66 6f 72 20 61 6c 6c 20 64 61 74 61  ged for all data
ddd0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
dde0: 0a 2a 2a 20 77 69 74 68 69 6e 20 74 68 65 20 73  .** within the s
ddf0: 61 6d 65 20 70 72 6f 63 65 73 73 2e 20 20 54 68  ame process.  Th
de00: 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  e argument is a 
de10: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 61 72  pointer to an ar
de20: 72 61 79 20 6f 66 20 74 77 6f 0a 2a 2a 20 69 6e  ray of two.** in
de30: 74 65 67 65 72 73 20 77 68 65 72 65 20 74 68 65  tegers where the
de40: 20 66 69 72 73 74 20 69 6e 74 65 67 65 72 20 69   first integer i
de50: 20 74 68 65 20 6e 65 77 20 72 65 74 72 79 20 63   the new retry c
de60: 6f 75 6e 74 20 61 6e 64 20 74 68 65 20 73 65 63  ount and the sec
de70: 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 69  ond.** integer i
de80: 73 20 74 68 65 20 64 65 6c 61 79 2e 20 20 49 66  s the delay.  If
de90: 20 65 69 74 68 65 72 20 69 6e 74 65 67 65 72 20   either integer 
dea0: 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65  is negative, the
deb0: 6e 20 74 68 65 20 73 65 74 74 69 6e 67 0a 2a 2a  n the setting.**
dec0: 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 20   is not changed 
ded0: 62 75 74 20 69 6e 73 74 65 61 64 20 74 68 65 20  but instead the 
dee0: 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 74  prior value of t
def0: 68 61 74 20 73 65 74 74 69 6e 67 20 69 73 20 77  hat setting is w
df00: 72 69 74 74 65 6e 0a 2a 2a 20 69 6e 74 6f 20 74  ritten.** into t
df10: 68 65 20 61 72 72 61 79 20 65 6e 74 72 79 2c 20  he array entry, 
df20: 61 6c 6c 6f 77 69 6e 67 20 74 68 65 20 63 75 72  allowing the cur
df30: 72 65 6e 74 20 72 65 74 72 79 20 73 65 74 74 69  rent retry setti
df40: 6e 67 73 20 74 6f 20 62 65 0a 2a 2a 20 69 6e 74  ngs to be.** int
df50: 65 72 72 6f 67 61 74 65 64 2e 20 20 54 68 65 20  errogated.  The 
df60: 7a 44 62 4e 61 6d 65 20 70 61 72 61 6d 65 74 65  zDbName paramete
df70: 72 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a  r is ignored..**
df80: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
df90: 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57  _FCNTL_PERSIST_W
dfa0: 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  AL]].** ^The [SQ
dfb0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49  LITE_FCNTL_PERSI
dfc0: 53 54 5f 57 41 4c 5d 20 6f 70 63 6f 64 65 20 69  ST_WAL] opcode i
dfd0: 73 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f 72  s used to set or
dfe0: 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 70 65   query the.** pe
dff0: 72 73 69 73 74 65 6e 74 20 5b 57 41 4c 20 7c 20  rsistent [WAL | 
e000: 57 72 69 74 65 20 41 68 65 61 64 20 4c 6f 67 5d  Write Ahead Log]
e010: 20 73 65 74 74 69 6e 67 2e 20 20 42 79 20 64 65   setting.  By de
e020: 66 61 75 6c 74 2c 20 74 68 65 20 61 75 78 69 6c  fault, the auxil
e030: 69 61 72 79 0a 2a 2a 20 77 72 69 74 65 20 61 68  iary.** write ah
e040: 65 61 64 20 6c 6f 67 20 61 6e 64 20 73 68 61 72  ead log and shar
e050: 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20  ed memory files 
e060: 75 73 65 64 20 66 6f 72 20 74 72 61 6e 73 61 63  used for transac
e070: 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20  tion control.** 
e080: 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  are automaticall
e090: 79 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 74  y deleted when t
e0a0: 68 65 20 6c 61 74 65 73 74 20 63 6f 6e 6e 65 63  he latest connec
e0b0: 74 69 6f 6e 20 74 6f 20 74 68 65 20 64 61 74 61  tion to the data
e0c0: 62 61 73 65 0a 2a 2a 20 63 6c 6f 73 65 73 2e 20  base.** closes. 
e0d0: 20 53 65 74 74 69 6e 67 20 70 65 72 73 69 73 74   Setting persist
e0e0: 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 63 61 75  ent WAL mode cau
e0f0: 73 65 73 20 74 68 6f 73 65 20 66 69 6c 65 73 20  ses those files 
e100: 74 6f 20 70 65 72 73 69 73 74 20 61 66 74 65 72  to persist after
e110: 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20 50 65 72 73  .** close.  Pers
e120: 69 73 74 69 6e 67 20 74 68 65 20 66 69 6c 65 73  isting the files
e130: 20 69 73 20 75 73 65 66 75 6c 20 77 68 65 6e 20   is useful when 
e140: 6f 74 68 65 72 20 70 72 6f 63 65 73 73 65 73 20  other processes 
e150: 74 68 61 74 20 64 6f 20 6e 6f 74 0a 2a 2a 20 68  that do not.** h
e160: 61 76 65 20 77 72 69 74 65 20 70 65 72 6d 69 73  ave write permis
e170: 73 69 6f 6e 20 6f 6e 20 74 68 65 20 64 69 72 65  sion on the dire
e180: 63 74 6f 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67  ctory containing
e190: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
e1a0: 6c 65 20 77 61 6e 74 0a 2a 2a 20 74 6f 20 72 65  le want.** to re
e1b0: 61 64 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ad the database 
e1c0: 66 69 6c 65 2c 20 61 73 20 74 68 65 20 57 41 4c  file, as the WAL
e1d0: 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d 6f   and shared memo
e1e0: 72 79 20 66 69 6c 65 73 20 6d 75 73 74 20 65 78  ry files must ex
e1f0: 69 73 74 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20  ist.** in order 
e200: 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 73 65  for the database
e210: 20 74 6f 20 62 65 20 72 65 61 64 61 62 6c 65 2e   to be readable.
e220: 20 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72    The fourth par
e230: 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71  ameter to.** [sq
e240: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
e250: 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20 6f  ol()] for this o
e260: 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65 20  pcode should be 
e270: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
e280: 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74  integer..** That
e290: 20 69 6e 74 65 67 65 72 20 69 73 20 30 20 74 6f   integer is 0 to
e2a0: 20 64 69 73 61 62 6c 65 20 70 65 72 73 69 73 74   disable persist
e2b0: 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 6f 72 20  ent WAL mode or 
e2c0: 31 20 74 6f 20 65 6e 61 62 6c 65 20 70 65 72 73  1 to enable pers
e2d0: 69 73 74 65 6e 74 0a 2a 2a 20 57 41 4c 20 6d 6f  istent.** WAL mo
e2e0: 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74 65  de.  If the inte
e2f0: 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20  ger is -1, then 
e300: 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 74 65  it is overwritte
e310: 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65  n with the curre
e320: 6e 74 0a 2a 2a 20 57 41 4c 20 70 65 72 73 69 73  nt.** WAL persis
e330: 74 65 6e 63 65 20 73 65 74 74 69 6e 67 2e 0a 2a  tence setting..*
e340: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
e350: 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46  E_FCNTL_POWERSAF
e360: 45 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a  E_OVERWRITE]].**
e370: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43   ^The [SQLITE_FC
e380: 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56  NTL_POWERSAFE_OV
e390: 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20  ERWRITE] opcode 
e3a0: 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f  is used to set o
e3b0: 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 70  r query the.** p
e3c0: 65 72 73 69 73 74 65 6e 74 20 22 70 6f 77 65 72  ersistent "power
e3d0: 73 61 66 65 2d 6f 76 65 72 77 72 69 74 65 22 20  safe-overwrite" 
e3e0: 6f 72 20 22 50 53 4f 57 22 20 73 65 74 74 69 6e  or "PSOW" settin
e3f0: 67 2e 20 20 54 68 65 20 50 53 4f 57 20 73 65 74  g.  The PSOW set
e400: 74 69 6e 67 0a 2a 2a 20 64 65 74 65 72 6d 69 6e  ting.** determin
e410: 65 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 49  es the [SQLITE_I
e420: 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f  OCAP_POWERSAFE_O
e430: 56 45 52 57 52 49 54 45 5d 20 62 69 74 20 6f 66  VERWRITE] bit of
e440: 20 74 68 65 0a 2a 2a 20 78 44 65 76 69 63 65 43   the.** xDeviceC
e450: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6d  haracteristics m
e460: 65 74 68 6f 64 73 2e 20 54 68 65 20 66 6f 75 72  ethods. The four
e470: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  th parameter to.
e480: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
e490: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20  _control()] for 
e4a0: 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68 6f 75  this opcode shou
e4b0: 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20  ld be a pointer 
e4c0: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a  to an integer..*
e4d0: 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72 20 69  * That integer i
e4e0: 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 7a  s 0 to disable z
e4f0: 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20  ero-damage mode 
e500: 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 7a  or 1 to enable z
e510: 65 72 6f 2d 64 61 6d 61 67 65 0a 2a 2a 20 6d 6f  ero-damage.** mo
e520: 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74 65  de.  If the inte
e530: 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20  ger is -1, then 
e540: 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 74 65  it is overwritte
e550: 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65  n with the curre
e560: 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64 61 6d 61 67  nt.** zero-damag
e570: 65 20 6d 6f 64 65 20 73 65 74 74 69 6e 67 2e 0a  e mode setting..
e580: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
e590: 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49  TE_FCNTL_OVERWRI
e5a0: 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  TE]].** ^The [SQ
e5b0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57  LITE_FCNTL_OVERW
e5c0: 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20  RITE] opcode is 
e5d0: 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c 69 74  invoked by SQLit
e5e0: 65 20 61 66 74 65 72 20 6f 70 65 6e 69 6e 67 0a  e after opening.
e5f0: 2a 2a 20 61 20 77 72 69 74 65 20 74 72 61 6e 73  ** a write trans
e600: 61 63 74 69 6f 6e 20 74 6f 20 69 6e 64 69 63 61  action to indica
e610: 74 65 20 74 68 61 74 2c 20 75 6e 6c 65 73 73 20  te that, unless 
e620: 69 74 20 69 73 20 72 6f 6c 6c 65 64 20 62 61 63  it is rolled bac
e630: 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a 2a 20 72 65  k for some.** re
e640: 61 73 6f 6e 2c 20 74 68 65 20 65 6e 74 69 72 65  ason, the entire
e650: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77   database file w
e660: 69 6c 6c 20 62 65 20 6f 76 65 72 77 72 69 74 74  ill be overwritt
e670: 65 6e 20 62 79 20 74 68 65 20 63 75 72 72 65 6e  en by the curren
e680: 74 20 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f  t .** transactio
e690: 6e 2e 20 54 68 69 73 20 69 73 20 75 73 65 64 20  n. This is used 
e6a0: 62 79 20 56 41 43 55 55 4d 20 6f 70 65 72 61 74  by VACUUM operat
e6b0: 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  ions..**.** <li>
e6c0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56  [[SQLITE_FCNTL_V
e6d0: 46 53 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 54 68 65  FSNAME]].** ^The
e6e0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56   [SQLITE_FCNTL_V
e6f0: 46 53 4e 41 4d 45 5d 20 6f 70 63 6f 64 65 20 63  FSNAME] opcode c
e700: 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62  an be used to ob
e710: 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f  tain the names o
e720: 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46 53 65 73 5d  f.** all [VFSes]
e730: 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 61 63   in the VFS stac
e740: 6b 2e 20 20 54 68 65 20 6e 61 6d 65 73 20 61 72  k.  The names ar
e750: 65 20 6f 66 20 61 6c 6c 20 56 46 53 20 73 68 69  e of all VFS shi
e760: 6d 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20 66 69  ms and the.** fi
e770: 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c 65 76 65 6c  nal bottom-level
e780: 20 56 46 53 20 61 72 65 20 77 72 69 74 74 65 6e   VFS are written
e790: 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74   into memory obt
e7a0: 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b  ained from .** [
e7b0: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
e7c0: 5d 20 61 6e 64 20 74 68 65 20 72 65 73 75 6c 74  ] and the result
e7d0: 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 74 68   is stored in th
e7e0: 65 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c 65  e char* variable
e7f0: 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 66 6f 75  .** that the fou
e800: 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f 66  rth parameter of
e810: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
e820: 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f 69 6e 74 73  ontrol()] points
e830: 20 74 6f 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c   to..** The call
e840: 65 72 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c  er is responsibl
e850: 65 20 66 6f 72 20 66 72 65 65 69 6e 67 20 74 68  e for freeing th
e860: 65 20 6d 65 6d 6f 72 79 20 77 68 65 6e 20 64 6f  e memory when do
e870: 6e 65 2e 20 20 41 73 20 77 69 74 68 0a 2a 2a 20  ne.  As with.** 
e880: 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c  all file-control
e890: 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 72 65 20   actions, there 
e8a0: 69 73 20 6e 6f 20 67 75 61 72 61 6e 74 65 65 20  is no guarantee 
e8b0: 74 68 61 74 20 74 68 69 73 20 77 69 6c 6c 20 61  that this will a
e8c0: 63 74 75 61 6c 6c 79 0a 2a 2a 20 64 6f 20 61 6e  ctually.** do an
e8d0: 79 74 68 69 6e 67 2e 20 20 43 61 6c 6c 65 72 73  ything.  Callers
e8e0: 20 73 68 6f 75 6c 64 20 69 6e 69 74 69 61 6c 69   should initiali
e8f0: 7a 65 20 74 68 65 20 63 68 61 72 2a 20 76 61 72  ze the char* var
e900: 69 61 62 6c 65 20 74 6f 20 61 20 4e 55 4c 4c 0a  iable to a NULL.
e910: 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 20 63 61  ** pointer in ca
e920: 73 65 20 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e  se this file-con
e930: 74 72 6f 6c 20 69 73 20 6e 6f 74 20 69 6d 70 6c  trol is not impl
e940: 65 6d 65 6e 74 65 64 2e 20 20 54 68 69 73 20 66  emented.  This f
e950: 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 69  ile-control.** i
e960: 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 64  s intended for d
e970: 69 61 67 6e 6f 73 74 69 63 20 75 73 65 20 6f 6e  iagnostic use on
e980: 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ly..**.** <li>[[
e990: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
e9a0: 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68 65 6e 65 76  GMA]].** ^Whenev
e9b0: 65 72 20 61 20 5b 50 52 41 47 4d 41 5d 20 73 74  er a [PRAGMA] st
e9c0: 61 74 65 6d 65 6e 74 20 69 73 20 70 61 72 73 65  atement is parse
e9d0: 64 2c 20 61 6e 20 5b 53 51 4c 49 54 45 5f 46 43  d, an [SQLITE_FC
e9e0: 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 0a 2a 2a 20  NTL_PRAGMA] .** 
e9f0: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20  file control is 
ea00: 73 65 6e 74 20 74 6f 20 74 68 65 20 6f 70 65 6e  sent to the open
ea10: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
ea20: 6f 62 6a 65 63 74 20 63 6f 72 72 65 73 70 6f 6e  object correspon
ea30: 64 69 6e 67 0a 2a 2a 20 74 6f 20 74 68 65 20 64  ding.** to the d
ea40: 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 6f 20  atabase file to 
ea50: 77 68 69 63 68 20 74 68 65 20 70 72 61 67 6d 61  which the pragma
ea60: 20 73 74 61 74 65 6d 65 6e 74 20 72 65 66 65 72   statement refer
ea70: 73 2e 20 5e 54 68 65 20 61 72 67 75 6d 65 6e 74  s. ^The argument
ea80: 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 53 51 4c 49  .** to the [SQLI
ea90: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
eaa0: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73   file control is
eab0: 20 61 6e 20 61 72 72 61 79 20 6f 66 0a 2a 2a 20   an array of.** 
eac0: 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69  pointers to stri
ead0: 6e 67 73 20 28 63 68 61 72 2a 2a 29 20 69 6e 20  ngs (char**) in 
eae0: 77 68 69 63 68 20 74 68 65 20 73 65 63 6f 6e 64  which the second
eaf0: 20 65 6c 65 6d 65 6e 74 20 6f 66 20 74 68 65 20   element of the 
eb00: 61 72 72 61 79 0a 2a 2a 20 69 73 20 74 68 65 20  array.** is the 
eb10: 6e 61 6d 65 20 6f 66 20 74 68 65 20 70 72 61 67  name of the prag
eb20: 6d 61 20 61 6e 64 20 74 68 65 20 74 68 69 72 64  ma and the third
eb30: 20 65 6c 65 6d 65 6e 74 20 69 73 20 74 68 65 20   element is the 
eb40: 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 0a  argument to the.
eb50: 2a 2a 20 70 72 61 67 6d 61 20 6f 72 20 4e 55 4c  ** pragma or NUL
eb60: 4c 20 69 66 20 74 68 65 20 70 72 61 67 6d 61 20  L if the pragma 
eb70: 68 61 73 20 6e 6f 20 61 72 67 75 6d 65 6e 74 2e  has no argument.
eb80: 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 20 66    ^The handler f
eb90: 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45  or an.** [SQLITE
eba0: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66  _FCNTL_PRAGMA] f
ebb0: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 63 61 6e 20  ile control can 
ebc0: 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d 61 6b 65 20  optionally make 
ebd0: 74 68 65 20 66 69 72 73 74 20 65 6c 65 6d 65 6e  the first elemen
ebe0: 74 0a 2a 2a 20 6f 66 20 74 68 65 20 63 68 61 72  t.** of the char
ebf0: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e  ** argument poin
ec00: 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6f 62  t to a string ob
ec10: 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
ec20: 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d 0a  ite3_mprintf()].
ec30: 2a 2a 20 6f 72 20 74 68 65 20 65 71 75 69 76 61  ** or the equiva
ec40: 6c 65 6e 74 20 61 6e 64 20 74 68 61 74 20 73 74  lent and that st
ec50: 72 69 6e 67 20 77 69 6c 6c 20 62 65 63 6f 6d 65  ring will become
ec60: 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20 74   the result of t
ec70: 68 65 20 70 72 61 67 6d 61 20 6f 72 0a 2a 2a 20  he pragma or.** 
ec80: 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
ec90: 65 20 69 66 20 74 68 65 20 70 72 61 67 6d 61 20  e if the pragma 
eca0: 66 61 69 6c 73 2e 20 5e 49 66 20 74 68 65 0a 2a  fails. ^If the.*
ecb0: 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  * [SQLITE_FCNTL_
ecc0: 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e  PRAGMA] file con
ecd0: 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53 51  trol returns [SQ
ece0: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20  LITE_NOTFOUND], 
ecf0: 74 68 65 6e 20 6e 6f 72 6d 61 6c 20 0a 2a 2a 20  then normal .** 
ed00: 5b 50 52 41 47 4d 41 5d 20 70 72 6f 63 65 73 73  [PRAGMA] process
ed10: 69 6e 67 20 63 6f 6e 74 69 6e 75 65 73 2e 20 20  ing continues.  
ed20: 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ^If the [SQLITE_
ed30: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a  FCNTL_PRAGMA].**
ed40: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65   file control re
ed50: 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
ed60: 5d 2c 20 74 68 65 6e 20 74 68 65 20 70 61 72 73  ], then the pars
ed70: 65 72 20 61 73 73 75 6d 65 73 20 74 68 61 74 20  er assumes that 
ed80: 74 68 65 0a 2a 2a 20 56 46 53 20 68 61 73 20 68  the.** VFS has h
ed90: 61 6e 64 6c 65 64 20 74 68 65 20 50 52 41 47 4d  andled the PRAGM
eda0: 41 20 69 74 73 65 6c 66 20 61 6e 64 20 74 68 65  A itself and the
edb0: 20 70 61 72 73 65 72 20 67 65 6e 65 72 61 74 65   parser generate
edc0: 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a 20 70 72 65  s a no-op.** pre
edd0: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 2e  pared statement.
ede0: 20 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54    ^If the [SQLIT
edf0: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20  E_FCNTL_PRAGMA] 
ee00: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74  file control ret
ee10: 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 72 65 73 75  urns.** any resu
ee20: 6c 74 20 63 6f 64 65 20 6f 74 68 65 72 20 74 68  lt code other th
ee30: 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  an [SQLITE_OK] o
ee40: 72 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55  r [SQLITE_NOTFOU
ee50: 4e 44 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a  ND], that means.
ee60: 2a 2a 20 74 68 61 74 20 74 68 65 20 56 46 53 20  ** that the VFS 
ee70: 65 6e 63 6f 75 6e 74 65 72 65 64 20 61 6e 20 65  encountered an e
ee80: 72 72 6f 72 20 77 68 69 6c 65 20 68 61 6e 64 6c  rror while handl
ee90: 69 6e 67 20 74 68 65 20 5b 50 52 41 47 4d 41 5d  ing the [PRAGMA]
eea0: 20 61 6e 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70   and the.** comp
eeb0: 69 6c 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 50  ilation of the P
eec0: 52 41 47 4d 41 20 66 61 69 6c 73 20 77 69 74 68  RAGMA fails with
eed0: 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 54 68 65   an error.  ^The
eee0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
eef0: 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63  RAGMA].** file c
ef00: 6f 6e 74 72 6f 6c 20 6f 63 63 75 72 73 20 61 74  ontrol occurs at
ef10: 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f   the beginning o
ef20: 66 20 70 72 61 67 6d 61 20 73 74 61 74 65 6d 65  f pragma stateme
ef30: 6e 74 20 61 6e 61 6c 79 73 69 73 20 61 6e 64 20  nt analysis and 
ef40: 73 6f 0a 2a 2a 20 69 74 20 69 73 20 61 62 6c 65  so.** it is able
ef50: 20 74 6f 20 6f 76 65 72 72 69 64 65 20 62 75 69   to override bui
ef60: 6c 74 2d 69 6e 20 5b 50 52 41 47 4d 41 5d 20 73  lt-in [PRAGMA] s
ef70: 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  tatements..**.**
ef80: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
ef90: 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d  NTL_BUSYHANDLER]
efa0: 5d 0a 2a 2a 20 5e 54 68 69 73 20 66 69 6c 65 2d  ].** ^This file-
efb0: 63 6f 6e 74 72 6f 6c 20 6d 61 79 20 62 65 20 69  control may be i
efc0: 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c 69 74 65  nvoked by SQLite
efd0: 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65   on the database
efe0: 20 66 69 6c 65 20 68 61 6e 64 6c 65 0a 2a 2a 20   file handle.** 
eff0: 73 68 6f 72 74 6c 79 20 61 66 74 65 72 20 69 74  shortly after it
f000: 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 6f 72   is opened in or
f010: 64 65 72 20 74 6f 20 70 72 6f 76 69 64 65 20 61  der to provide a
f020: 20 63 75 73 74 6f 6d 20 56 46 53 20 77 69 74 68   custom VFS with
f030: 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 74 68   access.** to th
f040: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 62 75  e connections bu
f050: 73 79 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62  sy-handler callb
f060: 61 63 6b 2e 20 54 68 65 20 61 72 67 75 6d 65 6e  ack. The argumen
f070: 74 20 69 73 20 6f 66 20 74 79 70 65 20 28 76 6f  t is of type (vo
f080: 69 64 20 2a 2a 29 0a 2a 2a 20 2d 20 61 6e 20 61  id **).** - an a
f090: 72 72 61 79 20 6f 66 20 74 77 6f 20 28 76 6f 69  rray of two (voi
f0a0: 64 20 2a 29 20 76 61 6c 75 65 73 2e 20 54 68 65  d *) values. The
f0b0: 20 66 69 72 73 74 20 28 76 6f 69 64 20 2a 29 20   first (void *) 
f0c0: 61 63 74 75 61 6c 6c 79 20 70 6f 69 6e 74 73 0a  actually points.
f0d0: 2a 2a 20 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e  ** to a function
f0e0: 20 6f 66 20 74 79 70 65 20 28 69 6e 74 20 28 2a   of type (int (*
f0f0: 29 28 76 6f 69 64 20 2a 29 29 2e 20 49 6e 20 6f  )(void *)). In o
f100: 72 64 65 72 20 74 6f 20 69 6e 76 6f 6b 65 20 74  rder to invoke t
f110: 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a  he connections.*
f120: 2a 20 62 75 73 79 2d 68 61 6e 64 6c 65 72 2c 20  * busy-handler, 
f130: 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 73 68  this function sh
f140: 6f 75 6c 64 20 62 65 20 69 6e 76 6f 6b 65 64 20  ould be invoked 
f150: 77 69 74 68 20 74 68 65 20 73 65 63 6f 6e 64 20  with the second 
f160: 28 76 6f 69 64 20 2a 29 20 69 6e 0a 2a 2a 20 74  (void *) in.** t
f170: 68 65 20 61 72 72 61 79 20 61 73 20 74 68 65 20  he array as the 
f180: 6f 6e 6c 79 20 61 72 67 75 6d 65 6e 74 2e 20 49  only argument. I
f190: 66 20 69 74 20 72 65 74 75 72 6e 73 20 6e 6f 6e  f it returns non
f1a0: 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20  -zero, then the 
f1b0: 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f  operation.** sho
f1c0: 75 6c 64 20 62 65 20 72 65 74 72 69 65 64 2e 20  uld be retried. 
f1d0: 49 66 20 69 74 20 72 65 74 75 72 6e 73 20 7a 65  If it returns ze
f1e0: 72 6f 2c 20 74 68 65 20 63 75 73 74 6f 6d 20 56  ro, the custom V
f1f0: 46 53 20 73 68 6f 75 6c 64 20 61 62 61 6e 64 6f  FS should abando
f200: 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74  n the.** current
f210: 20 6f 70 65 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a   operation..**.*
f220: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
f230: 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d  CNTL_TEMPFILENAM
f240: 45 5d 5d 0a 2a 2a 20 5e 41 70 70 6c 69 63 61 74  E]].** ^Applicat
f250: 69 6f 6e 20 63 61 6e 20 69 6e 76 6f 6b 65 20 74  ion can invoke t
f260: 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c  his file-control
f270: 20 74 6f 20 68 61 76 65 20 53 51 4c 69 74 65 20   to have SQLite 
f280: 67 65 6e 65 72 61 74 65 20 61 0a 2a 2a 20 74 65  generate a.** te
f290: 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d 65  mporary filename
f2a0: 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65 20   using the same 
f2b0: 61 6c 67 6f 72 69 74 68 6d 20 74 68 61 74 20 69  algorithm that i
f2c0: 73 20 66 6f 6c 6c 6f 77 65 64 20 74 6f 20 67 65  s followed to ge
f2d0: 6e 65 72 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72  nerate.** tempor
f2e0: 61 72 79 20 66 69 6c 65 6e 61 6d 65 73 20 66 6f  ary filenames fo
f2f0: 72 20 54 45 4d 50 20 74 61 62 6c 65 73 20 61 6e  r TEMP tables an
f300: 64 20 6f 74 68 65 72 20 69 6e 74 65 72 6e 61 6c  d other internal
f310: 20 75 73 65 73 2e 20 20 54 68 65 0a 2a 2a 20 61   uses.  The.** a
f320: 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62  rgument should b
f330: 65 20 61 20 63 68 61 72 2a 2a 20 77 68 69 63 68  e a char** which
f340: 20 77 69 6c 6c 20 62 65 20 66 69 6c 6c 65 64 20   will be filled 
f350: 77 69 74 68 20 74 68 65 20 66 69 6c 65 6e 61 6d  with the filenam
f360: 65 0a 2a 2a 20 77 72 69 74 74 65 6e 20 69 6e 74  e.** written int
f370: 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  o memory obtaine
f380: 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
f390: 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 68 65 20  malloc()].  The 
f3a0: 63 61 6c 6c 65 72 20 73 68 6f 75 6c 64 0a 2a 2a  caller should.**
f3b0: 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33   invoke [sqlite3
f3c0: 5f 66 72 65 65 28 29 5d 20 6f 6e 20 74 68 65 20  _free()] on the 
f3d0: 72 65 73 75 6c 74 20 74 6f 20 61 76 6f 69 64 20  result to avoid 
f3e0: 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 2e 0a 2a  a memory leak..*
f3f0: 2a 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64  *.** </ul>.*/.#d
f400: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
f410: 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20 20  TL_LOCKSTATE    
f420: 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65             1.#de
f430: 66 69 6e 65 20 53 51 4c 49 54 45 5f 47 45 54 5f  fine SQLITE_GET_
f440: 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20  LOCKPROXYFILE   
f450: 20 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66            2.#def
f460: 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c  ine SQLITE_SET_L
f470: 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20  OCKPROXYFILE    
f480: 20 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69           3.#defi
f490: 6e 65 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f 45  ne SQLITE_LAST_E
f4a0: 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20  RRNO            
f4b0: 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e          4.#defin
f4c0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53  e SQLITE_FCNTL_S
f4d0: 49 5a 45 5f 48 49 4e 54 20 20 20 20 20 20 20 20  IZE_HINT        
f4e0: 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65         5.#define
f4f0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48   SQLITE_FCNTL_CH
f500: 55 4e 4b 5f 53 49 5a 45 20 20 20 20 20 20 20 20  UNK_SIZE        
f510: 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20        6.#define 
f520: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c  SQLITE_FCNTL_FIL
f530: 45 5f 50 4f 49 4e 54 45 52 20 20 20 20 20 20 20  E_POINTER       
f540: 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53       7.#define S
f550: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43  QLITE_FCNTL_SYNC
f560: 5f 4f 4d 49 54 54 45 44 20 20 20 20 20 20 20 20  _OMITTED        
f570: 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51      8.#define SQ
f580: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32  LITE_FCNTL_WIN32
f590: 5f 41 56 5f 52 45 54 52 59 20 20 20 20 20 20 20  _AV_RETRY       
f5a0: 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c     9.#define SQL
f5b0: 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53  ITE_FCNTL_PERSIS
f5c0: 54 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20 20  T_WAL           
f5d0: 20 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   10.#define SQLI
f5e0: 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49  TE_FCNTL_OVERWRI
f5f0: 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TE              
f600: 31 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  11.#define SQLIT
f610: 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 20  E_FCNTL_VFSNAME 
f620: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
f630: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
f640: 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45  _FCNTL_POWERSAFE
f650: 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 31 33  _OVERWRITE    13
f660: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
f670: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 20 20 20 20  FCNTL_PRAGMA    
f680: 20 20 20 20 20 20 20 20 20 20 20 20 20 31 34 0a               14.
f690: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
f6a0: 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52  CNTL_BUSYHANDLER
f6b0: 20 20 20 20 20 20 20 20 20 20 20 20 31 35 0a 23              15.#
f6c0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
f6d0: 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45  NTL_TEMPFILENAME
f6e0: 20 20 20 20 20 20 20 20 20 20 20 31 36 0a 0a 2f             16../
f6f0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
f700: 75 74 65 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a  utex Handle.**.*
f710: 2a 20 54 68 65 20 6d 75 74 65 78 20 6d 6f 64 75  * The mutex modu
f720: 6c 65 20 77 69 74 68 69 6e 20 53 51 4c 69 74 65  le within SQLite
f730: 20 64 65 66 69 6e 65 73 20 5b 73 71 6c 69 74 65   defines [sqlite
f740: 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65 20 61  3_mutex] to be a
f750: 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74 20 74 79  n.** abstract ty
f760: 70 65 20 66 6f 72 20 61 20 6d 75 74 65 78 20 6f  pe for a mutex o
f770: 62 6a 65 63 74 2e 20 20 54 68 65 20 53 51 4c 69  bject.  The SQLi
f780: 74 65 20 63 6f 72 65 20 6e 65 76 65 72 20 6c 6f  te core never lo
f790: 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20 69 6e  oks.** at the in
f7a0: 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74  ternal represent
f7b0: 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 6c  ation of an [sql
f7c0: 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49 74  ite3_mutex].  It
f7d0: 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 77   only.** deals w
f7e0: 69 74 68 20 70 6f 69 6e 74 65 72 73 20 74 6f 20  ith pointers to 
f7f0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  the [sqlite3_mut
f800: 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a  ex] object..**.*
f810: 2a 20 4d 75 74 65 78 65 73 20 61 72 65 20 63 72  * Mutexes are cr
f820: 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  eated using [sql
f830: 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63  ite3_mutex_alloc
f840: 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ()]..*/.typedef 
f850: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d  struct sqlite3_m
f860: 75 74 65 78 20 73 71 6c 69 74 65 33 5f 6d 75 74  utex sqlite3_mut
f870: 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  ex;../*.** CAPI3
f880: 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63  REF: OS Interfac
f890: 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41  e Object.**.** A
f8a0: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
f8b0: 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62  e sqlite3_vfs ob
f8c0: 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65  ject defines the
f8d0: 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65   interface betwe
f8e0: 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74 65  en.** the SQLite
f8f0: 20 63 6f 72 65 20 61 6e 64 20 74 68 65 20 75 6e   core and the un
f900: 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69  derlying operati
f910: 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 68 65 20  ng system.  The 
f920: 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20  "vfs".** in the 
f930: 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a 65  name of the obje
f940: 63 74 20 73 74 61 6e 64 73 20 66 6f 72 20 22 76  ct stands for "v
f950: 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74  irtual file syst
f960: 65 6d 22 2e 20 20 53 65 65 0a 2a 2a 20 74 68 65  em".  See.** the
f970: 20 5b 56 46 53 20 7c 20 56 46 53 20 64 6f 63 75   [VFS | VFS docu
f980: 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 66  mentation] for f
f990: 75 72 74 68 65 72 20 69 6e 66 6f 72 6d 61 74 69  urther informati
f9a0: 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 61  on..**.** The va
f9b0: 6c 75 65 20 6f 66 20 74 68 65 20 69 56 65 72 73  lue of the iVers
f9c0: 69 6f 6e 20 66 69 65 6c 64 20 69 73 20 69 6e 69  ion field is ini
f9d0: 74 69 61 6c 6c 79 20 31 20 62 75 74 20 6d 61 79  tially 1 but may
f9e0: 20 62 65 20 6c 61 72 67 65 72 20 69 6e 0a 2a 2a   be larger in.**
f9f0: 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   future versions
fa00: 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 64 64   of SQLite.  Add
fa10: 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d  itional fields m
fa20: 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 74  ay be appended t
fa30: 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74  o this.** object
fa40: 20 77 68 65 6e 20 74 68 65 20 69 56 65 72 73 69   when the iVersi
fa50: 6f 6e 20 76 61 6c 75 65 20 69 73 20 69 6e 63 72  on value is incr
fa60: 65 61 73 65 64 2e 20 20 4e 6f 74 65 20 74 68 61  eased.  Note tha
fa70: 74 20 74 68 65 20 73 74 72 75 63 74 75 72 65 0a  t the structure.
fa80: 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  ** of the sqlite
fa90: 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 63 68 61  3_vfs object cha
faa0: 6e 67 65 73 20 69 6e 20 74 68 65 20 74 72 61 6e  nges in the tran
fab0: 73 61 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 0a  saction between.
fac0: 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  ** SQLite versio
fad0: 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e 36 2e  n 3.5.9 and 3.6.
fae0: 30 20 61 6e 64 20 79 65 74 20 74 68 65 20 69 56  0 and yet the iV
faf0: 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 77 61 73  ersion field was
fb00: 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69 65 64   not.** modified
fb10: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73  ..**.** The szOs
fb20: 46 69 6c 65 20 66 69 65 6c 64 20 69 73 20 74 68  File field is th
fb30: 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 73 75  e size of the su
fb40: 62 63 6c 61 73 73 65 64 20 5b 73 71 6c 69 74 65  bclassed [sqlite
fb50: 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63  3_file].** struc
fb60: 74 75 72 65 20 75 73 65 64 20 62 79 20 74 68 69  ture used by thi
fb70: 73 20 56 46 53 2e 20 20 6d 78 50 61 74 68 6e 61  s VFS.  mxPathna
fb80: 6d 65 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75  me is the maximu
fb90: 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61  m length of.** a
fba0: 20 70 61 74 68 6e 61 6d 65 20 69 6e 20 74 68 69   pathname in thi
fbb0: 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67  s VFS..**.** Reg
fbc0: 69 73 74 65 72 65 64 20 73 71 6c 69 74 65 33 5f  istered sqlite3_
fbd0: 76 66 73 20 6f 62 6a 65 63 74 73 20 61 72 65 20  vfs objects are 
fbe0: 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64  kept on a linked
fbf0: 20 6c 69 73 74 20 66 6f 72 6d 65 64 20 62 79 0a   list formed by.
fc00: 2a 2a 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69  ** the pNext poi
fc10: 6e 74 65 72 2e 20 20 54 68 65 20 5b 73 71 6c 69  nter.  The [sqli
fc20: 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72  te3_vfs_register
fc30: 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69  ()].** and [sqli
fc40: 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74  te3_vfs_unregist
fc50: 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73  er()] interfaces
fc60: 20 6d 61 6e 61 67 65 20 74 68 69 73 20 6c 69 73   manage this lis
fc70: 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65 61 64  t.** in a thread
fc80: 2d 73 61 66 65 20 77 61 79 2e 20 20 54 68 65 20  -safe way.  The 
fc90: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e  [sqlite3_vfs_fin
fca0: 64 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a  d()] interface.*
fcb0: 2a 20 73 65 61 72 63 68 65 73 20 74 68 65 20 6c  * searches the l
fcc0: 69 73 74 2e 20 20 4e 65 69 74 68 65 72 20 74 68  ist.  Neither th
fcd0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f  e application co
fce0: 64 65 20 6e 6f 72 20 74 68 65 20 56 46 53 0a 2a  de nor the VFS.*
fcf0: 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
fd00: 20 73 68 6f 75 6c 64 20 75 73 65 20 74 68 65 20   should use the 
fd10: 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a  pNext pointer..*
fd20: 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74 20 66  *.** The pNext f
fd30: 69 65 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c 79  ield is the only
fd40: 20 66 69 65 6c 64 20 69 6e 20 74 68 65 20 73 71   field in the sq
fd50: 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72  lite3_vfs.** str
fd60: 75 63 74 75 72 65 20 74 68 61 74 20 53 51 4c 69  ucture that SQLi
fd70: 74 65 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64  te will ever mod
fd80: 69 66 79 2e 20 20 53 51 4c 69 74 65 20 77 69 6c  ify.  SQLite wil
fd90: 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a  l only access.**
fda0: 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20   or modify this 
fdb0: 66 69 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64  field while hold
fdc0: 69 6e 67 20 61 20 70 61 72 74 69 63 75 6c 61 72  ing a particular
fdd0: 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a   static mutex..*
fde0: 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
fdf0: 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d  n should never m
fe00: 6f 64 69 66 79 20 61 6e 79 74 68 69 6e 67 20 77  odify anything w
fe10: 69 74 68 69 6e 20 74 68 65 20 73 71 6c 69 74 65  ithin the sqlite
fe20: 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20  3_vfs.** object 
fe30: 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65 63 74 20  once the object 
fe40: 68 61 73 20 62 65 65 6e 20 72 65 67 69 73 74 65  has been registe
fe50: 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a  red..**.** The z
fe60: 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64 73  Name field holds
fe70: 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
fe80: 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68   VFS module.  Th
fe90: 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62  e name must.** b
fea0: 65 20 75 6e 69 71 75 65 20 61 63 72 6f 73 73 20  e unique across 
feb0: 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e  all VFS modules.
fec0: 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33  .**.** [[sqlite3
fed0: 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a 20  _vfs.xOpen]].** 
fee0: 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65  ^SQLite guarante
fef0: 65 73 20 74 68 61 74 20 74 68 65 20 7a 46 69 6c  es that the zFil
ff00: 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20  ename parameter 
ff10: 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 65  to xOpen.** is e
ff20: 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69  ither a NULL poi
ff30: 6e 74 65 72 20 6f 72 20 73 74 72 69 6e 67 20 6f  nter or string o
ff40: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
ff50: 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29 20  xFullPathname() 
ff60: 77 69 74 68 20 61 6e 20 6f 70 74 69 6f 6e 61 6c  with an optional
ff70: 20 73 75 66 66 69 78 20 61 64 64 65 64 2e 0a 2a   suffix added..*
ff80: 2a 20 5e 49 66 20 61 20 73 75 66 66 69 78 20 69  * ^If a suffix i
ff90: 73 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 7a  s added to the z
ffa0: 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74  Filename paramet
ffb0: 65 72 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a 20 63  er, it will.** c
ffc0: 6f 6e 73 69 73 74 20 6f 66 20 61 20 73 69 6e 67  onsist of a sing
ffd0: 6c 65 20 22 2d 22 20 63 68 61 72 61 63 74 65 72  le "-" character
ffe0: 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 6e 6f 20   followed by no 
fff0: 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a 20 31 31 20  more than.** 11 
10000 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 61 6e 64  alphanumeric and
10010 2f 6f 72 20 22 2d 22 20 63 68 61 72 61 63 74 65  /or "-" characte
10020 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 66  rs..** ^SQLite f
10030 75 72 74 68 65 72 20 67 75 61 72 61 6e 74 65 65  urther guarantee
10040 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 73 74  s that.** the st
10050 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 76 61 6c  ring will be val
10060 69 64 20 61 6e 64 20 75 6e 63 68 61 6e 67 65 64  id and unchanged
10070 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29 20   until xClose() 
10080 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65  is.** called. Be
10090 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 65  cause of the pre
100a0 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 2c 0a  vious sentence,.
100b0 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** the [sqlite3_
100c0 66 69 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c 79  file] can safely
100d0 20 73 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 72   store a pointer
100e0 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e   to the.** filen
100f0 61 6d 65 20 69 66 20 69 74 20 6e 65 65 64 73 20  ame if it needs 
10100 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 68 65 20  to remember the 
10110 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d  filename for som
10120 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20  e reason..** If 
10130 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61  the zFilename pa
10140 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e  rameter to xOpen
10150 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
10160 65 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a  er then xOpen.**
10170 20 6d 75 73 74 20 69 6e 76 65 6e 74 20 69 74 73   must invent its
10180 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e   own temporary n
10190 61 6d 65 20 66 6f 72 20 74 68 65 20 66 69 6c 65  ame for the file
101a0 2e 20 20 5e 57 68 65 6e 65 76 65 72 20 74 68 65  .  ^Whenever the
101b0 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70   .** xFilename p
101c0 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c  arameter is NULL
101d0 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65   it will also be
101e0 20 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74   the case that t
101f0 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72 61  he.** flags para
10200 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75  meter will inclu
10210 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  de [SQLITE_OPEN_
10220 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a  DELETEONCLOSE]..
10230 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20  **.** The flags 
10240 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65  argument to xOpe
10250 6e 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c  n() includes all
10260 20 62 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20   bits set in.** 
10270 74 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  the flags argume
10280 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f  nt to [sqlite3_o
10290 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69  pen_v2()].  Or i
102a0 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  f [sqlite3_open(
102b0 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65  )].** or [sqlite
102c0 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75  3_open16()] is u
102d0 73 65 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20  sed, then flags 
102e0 69 6e 63 6c 75 64 65 73 20 61 74 20 6c 65 61 73  includes at leas
102f0 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45  t.** [SQLITE_OPE
10300 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b  N_READWRITE] | [
10310 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
10320 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65  TE]. .** If xOpe
10330 6e 28 29 20 6f 70 65 6e 73 20 61 20 66 69 6c 65  n() opens a file
10340 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20   read-only then 
10350 69 74 20 73 65 74 73 20 2a 70 4f 75 74 46 6c 61  it sets *pOutFla
10360 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65  gs to.** include
10370 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45   [SQLITE_OPEN_RE
10380 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20  ADONLY].  Other 
10390 62 69 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61  bits in *pOutFla
103a0 67 73 20 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a  gs may be set..*
103b0 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 20 77 69  *.** ^(SQLite wi
103c0 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20  ll also add one 
103d0 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  of the following
103e0 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f   flags to the xO
103f0 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64  pen().** call, d
10400 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20  epending on the 
10410 6f 62 6a 65 63 74 20 62 65 69 6e 67 20 6f 70 65  object being ope
10420 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ned:.**.** <ul>.
10430 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
10440 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a  _OPEN_MAIN_DB].*
10450 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
10460 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41  OPEN_MAIN_JOURNA
10470 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  L].** <li>  [SQL
10480 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42  ITE_OPEN_TEMP_DB
10490 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
104a0 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55  TE_OPEN_TEMP_JOU
104b0 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  RNAL].** <li>  [
104c0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e  SQLITE_OPEN_TRAN
104d0 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69  SIENT_DB].** <li
104e0 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
104f0 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c  SUBJOURNAL].** <
10500 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
10510 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c  N_MASTER_JOURNAL
10520 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
10530 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a 2a 20  TE_OPEN_WAL].** 
10540 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  </ul>)^.**.** Th
10550 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65  e file I/O imple
10560 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75 73  mentation can us
10570 65 20 74 68 65 20 6f 62 6a 65 63 74 20 74 79 70  e the object typ
10580 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68  e flags to.** ch
10590 61 6e 67 65 20 74 68 65 20 77 61 79 20 69 74 20  ange the way it 
105a0 64 65 61 6c 73 20 77 69 74 68 20 66 69 6c 65 73  deals with files
105b0 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20  .  For example, 
105c0 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a  an application.*
105d0 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20  * that does not 
105e0 63 61 72 65 20 61 62 6f 75 74 20 63 72 61 73 68  care about crash
105f0 20 72 65 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c   recovery or rol
10600 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65  lback might make
10610 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 20  .** the open of 
10620 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61  a journal file a
10630 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 20   no-op.  Writes 
10640 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20  to this journal 
10650 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65  would.** also be
10660 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79   no-ops, and any
10670 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64   attempt to read
10680 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75   the journal wou
10690 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c  ld return.** SQL
106a0 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74  ITE_IOERR.  Or t
106b0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
106c0 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 7a  n might recogniz
106d0 65 20 74 68 61 74 20 61 20 64 61 74 61 62 61 73  e that a databas
106e0 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62  e.** file will b
106f0 65 20 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69  e doing page-ali
10700 67 6e 65 64 20 73 65 63 74 6f 72 20 72 65 61 64  gned sector read
10710 73 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e 20  s and writes in 
10720 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65  a random.** orde
10730 72 20 61 6e 64 20 73 65 74 20 75 70 20 69 74 73  r and set up its
10740 20 49 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 61   I/O subsystem a
10750 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a  ccordingly..**.*
10760 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61  * SQLite might a
10770 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74  lso add one of t
10780 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61  he following fla
10790 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20  gs to the xOpen 
107a0 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75  method:.**.** <u
107b0 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  l>.** <li> [SQLI
107c0 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
107d0 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  CLOSE].** <li> [
107e0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
107f0 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a  USIVE].** </ul>.
10800 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  **.** The [SQLIT
10810 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
10820 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73  LOSE] flag means
10830 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64   the file should
10840 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77   be.** deleted w
10850 68 65 6e 20 69 74 20 69 73 20 63 6c 6f 73 65 64  hen it is closed
10860 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  .  ^The [SQLITE_
10870 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
10880 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73  SE].** will be s
10890 65 74 20 66 6f 72 20 54 45 4d 50 20 64 61 74 61  et for TEMP data
108a0 62 61 73 65 73 20 61 6e 64 20 74 68 65 69 72 20  bases and their 
108b0 6a 6f 75 72 6e 61 6c 73 2c 20 74 72 61 6e 73 69  journals, transi
108c0 65 6e 74 0a 2a 2a 20 64 61 74 61 62 61 73 65 73  ent.** databases
108d0 2c 20 61 6e 64 20 73 75 62 6a 6f 75 72 6e 61 6c  , and subjournal
108e0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53  s..**.** ^The [S
108f0 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55  QLITE_OPEN_EXCLU
10900 53 49 56 45 5d 20 66 6c 61 67 20 69 73 20 61 6c  SIVE] flag is al
10910 77 61 79 73 20 75 73 65 64 20 69 6e 20 63 6f 6e  ways used in con
10920 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68  junction.** with
10930 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   the [SQLITE_OPE
10940 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61 67 2c 20  N_CREATE] flag, 
10950 77 68 69 63 68 20 61 72 65 20 62 6f 74 68 20 64  which are both d
10960 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c 6f  irectly.** analo
10970 67 6f 75 73 20 74 6f 20 74 68 65 20 4f 5f 45 58  gous to the O_EX
10980 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41 54 20 66  CL and O_CREAT f
10990 6c 61 67 73 20 6f 66 20 74 68 65 20 50 4f 53 49  lags of the POSI
109a0 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 49 2e  X open().** API.
109b0 20 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 50 45    The SQLITE_OPE
109c0 4e 5f 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67  N_EXCLUSIVE flag
109d0 2c 20 77 68 65 6e 20 70 61 69 72 65 64 20 77 69  , when paired wi
109e0 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49 54  th the .** SQLIT
109f0 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2c 20 69  E_OPEN_CREATE, i
10a00 73 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61  s used to indica
10a10 74 65 20 74 68 61 74 20 66 69 6c 65 20 73 68 6f  te that file sho
10a20 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65  uld always.** be
10a30 20 63 72 65 61 74 65 64 2c 20 61 6e 64 20 74 68   created, and th
10a40 61 74 20 69 74 20 69 73 20 61 6e 20 65 72 72 6f  at it is an erro
10a50 72 20 69 66 20 69 74 20 61 6c 72 65 61 64 79 20  r if it already 
10a60 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74 20 69 73  exists..** It is
10a70 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65 64   <i>not</i> used
10a80 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 65   to indicate the
10a90 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 20   file should be 
10aa0 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 20 65  opened .** for e
10ab0 78 63 6c 75 73 69 76 65 20 61 63 63 65 73 73 2e  xclusive access.
10ac0 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61 73 74  .**.** ^At least
10ad0 20 73 7a 4f 73 46 69 6c 65 20 62 79 74 65 73 20   szOsFile bytes 
10ae0 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c  of memory are al
10af0 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c 69 74  located by SQLit
10b00 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65  e.** to hold the
10b10 20 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d    [sqlite3_file]
10b20 20 73 74 72 75 63 74 75 72 65 20 70 61 73 73 65   structure passe
10b30 64 20 61 73 20 74 68 65 20 74 68 69 72 64 0a 2a  d as the third.*
10b40 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f  * argument to xO
10b50 70 65 6e 2e 20 20 54 68 65 20 78 4f 70 65 6e 20  pen.  The xOpen 
10b60 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20  method does not 
10b70 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63  have to.** alloc
10b80 61 74 65 20 74 68 65 20 73 74 72 75 63 74 75 72  ate the structur
10b90 65 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a 75 73  e; it should jus
10ba0 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e 20 20 4e  t fill it in.  N
10bb0 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ote that.** the 
10bc0 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6d 75 73  xOpen method mus
10bd0 74 20 73 65 74 20 74 68 65 20 73 71 6c 69 74 65  t set the sqlite
10be0 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20  3_file.pMethods 
10bf0 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 61 20 76  to either.** a v
10c00 61 6c 69 64 20 5b 73 71 6c 69 74 65 33 5f 69 6f  alid [sqlite3_io
10c10 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
10c20 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f   or to NULL.  xO
10c30 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a 20 74  pen must do.** t
10c40 68 69 73 20 65 76 65 6e 20 69 66 20 74 68 65 20  his even if the 
10c50 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20 53 51 4c  open fails.  SQL
10c60 69 74 65 20 65 78 70 65 63 74 73 20 74 68 61 74  ite expects that
10c70 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c   the sqlite3_fil
10c80 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 65 6c  e.pMethods.** el
10c90 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 76 61  ement will be va
10ca0 6c 69 64 20 61 66 74 65 72 20 78 4f 70 65 6e 20  lid after xOpen 
10cb0 72 65 74 75 72 6e 73 20 72 65 67 61 72 64 6c 65  returns regardle
10cc0 73 73 20 6f 66 20 74 68 65 20 73 75 63 63 65 73  ss of the succes
10cd0 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75 72 65 20  s.** or failure 
10ce0 6f 66 20 74 68 65 20 78 4f 70 65 6e 20 63 61 6c  of the xOpen cal
10cf0 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74  l..**.** [[sqlit
10d00 65 33 5f 76 66 73 2e 78 41 63 63 65 73 73 5d 5d  e3_vfs.xAccess]]
10d10 0a 2a 2a 20 5e 54 68 65 20 66 6c 61 67 73 20 61  .** ^The flags a
10d20 72 67 75 6d 65 6e 74 20 74 6f 20 78 41 63 63 65  rgument to xAcce
10d30 73 73 28 29 20 6d 61 79 20 62 65 20 5b 53 51 4c  ss() may be [SQL
10d40 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54  ITE_ACCESS_EXIST
10d50 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 66 6f  S].** to test fo
10d60 72 20 74 68 65 20 65 78 69 73 74 65 6e 63 65 20  r the existence 
10d70 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72 20 5b 53  of a file, or [S
10d80 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
10d90 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a 20 74 65  DWRITE] to.** te
10da0 73 74 20 77 68 65 74 68 65 72 20 61 20 66 69 6c  st whether a fil
10db0 65 20 69 73 20 72 65 61 64 61 62 6c 65 20 61 6e  e is readable an
10dc0 64 20 77 72 69 74 61 62 6c 65 2c 20 6f 72 20 5b  d writable, or [
10dd0 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
10de0 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 77  AD].** to test w
10df0 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 73  hether a file is
10e00 20 61 74 20 6c 65 61 73 74 20 72 65 61 64 61 62   at least readab
10e10 6c 65 2e 20 20 20 54 68 65 20 66 69 6c 65 20 63  le.   The file c
10e20 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69 72 65 63  an be a.** direc
10e30 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c  tory..**.** ^SQL
10e40 69 74 65 20 77 69 6c 6c 20 61 6c 77 61 79 73 20  ite will always 
10e50 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c 65 61 73  allocate at leas
10e60 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b 31 20 62  t mxPathname+1 b
10e70 79 74 65 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20  ytes for the.** 
10e80 6f 75 74 70 75 74 20 62 75 66 66 65 72 20 78 46  output buffer xF
10e90 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20 20 54 68  ullPathname.  Th
10ea0 65 20 65 78 61 63 74 20 73 69 7a 65 20 6f 66 20  e exact size of 
10eb0 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66 65  the output buffe
10ec0 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20 70 61 73  r.** is also pas
10ed0 73 65 64 20 61 73 20 61 20 70 61 72 61 6d 65 74  sed as a paramet
10ee0 65 72 20 74 6f 20 62 6f 74 68 20 20 6d 65 74 68  er to both  meth
10ef0 6f 64 73 2e 20 49 66 20 74 68 65 20 6f 75 74 70  ods. If the outp
10f00 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20  ut buffer.** is 
10f10 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f 75 67 68  not large enough
10f20 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  , [SQLITE_CANTOP
10f30 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65 20 72 65  EN] should be re
10f40 74 75 72 6e 65 64 2e 20 53 69 6e 63 65 20 74 68  turned. Since th
10f50 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64 6c 65 64  is is.** handled
10f60 20 61 73 20 61 20 66 61 74 61 6c 20 65 72 72 6f   as a fatal erro
10f70 72 20 62 79 20 53 51 4c 69 74 65 2c 20 76 66 73  r by SQLite, vfs
10f80 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
10f90 20 73 68 6f 75 6c 64 20 65 6e 64 65 61 76 6f 72   should endeavor
10fa0 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e 74 20 74  .** to prevent t
10fb0 68 69 73 20 62 79 20 73 65 74 74 69 6e 67 20 6d  his by setting m
10fc0 78 50 61 74 68 6e 61 6d 65 20 74 6f 20 61 20 73  xPathname to a s
10fd0 75 66 66 69 63 69 65 6e 74 6c 79 20 6c 61 72 67  ufficiently larg
10fe0 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54  e value..**.** T
10ff0 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29  he xRandomness()
11000 2c 20 78 53 6c 65 65 70 28 29 2c 20 78 43 75 72  , xSleep(), xCur
11010 72 65 6e 74 54 69 6d 65 28 29 2c 20 61 6e 64 20  rentTime(), and 
11020 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36  xCurrentTimeInt6
11030 34 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  4().** interface
11040 73 20 61 72 65 20 6e 6f 74 20 73 74 72 69 63 74  s are not strict
11050 6c 79 20 61 20 70 61 72 74 20 6f 66 20 74 68 65  ly a part of the
11060 20 66 69 6c 65 73 79 73 74 65 6d 2c 20 62 75 74   filesystem, but
11070 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63   they are.** inc
11080 6c 75 64 65 64 20 69 6e 20 74 68 65 20 56 46 53  luded in the VFS
11090 20 73 74 72 75 63 74 75 72 65 20 66 6f 72 20 63   structure for c
110a0 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20  ompleteness..** 
110b0 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28  The xRandomness(
110c0 29 20 66 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d  ) function attem
110d0 70 74 73 20 74 6f 20 72 65 74 75 72 6e 20 6e 42  pts to return nB
110e0 79 74 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66  ytes bytes.** of
110f0 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72 61   good-quality ra
11100 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f  ndomness into zO
11110 75 74 2e 20 20 54 68 65 20 72 65 74 75 72 6e 20  ut.  The return 
11120 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65 20  value is.** the 
11130 61 63 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66  actual number of
11140 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d   bytes of random
11150 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a 2a  ness obtained..*
11160 2a 20 54 68 65 20 78 53 6c 65 65 70 28 29 20 6d  * The xSleep() m
11170 65 74 68 6f 64 20 63 61 75 73 65 73 20 74 68 65  ethod causes the
11180 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 20   calling thread 
11190 74 6f 20 73 6c 65 65 70 20 66 6f 72 20 61 74 0a  to sleep for at.
111a0 2a 2a 20 6c 65 61 73 74 20 74 68 65 20 6e 75 6d  ** least the num
111b0 62 65 72 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f  ber of microseco
111c0 6e 64 73 20 67 69 76 65 6e 2e 20 20 5e 54 68 65  nds given.  ^The
111d0 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 0a   xCurrentTime().
111e0 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e  ** method return
111f0 73 20 61 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e  s a Julian Day N
11200 75 6d 62 65 72 20 66 6f 72 20 74 68 65 20 63 75  umber for the cu
11210 72 72 65 6e 74 20 64 61 74 65 20 61 6e 64 20 74  rrent date and t
11220 69 6d 65 20 61 73 0a 2a 2a 20 61 20 66 6c 6f 61  ime as.** a floa
11230 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65  ting point value
11240 2e 0a 2a 2a 20 5e 54 68 65 20 78 43 75 72 72 65  ..** ^The xCurre
11250 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65  ntTimeInt64() me
11260 74 68 6f 64 20 72 65 74 75 72 6e 73 2c 20 61 73  thod returns, as
11270 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 65   an integer, the
11280 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44 61 79 20 4e   Julian.** Day N
11290 75 6d 62 65 72 20 6d 75 6c 74 69 70 6c 69 65 64  umber multiplied
112a0 20 62 79 20 38 36 34 30 30 30 30 30 20 28 74 68   by 86400000 (th
112b0 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c  e number of mill
112c0 69 73 65 63 6f 6e 64 73 20 69 6e 20 0a 2a 2a 20  iseconds in .** 
112d0 61 20 32 34 2d 68 6f 75 72 20 64 61 79 29 2e 20  a 24-hour day). 
112e0 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c   .** ^SQLite wil
112f0 6c 20 75 73 65 20 74 68 65 20 78 43 75 72 72 65  l use the xCurre
11300 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65  ntTimeInt64() me
11310 74 68 6f 64 20 74 6f 20 67 65 74 20 74 68 65 20  thod to get the 
11320 63 75 72 72 65 6e 74 0a 2a 2a 20 64 61 74 65 20  current.** date 
11330 61 6e 64 20 74 69 6d 65 20 69 66 20 74 68 61 74  and time if that
11340 20 6d 65 74 68 6f 64 20 69 73 20 61 76 61 69 6c   method is avail
11350 61 62 6c 65 20 28 69 66 20 69 56 65 72 73 69 6f  able (if iVersio
11360 6e 20 69 73 20 32 20 6f 72 20 0a 2a 2a 20 67 72  n is 2 or .** gr
11370 65 61 74 65 72 20 61 6e 64 20 74 68 65 20 66 75  eater and the fu
11380 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69  nction pointer i
11390 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 61 6e 64 20  s not NULL) and 
113a0 77 69 6c 6c 20 66 61 6c 6c 20 62 61 63 6b 0a 2a  will fall back.*
113b0 2a 20 74 6f 20 78 43 75 72 72 65 6e 74 54 69 6d  * to xCurrentTim
113c0 65 28 29 20 69 66 20 78 43 75 72 72 65 6e 74 54  e() if xCurrentT
113d0 69 6d 65 49 6e 74 36 34 28 29 20 69 73 20 75 6e  imeInt64() is un
113e0 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a  available..**.**
113f0 20 5e 54 68 65 20 78 53 65 74 53 79 73 74 65 6d   ^The xSetSystem
11400 43 61 6c 6c 28 29 2c 20 78 47 65 74 53 79 73 74  Call(), xGetSyst
11410 65 6d 43 61 6c 6c 28 29 2c 20 61 6e 64 20 78 4e  emCall(), and xN
11420 65 73 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 20  estSystemCall() 
11430 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 61 72  interfaces.** ar
11440 65 20 6e 6f 74 20 75 73 65 64 20 62 79 20 74 68  e not used by th
11450 65 20 53 51 4c 69 74 65 20 63 6f 72 65 2e 20 20  e SQLite core.  
11460 54 68 65 73 65 20 6f 70 74 69 6f 6e 61 6c 20 69  These optional i
11470 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 70 72  nterfaces are pr
11480 6f 76 69 64 65 64 0a 2a 2a 20 62 79 20 73 6f 6d  ovided.** by som
11490 65 20 56 46 53 65 73 20 74 6f 20 66 61 63 69 6c  e VFSes to facil
114a0 69 74 61 74 65 20 74 65 73 74 69 6e 67 20 6f 66  itate testing of
114b0 20 74 68 65 20 56 46 53 20 63 6f 64 65 2e 20 42   the VFS code. B
114c0 79 20 6f 76 65 72 72 69 64 69 6e 67 20 0a 2a 2a  y overriding .**
114d0 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 77 69   system calls wi
114e0 74 68 20 66 75 6e 63 74 69 6f 6e 73 20 75 6e 64  th functions und
114f0 65 72 20 69 74 73 20 63 6f 6e 74 72 6f 6c 2c 20  er its control, 
11500 61 20 74 65 73 74 20 70 72 6f 67 72 61 6d 20 63  a test program c
11510 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61 74 65 20 66  an.** simulate f
11520 61 75 6c 74 73 20 61 6e 64 20 65 72 72 6f 72 20  aults and error 
11530 63 6f 6e 64 69 74 69 6f 6e 73 20 74 68 61 74 20  conditions that 
11540 77 6f 75 6c 64 20 6f 74 68 65 72 77 69 73 65 20  would otherwise 
11550 62 65 20 64 69 66 66 69 63 75 6c 74 0a 2a 2a 20  be difficult.** 
11560 6f 72 20 69 6d 70 6f 73 73 69 62 6c 65 20 74 6f  or impossible to
11570 20 69 6e 64 75 63 65 2e 20 20 54 68 65 20 73 65   induce.  The se
11580 74 20 6f 66 20 73 79 73 74 65 6d 20 63 61 6c 6c  t of system call
11590 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 6f 76  s that can be ov
115a0 65 72 72 69 64 64 65 6e 0a 2a 2a 20 76 61 72 69  erridden.** vari
115b0 65 73 20 66 72 6f 6d 20 6f 6e 65 20 56 46 53 20  es from one VFS 
115c0 74 6f 20 61 6e 6f 74 68 65 72 2c 20 61 6e 64 20  to another, and 
115d0 66 72 6f 6d 20 6f 6e 65 20 76 65 72 73 69 6f 6e  from one version
115e0 20 6f 66 20 74 68 65 20 73 61 6d 65 20 56 46 53   of the same VFS
115f0 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65 78 74 2e   to the.** next.
11600 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74    Applications t
11610 68 61 74 20 75 73 65 20 74 68 65 73 65 20 69 6e  hat use these in
11620 74 65 72 66 61 63 65 73 20 6d 75 73 74 20 62 65  terfaces must be
11630 20 70 72 65 70 61 72 65 64 20 66 6f 72 20 61 6e   prepared for an
11640 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20 6f 66 20 74  y.** or all of t
11650 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20  hese interfaces 
11660 74 6f 20 62 65 20 4e 55 4c 4c 20 6f 72 20 66 6f  to be NULL or fo
11670 72 20 74 68 65 69 72 20 62 65 68 61 76 69 6f 72  r their behavior
11680 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 66 72   to change.** fr
11690 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 74  om one release t
116a0 6f 20 74 68 65 20 6e 65 78 74 2e 20 20 41 70 70  o the next.  App
116b0 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73 74 20 6e  lications must n
116c0 6f 74 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63  ot attempt to ac
116d0 63 65 73 73 0a 2a 2a 20 61 6e 79 20 6f 66 20 74  cess.** any of t
116e0 68 65 73 65 20 6d 65 74 68 6f 64 73 20 69 66 20  hese methods if 
116f0 74 68 65 20 69 56 65 72 73 69 6f 6e 20 6f 66 20  the iVersion of 
11700 74 68 65 20 56 46 53 20 69 73 20 6c 65 73 73 20  the VFS is less 
11710 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74 79 70 65 64  than 3..*/.typed
11720 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
11730 33 5f 76 66 73 20 73 71 6c 69 74 65 33 5f 76 66  3_vfs sqlite3_vf
11740 73 3b 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20  s;.typedef void 
11750 28 2a 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c  (*sqlite3_syscal
11760 6c 5f 70 74 72 29 28 76 6f 69 64 29 3b 0a 73 74  l_ptr)(void);.st
11770 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73  ruct sqlite3_vfs
11780 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f   {.  int iVersio
11790 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  n;            /*
117a0 20 53 74 72 75 63 74 75 72 65 20 76 65 72 73 69   Structure versi
117b0 6f 6e 20 6e 75 6d 62 65 72 20 28 63 75 72 72 65  on number (curre
117c0 6e 74 6c 79 20 33 29 20 2a 2f 0a 20 20 69 6e 74  ntly 3) */.  int
117d0 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20 20   szOsFile;      
117e0 20 20 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f 66        /* Size of
117f0 20 73 75 62 63 6c 61 73 73 65 64 20 73 71 6c 69   subclassed sqli
11800 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69 6e  te3_file */.  in
11810 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20 20  t mxPathname;   
11820 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
11830 6d 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20  m file pathname 
11840 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c 69  length */.  sqli
11850 74 65 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b 20  te3_vfs *pNext; 
11860 20 20 20 20 20 2f 2a 20 4e 65 78 74 20 72 65 67       /* Next reg
11870 69 73 74 65 72 65 64 20 56 46 53 20 2a 2f 0a 20  istered VFS */. 
11880 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
11890 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d  me;       /* Nam
118a0 65 20 6f 66 20 74 68 69 73 20 76 69 72 74 75 61  e of this virtua
118b0 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 20 2a 2f  l file system */
118c0 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74  .  void *pAppDat
118d0 61 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 50  a;          /* P
118e0 6f 69 6e 74 65 72 20 74 6f 20 61 70 70 6c 69 63  ointer to applic
118f0 61 74 69 6f 6e 2d 73 70 65 63 69 66 69 63 20 64  ation-specific d
11900 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ata */.  int (*x
11910 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66  Open)(sqlite3_vf
11920 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
11930 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 66  zName, sqlite3_f
11940 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20 20 20  ile*,.          
11950 20 20 20 20 20 69 6e 74 20 66 6c 61 67 73 2c 20       int flags, 
11960 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73 29 3b  int *pOutFlags);
11970 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c 65 74 65  .  int (*xDelete
11980 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
11990 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
119a0 65 2c 20 69 6e 74 20 73 79 6e 63 44 69 72 29 3b  e, int syncDir);
119b0 0a 20 20 69 6e 74 20 28 2a 78 41 63 63 65 73 73  .  int (*xAccess
119c0 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
119d0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
119e0 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e  e, int flags, in
119f0 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69  t *pResOut);.  i
11a00 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e 61  nt (*xFullPathna
11a10 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  me)(sqlite3_vfs*
11a20 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
11a30 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 63  ame, int nOut, c
11a40 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f  har *zOut);.  vo
11a50 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28 73  id *(*xDlOpen)(s
11a60 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
11a70 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61  st char *zFilena
11a80 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44  me);.  void (*xD
11a90 6c 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f  lError)(sqlite3_
11aa0 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c  vfs*, int nByte,
11ab0 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 29 3b   char *zErrMsg);
11ac0 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78 44 6c 53  .  void (*(*xDlS
11ad0 79 6d 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ym)(sqlite3_vfs*
11ae0 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68  ,void*, const ch
11af0 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29 28 76 6f  ar *zSymbol))(vo
11b00 69 64 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44  id);.  void (*xD
11b10 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f  lClose)(sqlite3_
11b20 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20  vfs*, void*);.  
11b30 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73  int (*xRandomnes
11b40 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  s)(sqlite3_vfs*,
11b50 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72   int nByte, char
11b60 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28   *zOut);.  int (
11b70 2a 78 53 6c 65 65 70 29 28 73 71 6c 69 74 65 33  *xSleep)(sqlite3
11b80 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f  _vfs*, int micro
11b90 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20  seconds);.  int 
11ba0 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 29 28  (*xCurrentTime)(
11bb0 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f  sqlite3_vfs*, do
11bc0 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  uble*);.  int (*
11bd0 78 47 65 74 4c 61 73 74 45 72 72 6f 72 29 28 73  xGetLastError)(s
11be0 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74  qlite3_vfs*, int
11bf0 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20 2f 2a 0a  , char *);.  /*.
11c00 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73    ** The methods
11c10 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65   above are in ve
11c20 72 73 69 6f 6e 20 31 20 6f 66 20 74 68 65 20 73  rsion 1 of the s
11c30 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74  qlite_vfs object
11c40 0a 20 20 2a 2a 20 64 65 66 69 6e 69 74 69 6f 6e  .  ** definition
11c50 2e 20 20 54 68 6f 73 65 20 74 68 61 74 20 66 6f  .  Those that fo
11c60 6c 6c 6f 77 20 61 72 65 20 61 64 64 65 64 20 69  llow are added i
11c70 6e 20 76 65 72 73 69 6f 6e 20 32 20 6f 72 20 6c  n version 2 or l
11c80 61 74 65 72 0a 20 20 2a 2f 0a 20 20 69 6e 74 20  ater.  */.  int 
11c90 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e  (*xCurrentTimeIn
11ca0 74 36 34 29 28 73 71 6c 69 74 65 33 5f 76 66 73  t64)(sqlite3_vfs
11cb0 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
11cc0 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68  *);.  /*.  ** Th
11cd0 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  e methods above 
11ce0 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20  are in versions 
11cf0 31 20 61 6e 64 20 32 20 6f 66 20 74 68 65 20 73  1 and 2 of the s
11d00 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74  qlite_vfs object
11d10 2e 0a 20 20 2a 2a 20 54 68 6f 73 65 20 62 65 6c  ..  ** Those bel
11d20 6f 77 20 61 72 65 20 66 6f 72 20 76 65 72 73 69  ow are for versi
11d30 6f 6e 20 33 20 61 6e 64 20 67 72 65 61 74 65 72  on 3 and greater
11d40 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ..  */.  int (*x
11d50 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73  SetSystemCall)(s
11d60 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
11d70 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
11d80 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f  sqlite3_syscall_
11d90 70 74 72 29 3b 0a 20 20 73 71 6c 69 74 65 33 5f  ptr);.  sqlite3_
11da0 73 79 73 63 61 6c 6c 5f 70 74 72 20 28 2a 78 47  syscall_ptr (*xG
11db0 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71  etSystemCall)(sq
11dc0 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
11dd0 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a  t char *zName);.
11de0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 28 2a    const char *(*
11df0 78 4e 65 78 74 53 79 73 74 65 6d 43 61 6c 6c 29  xNextSystemCall)
11e00 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
11e10 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
11e20 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65  );.  /*.  ** The
11e30 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61   methods above a
11e40 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31  re in versions 1
11e50 20 74 68 72 6f 75 67 68 20 33 20 6f 66 20 74 68   through 3 of th
11e60 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a  e sqlite_vfs obj
11e70 65 63 74 2e 0a 20 20 2a 2a 20 4e 65 77 20 66 69  ect..  ** New fi
11e80 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70 65  elds may be appe
11e90 6e 64 65 64 20 69 6e 20 66 69 67 75 72 65 20 76  nded in figure v
11ea0 65 72 73 69 6f 6e 73 2e 20 20 54 68 65 20 69 56  ersions.  The iV
11eb0 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75  ersion.  ** valu
11ec0 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74  e will increment
11ed0 20 77 68 65 6e 65 76 65 72 20 74 68 69 73 20 68   whenever this h
11ee0 61 70 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a 7d 3b  appens. .  */.};
11ef0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
11f00 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20  : Flags for the 
11f10 78 41 63 63 65 73 73 20 56 46 53 20 6d 65 74 68  xAccess VFS meth
11f20 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69  od.**.** These i
11f30 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73  nteger constants
11f40 20 63 61 6e 20 62 65 20 75 73 65 64 20 61 73 20   can be used as 
11f50 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
11f60 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41  ter to.** the xA
11f70 63 63 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20  ccess method of 
11f80 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  an [sqlite3_vfs]
11f90 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 79 20 64   object.  They d
11fa0 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74  etermine.** what
11fb0 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69 73 73   kind of permiss
11fc0 69 6f 6e 73 20 74 68 65 20 78 41 63 63 65 73 73  ions the xAccess
11fd0 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69   method is looki
11fe0 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 20  ng for..** With 
11ff0 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58  SQLITE_ACCESS_EX
12000 49 53 54 53 2c 20 74 68 65 20 78 41 63 63 65 73  ISTS, the xAcces
12010 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70  s method.** simp
12020 6c 79 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  ly checks whethe
12030 72 20 74 68 65 20 66 69 6c 65 20 65 78 69 73 74  r the file exist
12040 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54  s..** With SQLIT
12050 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49  E_ACCESS_READWRI
12060 54 45 2c 20 74 68 65 20 78 41 63 63 65 73 73 20  TE, the xAccess 
12070 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73  method.** checks
12080 20 77 68 65 74 68 65 72 20 74 68 65 20 6e 61 6d   whether the nam
12090 65 64 20 64 69 72 65 63 74 6f 72 79 20 69 73 20  ed directory is 
120a0 62 6f 74 68 20 72 65 61 64 61 62 6c 65 20 61 6e  both readable an
120b0 64 20 77 72 69 74 61 62 6c 65 0a 2a 2a 20 28 69  d writable.** (i
120c0 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69  n other words, i
120d0 66 20 66 69 6c 65 73 20 63 61 6e 20 62 65 20 61  f files can be a
120e0 64 64 65 64 2c 20 72 65 6d 6f 76 65 64 2c 20 61  dded, removed, a
120f0 6e 64 20 72 65 6e 61 6d 65 64 20 77 69 74 68 69  nd renamed withi
12100 6e 0a 2a 2a 20 74 68 65 20 64 69 72 65 63 74 6f  n.** the directo
12110 72 79 29 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49  ry)..** The SQLI
12120 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52  TE_ACCESS_READWR
12130 49 54 45 20 63 6f 6e 73 74 61 6e 74 20 69 73 20  ITE constant is 
12140 63 75 72 72 65 6e 74 6c 79 20 75 73 65 64 20 6f  currently used o
12150 6e 6c 79 20 62 79 20 74 68 65 0a 2a 2a 20 5b 74  nly by the.** [t
12160 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74  emp_store_direct
12170 6f 72 79 20 70 72 61 67 6d 61 5d 2c 20 74 68 6f  ory pragma], tho
12180 75 67 68 20 74 68 69 73 20 63 6f 75 6c 64 20 63  ugh this could c
12190 68 61 6e 67 65 20 69 6e 20 61 20 66 75 74 75 72  hange in a futur
121a0 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66 20  e.** release of 
121b0 53 51 4c 69 74 65 2e 0a 2a 2a 20 57 69 74 68 20  SQLite..** With 
121c0 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
121d0 41 44 2c 20 74 68 65 20 78 41 63 63 65 73 73 20  AD, the xAccess 
121e0 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73  method.** checks
121f0 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69 6c   whether the fil
12200 65 20 69 73 20 72 65 61 64 61 62 6c 65 2e 20 20  e is readable.  
12210 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53  The SQLITE_ACCES
12220 53 5f 52 45 41 44 20 63 6f 6e 73 74 61 6e 74 20  S_READ constant 
12230 69 73 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20  is.** currently 
12240 75 6e 75 73 65 64 2c 20 74 68 6f 75 67 68 20 69  unused, though i
12250 74 20 6d 69 67 68 74 20 62 65 20 75 73 65 64 20  t might be used 
12260 69 6e 20 61 20 66 75 74 75 72 65 20 72 65 6c 65  in a future rele
12270 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65  ase of.** SQLite
12280 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
12290 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54  ITE_ACCESS_EXIST
122a0 53 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53  S    0.#define S
122b0 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
122c0 44 57 52 49 54 45 20 31 20 20 20 2f 2a 20 55 73  DWRITE 1   /* Us
122d0 65 64 20 62 79 20 50 52 41 47 4d 41 20 74 65 6d  ed by PRAGMA tem
122e0 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72  p_store_director
122f0 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
12300 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20  ITE_ACCESS_READ 
12310 20 20 20 20 20 32 20 20 20 2f 2a 20 55 6e 75 73       2   /* Unus
12320 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ed */../*.** CAP
12330 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72  I3REF: Flags for
12340 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20 56 46   the xShmLock VF
12350 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54  S method.**.** T
12360 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  hese integer con
12370 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 74 68  stants define th
12380 65 20 76 61 72 69 6f 75 73 20 6c 6f 63 6b 69 6e  e various lockin
12390 67 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20  g operations.** 
123a0 61 6c 6c 6f 77 65 64 20 62 79 20 74 68 65 20 78  allowed by the x
123b0 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f  ShmLock method o
123c0 66 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  f [sqlite3_io_me
123d0 74 68 6f 64 73 5d 2e 20 20 54 68 65 0a 2a 2a 20  thods].  The.** 
123e0 66 6f 6c 6c 6f 77 69 6e 67 20 61 72 65 20 74 68  following are th
123f0 65 20 6f 6e 6c 79 20 6c 65 67 61 6c 20 63 6f 6d  e only legal com
12400 62 69 6e 61 74 69 6f 6e 73 20 6f 66 20 66 6c 61  binations of fla
12410 67 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 68  gs to the.** xSh
12420 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a 2a 2a  mLock method:.**
12430 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
12440 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43    SQLITE_SHM_LOC
12450 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53  K | SQLITE_SHM_S
12460 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53  HARED.** <li>  S
12470 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c  QLITE_SHM_LOCK |
12480 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c   SQLITE_SHM_EXCL
12490 55 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53  USIVE.** <li>  S
124a0 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b  QLITE_SHM_UNLOCK
124b0 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48   | SQLITE_SHM_SH
124c0 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51  ARED.** <li>  SQ
124d0 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20  LITE_SHM_UNLOCK 
124e0 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43  | SQLITE_SHM_EXC
124f0 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a  LUSIVE.** </ul>.
12500 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c 6f 63  **.** When unloc
12510 6b 69 6e 67 2c 20 74 68 65 20 73 61 6d 65 20 53  king, the same S
12520 48 41 52 45 44 20 6f 72 20 45 58 43 4c 55 53 49  HARED or EXCLUSI
12530 56 45 20 66 6c 61 67 20 6d 75 73 74 20 62 65 20  VE flag must be 
12540 73 75 70 70 6c 69 65 64 20 61 73 0a 2a 2a 20 77  supplied as.** w
12550 61 73 20 67 69 76 65 6e 20 6e 6f 20 74 68 65 20  as given no the 
12560 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6c 6f  corresponding lo
12570 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ck.  .**.** The 
12580 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20  xShmLock method 
12590 63 61 6e 20 74 72 61 6e 73 69 74 69 6f 6e 20 62  can transition b
125a0 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20  etween unlocked 
125b0 61 6e 64 20 53 48 41 52 45 44 20 6f 72 0a 2a 2a  and SHARED or.**
125c0 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65   between unlocke
125d0 64 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e  d and EXCLUSIVE.
125e0 20 20 49 74 20 63 61 6e 6e 6f 74 20 74 72 61 6e    It cannot tran
125f0 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 53  sition between S
12600 48 41 52 45 44 0a 2a 2a 20 61 6e 64 20 45 58 43  HARED.** and EXC
12610 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23 64 65 66 69  LUSIVE..*/.#defi
12620 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e  ne SQLITE_SHM_UN
12630 4c 4f 43 4b 20 20 20 20 20 20 20 31 0a 23 64 65  LOCK       1.#de
12640 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f  fine SQLITE_SHM_
12650 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 32 0a 23  LOCK         2.#
12660 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
12670 4d 5f 53 48 41 52 45 44 20 20 20 20 20 20 20 34  M_SHARED       4
12680 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
12690 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 20 20 20  SHM_EXCLUSIVE   
126a0 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52   8../*.** CAPI3R
126b0 45 46 3a 20 4d 61 78 69 6d 75 6d 20 78 53 68 6d  EF: Maximum xShm
126c0 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a 2a 2a  Lock index.**.**
126d0 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65   The xShmLock me
126e0 74 68 6f 64 20 6f 6e 20 5b 73 71 6c 69 74 65 33  thod on [sqlite3
126f0 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d 61 79  _io_methods] may
12700 20 75 73 65 20 76 61 6c 75 65 73 0a 2a 2a 20 62   use values.** b
12710 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68 69  etween 0 and thi
12720 73 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61 73  s upper bound as
12730 20 69 74 73 20 22 6f 66 66 73 65 74 22 20 61 72   its "offset" ar
12740 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 53  gument..** The S
12750 51 4c 69 74 65 20 63 6f 72 65 20 77 69 6c 6c 20  QLite core will 
12760 6e 65 76 65 72 20 61 74 74 65 6d 70 74 20 74 6f  never attempt to
12770 20 61 63 71 75 69 72 65 20 6f 72 20 72 65 6c 65   acquire or rele
12780 61 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20 6f 75  ase a.** lock ou
12790 74 73 69 64 65 20 6f 66 20 74 68 69 73 20 72 61  tside of this ra
127a0 6e 67 65 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nge.*/.#define S
127b0 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43 4b 20  QLITE_SHM_NLOCK 
127c0 20 20 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a         8.../*.**
127d0 20 43 41 50 49 33 52 45 46 3a 20 49 6e 69 74 69   CAPI3REF: Initi
127e0 61 6c 69 7a 65 20 54 68 65 20 53 51 4c 69 74 65  alize The SQLite
127f0 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 5e   Library.**.** ^
12800 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  The sqlite3_init
12810 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65  ialize() routine
12820 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65   initializes the
12830 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69 62 72 61  .** SQLite libra
12840 72 79 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  ry.  ^The sqlite
12850 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 72 6f 75  3_shutdown() rou
12860 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61  tine.** dealloca
12870 74 65 73 20 61 6e 79 20 72 65 73 6f 75 72 63 65  tes any resource
12880 73 20 74 68 61 74 20 77 65 72 65 20 61 6c 6c 6f  s that were allo
12890 63 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33  cated by sqlite3
128a0 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a  _initialize()..*
128b0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
128c0 20 61 72 65 20 64 65 73 69 67 6e 65 64 20 74 6f   are designed to
128d0 20 61 69 64 20 69 6e 20 70 72 6f 63 65 73 73 20   aid in process 
128e0 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61  initialization a
128f0 6e 64 0a 2a 2a 20 73 68 75 74 64 6f 77 6e 20 6f  nd.** shutdown o
12900 6e 20 65 6d 62 65 64 64 65 64 20 73 79 73 74 65  n embedded syste
12910 6d 73 2e 20 20 57 6f 72 6b 73 74 61 74 69 6f 6e  ms.  Workstation
12920 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 75 73   applications us
12930 69 6e 67 0a 2a 2a 20 53 51 4c 69 74 65 20 6e 6f  ing.** SQLite no
12940 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 6e 65  rmally do not ne
12950 65 64 20 74 6f 20 69 6e 76 6f 6b 65 20 65 69 74  ed to invoke eit
12960 68 65 72 20 6f 66 20 74 68 65 73 65 20 72 6f 75  her of these rou
12970 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63  tines..**.** A c
12980 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69  all to sqlite3_i
12990 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 61  nitialize() is a
129a0 6e 20 22 65 66 66 65 63 74 69 76 65 22 20 63 61  n "effective" ca
129b0 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a 2a 20 74  ll if it is.** t
129c0 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71  he first time sq
129d0 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
129e0 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 64 75  () is invoked du
129f0 72 69 6e 67 20 74 68 65 20 6c 69 66 65 74 69 6d  ring the lifetim
12a00 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63  e of.** the proc
12a10 65 73 73 2c 20 6f 72 20 69 66 20 69 74 20 69 73  ess, or if it is
12a20 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20   the first time 
12a30 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
12a40 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a  ze() is invoked.
12a50 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63  ** following a c
12a60 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
12a70 68 75 74 64 6f 77 6e 28 29 2e 20 20 5e 28 4f 6e  hutdown().  ^(On
12a80 6c 79 20 61 6e 20 65 66 66 65 63 74 69 76 65 20  ly an effective 
12a90 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 74  call.** of sqlit
12aa0 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
12ab0 64 6f 65 73 20 61 6e 79 20 69 6e 69 74 69 61 6c  does any initial
12ac0 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74  ization.  All ot
12ad0 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 65  her calls.** are
12ae0 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73   harmless no-ops
12af0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c  .)^.**.** A call
12b00 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74   to sqlite3_shut
12b10 64 6f 77 6e 28 29 20 69 73 20 61 6e 20 22 65 66  down() is an "ef
12b20 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66  fective" call if
12b30 20 69 74 20 69 73 20 74 68 65 20 66 69 72 73 74   it is the first
12b40 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  .** call to sqli
12b50 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 73  te3_shutdown() s
12b60 69 6e 63 65 20 74 68 65 20 6c 61 73 74 20 73 71  ince the last sq
12b70 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
12b80 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61  ().  ^(Only.** a
12b90 6e 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c  n effective call
12ba0 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74   to sqlite3_shut
12bb0 64 6f 77 6e 28 29 20 64 6f 65 73 20 61 6e 79 20  down() does any 
12bc0 64 65 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  deinitialization
12bd0 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65 72 20 76  ..** All other v
12be0 61 6c 69 64 20 63 61 6c 6c 73 20 74 6f 20 73 71  alid calls to sq
12bf0 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
12c00 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f   are harmless no
12c10 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  -ops.)^.**.** Th
12c20 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
12c30 6c 69 7a 65 28 29 20 69 6e 74 65 72 66 61 63 65  lize() interface
12c40 20 69 73 20 74 68 72 65 61 64 73 61 66 65 2c 20   is threadsafe, 
12c50 62 75 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74  but sqlite3_shut
12c60 64 6f 77 6e 28 29 0a 2a 2a 20 69 73 20 6e 6f 74  down().** is not
12c70 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73  .  The sqlite3_s
12c80 68 75 74 64 6f 77 6e 28 29 20 69 6e 74 65 72 66  hutdown() interf
12c90 61 63 65 20 6d 75 73 74 20 6f 6e 6c 79 20 62 65  ace must only be
12ca0 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 0a 2a   called from a.*
12cb0 2a 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e  * single thread.
12cc0 20 20 41 6c 6c 20 6f 70 65 6e 20 5b 64 61 74 61    All open [data
12cd0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
12ce0 5d 20 6d 75 73 74 20 62 65 20 63 6c 6f 73 65 64  ] must be closed
12cf0 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74 68 65   and all.** othe
12d00 72 20 53 51 4c 69 74 65 20 72 65 73 6f 75 72 63  r SQLite resourc
12d10 65 73 20 6d 75 73 74 20 62 65 20 64 65 61 6c 6c  es must be deall
12d20 6f 63 61 74 65 64 20 70 72 69 6f 72 20 74 6f 20  ocated prior to 
12d30 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69  invoking.** sqli
12d40 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 0a  te3_shutdown()..
12d50 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68 65  **.** Among othe
12d60 72 20 74 68 69 6e 67 73 2c 20 5e 73 71 6c 69 74  r things, ^sqlit
12d70 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
12d80 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73  will invoke.** s
12d90 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
12da0 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c 20 5e 73  .  Similarly, ^s
12db0 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
12dc0 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f 6b 65  ).** will invoke
12dd0 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
12de0 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  )..**.** ^The sq
12df0 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
12e00 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
12e10 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  ns [SQLITE_OK] o
12e20 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a 20 5e 49  n success..** ^I
12e30 66 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f  f for some reaso
12e40 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  n, sqlite3_initi
12e50 61 6c 69 7a 65 28 29 20 69 73 20 75 6e 61 62 6c  alize() is unabl
12e60 65 20 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65 0a  e to initialize.
12e70 2a 2a 20 74 68 65 20 6c 69 62 72 61 72 79 20 28  ** the library (
12e80 70 65 72 68 61 70 73 20 69 74 20 69 73 20 75 6e  perhaps it is un
12e90 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  able to allocate
12ea0 20 61 20 6e 65 65 64 65 64 20 72 65 73 6f 75 72   a needed resour
12eb0 63 65 20 73 75 63 68 0a 2a 2a 20 61 73 20 61 20  ce such.** as a 
12ec0 6d 75 74 65 78 29 20 69 74 20 72 65 74 75 72 6e  mutex) it return
12ed0 73 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65  s an [error code
12ee0 5d 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  ] other than [SQ
12ef0 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20  LITE_OK]..**.** 
12f00 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  ^The sqlite3_ini
12f10 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e  tialize() routin
12f20 65 20 69 73 20 63 61 6c 6c 65 64 20 69 6e 74 65  e is called inte
12f30 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f  rnally by many o
12f40 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69  ther.** SQLite i
12f50 6e 74 65 72 66 61 63 65 73 20 73 6f 20 74 68 61  nterfaces so tha
12f60 74 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  t an application
12f70 20 75 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f   usually does no
12f80 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76  t need to.** inv
12f90 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  oke sqlite3_init
12fa0 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c  ialize() directl
12fb0 79 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c  y.  For example,
12fc0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
12fd0 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74  ].** calls sqlit
12fe0 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
12ff0 73 6f 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69  so the SQLite li
13000 62 72 61 72 79 20 77 69 6c 6c 20 62 65 20 61 75  brary will be au
13010 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69  tomatically.** i
13020 6e 69 74 69 61 6c 69 7a 65 64 20 77 68 65 6e 20  nitialized when 
13030 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
13040 20 69 73 20 63 61 6c 6c 65 64 20 69 66 20 69 74   is called if it
13050 20 68 61 73 20 6e 6f 74 20 62 65 20 69 6e 69 74   has not be init
13060 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61  ialized.** alrea
13070 64 79 2e 20 20 5e 48 6f 77 65 76 65 72 2c 20 69  dy.  ^However, i
13080 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
13090 69 6c 65 64 20 77 69 74 68 20 74 68 65 20 5b 53  iled with the [S
130a0 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49  QLITE_OMIT_AUTOI
130b0 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d  NIT].** compile-
130c0 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 68 65  time option, the
130d0 6e 20 74 68 65 20 61 75 74 6f 6d 61 74 69 63 20  n the automatic 
130e0 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
130f0 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a  _initialize().**
13100 20 61 72 65 20 6f 6d 69 74 74 65 64 20 61 6e 64   are omitted and
13110 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
13120 20 6d 75 73 74 20 63 61 6c 6c 20 73 71 6c 69 74   must call sqlit
13130 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
13140 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70 72 69 6f  directly.** prio
13150 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f  r to using any o
13160 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65  ther SQLite inte
13170 72 66 61 63 65 2e 20 20 46 6f 72 20 6d 61 78 69  rface.  For maxi
13180 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69 74 79 2c  mum portability,
13190 0a 2a 2a 20 69 74 20 69 73 20 72 65 63 6f 6d 6d  .** it is recomm
131a0 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c 69  ended that appli
131b0 63 61 74 69 6f 6e 73 20 61 6c 77 61 79 73 20 69  cations always i
131c0 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e  nvoke sqlite3_in
131d0 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 64 69  itialize().** di
131e0 72 65 63 74 6c 79 20 70 72 69 6f 72 20 74 6f 20  rectly prior to 
131f0 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20  using any other 
13200 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
13210 2e 20 20 46 75 74 75 72 65 20 72 65 6c 65 61 73  .  Future releas
13220 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20  es.** of SQLite 
13230 6d 61 79 20 72 65 71 75 69 72 65 20 74 68 69 73  may require this
13240 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  .  In other word
13250 73 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  s, the behavior 
13260 65 78 68 69 62 69 74 65 64 0a 2a 2a 20 77 68 65  exhibited.** whe
13270 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  n SQLite is comp
13280 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54  iled with [SQLIT
13290 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d  E_OMIT_AUTOINIT]
132a0 20 6d 69 67 68 74 20 62 65 63 6f 6d 65 20 74 68   might become th
132b0 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20 62 65 68  e.** default beh
132c0 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65 20 66 75  avior in some fu
132d0 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 20  ture release of 
132e0 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  SQLite..**.** Th
132f0 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  e sqlite3_os_ini
13300 74 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73  t() routine does
13310 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65   operating-syste
13320 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 69 6e  m specific.** in
13330 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20  itialization of 
13340 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61  the SQLite libra
13350 72 79 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  ry.  The sqlite3
13360 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f 75  _os_end().** rou
13370 74 69 6e 65 20 75 6e 64 6f 65 73 20 74 68 65 20  tine undoes the 
13380 65 66 66 65 63 74 20 6f 66 20 73 71 6c 69 74 65  effect of sqlite
13390 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 54 79  3_os_init().  Ty
133a0 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a 2a 20 70  pical tasks.** p
133b0 65 72 66 6f 72 6d 65 64 20 62 79 20 74 68 65 73  erformed by thes
133c0 65 20 72 6f 75 74 69 6e 65 73 20 69 6e 63 6c 75  e routines inclu
133d0 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72  de allocation or
133e0 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a   deallocation.**
133f0 20 6f 66 20 73 74 61 74 69 63 20 72 65 73 6f 75   of static resou
13400 72 63 65 73 2c 20 69 6e 69 74 69 61 6c 69 7a 61  rces, initializa
13410 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c 20 76  tion of global v
13420 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 65 74  ariables,.** set
13430 74 69 6e 67 20 75 70 20 61 20 64 65 66 61 75 6c  ting up a defaul
13440 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  t [sqlite3_vfs] 
13450 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65 74 74 69  module, or setti
13460 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65 66 61 75  ng up.** a defau
13470 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  lt configuration
13480 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
13490 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a  config()]..**.**
134a0 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
134b0 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 69 6e   should never in
134c0 76 6f 6b 65 20 65 69 74 68 65 72 20 73 71 6c 69  voke either sqli
134d0 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a  te3_os_init().**
134e0 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65   or sqlite3_os_e
134f0 6e 64 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20  nd() directly.  
13500 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
13510 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f  should only invo
13520 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e  ke.** sqlite3_in
13530 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 20 73  itialize() and s
13540 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
13550 29 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  ).  The sqlite3_
13560 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 6e 74  os_init().** int
13570 65 72 66 61 63 65 20 69 73 20 63 61 6c 6c 65 64  erface is called
13580 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62   automatically b
13590 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  y sqlite3_initia
135a0 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 73 71  lize() and.** sq
135b0 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 69  lite3_os_end() i
135c0 73 20 63 61 6c 6c 65 64 20 62 79 20 73 71 6c 69  s called by sqli
135d0 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20  te3_shutdown(). 
135e0 20 41 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20   Appropriate.** 
135f0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
13600 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  for sqlite3_os_i
13610 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65  nit() and sqlite
13620 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 61 72  3_os_end().** ar
13630 65 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c  e built into SQL
13640 69 74 65 20 77 68 65 6e 20 69 74 20 69 73 20 63  ite when it is c
13650 6f 6d 70 69 6c 65 64 20 66 6f 72 20 55 6e 69 78  ompiled for Unix
13660 2c 20 57 69 6e 64 6f 77 73 2c 20 6f 72 20 4f 53  , Windows, or OS
13670 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63 75 73  /2..** When [cus
13680 74 6f 6d 20 62 75 69 6c 64 73 20 7c 20 62 75 69  tom builds | bui
13690 6c 74 20 66 6f 72 20 6f 74 68 65 72 20 70 6c 61  lt for other pla
136a0 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e  tforms].** (usin
136b0 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 53  g the [SQLITE_OS
136c0 5f 4f 54 48 45 52 3d 31 5d 20 63 6f 6d 70 69 6c  _OTHER=1] compil
136d0 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e  e-time.** option
136e0 29 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  ) the applicatio
136f0 6e 20 6d 75 73 74 20 73 75 70 70 6c 79 20 61 20  n must supply a 
13700 73 75 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65  suitable impleme
13710 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73  ntation for.** s
13720 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
13730 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f   and sqlite3_os_
13740 65 6e 64 28 29 2e 20 20 41 6e 20 61 70 70 6c 69  end().  An appli
13750 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a  cation-supplied.
13760 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
13770 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f  n of sqlite3_os_
13780 69 6e 69 74 28 29 20 6f 72 20 73 71 6c 69 74 65  init() or sqlite
13790 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75  3_os_end().** mu
137a0 73 74 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  st return [SQLIT
137b0 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73  E_OK] on success
137c0 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72 20   and some other 
137d0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f  [error code] upo
137e0 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f  n.** failure..*/
137f0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
13800 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
13810 7a 65 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45  ze(void);.SQLITE
13820 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
13830 5f 73 68 75 74 64 6f 77 6e 28 76 6f 69 64 29 3b  _shutdown(void);
13840 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
13850 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
13860 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50  void);.SQLITE_AP
13870 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73  I int sqlite3_os
13880 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a  _end(void);../*.
13890 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
138a0 66 69 67 75 72 69 6e 67 20 54 68 65 20 53 51 4c  figuring The SQL
138b0 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a  ite Library.**.*
138c0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  * The sqlite3_co
138d0 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65  nfig() interface
138e0 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65   is used to make
138f0 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72   global configur
13900 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73  ation.** changes
13910 20 74 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f 72   to SQLite in or
13920 64 65 72 20 74 6f 20 74 75 6e 65 20 53 51 4c 69  der to tune SQLi
13930 74 65 20 74 6f 20 74 68 65 20 73 70 65 63 69 66  te to the specif
13940 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74  ic needs of.** t
13950 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20  he application. 
13960 20 54 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6e   The default con
13970 66 69 67 75 72 61 74 69 6f 6e 20 69 73 20 72 65  figuration is re
13980 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f  commended for mo
13990 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f  st.** applicatio
139a0 6e 73 20 61 6e 64 20 73 6f 20 74 68 69 73 20 72  ns and so this r
139b0 6f 75 74 69 6e 65 20 69 73 20 75 73 75 61 6c 6c  outine is usuall
139c0 79 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 79 2e  y not necessary.
139d0 20 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69    It is.** provi
139e0 64 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20 72  ded to support r
139f0 61 72 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  are applications
13a00 20 77 69 74 68 20 75 6e 75 73 75 61 6c 20 6e 65   with unusual ne
13a10 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  eds..**.** The s
13a20 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
13a30 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74  interface is not
13a40 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 54 68   threadsafe.  Th
13a50 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a  e application.**
13a60 20 6d 75 73 74 20 69 6e 73 75 72 65 20 74 68 61   must insure tha
13a70 74 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69 74  t no other SQLit
13a80 65 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  e interfaces are
13a90 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68 65   invoked by othe
13aa0 72 0a 2a 2a 20 74 68 72 65 61 64 73 20 77 68 69  r.** threads whi
13ab0 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  le sqlite3_confi
13ac0 67 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20  g() is running. 
13ad0 20 46 75 72 74 68 65 72 6d 6f 72 65 2c 20 73 71   Furthermore, sq
13ae0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 0a 2a  lite3_config().*
13af0 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e  * may only be in
13b00 76 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f 20 6c  voked prior to l
13b10 69 62 72 61 72 79 20 69 6e 69 74 69 61 6c 69 7a  ibrary initializ
13b20 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b  ation using.** [
13b30 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
13b40 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 73  ze()] or after s
13b50 68 75 74 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69  hutdown by [sqli
13b60 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e  te3_shutdown()].
13b70 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  .** ^If sqlite3_
13b80 63 6f 6e 66 69 67 28 29 20 69 73 20 63 61 6c 6c  config() is call
13b90 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65  ed after [sqlite
13ba0 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20  3_initialize()] 
13bb0 61 6e 64 20 62 65 66 6f 72 65 0a 2a 2a 20 5b 73  and before.** [s
13bc0 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
13bd0 29 5d 20 74 68 65 6e 20 69 74 20 77 69 6c 6c 20  )] then it will 
13be0 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49  return SQLITE_MI
13bf0 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68  SUSE..** Note, h
13c00 6f 77 65 76 65 72 2c 20 74 68 61 74 20 5e 73 71  owever, that ^sq
13c10 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 63  lite3_config() c
13c20 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 73 20  an be called as 
13c30 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 69  part of the.** i
13c40 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
13c50 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   an application-
13c60 64 65 66 69 6e 65 64 20 5b 73 71 6c 69 74 65 33  defined [sqlite3
13c70 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a  _os_init()]..**.
13c80 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
13c90 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
13ca0 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 61 6e 20  _config() is an 
13cb0 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 63 6f 6e 66  integer.** [conf
13cc0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
13cd0 5d 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65  ] that determine
13ce0 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f 70 65 72  s.** what proper
13cf0 74 79 20 6f 66 20 53 51 4c 69 74 65 20 69 73 20  ty of SQLite is 
13d00 74 6f 20 62 65 20 63 6f 6e 66 69 67 75 72 65 64  to be configured
13d10 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 61 72  .  Subsequent ar
13d20 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 72 79 20  guments.** vary 
13d30 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65  depending on the
13d40 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20   [configuration 
13d50 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68  option].** in th
13d60 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
13d70 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 61 20  ..**.** ^When a 
13d80 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
13d90 74 69 6f 6e 20 69 73 20 73 65 74 2c 20 73 71 6c  tion is set, sql
13da0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 72 65  ite3_config() re
13db0 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
13dc0 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6f 70  ]..** ^If the op
13dd0 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20  tion is unknown 
13de0 6f 72 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61  or SQLite is una
13df0 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 6f  ble to set the o
13e00 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 68  ption.** then th
13e10 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  is routine retur
13e20 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65  ns a non-zero [e
13e30 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 53  rror code]..*/.S
13e40 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
13e50 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74  lite3_config(int
13e60 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  , ...);../*.** C
13e70 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75  API3REF: Configu
13e80 72 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  re database conn
13e90 65 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  ections.**.** Th
13ea0 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e  e sqlite3_db_con
13eb0 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20  fig() interface 
13ec0 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20  is used to make 
13ed0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a  configuration.**
13ee0 20 63 68 61 6e 67 65 73 20 74 6f 20 61 20 5b 64   changes to a [d
13ef0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
13f00 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65 72 66  on].  The interf
13f10 61 63 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74  ace is similar t
13f20 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  o.** [sqlite3_co
13f30 6e 66 69 67 28 29 5d 20 65 78 63 65 70 74 20 74  nfig()] except t
13f40 68 61 74 20 74 68 65 20 63 68 61 6e 67 65 73 20  hat the changes 
13f50 61 70 70 6c 79 20 74 6f 20 61 20 73 69 6e 67 6c  apply to a singl
13f60 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  e.** [database c
13f70 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70 65 63  onnection] (spec
13f80 69 66 69 65 64 20 69 6e 20 74 68 65 20 66 69 72  ified in the fir
13f90 73 74 20 61 72 67 75 6d 65 6e 74 29 2e 0a 2a 2a  st argument)..**
13fa0 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61  .** The second a
13fb0 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
13fc0 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44 2c 56  e3_db_config(D,V
13fd0 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a 2a 2a  ,...)  is the.**
13fe0 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49   [SQLITE_DBCONFI
13ff0 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 7c 20 63 6f  G_LOOKASIDE | co
14000 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62  nfiguration verb
14010 5d 20 2d 20 61 6e 20 69 6e 74 65 67 65 72 20 63  ] - an integer c
14020 6f 64 65 20 0a 2a 2a 20 74 68 61 74 20 69 6e 64  ode .** that ind
14030 69 63 61 74 65 73 20 77 68 61 74 20 61 73 70 65  icates what aspe
14040 63 74 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62  ct of the [datab
14050 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
14060 69 73 20 62 65 69 6e 67 20 63 6f 6e 66 69 67 75  is being configu
14070 72 65 64 2e 0a 2a 2a 20 53 75 62 73 65 71 75 65  red..** Subseque
14080 6e 74 20 61 72 67 75 6d 65 6e 74 73 20 76 61 72  nt arguments var
14090 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  y depending on t
140a0 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  he configuration
140b0 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61   verb..**.** ^Ca
140c0 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 64  lls to sqlite3_d
140d0 62 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72  b_config() retur
140e0 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66 20 61  n SQLITE_OK if a
140f0 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 74 68  nd only if.** th
14100 65 20 63 61 6c 6c 20 69 73 20 63 6f 6e 73 69 64  e call is consid
14110 65 72 65 64 20 73 75 63 63 65 73 73 66 75 6c 2e  ered successful.
14120 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
14130 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  nt sqlite3_db_co
14140 6e 66 69 67 28 73 71 6c 69 74 65 33 2a 2c 20 69  nfig(sqlite3*, i
14150 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a  nt op, ...);../*
14160 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65  .** CAPI3REF: Me
14170 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20  mory Allocation 
14180 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 41  Routines.**.** A
14190 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
141a0 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65  is object define
141b0 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20  s the interface 
141c0 62 65 74 77 65 65 6e 20 53 51 4c 69 74 65 0a 2a  between SQLite.*
141d0 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c 20  * and low-level 
141e0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
141f0 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a  n routines..**.*
14200 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73  * This object is
14210 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e   used in only on
14220 65 20 70 6c 61 63 65 20 69 6e 20 74 68 65 20 53  e place in the S
14230 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e  QLite interface.
14240 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f  .** A pointer to
14250 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
14260 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 74  this object is t
14270 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  he argument to.*
14280 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
14290 67 28 29 5d 20 77 68 65 6e 20 74 68 65 20 63 6f  g()] when the co
142a0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
142b0 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 45  on is.** [SQLITE
142c0 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20  _CONFIG_MALLOC] 
142d0 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  or [SQLITE_CONFI
142e0 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a  G_GETMALLOC].  .
142f0 2a 2a 20 42 79 20 63 72 65 61 74 69 6e 67 20 61  ** By creating a
14300 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
14310 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64  is object.** and
14320 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b   passing it to [
14330 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28  sqlite3_config](
14340 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
14350 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 69 6e  ALLOC]).** durin
14360 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c  g configuration,
14370 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
14380 63 61 6e 20 73 70 65 63 69 66 79 20 61 6e 20 61  can specify an a
14390 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65  lternative.** me
143a0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
143b0 73 75 62 73 79 73 74 65 6d 20 66 6f 72 20 53 51  subsystem for SQ
143c0 4c 69 74 65 20 74 6f 20 75 73 65 20 66 6f 72 20  Lite to use for 
143d0 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 64 79  all of its.** dy
143e0 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65  namic memory nee
143f0 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  ds..**.** Note t
14400 68 61 74 20 53 51 4c 69 74 65 20 63 6f 6d 65 73  hat SQLite comes
14410 20 77 69 74 68 20 73 65 76 65 72 61 6c 20 5b 62   with several [b
14420 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61  uilt-in memory a
14430 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 74 68  llocators].** th
14440 61 74 20 61 72 65 20 70 65 72 66 65 63 74 6c 79  at are perfectly
14450 20 61 64 65 71 75 61 74 65 20 66 6f 72 20 74 68   adequate for th
14460 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20 6d  e overwhelming m
14470 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69  ajority of appli
14480 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74  cations.** and t
14490 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63 74 20  hat this object 
144a0 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20 74  is only useful t
144b0 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69 74  o a tiny minorit
144c0 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e  y of application
144d0 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63 69 61  s.** with specia
144e0 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c  lized memory all
144f0 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72 65 6d  ocation requirem
14500 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62 6a 65  ents.  This obje
14510 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 73  ct is.** also us
14520 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e  ed during testin
14530 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e 20 6f  g of SQLite in o
14540 72 64 65 72 20 74 6f 20 73 70 65 63 69 66 79 20  rder to specify 
14550 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a  an alternative.*
14560 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * memory allocat
14570 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 65  or that simulate
14580 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d  s memory out-of-
14590 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f 6e  memory condition
145a0 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 6f  s in.** order to
145b0 20 76 65 72 69 66 79 20 74 68 61 74 20 53 51 4c   verify that SQL
145c0 69 74 65 20 72 65 63 6f 76 65 72 73 20 67 72 61  ite recovers gra
145d0 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75 63  cefully from suc
145e0 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 2e  h.** conditions.
145f0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c 6c  .**.** The xMall
14600 6f 63 2c 20 78 52 65 61 6c 6c 6f 63 2c 20 61 6e  oc, xRealloc, an
14610 64 20 78 46 72 65 65 20 6d 65 74 68 6f 64 73 20  d xFree methods 
14620 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20 74  must work like t
14630 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 2c 20  he.** malloc(), 
14640 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72  realloc() and fr
14650 65 65 28 29 20 66 75 6e 63 74 69 6f 6e 73 20 66  ee() functions f
14660 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64  rom the standard
14670 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 5e   C library..** ^
14680 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65  SQLite guarantee
14690 73 20 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e  s that the secon
146a0 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  d argument to.**
146b0 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 61 6c 77   xRealloc is alw
146c0 61 79 73 20 61 20 76 61 6c 75 65 20 72 65 74 75  ays a value retu
146d0 72 6e 65 64 20 62 79 20 61 20 70 72 69 6f 72 20  rned by a prior 
146e0 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 75 70  call to xRoundup
146f0 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68  ..**.** xSize sh
14700 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20  ould return the 
14710 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f  allocated size o
14720 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  f a memory alloc
14730 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75  ation.** previou
14740 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  sly obtained fro
14750 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65  m xMalloc or xRe
14760 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f  alloc.  The allo
14770 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73  cated size.** is
14780 20 61 6c 77 61 79 73 20 61 74 20 6c 65 61 73 74   always at least
14790 20 61 73 20 62 69 67 20 61 73 20 74 68 65 20 72   as big as the r
147a0 65 71 75 65 73 74 65 64 20 73 69 7a 65 20 62 75  equested size bu
147b0 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72 2e  t may be larger.
147c0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e  .**.** The xRoun
147d0 64 75 70 20 6d 65 74 68 6f 64 20 72 65 74 75 72  dup method retur
147e0 6e 73 20 77 68 61 74 20 77 6f 75 6c 64 20 62 65  ns what would be
147f0 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73   the allocated s
14800 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f  ize of.** a memo
14810 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69  ry allocation gi
14820 76 65 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72  ven a particular
14830 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 2e   requested size.
14840 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a    Most memory.**
14850 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e   allocators roun
14860 64 20 75 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  d up memory allo
14870 63 61 74 69 6f 6e 73 20 61 74 20 6c 65 61 73 74  cations at least
14880 20 74 6f 20 74 68 65 20 6e 65 78 74 20 6d 75 6c   to the next mul
14890 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20  tiple.** of 8.  
148a0 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20  Some allocators 
148b0 72 6f 75 6e 64 20 75 70 20 74 6f 20 61 20 6c 61  round up to a la
148c0 72 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72  rger multiple or
148d0 20 74 6f 20 61 20 70 6f 77 65 72 20 6f 66 20 32   to a power of 2
148e0 2e 0a 2a 2a 20 45 76 65 72 79 20 6d 65 6d 6f 72  ..** Every memor
148f0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71  y allocation req
14900 75 65 73 74 20 63 6f 6d 69 6e 67 20 69 6e 20 74  uest coming in t
14910 68 72 6f 75 67 68 20 5b 73 71 6c 69 74 65 33 5f  hrough [sqlite3_
14920 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20  malloc()].** or 
14930 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
14940 28 29 5d 20 66 69 72 73 74 20 63 61 6c 6c 73 20  ()] first calls 
14950 78 52 6f 75 6e 64 75 70 2e 20 20 49 66 20 78 52  xRoundup.  If xR
14960 6f 75 6e 64 75 70 20 72 65 74 75 72 6e 73 20 30  oundup returns 0
14970 2c 20 0a 2a 2a 20 74 68 61 74 20 63 61 75 73 65  , .** that cause
14980 73 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  s the correspond
14990 69 6e 67 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ing memory alloc
149a0 61 74 69 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a  ation to fail..*
149b0 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74 20 6d  *.** The xInit m
149c0 65 74 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65  ethod initialize
149d0 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  s the memory all
149e0 6f 63 61 74 6f 72 2e 20 20 28 46 6f 72 20 65 78  ocator.  (For ex
149f0 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67  ample,.** it mig
14a00 68 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20  ht allocate any 
14a10 72 65 71 75 69 72 65 20 6d 75 74 65 78 65 73 20  require mutexes 
14a20 6f 72 20 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e  or initialize in
14a30 74 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73  ternal data.** s
14a40 74 72 75 63 74 75 72 65 73 2e 20 20 54 68 65 20  tructures.  The 
14a50 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64  xShutdown method
14a60 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64   is invoked (ind
14a70 69 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b  irectly) by.** [
14a80 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
14a90 28 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20 64  ()] and should d
14aa0 65 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65  eallocate any re
14ab0 73 6f 75 72 63 65 73 20 61 63 71 75 69 72 65 64  sources acquired
14ac0 0a 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20 20 54  .** by xInit.  T
14ad0 68 65 20 70 41 70 70 44 61 74 61 20 70 6f 69 6e  he pAppData poin
14ae0 74 65 72 20 69 73 20 75 73 65 64 20 61 73 20 74  ter is used as t
14af0 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65  he only paramete
14b00 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e  r to.** xInit an
14b10 64 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a  d xShutdown..**.
14b20 2a 2a 20 53 51 4c 69 74 65 20 68 6f 6c 64 73 20  ** SQLite holds 
14b30 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45  the [SQLITE_MUTE
14b40 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 45 52 5d  X_STATIC_MASTER]
14b50 20 6d 75 74 65 78 20 77 68 65 6e 20 69 74 20 69   mutex when it i
14b60 6e 76 6f 6b 65 73 0a 2a 2a 20 74 68 65 20 78 49  nvokes.** the xI
14b70 6e 69 74 20 6d 65 74 68 6f 64 2c 20 73 6f 20 74  nit method, so t
14b80 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20  he xInit method 
14b90 6e 65 65 64 20 6e 6f 74 20 62 65 20 74 68 72 65  need not be thre
14ba0 61 64 73 61 66 65 2e 20 20 54 68 65 0a 2a 2a 20  adsafe.  The.** 
14bb0 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64  xShutdown method
14bc0 20 69 73 20 6f 6e 6c 79 20 63 61 6c 6c 65 64 20   is only called 
14bd0 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73 68  from [sqlite3_sh
14be0 75 74 64 6f 77 6e 28 29 5d 20 73 6f 20 69 74 20  utdown()] so it 
14bf0 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64  does.** not need
14c00 20 74 6f 20 62 65 20 74 68 72 65 61 64 73 61 66   to be threadsaf
14c10 65 20 65 69 74 68 65 72 2e 20 20 46 6f 72 20 61  e either.  For a
14c20 6c 6c 20 6f 74 68 65 72 20 6d 65 74 68 6f 64 73  ll other methods
14c30 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64  , SQLite.** hold
14c40 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55  s the [SQLITE_MU
14c50 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 5d 20  TEX_STATIC_MEM] 
14c60 6d 75 74 65 78 20 61 73 20 6c 6f 6e 67 20 61 73  mutex as long as
14c70 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
14c80 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
14c90 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  ] configuration 
14ca0 6f 70 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64  option is turned
14cb0 20 6f 6e 20 28 77 68 69 63 68 0a 2a 2a 20 69 74   on (which.** it
14cc0 20 69 73 20 62 79 20 64 65 66 61 75 6c 74 29 20   is by default) 
14cd0 61 6e 64 20 73 6f 20 74 68 65 20 6d 65 74 68 6f  and so the metho
14ce0 64 73 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63  ds are automatic
14cf0 61 6c 6c 79 20 73 65 72 69 61 6c 69 7a 65 64 2e  ally serialized.
14d00 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 69 66 20  .** However, if 
14d10 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
14d20 45 4d 53 54 41 54 55 53 5d 20 69 73 20 64 69 73  EMSTATUS] is dis
14d30 61 62 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20  abled, then the 
14d40 6f 74 68 65 72 0a 2a 2a 20 6d 65 74 68 6f 64 73  other.** methods
14d50 20 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 73   must be threads
14d60 61 66 65 20 6f 72 20 65 6c 73 65 20 6d 61 6b 65  afe or else make
14d70 20 74 68 65 69 72 20 6f 77 6e 20 61 72 72 61 6e   their own arran
14d80 67 65 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a 20 73  gements for.** s
14d90 65 72 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a  erialization..**
14da0 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  .** SQLite will 
14db0 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 78 49 6e  never invoke xIn
14dc0 69 74 28 29 20 6d 6f 72 65 20 74 68 61 6e 20 6f  it() more than o
14dd0 6e 63 65 20 77 69 74 68 6f 75 74 20 61 6e 20 69  nce without an i
14de0 6e 74 65 72 76 65 6e 69 6e 67 0a 2a 2a 20 63 61  ntervening.** ca
14df0 6c 6c 20 74 6f 20 78 53 68 75 74 64 6f 77 6e 28  ll to xShutdown(
14e00 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  )..*/.typedef st
14e10 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d  ruct sqlite3_mem
14e20 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33  _methods sqlite3
14e30 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74  _mem_methods;.st
14e40 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d  ruct sqlite3_mem
14e50 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69  _methods {.  voi
14e60 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e  d *(*xMalloc)(in
14e70 74 29 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 4d  t);         /* M
14e80 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
14e90 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76   function */.  v
14ea0 6f 69 64 20 28 2a 78 46 72 65 65 29 28 76 6f 69  oid (*xFree)(voi
14eb0 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a  d*);          /*
14ec0 20 46 72 65 65 20 61 20 70 72 69 6f 72 20 61 6c   Free a prior al
14ed0 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f  location */.  vo
14ee0 69 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28  id *(*xRealloc)(
14ef0 76 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20  void*,int);  /* 
14f00 52 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61  Resize an alloca
14f10 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  tion */.  int (*
14f20 78 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20  xSize)(void*);  
14f30 20 20 20 20 20 20 20 20 20 2f 2a 20 52 65 74 75           /* Retu
14f40 72 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61  rn the size of a
14f50 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a  n allocation */.
14f60 20 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70    int (*xRoundup
14f70 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20  )(int);         
14f80 20 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72 65 71   /* Round up req
14f90 75 65 73 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c  uest size to all
14fa0 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a  ocation size */.
14fb0 20 20 69 6e 74 20 28 2a 78 49 6e 69 74 29 28 76    int (*xInit)(v
14fc0 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20  oid*);          
14fd0 20 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65 20 74   /* Initialize t
14fe0 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
14ff0 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a  tor */.  void (*
15000 78 53 68 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a  xShutdown)(void*
15010 29 3b 20 20 20 20 20 20 2f 2a 20 44 65 69 6e 69  );      /* Deini
15020 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f  tialize the memo
15030 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a  ry allocator */.
15040 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61    void *pAppData
15050 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ;               
15060 20 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74 6f 20   /* Argument to 
15070 78 49 6e 69 74 28 29 20 61 6e 64 20 78 53 68 75  xInit() and xShu
15080 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f  tdown() */.};../
15090 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
150a0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74  onfiguration Opt
150b0 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ions.** KEYWORDS
150c0 3a 20 7b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  : {configuration
150d0 20 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54   option}.**.** T
150e0 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61  hese constants a
150f0 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65  re the available
15100 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75   integer configu
15110 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74  ration options t
15120 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61  hat.** can be pa
15130 73 73 65 64 20 61 73 20 74 68 65 20 66 69 72 73  ssed as the firs
15140 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
15150 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  e [sqlite3_confi
15160 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a  g()] interface..
15170 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67  **.** New config
15180 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
15190 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
151a0 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
151b0 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78  of SQLite..** Ex
151c0 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61  isting configura
151d0 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67  tion options mig
151e0 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75  ht be discontinu
151f0 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  ed.  Application
15200 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63  s.** should chec
15210 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64  k the return cod
15220 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  e from [sqlite3_
15230 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b  config()] to mak
15240 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74  e sure that.** t
15250 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20  he call worked. 
15260 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
15270 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63  nfig()] interfac
15280 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a  e will return a.
15290 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72  ** non-zero [err
152a0 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69  or code] if a di
152b0 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e  scontinued or un
152c0 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67  supported config
152d0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a  uration option.*
152e0 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a  * is invoked..**
152f0 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51  .** <dl>.** [[SQ
15300 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
15310 4c 45 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53  LETHREAD]] <dt>S
15320 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
15330 47 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a  GLETHREAD</dt>.*
15340 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20  * <dd>There are 
15350 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  no arguments to 
15360 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54  this option.  ^T
15370 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20  his option sets 
15380 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e  the.** [threadin
15390 67 20 6d 6f 64 65 5d 20 74 6f 20 53 69 6e 67 6c  g mode] to Singl
153a0 65 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74  e-thread.  In ot
153b0 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69  her words, it di
153c0 73 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75  sables.** all mu
153d0 74 65 78 69 6e 67 20 61 6e 64 20 70 75 74 73 20  texing and puts 
153e0 53 51 4c 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f  SQLite into a mo
153f0 64 65 20 77 68 65 72 65 20 69 74 20 63 61 6e 20  de where it can 
15400 6f 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a 2a 20  only be used.** 
15410 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65  by a single thre
15420 61 64 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65  ad.   ^If SQLite
15430 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
15440 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  h.** the [SQLITE
15450 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51  _THREADSAFE | SQ
15460 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
15470 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  0] compile-time 
15480 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69  option then.** i
15490 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c  t is not possibl
154a0 65 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20  e to change the 
154b0 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
154c0 20 66 72 6f 6d 20 69 74 73 20 64 65 66 61 75 6c   from its defaul
154d0 74 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 53 69  t.** value of Si
154e0 6e 67 6c 65 2d 74 68 72 65 61 64 20 61 6e 64 20  ngle-thread and 
154f0 73 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  so [sqlite3_conf
15500 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  ig()] will retur
15510 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52  n .** [SQLITE_ER
15520 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77  ROR] if called w
15530 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43  ith the SQLITE_C
15540 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
15550 41 44 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74  AD.** configurat
15560 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e  ion option.</dd>
15570 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
15580 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
15590 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  AD]] <dt>SQLITE_
155a0 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
155b0 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  AD</dt>.** <dd>T
155c0 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75  here are no argu
155d0 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70  ments to this op
155e0 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74  tion.  ^This opt
155f0 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20  ion sets the.** 
15600 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
15610 20 74 6f 20 4d 75 6c 74 69 2d 74 68 72 65 61 64   to Multi-thread
15620 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  .  In other word
15630 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a  s, it disables.*
15640 2a 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64  * mutexing on [d
15650 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
15660 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65  on] and [prepare
15670 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a  d statement] obj
15680 65 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70  ects..** The app
15690 6c 69 63 61 74 69 6f 6e 20 69 73 20 72 65 73 70  lication is resp
156a0 6f 6e 73 69 62 6c 65 20 66 6f 72 20 73 65 72 69  onsible for seri
156b0 61 6c 69 7a 69 6e 67 20 61 63 63 65 73 73 20 74  alizing access t
156c0 6f 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  o.** [database c
156d0 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20  onnections] and 
156e0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
156f0 65 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74 68 65  ents].  But othe
15700 72 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65  r mutexes.** are
15710 20 65 6e 61 62 6c 65 64 20 73 6f 20 74 68 61 74   enabled so that
15720 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20   SQLite will be 
15730 73 61 66 65 20 74 6f 20 75 73 65 20 69 6e 20 61  safe to use in a
15740 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 0a   multi-threaded.
15750 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 61  ** environment a
15760 73 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f  s long as no two
15770 20 74 68 72 65 61 64 73 20 61 74 74 65 6d 70 74   threads attempt
15780 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65   to use the same
15790 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
157a0 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 74 68 65  nnection] at the
157b0 20 73 61 6d 65 20 74 69 6d 65 2e 20 20 5e 49 66   same time.  ^If
157c0 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
157d0 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
157e0 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
157f0 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45  FE | SQLITE_THRE
15800 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c  ADSAFE=0] compil
15810 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68  e-time option th
15820 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20  en.** it is not 
15830 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20  possible to set 
15840 74 68 65 20 4d 75 6c 74 69 2d 74 68 72 65 61 64  the Multi-thread
15850 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
15860 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
15870 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c  3_config()] will
15880 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
15890 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64  ERROR] if called
158a0 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c   with the.** SQL
158b0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49  ITE_CONFIG_MULTI
158c0 54 48 52 45 41 44 20 63 6f 6e 66 69 67 75 72 61  THREAD configura
158d0 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64  tion option.</dd
158e0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
158f0 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a  _CONFIG_SERIALIZ
15900 45 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  ED]] <dt>SQLITE_
15910 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
15920 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
15930 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d  ere are no argum
15940 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74  ents to this opt
15950 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69  ion.  ^This opti
15960 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b  on sets the.** [
15970 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
15980 74 6f 20 53 65 72 69 61 6c 69 7a 65 64 2e 20 49  to Serialized. I
15990 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74  n other words, t
159a0 68 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c  his option enabl
159b0 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65  es.** all mutexe
159c0 73 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 65 20  s including the 
159d0 72 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74  recursive.** mut
159e0 65 78 65 73 20 6f 6e 20 5b 64 61 74 61 62 61 73  exes on [databas
159f0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e  e connection] an
15a00 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
15a10 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a  ement] objects..
15a20 2a 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64 65 20  ** In this mode 
15a30 28 77 68 69 63 68 20 69 73 20 74 68 65 20 64 65  (which is the de
15a40 66 61 75 6c 74 20 77 68 65 6e 20 53 51 4c 69 74  fault when SQLit
15a50 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
15a60 74 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48  th.** [SQLITE_TH
15a70 52 45 41 44 53 41 46 45 3d 31 5d 29 20 74 68 65  READSAFE=1]) the
15a80 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20   SQLite library 
15a90 77 69 6c 6c 20 69 74 73 65 6c 66 20 73 65 72 69  will itself seri
15aa0 61 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20  alize access.** 
15ab0 74 6f 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  to [database con
15ac0 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70  nections] and [p
15ad0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
15ae0 74 73 5d 20 73 6f 20 74 68 61 74 20 74 68 65 0a  ts] so that the.
15af0 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69  ** application i
15b00 73 20 66 72 65 65 20 74 6f 20 75 73 65 20 74 68  s free to use th
15b10 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65  e same [database
15b20 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20   connection] or 
15b30 74 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65  the.** same [pre
15b40 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
15b50 20 69 6e 20 64 69 66 66 65 72 65 6e 74 20 74 68   in different th
15b60 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d  reads at the sam
15b70 65 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53  e time..** ^If S
15b80 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
15b90 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53  d with.** the [S
15ba0 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
15bb0 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44   | SQLITE_THREAD
15bc0 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d  SAFE=0] compile-
15bd0 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e  time option then
15be0 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f  .** it is not po
15bf0 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68  ssible to set th
15c00 65 20 53 65 72 69 61 6c 69 7a 65 64 20 5b 74 68  e Serialized [th
15c10 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e  reading mode] an
15c20 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d.** [sqlite3_co
15c30 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74  nfig()] will ret
15c40 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  urn [SQLITE_ERRO
15c50 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74  R] if called wit
15c60 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f  h the.** SQLITE_
15c70 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
15c80 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  D configuration 
15c90 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a  option.</dd>.**.
15ca0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
15cb0 49 47 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e  IG_MALLOC]] <dt>
15cc0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
15cd0 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  LLOC</dt>.** <dd
15ce0 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20  > ^(This option 
15cf0 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
15d00 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
15d10 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
15d20 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20  .** instance of 
15d30 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  the [sqlite3_mem
15d40 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
15d50 75 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65  ure.  The argume
15d60 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  nt specifies.** 
15d70 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d  alternative low-
15d80 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c  level memory all
15d90 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
15da0 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70   to be used in p
15db0 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d  lace of.** the m
15dc0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
15dd0 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20   routines built 
15de0 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 5e  into SQLite.)^ ^
15df0 53 51 4c 69 74 65 20 6d 61 6b 65 73 0a 2a 2a 20  SQLite makes.** 
15e00 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20  its own private 
15e10 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74  copy of the cont
15e20 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  ent of the [sqli
15e30 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
15e40 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 62 65   structure.** be
15e50 66 6f 72 65 20 74 68 65 20 5b 73 71 6c 69 74 65  fore the [sqlite
15e60 33 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6c 6c  3_config()] call
15e70 20 72 65 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a   returns.</dd>.*
15e80 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
15e90 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d  NFIG_GETMALLOC]]
15ea0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
15eb0 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74  IG_GETMALLOC</dt
15ec0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73  >.** <dd> ^(This
15ed0 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
15ee0 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
15ef0 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74  which is a point
15f00 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74  er to an.** inst
15f10 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c  ance of the [sql
15f20 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
15f30 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68  ] structure.  Th
15f40 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  e [sqlite3_mem_m
15f50 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63  ethods].** struc
15f60 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77  ture is filled w
15f70 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c  ith the currentl
15f80 79 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f 72 79  y defined memory
15f90 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
15fa0 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20  ines.)^.** This 
15fb0 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73  option can be us
15fc0 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74  ed to overload t
15fd0 68 65 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72  he default memor
15fe0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  y allocation.** 
15ff0 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20  routines with a 
16000 77 72 61 70 70 65 72 20 74 68 61 74 20 73 69 6d  wrapper that sim
16010 75 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 20  ulations memory 
16020 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75  allocation failu
16030 72 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 20  re or.** tracks 
16040 6d 65 6d 6f 72 79 20 75 73 61 67 65 2c 20 66 6f  memory usage, fo
16050 72 20 65 78 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e  r example. </dd>
16060 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
16070 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
16080 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
16090 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c 2f  NFIG_MEMSTATUS</
160a0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69  dt>.** <dd> ^Thi
160b0 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 73  s option takes s
160c0 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f  ingle argument o
160d0 66 20 74 79 70 65 20 69 6e 74 2c 20 69 6e 74 65  f type int, inte
160e0 72 70 72 65 74 65 64 20 61 73 20 61 20 0a 2a 2a  rpreted as a .**
160f0 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20   boolean, which 
16100 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62  enables or disab
16110 6c 65 73 20 74 68 65 20 63 6f 6c 6c 65 63 74 69  les the collecti
16120 6f 6e 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c  on of memory all
16130 6f 63 61 74 69 6f 6e 20 0a 2a 2a 20 73 74 61 74  ocation .** stat
16140 69 73 74 69 63 73 2e 20 5e 28 57 68 65 6e 20 6d  istics. ^(When m
16150 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
16160 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20   statistics are 
16170 64 69 73 61 62 6c 65 64 2c 20 74 68 65 20 0a 2a  disabled, the .*
16180 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69  * following SQLi
16190 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 62 65  te interfaces be
161a0 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61 74 69  come non-operati
161b0 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a  onal:.**   <ul>.
161c0 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74  **   <li> [sqlit
161d0 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
161e0 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c  ].**   <li> [sql
161f0 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
16200 77 61 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c  water()].**   <l
16210 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74  i> [sqlite3_soft
16220 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 5d  _heap_limit64()]
16230 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69  .**   <li> [sqli
16240 74 65 33 5f 73 74 61 74 75 73 28 29 5d 0a 2a 2a  te3_status()].**
16250 20 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d     </ul>)^.** ^M
16260 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
16270 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20   statistics are 
16280 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  enabled by defau
16290 6c 74 20 75 6e 6c 65 73 73 20 53 51 4c 69 74 65  lt unless SQLite
162a0 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20   is.** compiled 
162b0 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 45 46  with [SQLITE_DEF
162c0 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 5d 3d  AULT_MEMSTATUS]=
162d0 30 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20  0 in which case 
162e0 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61  memory.** alloca
162f0 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20  tion statistics 
16300 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20  are disabled by 
16310 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64  default..** </dd
16320 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
16330 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d  _CONFIG_SCRATCH]
16340 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
16350 46 49 47 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e  FIG_SCRATCH</dt>
16360 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f  .** <dd> ^This o
16370 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20  ption specifies 
16380 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20  a static memory 
16390 62 75 66 66 65 72 20 74 68 61 74 20 53 51 4c 69  buffer that SQLi
163a0 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a  te can use for.*
163b0 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79  * scratch memory
163c0 2e 20 20 54 68 65 72 65 20 61 72 65 20 74 68 72  .  There are thr
163d0 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 20 41  ee arguments:  A
163e0 20 70 6f 69 6e 74 65 72 20 61 6e 20 38 2d 62 79   pointer an 8-by
163f0 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 6d 65  te.** aligned me
16400 6d 6f 72 79 20 62 75 66 66 65 72 20 66 72 6f 6d  mory buffer from
16410 20 77 68 69 63 68 20 74 68 65 20 73 63 72 61 74   which the scrat
16420 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 77  ch allocations w
16430 69 6c 6c 20 62 65 0a 2a 2a 20 64 72 61 77 6e 2c  ill be.** drawn,
16440 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63   the size of eac
16450 68 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61  h scratch alloca
16460 74 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e  tion (sz),.** an
16470 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d the maximum nu
16480 6d 62 65 72 20 6f 66 20 73 63 72 61 74 63 68 20  mber of scratch 
16490 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 28 4e 29 2e  allocations (N).
164a0 20 20 54 68 65 20 73 7a 0a 2a 2a 20 61 72 67 75    The sz.** argu
164b0 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 6d  ment must be a m
164c0 75 6c 74 69 70 6c 65 20 6f 66 20 31 36 2e 0a 2a  ultiple of 16..*
164d0 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
164e0 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 70  ment must be a p
164f0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d 62  ointer to an 8-b
16500 79 74 65 20 61 6c 69 67 6e 65 64 20 62 75 66 66  yte aligned buff
16510 65 72 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73  er.** of at leas
16520 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20  t sz*N bytes of 
16530 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69  memory..** ^SQLi
16540 74 65 20 77 69 6c 6c 20 75 73 65 20 6e 6f 20 6d  te will use no m
16550 6f 72 65 20 74 68 61 6e 20 74 77 6f 20 73 63 72  ore than two scr
16560 61 74 63 68 20 62 75 66 66 65 72 73 20 70 65 72  atch buffers per
16570 20 74 68 72 65 61 64 2e 20 20 53 6f 0a 2a 2a 20   thread.  So.** 
16580 4e 20 73 68 6f 75 6c 64 20 62 65 20 73 65 74 20  N should be set 
16590 74 6f 20 74 77 69 63 65 20 74 68 65 20 65 78 70  to twice the exp
165a0 65 63 74 65 64 20 6d 61 78 69 6d 75 6d 20 6e 75  ected maximum nu
165b0 6d 62 65 72 20 6f 66 20 74 68 72 65 61 64 73 2e  mber of threads.
165c0 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c  .** ^SQLite will
165d0 20 6e 65 76 65 72 20 72 65 71 75 69 72 65 20 61   never require a
165e0 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72 20   scratch buffer 
165f0 74 68 61 74 20 69 73 20 6d 6f 72 65 20 74 68 61  that is more tha
16600 6e 20 36 0a 2a 2a 20 74 69 6d 65 73 20 74 68 65  n 6.** times the
16610 20 64 61 74 61 62 61 73 65 20 70 61 67 65 20 73   database page s
16620 69 7a 65 2e 20 5e 49 66 20 53 51 4c 69 74 65 20  ize. ^If SQLite 
16630 6e 65 65 64 73 20 6e 65 65 64 73 20 61 64 64 69  needs needs addi
16640 74 69 6f 6e 61 6c 0a 2a 2a 20 73 63 72 61 74 63  tional.** scratc
16650 68 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e 64 20  h memory beyond 
16660 77 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64  what is provided
16670 20 62 79 20 74 68 69 73 20 63 6f 6e 66 69 67 75   by this configu
16680 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2c 20 74  ration option, t
16690 68 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  hen .** [sqlite3
166a0 5f 6d 61 6c 6c 6f 63 28 29 5d 20 77 69 6c 6c 20  _malloc()] will 
166b0 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69  be used to obtai
166c0 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 6e 65 65  n the memory nee
166d0 64 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ded.</dd>.**.** 
166e0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
166f0 50 41 47 45 43 41 43 48 45 5d 5d 20 3c 64 74 3e  PAGECACHE]] <dt>
16700 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
16710 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20  GECACHE</dt>.** 
16720 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
16730 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74  n specifies a st
16740 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66  atic memory buff
16750 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 63  er that SQLite c
16760 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68  an use for.** th
16770 65 20 64 61 74 61 62 61 73 65 20 70 61 67 65 20  e database page 
16780 63 61 63 68 65 20 77 69 74 68 20 74 68 65 20 64  cache with the d
16790 65 66 61 75 6c 74 20 70 61 67 65 20 63 61 63 68  efault page cach
167a0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
167b0 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f 6e 66  .  .** This conf
167c0 69 67 75 72 61 74 69 6f 6e 20 73 68 6f 75 6c 64  iguration should
167d0 20 6e 6f 74 20 62 65 20 75 73 65 64 20 69 66 20   not be used if 
167e0 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  an application-d
167f0 65 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63 61  efine page.** ca
16800 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  che implementati
16810 6f 6e 20 69 73 20 6c 6f 61 64 65 64 20 75 73 69  on is loaded usi
16820 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f  ng the SQLITE_CO
16830 4e 46 49 47 5f 50 43 41 43 48 45 32 20 6f 70 74  NFIG_PCACHE2 opt
16840 69 6f 6e 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72  ion..** There ar
16850 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74  e three argument
16860 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e  s to this option
16870 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 38  : A pointer to 8
16880 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 0a 2a 2a  -byte aligned.**
16890 20 6d 65 6d 6f 72 79 2c 20 74 68 65 20 73 69 7a   memory, the siz
168a0 65 20 6f 66 20 65 61 63 68 20 70 61 67 65 20 62  e of each page b
168b0 75 66 66 65 72 20 28 73 7a 29 2c 20 61 6e 64 20  uffer (sz), and 
168c0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 61  the number of pa
168d0 67 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20  ges (N)..** The 
168e0 73 7a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  sz argument shou
168f0 6c 64 20 62 65 20 74 68 65 20 73 69 7a 65 20 6f  ld be the size o
16900 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 64 61  f the largest da
16910 74 61 62 61 73 65 20 70 61 67 65 0a 2a 2a 20 28  tabase page.** (
16920 61 20 70 6f 77 65 72 20 6f 66 20 74 77 6f 20 62  a power of two b
16930 65 74 77 65 65 6e 20 35 31 32 20 61 6e 64 20 33  etween 512 and 3
16940 32 37 36 38 29 20 70 6c 75 73 20 61 20 6c 69 74  2768) plus a lit
16950 74 6c 65 20 65 78 74 72 61 20 66 6f 72 20 65 61  tle extra for ea
16960 63 68 0a 2a 2a 20 70 61 67 65 20 68 65 61 64 65  ch.** page heade
16970 72 2e 20 20 5e 54 68 65 20 70 61 67 65 20 68 65  r.  ^The page he
16980 61 64 65 72 20 73 69 7a 65 20 69 73 20 32 30 20  ader size is 20 
16990 74 6f 20 34 30 20 62 79 74 65 73 20 64 65 70 65  to 40 bytes depe
169a0 6e 64 69 6e 67 20 6f 6e 0a 2a 2a 20 74 68 65 20  nding on.** the 
169b0 68 6f 73 74 20 61 72 63 68 69 74 65 63 74 75 72  host architectur
169c0 65 2e 20 20 5e 49 74 20 69 73 20 68 61 72 6d 6c  e.  ^It is harml
169d0 65 73 73 2c 20 61 70 61 72 74 20 66 72 6f 6d 20  ess, apart from 
169e0 74 68 65 20 77 61 73 74 65 64 20 6d 65 6d 6f 72  the wasted memor
169f0 79 2c 0a 2a 2a 20 74 6f 20 6d 61 6b 65 20 73 7a  y,.** to make sz
16a00 20 61 20 6c 69 74 74 6c 65 20 74 6f 6f 20 6c 61   a little too la
16a10 72 67 65 2e 20 20 54 68 65 20 66 69 72 73 74 0a  rge.  The first.
16a20 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  ** argument shou
16a30 6c 64 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61  ld point to an a
16a40 6c 6c 6f 63 61 74 69 6f 6e 20 6f 66 20 61 74 20  llocation of at 
16a50 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73  least sz*N bytes
16a60 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e   of memory..** ^
16a70 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20  SQLite will use 
16a80 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69  the memory provi
16a90 64 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  ded by the first
16aa0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 61 74   argument to sat
16ab0 69 73 66 79 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f  isfy its.** memo
16ac0 72 79 20 6e 65 65 64 73 20 66 6f 72 20 74 68 65  ry needs for the
16ad0 20 66 69 72 73 74 20 4e 20 70 61 67 65 73 20 74   first N pages t
16ae0 68 61 74 20 69 74 20 61 64 64 73 20 74 6f 20 63  hat it adds to c
16af0 61 63 68 65 2e 20 20 5e 49 66 20 61 64 64 69 74  ache.  ^If addit
16b00 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61  ional.** page ca
16b10 63 68 65 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65  che memory is ne
16b20 65 64 65 64 20 62 65 79 6f 6e 64 20 77 68 61 74  eded beyond what
16b30 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20   is provided by 
16b40 74 68 69 73 20 6f 70 74 69 6f 6e 2c 20 74 68 65  this option, the
16b50 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 67 6f 65 73  n.** SQLite goes
16b60 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   to [sqlite3_mal
16b70 6c 6f 63 28 29 5d 20 66 6f 72 20 74 68 65 20 61  loc()] for the a
16b80 64 64 69 74 69 6f 6e 61 6c 20 73 74 6f 72 61 67  dditional storag
16b90 65 20 73 70 61 63 65 2e 0a 2a 2a 20 54 68 65 20  e space..** The 
16ba0 70 6f 69 6e 74 65 72 20 69 6e 20 74 68 65 20 66  pointer in the f
16bb0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75  irst argument mu
16bc0 73 74 0a 2a 2a 20 62 65 20 61 6c 69 67 6e 65 64  st.** be aligned
16bd0 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f   to an 8-byte bo
16be0 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65 71  undary or subseq
16bf0 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66  uent behavior of
16c00 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20   SQLite.** will 
16c10 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 3c 2f 64  be undefined.</d
16c20 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
16c30 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 5d 5d 20  E_CONFIG_HEAP]] 
16c40 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
16c50 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c  G_HEAP</dt>.** <
16c60 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
16c70 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61   specifies a sta
16c80 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  tic memory buffe
16c90 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69  r that SQLite wi
16ca0 6c 6c 20 75 73 65 0a 2a 2a 20 66 6f 72 20 61 6c  ll use.** for al
16cb0 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63  l of its dynamic
16cc0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
16cd0 6f 6e 20 6e 65 65 64 73 20 62 65 79 6f 6e 64 20  on needs beyond 
16ce0 74 68 6f 73 65 20 70 72 6f 76 69 64 65 64 0a 2a  those provided.*
16cf0 2a 20 66 6f 72 20 62 79 20 5b 53 51 4c 49 54 45  * for by [SQLITE
16d00 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d  _CONFIG_SCRATCH]
16d10 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 43 4f 4e   and [SQLITE_CON
16d20 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a  FIG_PAGECACHE]..
16d30 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 68 72  ** There are thr
16d40 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 41 6e  ee arguments: An
16d50 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20   8-byte aligned 
16d60 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d  pointer to the m
16d70 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68 65 20 6e 75  emory,.** the nu
16d80 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
16d90 20 74 68 65 20 6d 65 6d 6f 72 79 20 62 75 66 66   the memory buff
16da0 65 72 2c 20 61 6e 64 20 74 68 65 20 6d 69 6e 69  er, and the mini
16db0 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  mum allocation s
16dc0 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ize..** ^If the 
16dd0 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74  first pointer (t
16de0 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65  he memory pointe
16df0 72 29 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  r) is NULL, then
16e00 20 53 51 4c 69 74 65 20 72 65 76 65 72 74 73 0a   SQLite reverts.
16e10 2a 2a 20 74 6f 20 75 73 69 6e 67 20 69 74 73 20  ** to using its 
16e20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61  default memory a
16e30 6c 6c 6f 63 61 74 6f 72 20 28 74 68 65 20 73 79  llocator (the sy
16e40 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d  stem malloc() im
16e50 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a  plementation),.*
16e60 2a 20 75 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72  * undoing any pr
16e70 69 6f 72 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f  ior invocation o
16e80 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  f [SQLITE_CONFIG
16e90 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 5e 49 66 20 74  _MALLOC].  ^If t
16ea0 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f 69  he.** memory poi
16eb0 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  nter is not NULL
16ec0 20 61 6e 64 20 65 69 74 68 65 72 20 5b 53 51 4c   and either [SQL
16ed0 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59  ITE_ENABLE_MEMSY
16ee0 53 33 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54  S3] or.** [SQLIT
16ef0 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 35  E_ENABLE_MEMSYS5
16f00 5d 20 61 72 65 20 64 65 66 69 6e 65 64 2c 20 74  ] are defined, t
16f10 68 65 6e 20 74 68 65 20 61 6c 74 65 72 6e 61 74  hen the alternat
16f20 69 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c  ive memory.** al
16f30 6c 6f 63 61 74 6f 72 20 69 73 20 65 6e 67 61 67  locator is engag
16f40 65 64 20 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c  ed to handle all
16f50 20 6f 66 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f   of SQLites memo
16f60 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65  ry allocation ne
16f70 65 64 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73  eds..** The firs
16f80 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d  t pointer (the m
16f90 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 6d  emory pointer) m
16fa0 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74  ust be aligned t
16fb0 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 62  o an 8-byte.** b
16fc0 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65  oundary or subse
16fd0 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f  quent behavior o
16fe0 66 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65  f SQLite will be
16ff0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54   undefined..** T
17000 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63  he minimum alloc
17010 61 74 69 6f 6e 20 73 69 7a 65 20 69 73 20 63 61  ation size is ca
17020 70 70 65 64 20 61 74 20 32 2a 2a 31 32 2e 20 52  pped at 2**12. R
17030 65 61 73 6f 6e 61 62 6c 65 20 76 61 6c 75 65 73  easonable values
17040 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d 69 6e 69  .** for the mini
17050 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  mum allocation s
17060 69 7a 65 20 61 72 65 20 32 2a 2a 35 20 74 68 72  ize are 2**5 thr
17070 6f 75 67 68 20 32 2a 2a 38 2e 3c 2f 64 64 3e 0a  ough 2**8.</dd>.
17080 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
17090 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 5d 20 3c 64  ONFIG_MUTEX]] <d
170a0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
170b0 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  MUTEX</dt>.** <d
170c0 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e  d> ^(This option
170d0 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
170e0 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
170f0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
17100 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66  n.** instance of
17110 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75   the [sqlite3_mu
17120 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  tex_methods] str
17130 75 63 74 75 72 65 2e 20 20 54 68 65 20 61 72 67  ucture.  The arg
17140 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a  ument specifies.
17150 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c  ** alternative l
17160 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20 72  ow-level mutex r
17170 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73  outines to be us
17180 65 64 20 69 6e 20 70 6c 61 63 65 0a 2a 2a 20 74  ed in place.** t
17190 68 65 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65  he mutex routine
171a0 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c  s built into SQL
171b0 69 74 65 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20  ite.)^  ^SQLite 
171c0 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20  makes a copy of 
171d0 74 68 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 6f  the.** content o
171e0 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
171f0 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74  utex_methods] st
17200 72 75 63 74 75 72 65 20 62 65 66 6f 72 65 20 74  ructure before t
17210 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73  he call to.** [s
17220 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
17230 20 72 65 74 75 72 6e 73 2e 20 5e 49 66 20 53 51   returns. ^If SQ
17240 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
17250 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
17260 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
17270 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
17280 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
17290 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
172a0 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75  ** the entire mu
172b0 74 65 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d  texing subsystem
172c0 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d   is omitted from
172d0 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68   the build and h
172e0 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  ence calls to.**
172f0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
17300 28 29 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c  ()] with the SQL
17310 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
17320 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
17330 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65  ption will.** re
17340 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52  turn [SQLITE_ERR
17350 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  OR].</dd>.**.** 
17360 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
17370 47 45 54 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53  GETMUTEX]] <dt>S
17380 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
17390 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  MUTEX</dt>.** <d
173a0 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e  d> ^(This option
173b0 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
173c0 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
173d0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
173e0 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66  n.** instance of
173f0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75   the [sqlite3_mu
17400 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  tex_methods] str
17410 75 63 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20  ucture.  The.** 
17420 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d  [sqlite3_mutex_m
17430 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63  ethods].** struc
17440 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77  ture is filled w
17450 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c  ith the currentl
17460 79 20 64 65 66 69 6e 65 64 20 6d 75 74 65 78 20  y defined mutex 
17470 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54  routines.)^.** T
17480 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62  his option can b
17490 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f  e used to overlo
174a0 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d  ad the default m
174b0 75 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a  utex allocation.
174c0 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68  ** routines with
174d0 20 61 20 77 72 61 70 70 65 72 20 75 73 65 64 20   a wrapper used 
174e0 74 6f 20 74 72 61 63 6b 20 6d 75 74 65 78 20 75  to track mutex u
174f0 73 61 67 65 20 66 6f 72 20 70 65 72 66 6f 72 6d  sage for perform
17500 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e  ance.** profilin
17510 67 20 6f 72 20 74 65 73 74 69 6e 67 2c 20 66 6f  g or testing, fo
17520 72 20 65 78 61 6d 70 6c 65 2e 20 20 20 5e 49 66  r example.   ^If
17530 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
17540 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
17550 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
17560 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45  FE | SQLITE_THRE
17570 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c  ADSAFE=0] compil
17580 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68  e-time option th
17590 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65  en.** the entire
175a0 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79 73   mutexing subsys
175b0 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66  tem is omitted f
175c0 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e  rom the build an
175d0 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f  d hence calls to
175e0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
175f0 66 69 67 28 29 5d 20 77 69 74 68 20 74 68 65 20  fig()] with the 
17600 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
17610 54 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61  TMUTEX configura
17620 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c  tion option will
17630 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  .** return [SQLI
17640 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a  TE_ERROR].</dd>.
17650 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
17660 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d  ONFIG_LOOKASIDE]
17670 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
17680 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64  FIG_LOOKASIDE</d
17690 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69  t>.** <dd> ^(Thi
176a0 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74  s option takes t
176b0 77 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61  wo arguments tha
176c0 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20  t determine the 
176d0 64 65 66 61 75 6c 74 0a 2a 2a 20 6d 65 6d 6f 72  default.** memor
176e0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72  y allocation for
176f0 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d   the lookaside m
17700 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
17710 6f 6e 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61  on each.** [data
17720 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
17730 2e 20 20 54 68 65 20 66 69 72 73 74 20 61 72 67  .  The first arg
17740 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20  ument is the.** 
17750 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f  size of each loo
17760 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c  kaside buffer sl
17770 6f 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e  ot and the secon
17780 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  d is the number 
17790 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f  of.** slots allo
177a0 63 61 74 65 64 20 74 6f 20 65 61 63 68 20 64 61  cated to each da
177b0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
177c0 6e 2e 29 5e 20 20 5e 28 54 68 69 73 20 6f 70 74  n.)^  ^(This opt
177d0 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20  ion sets the.** 
177e0 3c 69 3e 64 65 66 61 75 6c 74 3c 2f 69 3e 20 6c  <i>default</i> l
177f0 6f 6f 6b 61 73 69 64 65 20 73 69 7a 65 2e 20 54  ookaside size. T
17800 68 65 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e  he [SQLITE_DBCON
17810 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a  FIG_LOOKASIDE].*
17820 2a 20 76 65 72 62 20 74 6f 20 5b 73 71 6c 69 74  * verb to [sqlit
17830 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
17840 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63  can be used to c
17850 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73  hange the lookas
17860 69 64 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61  ide.** configura
17870 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75  tion on individu
17880 61 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29  al connections.)
17890 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  ^ </dd>.**.** [[
178a0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
178b0 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49  ACHE2]] <dt>SQLI
178c0 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
178d0 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  2</dt>.** <dd> ^
178e0 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  (This option tak
178f0 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
17900 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20  ment which is a 
17910 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 61 6e  pointer to.** an
17920 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65   [sqlite3_pcache
17930 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63  _methods2] objec
17940 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20  t.  This object 
17950 73 70 65 63 69 66 69 65 73 20 74 68 65 20 69 6e  specifies the in
17960 74 65 72 66 61 63 65 0a 2a 2a 20 74 6f 20 61 20  terface.** to a 
17970 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61 63 68  custom page cach
17980 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
17990 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b  .)^  ^SQLite mak
179a0 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  es a copy of the
179b0 0a 2a 2a 20 6f 62 6a 65 63 74 20 61 6e 64 20 75  .** object and u
179c0 73 65 73 20 69 74 20 66 6f 72 20 70 61 67 65 20  ses it for page 
179d0 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  cache memory all
179e0 6f 63 61 74 69 6f 6e 73 2e 3c 2f 64 64 3e 0a 2a  ocations.</dd>.*
179f0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
17a00 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 5d  NFIG_GETPCACHE2]
17a10 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
17a20 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 3c 2f  FIG_GETPCACHE2</
17a30 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
17a40 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
17a50 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
17a60 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69  t which is a poi
17a70 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73  nter to an.** [s
17a80 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65  qlite3_pcache_me
17a90 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20  thods2] object. 
17aa0 20 53 51 4c 69 74 65 20 63 6f 70 69 65 73 20 6f   SQLite copies o
17ab0 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a  f the current.**
17ac0 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c   page cache impl
17ad0 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74 6f 20  ementation into 
17ae0 74 68 61 74 20 6f 62 6a 65 63 74 2e 29 5e 20 3c  that object.)^ <
17af0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
17b00 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 5d 5d  ITE_CONFIG_LOG]]
17b10 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
17b20 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c  IG_LOG</dt>.** <
17b30 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f  dd> ^The SQLITE_
17b40 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f  CONFIG_LOG optio
17b50 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75  n takes two argu
17b60 6d 65 6e 74 73 3a 20 61 20 70 6f 69 6e 74 65 72  ments: a pointer
17b70 20 74 6f 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f   to a.** functio
17b80 6e 20 77 69 74 68 20 61 20 63 61 6c 6c 20 73 69  n with a call si
17b90 67 6e 61 74 75 72 65 20 6f 66 20 76 6f 69 64 28  gnature of void(
17ba0 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  *)(void*,int,con
17bb0 73 74 20 63 68 61 72 2a 29 2c 20 0a 2a 2a 20 61  st char*), .** a
17bc0 6e 64 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  nd a pointer to 
17bd0 76 6f 69 64 2e 20 5e 49 66 20 74 68 65 20 66 75  void. ^If the fu
17be0 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69  nction pointer i
17bf0 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 69 74 20 69  s not NULL, it i
17c00 73 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 62 79 20  s.** invoked by 
17c10 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20  [sqlite3_log()] 
17c20 74 6f 20 70 72 6f 63 65 73 73 20 65 61 63 68 20  to process each 
17c30 6c 6f 67 67 69 6e 67 20 65 76 65 6e 74 2e 20 20  logging event.  
17c40 5e 49 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74  ^If the.** funct
17c50 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 4e  ion pointer is N
17c60 55 4c 4c 2c 20 74 68 65 20 5b 73 71 6c 69 74 65  ULL, the [sqlite
17c70 33 5f 6c 6f 67 28 29 5d 20 69 6e 74 65 72 66 61  3_log()] interfa
17c80 63 65 20 62 65 63 6f 6d 65 73 20 61 20 6e 6f 2d  ce becomes a no-
17c90 6f 70 2e 0a 2a 2a 20 5e 54 68 65 20 76 6f 69 64  op..** ^The void
17ca0 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73   pointer that is
17cb0 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
17cc0 6d 65 6e 74 20 74 6f 20 53 51 4c 49 54 45 5f 43  ment to SQLITE_C
17cd0 4f 4e 46 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20  ONFIG_LOG is.** 
17ce0 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 61  passed through a
17cf0 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  s the first para
17d00 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 70 70  meter to the app
17d10 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
17d20 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74   logger.** funct
17d30 69 6f 6e 20 77 68 65 6e 65 76 65 72 20 74 68 61  ion whenever tha
17d40 74 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e  t function is in
17d50 76 6f 6b 65 64 2e 20 20 5e 54 68 65 20 73 65 63  voked.  ^The sec
17d60 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ond parameter to
17d70 0a 2a 2a 20 74 68 65 20 6c 6f 67 67 65 72 20 66  .** the logger f
17d80 75 6e 63 74 69 6f 6e 20 69 73 20 61 20 63 6f 70  unction is a cop
17d90 79 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 70  y of the first p
17da0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
17db0 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a  corresponding.**
17dc0 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d   [sqlite3_log()]
17dd0 20 63 61 6c 6c 20 61 6e 64 20 69 73 20 69 6e 74   call and is int
17de0 65 6e 64 65 64 20 74 6f 20 62 65 20 61 20 5b 72  ended to be a [r
17df0 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 61  esult code] or a
17e00 6e 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72  n.** [extended r
17e10 65 73 75 6c 74 20 63 6f 64 65 5d 2e 20 20 5e 54  esult code].  ^T
17e20 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
17e30 65 72 20 70 61 73 73 65 64 20 74 6f 20 74 68 65  er passed to the
17e40 20 6c 6f 67 67 65 72 20 69 73 0a 2a 2a 20 6c 6f   logger is.** lo
17e50 67 20 6d 65 73 73 61 67 65 20 61 66 74 65 72 20  g message after 
17e60 66 6f 72 6d 61 74 74 69 6e 67 20 76 69 61 20 5b  formatting via [
17e70 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
17e80 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69  ()]..** The SQLi
17e90 74 65 20 6c 6f 67 67 69 6e 67 20 69 6e 74 65 72  te logging inter
17ea0 66 61 63 65 20 69 73 20 6e 6f 74 20 72 65 65 6e  face is not reen
17eb0 74 72 61 6e 74 3b 20 74 68 65 20 6c 6f 67 67 65  trant; the logge
17ec0 72 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75  r function.** su
17ed0 70 70 6c 69 65 64 20 62 79 20 74 68 65 20 61 70  pplied by the ap
17ee0 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e  plication must n
17ef0 6f 74 20 69 6e 76 6f 6b 65 20 61 6e 79 20 53 51  ot invoke any SQ
17f00 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a  Lite interface..
17f10 2a 2a 20 49 6e 20 61 20 6d 75 6c 74 69 2d 74 68  ** In a multi-th
17f20 72 65 61 64 65 64 20 61 70 70 6c 69 63 61 74 69  readed applicati
17f30 6f 6e 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74  on, the applicat
17f40 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67  ion-defined logg
17f50 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d  er.** function m
17f60 75 73 74 20 62 65 20 74 68 72 65 61 64 73 61 66  ust be threadsaf
17f70 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  e. </dd>.**.** [
17f80 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55  [SQLITE_CONFIG_U
17f90 52 49 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  RI]] <dt>SQLITE_
17fa0 43 4f 4e 46 49 47 5f 55 52 49 0a 2a 2a 20 3c 64  CONFIG_URI.** <d
17fb0 64 3e 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 74  d> This option t
17fc0 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
17fd0 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69  gument of type i
17fe0 6e 74 2e 20 49 66 20 6e 6f 6e 2d 7a 65 72 6f 2c  nt. If non-zero,
17ff0 20 74 68 65 6e 0a 2a 2a 20 55 52 49 20 68 61 6e   then.** URI han
18000 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c  dling is globall
18010 79 20 65 6e 61 62 6c 65 64 2e 20 49 66 20 74 68  y enabled. If th
18020 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 7a  e parameter is z
18030 65 72 6f 2c 20 74 68 65 6e 20 55 52 49 20 68 61  ero, then URI ha
18040 6e 64 6c 69 6e 67 0a 2a 2a 20 69 73 20 67 6c 6f  ndling.** is glo
18050 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2e 20  bally disabled. 
18060 49 66 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20  If URI handling 
18070 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62  is globally enab
18080 6c 65 64 2c 20 61 6c 6c 20 66 69 6c 65 6e 61 6d  led, all filenam
18090 65 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 6f 20  es.** passed to 
180a0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
180b0 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  , [sqlite3_open_
180c0 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  v2()], [sqlite3_
180d0 6f 70 65 6e 31 36 28 29 5d 20 6f 72 0a 2a 2a 20  open16()] or.** 
180e0 73 70 65 63 69 66 69 65 64 20 61 73 20 70 61 72  specified as par
180f0 74 20 6f 66 20 5b 41 54 54 41 43 48 5d 20 63 6f  t of [ATTACH] co
18100 6d 6d 61 6e 64 73 20 61 72 65 20 69 6e 74 65 72  mmands are inter
18110 70 72 65 74 65 64 20 61 73 20 55 52 49 73 2c 20  preted as URIs, 
18120 72 65 67 61 72 64 6c 65 73 73 0a 2a 2a 20 6f 66  regardless.** of
18130 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
18140 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  the [SQLITE_OPEN
18150 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 20 73 65  _URI] flag is se
18160 74 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62  t when the datab
18170 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
18180 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 49 66 20  n is opened. If 
18190 69 74 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64  it is globally d
181a0 69 73 61 62 6c 65 64 2c 20 66 69 6c 65 6e 61 6d  isabled, filenam
181b0 65 73 20 61 72 65 0a 2a 2a 20 6f 6e 6c 79 20 69  es are.** only i
181c0 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55 52  nterpreted as UR
181d0 49 73 20 69 66 20 74 68 65 20 53 51 4c 49 54 45  Is if the SQLITE
181e0 5f 4f 50 45 4e 5f 55 52 49 20 66 6c 61 67 20 69  _OPEN_URI flag i
181f0 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 0a 2a  s set when the.*
18200 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
18210 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e  ction is opened.
18220 20 42 79 20 64 65 66 61 75 6c 74 2c 20 55 52 49   By default, URI
18230 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f   handling is glo
18240 62 61 6c 6c 79 0a 2a 2a 20 64 69 73 61 62 6c 65  bally.** disable
18250 64 2e 20 54 68 65 20 64 65 66 61 75 6c 74 20 76  d. The default v
18260 61 6c 75 65 20 6d 61 79 20 62 65 20 63 68 61 6e  alue may be chan
18270 67 65 64 20 62 79 20 63 6f 6d 70 69 6c 69 6e 67  ged by compiling
18280 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51   with the.** [SQ
18290 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 73 79  LITE_USE_URI] sy
182a0 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 0a 2a 2a  mbol defined..**
182b0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
182c0 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44  FIG_COVERING_IND
182d0 45 58 5f 53 43 41 4e 5d 5d 20 3c 64 74 3e 53 51  EX_SCAN]] <dt>SQ
182e0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45  LITE_CONFIG_COVE
182f0 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 0a  RING_INDEX_SCAN.
18300 2a 2a 20 3c 64 64 3e 20 54 68 69 73 20 6f 70 74  ** <dd> This opt
18310 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
18320 6c 65 20 69 6e 74 65 67 65 72 20 61 72 67 75 6d  le integer argum
18330 65 6e 74 20 77 68 69 63 68 20 69 73 20 69 6e 74  ent which is int
18340 65 72 70 72 65 74 65 64 20 61 73 0a 2a 2a 20 61  erpreted as.** a
18350 20 62 6f 6f 6c 65 61 6e 20 69 6e 20 6f 72 64 65   boolean in orde
18360 72 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64  r to enable or d
18370 69 73 61 62 6c 65 20 74 68 65 20 75 73 65 20 6f  isable the use o
18380 66 20 63 6f 76 65 72 69 6e 67 20 69 6e 64 69 63  f covering indic
18390 65 73 20 66 6f 72 0a 2a 2a 20 66 75 6c 6c 20 74  es for.** full t
183a0 61 62 6c 65 20 73 63 61 6e 73 20 69 6e 20 74 68  able scans in th
183b0 65 20 71 75 65 72 79 20 6f 70 74 69 6d 69 7a 65  e query optimize
183c0 72 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20  r.  The default 
183d0 73 65 74 74 69 6e 67 20 69 73 20 64 65 74 65 72  setting is deter
183e0 6d 69 6e 65 64 0a 2a 2a 20 62 79 20 74 68 65 20  mined.** by the 
183f0 5b 53 51 4c 49 54 45 5f 41 4c 4c 4f 57 5f 43 4f  [SQLITE_ALLOW_CO
18400 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41  VERING_INDEX_SCA
18410 4e 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  N] compile-time 
18420 6f 70 74 69 6f 6e 2c 20 6f 72 20 69 73 20 22 6f  option, or is "o
18430 6e 22 0a 2a 2a 20 69 66 20 74 68 61 74 20 63 6f  n".** if that co
18440 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
18450 6e 20 69 73 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a  n is omitted..**
18460 20 54 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20   The ability to 
18470 64 69 73 61 62 6c 65 20 74 68 65 20 75 73 65 20  disable the use 
18480 6f 66 20 63 6f 76 65 72 69 6e 67 20 69 6e 64 69  of covering indi
18490 63 65 73 20 66 6f 72 20 66 75 6c 6c 20 74 61 62  ces for full tab
184a0 6c 65 20 73 63 61 6e 73 0a 2a 2a 20 69 73 20 62  le scans.** is b
184b0 65 63 61 75 73 65 20 73 6f 6d 65 20 69 6e 63 6f  ecause some inco
184c0 72 72 65 63 74 6c 79 20 63 6f 64 65 64 20 6c 65  rrectly coded le
184d0 67 61 63 79 20 61 70 70 6c 69 63 61 74 69 6f 6e  gacy application
184e0 73 20 6d 69 67 68 74 20 6d 61 6c 66 75 6e 63 74  s might malfunct
184f0 69 6f 6e 0a 2a 2a 20 6d 61 6c 66 75 6e 63 74 69  ion.** malfuncti
18500 6f 6e 20 77 68 65 6e 20 74 68 65 20 6f 70 74 69  on when the opti
18510 6d 69 7a 61 74 69 6f 6e 20 69 73 20 65 6e 61 62  mization is enab
18520 6c 65 64 2e 20 20 50 72 6f 76 69 64 69 6e 67 20  led.  Providing 
18530 74 68 65 20 61 62 69 6c 69 74 79 20 74 6f 0a 2a  the ability to.*
18540 2a 20 64 69 73 61 62 6c 65 20 74 68 65 20 6f 70  * disable the op
18550 74 69 6d 69 7a 61 74 69 6f 6e 20 61 6c 6c 6f 77  timization allow
18560 73 20 74 68 65 20 6f 6c 64 65 72 2c 20 62 75 67  s the older, bug
18570 67 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63  gy application c
18580 6f 64 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77  ode to work.** w
18590 69 74 68 6f 75 74 20 63 68 61 6e 67 65 20 65 76  ithout change ev
185a0 65 6e 20 77 69 74 68 20 6e 65 77 65 72 20 76 65  en with newer ve
185b0 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
185c0 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ..**.** [[SQLITE
185d0 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5d 5d  _CONFIG_PCACHE]]
185e0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
185f0 5f 47 45 54 50 43 41 43 48 45 5d 5d 0a 2a 2a 20  _GETPCACHE]].** 
18600 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
18610 47 5f 50 43 41 43 48 45 20 61 6e 64 20 53 51 4c  G_PCACHE and SQL
18620 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
18630 41 43 48 45 0a 2a 2a 20 3c 64 64 3e 20 54 68 65  ACHE.** <dd> The
18640 73 65 20 6f 70 74 69 6f 6e 73 20 61 72 65 20 6f  se options are o
18650 62 73 6f 6c 65 74 65 20 61 6e 64 20 73 68 6f 75  bsolete and shou
18660 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20 62  ld not be used b
18670 79 20 6e 65 77 20 63 6f 64 65 2e 0a 2a 2a 20 54  y new code..** T
18680 68 65 79 20 61 72 65 20 72 65 74 61 69 6e 65 64  hey are retained
18690 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63   for backwards c
186a0 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 62 75 74  ompatibility but
186b0 20 61 72 65 20 6e 6f 77 20 6e 6f 2d 6f 70 73 2e   are now no-ops.
186c0 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </dl>.**.** 
186d0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
186e0 53 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20 3c 64 74 3e  SQLLOG]].** <dt>
186f0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51  SQLITE_CONFIG_SQ
18700 4c 4c 4f 47 0a 2a 2a 20 3c 64 64 3e 54 68 69 73  LLOG.** <dd>This
18710 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20   option is only 
18720 61 76 61 69 6c 61 62 6c 65 20 69 66 20 73 71 6c  available if sql
18730 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
18740 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49  with the.** SQLI
18750 54 45 5f 45 4e 41 42 4c 45 5f 53 51 4c 4c 4f 47  TE_ENABLE_SQLLOG
18760 20 70 72 65 2d 70 72 6f 63 65 73 73 6f 72 20 6d   pre-processor m
18770 61 63 72 6f 20 64 65 66 69 6e 65 64 2e 20 54 68  acro defined. Th
18780 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
18790 20 73 68 6f 75 6c 64 0a 2a 2a 20 62 65 20 61 20   should.** be a 
187a0 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 66 75 6e  pointer to a fun
187b0 63 74 69 6f 6e 20 6f 66 20 74 79 70 65 20 76 6f  ction of type vo
187c0 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69  id(*)(void*,sqli
187d0 74 65 33 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  te3*,const char*
187e0 2c 20 69 6e 74 29 2e 0a 2a 2a 20 54 68 65 20 73  , int)..** The s
187f0 65 63 6f 6e 64 20 73 68 6f 75 6c 64 20 62 65 20  econd should be 
18800 6f 66 20 74 79 70 65 20 28 76 6f 69 64 2a 29 2e  of type (void*).
18810 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   The callback is
18820 20 69 6e 76 6f 6b 65 64 20 62 79 20 74 68 65 20   invoked by the 
18830 6c 69 62 72 61 72 79 0a 2a 2a 20 69 6e 20 74 68  library.** in th
18840 72 65 65 20 73 65 70 61 72 61 74 65 20 63 69 72  ree separate cir
18850 63 75 6d 73 74 61 6e 63 65 73 2c 20 69 64 65 6e  cumstances, iden
18860 74 69 66 69 65 64 20 62 79 20 74 68 65 20 76 61  tified by the va
18870 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74 68  lue passed as th
18880 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61 72 61  e.** fourth para
18890 6d 65 74 65 72 2e 20 49 66 20 74 68 65 20 66 6f  meter. If the fo
188a0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
188b0 73 20 30 2c 20 74 68 65 6e 20 74 68 65 20 64 61  s 0, then the da
188c0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
188d0 6e 0a 2a 2a 20 70 61 73 73 65 64 20 61 73 20 74  n.** passed as t
188e0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
188f0 6e 74 20 68 61 73 20 6a 75 73 74 20 62 65 65 6e  nt has just been
18900 20 6f 70 65 6e 65 64 2e 20 54 68 65 20 74 68 69   opened. The thi
18910 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 70  rd argument.** p
18920 6f 69 6e 74 73 20 74 6f 20 61 20 62 75 66 66 65  oints to a buffe
18930 72 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  r containing the
18940 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6d 61 69   name of the mai
18950 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e  n database file.
18960 20 49 66 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74   If the.** fourt
18970 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 31  h parameter is 1
18980 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20 73  , then the SQL s
18990 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 74 68  tatement that th
189a0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
189b0 72 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20 68  r.** points to h
189c0 61 73 20 6a 75 73 74 20 62 65 65 6e 20 65 78 65  as just been exe
189d0 63 75 74 65 64 2e 20 4f 72 2c 20 69 66 20 74 68  cuted. Or, if th
189e0 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
189f0 65 72 20 69 73 20 32 2c 20 74 68 65 6e 0a 2a 2a  er is 2, then.**
18a00 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20   the connection 
18a10 62 65 69 6e 67 20 70 61 73 73 65 64 20 61 73 20  being passed as 
18a20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
18a30 65 74 65 72 20 69 73 20 62 65 69 6e 67 20 63 6c  eter is being cl
18a40 6f 73 65 64 2e 20 54 68 65 0a 2a 2a 20 74 68 69  osed. The.** thi
18a50 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  rd parameter is 
18a60 70 61 73 73 65 64 20 4e 55 4c 4c 20 49 6e 20 74  passed NULL In t
18a70 68 69 73 20 63 61 73 65 2e 0a 2a 2a 20 3c 2f 64  his case..** </d
18a80 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  l>.*/.#define SQ
18a90 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
18aa0 4c 45 54 48 52 45 41 44 20 20 31 20 20 2f 2a 20  LETHREAD  1  /* 
18ab0 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nil */.#define S
18ac0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
18ad0 54 49 54 48 52 45 41 44 20 20 20 32 20 20 2f 2a  TITHREAD   2  /*
18ae0 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20   nil */.#define 
18af0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45  SQLITE_CONFIG_SE
18b00 52 49 41 4c 49 5a 45 44 20 20 20 20 33 20 20 2f  RIALIZED    3  /
18b10 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65  * nil */.#define
18b20 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
18b30 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 34 20 20  ALLOC        4  
18b40 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  /* sqlite3_mem_m
18b50 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69  ethods* */.#defi
18b60 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
18b70 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20 20 35  _GETMALLOC     5
18b80 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d    /* sqlite3_mem
18b90 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65  _methods* */.#de
18ba0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
18bb0 49 47 5f 53 43 52 41 54 43 48 20 20 20 20 20 20  IG_SCRATCH      
18bc0 20 36 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e   6  /* void*, in
18bd0 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23  t sz, int N */.#
18be0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
18bf0 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 20 20  NFIG_PAGECACHE  
18c00 20 20 20 37 20 20 2f 2a 20 76 6f 69 64 2a 2c 20     7  /* void*, 
18c10 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f  int sz, int N */
18c20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18c30 43 4f 4e 46 49 47 5f 48 45 41 50 20 20 20 20 20  CONFIG_HEAP     
18c40 20 20 20 20 20 38 20 20 2f 2a 20 76 6f 69 64 2a       8  /* void*
18c50 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 69 6e 74  , int nByte, int
18c60 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20   min */.#define 
18c70 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
18c80 4d 53 54 41 54 55 53 20 20 20 20 20 39 20 20 2f  MSTATUS     9  /
18c90 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65  * boolean */.#de
18ca0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
18cb0 49 47 5f 4d 55 54 45 58 20 20 20 20 20 20 20 20  IG_MUTEX        
18cc0 31 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d  10  /* sqlite3_m
18cd0 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f  utex_methods* */
18ce0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18cf0 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20  CONFIG_GETMUTEX 
18d00 20 20 20 20 31 31 20 20 2f 2a 20 73 71 6c 69 74      11  /* sqlit
18d10 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
18d20 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f 75 73  * */./* previous
18d30 6c 79 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ly SQLITE_CONFIG
18d40 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 31 32 20 77  _CHUNKALLOC 12 w
18d50 68 69 63 68 20 69 73 20 6e 6f 77 20 75 6e 75 73  hich is now unus
18d60 65 64 2e 20 2a 2f 20 0a 23 64 65 66 69 6e 65 20  ed. */ .#define 
18d70 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
18d80 4f 4b 41 53 49 44 45 20 20 20 20 31 33 20 20 2f  OKASIDE    13  /
18d90 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65  * int int */.#de
18da0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
18db0 49 47 5f 50 43 41 43 48 45 20 20 20 20 20 20 20  IG_PCACHE       
18dc0 31 34 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a  14  /* no-op */.
18dd0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
18de0 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 20  ONFIG_GETPCACHE 
18df0 20 20 20 31 35 20 20 2f 2a 20 6e 6f 2d 6f 70 20     15  /* no-op 
18e00 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
18e10 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 20 20 20  E_CONFIG_LOG    
18e20 20 20 20 20 20 20 31 36 20 20 2f 2a 20 78 46 75        16  /* xFu
18e30 6e 63 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65  nc, void* */.#de
18e40 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
18e50 49 47 5f 55 52 49 20 20 20 20 20 20 20 20 20 20  IG_URI          
18e60 31 37 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64  17  /* int */.#d
18e70 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
18e80 46 49 47 5f 50 43 41 43 48 45 32 20 20 20 20 20  FIG_PCACHE2     
18e90 20 31 38 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f   18  /* sqlite3_
18ea0 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a  pcache_methods2*
18eb0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
18ec0 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41  TE_CONFIG_GETPCA
18ed0 43 48 45 32 20 20 20 31 39 20 20 2f 2a 20 73 71  CHE2   19  /* sq
18ee0 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74  lite3_pcache_met
18ef0 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e  hods2* */.#defin
18f00 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
18f10 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53  COVERING_INDEX_S
18f20 43 41 4e 20 32 30 20 20 2f 2a 20 69 6e 74 20 2a  CAN 20  /* int *
18f30 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
18f40 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 20 20  _CONFIG_SQLLOG  
18f50 20 20 20 20 20 32 31 20 20 2f 2a 20 78 53 71 6c       21  /* xSql
18f60 6c 6f 67 2c 20 76 6f 69 64 2a 20 2a 2f 0a 0a 2f  log, void* */../
18f70 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
18f80 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
18f90 6f 6e 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e  on Configuration
18fa0 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54   Options.**.** T
18fb0 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61  hese constants a
18fc0 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65  re the available
18fd0 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75   integer configu
18fe0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74  ration options t
18ff0 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61  hat.** can be pa
19000 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  ssed as the seco
19010 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  nd argument to t
19020 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  he [sqlite3_db_c
19030 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61  onfig()] interfa
19040 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f  ce..**.** New co
19050 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
19060 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  ons may be added
19070 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
19080 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ses of SQLite..*
19090 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69  * Existing confi
190a0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
190b0 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e   might be discon
190c0 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61  tinued.  Applica
190d0 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20  tions.** should 
190e0 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e  check the return
190f0 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69   code from [sqli
19100 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d  te3_db_config()]
19110 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68   to make sure th
19120 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77  at.** the call w
19130 6f 72 6b 65 64 2e 20 20 5e 54 68 65 20 5b 73 71  orked.  ^The [sq
19140 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
19150 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c  )] interface wil
19160 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f  l return a.** no
19170 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f  n-zero [error co
19180 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74  de] if a discont
19190 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f  inued or unsuppo
191a0 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69  rted configurati
191b0 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20  on option.** is 
191c0 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c  invoked..**.** <
191d0 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  dl>.** <dt>SQLIT
191e0 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
191f0 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  SIDE</dt>.** <dd
19200 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74  > ^This option t
19210 61 6b 65 73 20 74 68 72 65 65 20 61 64 64 69 74  akes three addit
19220 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 20  ional arguments 
19230 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74  that determine t
19240 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64  he .** [lookasid
19250 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
19260 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  or] configuratio
19270 6e 20 66 6f 72 20 74 68 65 20 5b 64 61 74 61 62  n for the [datab
19280 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
19290 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61  .** ^The first a
192a0 72 67 75 6d 65 6e 74 20 28 74 68 65 20 74 68 69  rgument (the thi
192b0 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
192c0 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
192d0 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a 20 70 6f  ig()] is a.** po
192e0 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72  inter to a memor
192f0 79 20 62 75 66 66 65 72 20 74 6f 20 75 73 65 20  y buffer to use 
19300 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  for lookaside me
19310 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65 20 66 69  mory..** ^The fi
19320 72 73 74 20 61 72 67 75 6d 65 6e 74 20 61 66 74  rst argument aft
19330 65 72 20 74 68 65 20 53 51 4c 49 54 45 5f 44 42  er the SQLITE_DB
19340 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
19350 20 76 65 72 62 0a 2a 2a 20 6d 61 79 20 62 65 20   verb.** may be 
19360 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68 20 63 61  NULL in which ca
19370 73 65 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61  se SQLite will a
19380 6c 6c 6f 63 61 74 65 20 74 68 65 0a 2a 2a 20 6c  llocate the.** l
19390 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20  ookaside buffer 
193a0 69 74 73 65 6c 66 20 75 73 69 6e 67 20 5b 73 71  itself using [sq
193b0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e  lite3_malloc()].
193c0 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67   ^The second arg
193d0 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20  ument is the.** 
193e0 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f  size of each loo
193f0 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c  kaside buffer sl
19400 6f 74 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20  ot.  ^The third 
19410 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
19420 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f  number of.** slo
19430 74 73 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66  ts.  The size of
19440 20 74 68 65 20 62 75 66 66 65 72 20 69 6e 20 74   the buffer in t
19450 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
19460 74 20 6d 75 73 74 20 62 65 20 67 72 65 61 74 65  t must be greate
19470 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 75  r than.** or equ
19480 61 6c 20 74 6f 20 74 68 65 20 70 72 6f 64 75 63  al to the produc
19490 74 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20  t of the second 
194a0 61 6e 64 20 74 68 69 72 64 20 61 72 67 75 6d 65  and third argume
194b0 6e 74 73 2e 20 20 54 68 65 20 62 75 66 66 65 72  nts.  The buffer
194c0 0a 2a 2a 20 6d 75 73 74 20 62 65 20 61 6c 69 67  .** must be alig
194d0 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65  ned to an 8-byte
194e0 20 62 6f 75 6e 64 61 72 79 2e 20 20 5e 49 66 20   boundary.  ^If 
194f0 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
19500 65 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c 49 54 45  ent to.** SQLITE
19510 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
19520 49 44 45 20 69 73 20 6e 6f 74 20 61 20 6d 75 6c  IDE is not a mul
19530 74 69 70 6c 65 20 6f 66 20 38 2c 20 69 74 20 69  tiple of 8, it i
19540 73 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20  s internally.** 
19550 72 6f 75 6e 64 65 64 20 64 6f 77 6e 20 74 6f 20  rounded down to 
19560 74 68 65 20 6e 65 78 74 20 73 6d 61 6c 6c 65 72  the next smaller
19570 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2e 20   multiple of 8. 
19580 20 5e 28 54 68 65 20 6c 6f 6f 6b 61 73 69 64 65   ^(The lookaside
19590 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66 69   memory.** confi
195a0 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 61 20 64  guration for a d
195b0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
195c0 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 63  on can only be c
195d0 68 61 6e 67 65 64 20 77 68 65 6e 20 74 68 61 74  hanged when that
195e0 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  .** connection i
195f0 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20  s not currently 
19600 75 73 69 6e 67 20 6c 6f 6f 6b 61 73 69 64 65 20  using lookaside 
19610 6d 65 6d 6f 72 79 2c 20 6f 72 20 69 6e 20 6f 74  memory, or in ot
19620 68 65 72 20 77 6f 72 64 73 0a 2a 2a 20 77 68 65  her words.** whe
19630 6e 20 74 68 65 20 22 63 75 72 72 65 6e 74 20 76  n the "current v
19640 61 6c 75 65 22 20 72 65 74 75 72 6e 65 64 20 62  alue" returned b
19650 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 64 62  y.** [sqlite3_db
19660 5f 73 74 61 74 75 73 5d 28 44 2c 5b 53 51 4c 49  _status](D,[SQLI
19670 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  TE_CONFIG_LOOKAS
19680 49 44 45 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65 72  IDE],...) is zer
19690 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70  o..** Any attemp
196a0 74 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20  t to change the 
196b0 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79  lookaside memory
196c0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 77   configuration w
196d0 68 65 6e 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a  hen lookaside.**
196e0 20 6d 65 6d 6f 72 79 20 69 73 20 69 6e 20 75 73   memory is in us
196f0 65 20 6c 65 61 76 65 73 20 74 68 65 20 63 6f 6e  e leaves the con
19700 66 69 67 75 72 61 74 69 6f 6e 20 75 6e 63 68 61  figuration uncha
19710 6e 67 65 64 20 61 6e 64 20 72 65 74 75 72 6e 73  nged and returns
19720 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53   .** [SQLITE_BUS
19730 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  Y].)^</dd>.**.**
19740 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f   <dt>SQLITE_DBCO
19750 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59  NFIG_ENABLE_FKEY
19760 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
19770 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73  his option is us
19780 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20  ed to enable or 
19790 64 69 73 61 62 6c 65 20 74 68 65 20 65 6e 66 6f  disable the enfo
197a0 72 63 65 6d 65 6e 74 20 6f 66 0a 2a 2a 20 5b 66  rcement of.** [f
197b0 6f 72 65 69 67 6e 20 6b 65 79 20 63 6f 6e 73 74  oreign key const
197c0 72 61 69 6e 74 73 5d 2e 20 20 54 68 65 72 65 20  raints].  There 
197d0 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64  should be two ad
197e0 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e  ditional argumen
197f0 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  ts..** The first
19800 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20   argument is an 
19810 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73  integer which is
19820 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 46 4b   0 to disable FK
19830 20 65 6e 66 6f 72 63 65 6d 65 6e 74 2c 0a 2a 2a   enforcement,.**
19840 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61   positive to ena
19850 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65  ble FK enforceme
19860 6e 74 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74  nt or negative t
19870 6f 20 6c 65 61 76 65 20 46 4b 20 65 6e 66 6f 72  o leave FK enfor
19880 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e 63 68 61 6e  cement.** unchan
19890 67 65 64 2e 20 20 54 68 65 20 73 65 63 6f 6e 64  ged.  The second
198a0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
198b0 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
198c0 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68  teger into which
198d0 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30  .** is written 0
198e0 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74   or 1 to indicat
198f0 65 20 77 68 65 74 68 65 72 20 46 4b 20 65 6e 66  e whether FK enf
19900 6f 72 63 65 6d 65 6e 74 20 69 73 20 6f 66 66 20  orcement is off 
19910 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77 69  or on.** followi
19920 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54  ng this call.  T
19930 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
19940 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c  ter may be a NUL
19950 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a  L pointer, in.**
19960 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20   which case the 
19970 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 73  FK enforcement s
19980 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65  etting is not re
19990 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64  ported back. </d
199a0 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
199b0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41  ITE_DBCONFIG_ENA
199c0 42 4c 45 5f 54 52 49 47 47 45 52 3c 2f 64 74 3e  BLE_TRIGGER</dt>
199d0 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f  .** <dd> ^This o
199e0 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f  ption is used to
199f0 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62   enable or disab
19a00 6c 65 20 5b 43 52 45 41 54 45 20 54 52 49 47 47  le [CREATE TRIGG
19a10 45 52 20 7c 20 74 72 69 67 67 65 72 73 5d 2e 0a  ER | triggers]..
19a20 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20  ** There should 
19a30 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61  be two additiona
19a40 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20  l arguments..** 
19a50 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
19a60 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  nt is an integer
19a70 20 77 68 69 63 68 20 69 73 20 30 20 74 6f 20 64   which is 0 to d
19a80 69 73 61 62 6c 65 20 74 72 69 67 67 65 72 73 2c  isable triggers,
19a90 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20  .** positive to 
19aa0 65 6e 61 62 6c 65 20 74 72 69 67 67 65 72 73 20  enable triggers 
19ab0 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c  or negative to l
19ac0 65 61 76 65 20 74 68 65 20 73 65 74 74 69 6e 67  eave the setting
19ad0 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 54   unchanged..** T
19ae0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
19af0 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ter is a pointer
19b00 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69   to an integer i
19b10 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  nto which.** is 
19b20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74  written 0 or 1 t
19b30 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 68  o indicate wheth
19b40 65 72 20 74 72 69 67 67 65 72 73 20 61 72 65 20  er triggers are 
19b50 64 69 73 61 62 6c 65 64 20 6f 72 20 65 6e 61 62  disabled or enab
19b60 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67  led.** following
19b70 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65   this call.  The
19b80 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
19b90 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20  r may be a NULL 
19ba0 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77  pointer, in.** w
19bb0 68 69 63 68 20 63 61 73 65 20 74 68 65 20 74 72  hich case the tr
19bc0 69 67 67 65 72 20 73 65 74 74 69 6e 67 20 69 73  igger setting is
19bd0 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61   not reported ba
19be0 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ck. </dd>.**.** 
19bf0 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65  </dl>.*/.#define
19c00 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
19c10 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 20 20  _LOOKASIDE      
19c20 20 31 30 30 31 20 20 2f 2a 20 76 6f 69 64 2a 20   1001  /* void* 
19c30 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69  int int */.#defi
19c40 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  ne SQLITE_DBCONF
19c50 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 20 20  IG_ENABLE_FKEY  
19c60 20 20 20 31 30 30 32 20 20 2f 2a 20 69 6e 74 20     1002  /* int 
19c70 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  int* */.#define 
19c80 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
19c90 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 20 20  ENABLE_TRIGGER  
19ca0 31 30 30 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74  1003  /* int int
19cb0 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  * */.../*.** CAP
19cc0 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72  I3REF: Enable Or
19cd0 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e 64 65   Disable Extende
19ce0 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a  d Result Codes.*
19cf0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
19d00 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c  3_extended_resul
19d10 74 5f 63 6f 64 65 73 28 29 20 72 6f 75 74 69 6e  t_codes() routin
19d20 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73  e enables or dis
19d30 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20 5b 65 78  ables the.** [ex
19d40 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
19d50 64 65 73 5d 20 66 65 61 74 75 72 65 20 6f 66 20  des] feature of 
19d60 53 51 4c 69 74 65 2e 20 5e 54 68 65 20 65 78 74  SQLite. ^The ext
19d70 65 6e 64 65 64 20 72 65 73 75 6c 74 0a 2a 2a 20  ended result.** 
19d80 63 6f 64 65 73 20 61 72 65 20 64 69 73 61 62 6c  codes are disabl
19d90 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 66 6f  ed by default fo
19da0 72 20 68 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d  r historical com
19db0 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2f 0a 53  patibility..*/.S
19dc0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
19dd0 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72  lite3_extended_r
19de0 65 73 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69  esult_codes(sqli
19df0 74 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29  te3*, int onoff)
19e00 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
19e10 46 3a 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52  F: Last Insert R
19e20 6f 77 69 64 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68  owid.**.** ^Each
19e30 20 65 6e 74 72 79 20 69 6e 20 61 6e 20 53 51 4c   entry in an SQL
19e40 69 74 65 20 74 61 62 6c 65 20 68 61 73 20 61 20  ite table has a 
19e50 75 6e 69 71 75 65 20 36 34 2d 62 69 74 20 73 69  unique 64-bit si
19e60 67 6e 65 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20  gned.** integer 
19e70 6b 65 79 20 63 61 6c 6c 65 64 20 74 68 65 20 5b  key called the [
19e80 52 4f 57 49 44 20 7c 20 22 72 6f 77 69 64 22 5d  ROWID | "rowid"]
19e90 2e 20 5e 54 68 65 20 72 6f 77 69 64 20 69 73 20  . ^The rowid is 
19ea0 61 6c 77 61 79 73 20 61 76 61 69 6c 61 62 6c 65  always available
19eb0 0a 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65 63 6c  .** as an undecl
19ec0 61 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65  ared column name
19ed0 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72  d ROWID, OID, or
19ee0 20 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e 67   _ROWID_ as long
19ef0 20 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d   as those.** nam
19f00 65 73 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f 20  es are not also 
19f10 75 73 65 64 20 62 79 20 65 78 70 6c 69 63 69 74  used by explicit
19f20 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75  ly declared colu
19f30 6d 6e 73 2e 20 5e 49 66 0a 2a 2a 20 74 68 65 20  mns. ^If.** the 
19f40 74 61 62 6c 65 20 68 61 73 20 61 20 63 6f 6c 75  table has a colu
19f50 6d 6e 20 6f 66 20 74 79 70 65 20 5b 49 4e 54 45  mn of type [INTE
19f60 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d  GER PRIMARY KEY]
19f70 20 74 68 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d   then that colum
19f80 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72 20  n.** is another 
19f90 61 6c 69 61 73 20 66 6f 72 20 74 68 65 20 72 6f  alias for the ro
19fa0 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  wid..**.** ^This
19fb0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
19fc0 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20   the [rowid] of 
19fd0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 0a  the most recent.
19fe0 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49  ** successful [I
19ff0 4e 53 45 52 54 5d 20 69 6e 74 6f 20 74 68 65 20  NSERT] into the 
1a000 64 61 74 61 62 61 73 65 20 66 72 6f 6d 20 74 68  database from th
1a010 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
1a020 65 63 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68  ection].** in th
1a030 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
1a040 2e 20 20 5e 41 73 20 6f 66 20 53 51 4c 69 74 65  .  ^As of SQLite
1a050 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 37 2c 20   version 3.7.7, 
1a060 74 68 69 73 20 72 6f 75 74 69 6e 65 73 0a 2a 2a  this routines.**
1a070 20 72 65 63 6f 72 64 73 20 74 68 65 20 6c 61 73   records the las
1a080 74 20 69 6e 73 65 72 74 20 72 6f 77 69 64 20 6f  t insert rowid o
1a090 66 20 62 6f 74 68 20 6f 72 64 69 6e 61 72 79 20  f both ordinary 
1a0a0 74 61 62 6c 65 73 20 61 6e 64 20 5b 76 69 72 74  tables and [virt
1a0b0 75 61 6c 20 74 61 62 6c 65 73 5d 2e 0a 2a 2a 20  ual tables]..** 
1a0c0 5e 49 66 20 6e 6f 20 73 75 63 63 65 73 73 66 75  ^If no successfu
1a0d0 6c 20 5b 49 4e 53 45 52 54 5d 73 0a 2a 2a 20 68  l [INSERT]s.** h
1a0e0 61 76 65 20 65 76 65 72 20 6f 63 63 75 72 72 65  ave ever occurre
1a0f0 64 20 6f 6e 20 74 68 61 74 20 64 61 74 61 62 61  d on that databa
1a100 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 7a  se connection, z
1a110 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ero is returned.
1a120 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e 20 5b  .**.** ^(If an [
1a130 49 4e 53 45 52 54 5d 20 6f 63 63 75 72 73 20 77  INSERT] occurs w
1a140 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 20  ithin a trigger 
1a150 6f 72 20 77 69 74 68 69 6e 20 61 20 5b 76 69 72  or within a [vir
1a160 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 6d  tual table].** m
1a170 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 69 73  ethod, then this
1a180 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 72 65   routine will re
1a190 74 75 72 6e 20 74 68 65 20 5b 72 6f 77 69 64 5d  turn the [rowid]
1a1a0 20 6f 66 20 74 68 65 20 69 6e 73 65 72 74 65 64   of the inserted
1a1b0 0a 2a 2a 20 72 6f 77 20 61 73 20 6c 6f 6e 67 20  .** row as long 
1a1c0 61 73 20 74 68 65 20 74 72 69 67 67 65 72 20 6f  as the trigger o
1a1d0 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20  r virtual table 
1a1e0 6d 65 74 68 6f 64 20 69 73 20 72 75 6e 6e 69 6e  method is runnin
1a1f0 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 20 74  g..** But once t
1a200 68 65 20 74 72 69 67 67 65 72 20 6f 72 20 76 69  he trigger or vi
1a210 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 65 74 68  rtual table meth
1a220 6f 64 20 65 6e 64 73 2c 20 74 68 65 20 76 61 6c  od ends, the val
1a230 75 65 20 72 65 74 75 72 6e 65 64 20 0a 2a 2a 20  ue returned .** 
1a240 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  by this routine 
1a250 72 65 76 65 72 74 73 20 74 6f 20 77 68 61 74 20  reverts to what 
1a260 69 74 20 77 61 73 20 62 65 66 6f 72 65 20 74 68  it was before th
1a270 65 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 72  e trigger or vir
1a280 74 75 61 6c 0a 2a 2a 20 74 61 62 6c 65 20 6d 65  tual.** table me
1a290 74 68 6f 64 20 62 65 67 61 6e 2e 29 5e 0a 2a 2a  thod began.)^.**
1a2a0 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 54 5d  .** ^An [INSERT]
1a2b0 20 74 68 61 74 20 66 61 69 6c 73 20 64 75 65 20   that fails due 
1a2c0 74 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20  to a constraint 
1a2d0 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74  violation is not
1a2e0 20 61 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c   a.** successful
1a2f0 20 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f   [INSERT] and do
1a300 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  es not change th
1a310 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
1a320 20 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74   by this.** rout
1a330 69 6e 65 2e 20 20 5e 54 68 75 73 20 49 4e 53 45  ine.  ^Thus INSE
1a340 52 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45  RT OR FAIL, INSE
1a350 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e  RT OR IGNORE, IN
1a360 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b  SERT OR ROLLBACK
1a370 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54 20  ,.** and INSERT 
1a380 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f  OR ABORT make no
1a390 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20   changes to the 
1a3a0 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
1a3b0 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  this.** routine 
1a3c0 77 68 65 6e 20 74 68 65 69 72 20 69 6e 73 65 72  when their inser
1a3d0 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 5e 28 57  tion fails.  ^(W
1a3e0 68 65 6e 20 49 4e 53 45 52 54 20 4f 52 20 52 45  hen INSERT OR RE
1a3f0 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74  PLACE.** encount
1a400 65 72 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74  ers a constraint
1a410 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64   violation, it d
1a420 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54  oes not fail.  T
1a430 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e  he.** INSERT con
1a440 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65  tinues to comple
1a450 74 69 6f 6e 20 61 66 74 65 72 20 64 65 6c 65 74  tion after delet
1a460 69 6e 67 20 72 6f 77 73 20 74 68 61 74 20 63 61  ing rows that ca
1a470 75 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73  used.** the cons
1a480 74 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73  traint problem s
1a490 6f 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c  o INSERT OR REPL
1a4a0 41 43 45 20 77 69 6c 6c 20 61 6c 77 61 79 73 20  ACE will always 
1a4b0 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65  change.** the re
1a4c0 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
1a4d0 69 73 20 69 6e 74 65 72 66 61 63 65 2e 29 5e 0a  is interface.)^.
1a4e0 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70  **.** ^For the p
1a4f0 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20  urposes of this 
1a500 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53  routine, an [INS
1a510 45 52 54 5d 20 69 73 20 63 6f 6e 73 69 64 65 72  ERT] is consider
1a520 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63  ed to.** be succ
1a530 65 73 73 66 75 6c 20 65 76 65 6e 20 69 66 20 69  essful even if i
1a540 74 20 69 73 20 73 75 62 73 65 71 75 65 6e 74 6c  t is subsequentl
1a550 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a  y rolled back..*
1a560 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69  *.** This functi
1a570 6f 6e 20 69 73 20 61 63 63 65 73 73 69 62 6c 65  on is accessible
1a580 20 74 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   to SQL statemen
1a590 74 73 20 76 69 61 20 74 68 65 0a 2a 2a 20 5b 6c  ts via the.** [l
1a5a0 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
1a5b0 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d  () SQL function]
1a5c0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70  ..**.** If a sep
1a5d0 61 72 61 74 65 20 74 68 72 65 61 64 20 70 65 72  arate thread per
1a5e0 66 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53  forms a new [INS
1a5f0 45 52 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65  ERT] on the same
1a600 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
1a610 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68  nection while th
1a620 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f  e [sqlite3_last_
1a630 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a  insert_rowid()].
1a640 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  ** function is r
1a650 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 73 20  unning and thus 
1a660 63 68 61 6e 67 65 73 20 74 68 65 20 6c 61 73 74  changes the last
1a670 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c   insert [rowid],
1a680 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 76 61 6c  .** then the val
1a690 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  ue returned by [
1a6a0 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73  sqlite3_last_ins
1a6b0 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a  ert_rowid()] is.
1a6c0 2a 2a 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65  ** unpredictable
1a6d0 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20 65   and might not e
1a6e0 71 75 61 6c 20 65 69 74 68 65 72 20 74 68 65 20  qual either the 
1a6f0 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a  old or the new.*
1a700 2a 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72  * last insert [r
1a710 6f 77 69 64 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45  owid]..*/.SQLITE
1a720 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74  _API sqlite3_int
1a730 36 34 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f  64 sqlite3_last_
1a740 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 71 6c  insert_rowid(sql
1a750 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
1a760 41 50 49 33 52 45 46 3a 20 43 6f 75 6e 74 20 54  API3REF: Count T
1a770 68 65 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77  he Number Of Row
1a780 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a  s Modified.**.**
1a790 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20   ^This function 
1a7a0 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
1a7b0 65 72 20 6f 66 20 64 61 74 61 62 61 73 65 20 72  er of database r
1a7c0 6f 77 73 20 74 68 61 74 20 77 65 72 65 20 63 68  ows that were ch
1a7d0 61 6e 67 65 64 0a 2a 2a 20 6f 72 20 69 6e 73 65  anged.** or inse
1a7e0 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 20  rted or deleted 
1a7f0 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  by the most rece
1a800 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 53  ntly completed S
1a810 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  QL statement.** 
1a820 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  on the [database
1a830 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65   connection] spe
1a840 63 69 66 69 65 64 20 62 79 20 74 68 65 20 66 69  cified by the fi
1a850 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  rst parameter..*
1a860 2a 20 5e 28 4f 6e 6c 79 20 63 68 61 6e 67 65 73  * ^(Only changes
1a870 20 74 68 61 74 20 61 72 65 20 64 69 72 65 63 74   that are direct
1a880 6c 79 20 73 70 65 63 69 66 69 65 64 20 62 79 20  ly specified by 
1a890 74 68 65 20 5b 49 4e 53 45 52 54 5d 2c 20 5b 55  the [INSERT], [U
1a8a0 50 44 41 54 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 44  PDATE],.** or [D
1a8b0 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65 6e 74  ELETE] statement
1a8c0 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 20 20 41   are counted.  A
1a8d0 75 78 69 6c 69 61 72 79 20 63 68 61 6e 67 65 73  uxiliary changes
1a8e0 20 63 61 75 73 65 64 20 62 79 0a 2a 2a 20 74 72   caused by.** tr
1a8f0 69 67 67 65 72 73 20 6f 72 20 5b 66 6f 72 65 69  iggers or [forei
1a900 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 20  gn key actions] 
1a910 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e  are not counted.
1a920 29 5e 20 55 73 65 20 74 68 65 0a 2a 2a 20 5b 73  )^ Use the.** [s
1a930 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
1a940 6e 67 65 73 28 29 5d 20 66 75 6e 63 74 69 6f 6e  nges()] function
1a950 20 74 6f 20 66 69 6e 64 20 74 68 65 20 74 6f 74   to find the tot
1a960 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61  al number of cha
1a970 6e 67 65 73 0a 2a 2a 20 69 6e 63 6c 75 64 69 6e  nges.** includin
1a980 67 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64  g changes caused
1a990 20 62 79 20 74 72 69 67 67 65 72 73 20 61 6e 64   by triggers and
1a9a0 20 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74   foreign key act
1a9b0 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 43 68 61  ions..**.** ^Cha
1a9c0 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77 20 74  nges to a view t
1a9d0 68 61 74 20 61 72 65 20 73 69 6d 75 6c 61 74 65  hat are simulate
1a9e0 64 20 62 79 20 61 6e 20 5b 49 4e 53 54 45 41 44  d by an [INSTEAD
1a9f0 20 4f 46 20 74 72 69 67 67 65 72 5d 0a 2a 2a 20   OF trigger].** 
1aa00 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e  are not counted.
1aa10 20 20 4f 6e 6c 79 20 72 65 61 6c 20 74 61 62 6c    Only real tabl
1aa20 65 20 63 68 61 6e 67 65 73 20 61 72 65 20 63 6f  e changes are co
1aa30 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41  unted..**.** ^(A
1aa40 20 22 72 6f 77 20 63 68 61 6e 67 65 22 20 69 73   "row change" is
1aa50 20 61 20 63 68 61 6e 67 65 20 74 6f 20 61 20 73   a change to a s
1aa60 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20 61 20 73  ingle row of a s
1aa70 69 6e 67 6c 65 20 74 61 62 6c 65 0a 2a 2a 20 63  ingle table.** c
1aa80 61 75 73 65 64 20 62 79 20 61 6e 20 49 4e 53 45  aused by an INSE
1aa90 52 54 2c 20 44 45 4c 45 54 45 2c 20 6f 72 20 55  RT, DELETE, or U
1aaa0 50 44 41 54 45 20 73 74 61 74 65 6d 65 6e 74 2e  PDATE statement.
1aab0 20 20 52 6f 77 73 20 74 68 61 74 0a 2a 2a 20 61    Rows that.** a
1aac0 72 65 20 63 68 61 6e 67 65 64 20 61 73 20 73 69  re changed as si
1aad0 64 65 20 65 66 66 65 63 74 73 20 6f 66 20 5b 52  de effects of [R
1aae0 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 69  EPLACE] constrai
1aaf0 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 0a 2a  nt resolution,.*
1ab00 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20 41 42 4f 52  * rollback, ABOR
1ab10 54 20 70 72 6f 63 65 73 73 69 6e 67 2c 20 5b 44  T processing, [D
1ab20 52 4f 50 20 54 41 42 4c 45 5d 2c 20 6f 72 20 62  ROP TABLE], or b
1ab30 79 20 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 6d  y any other.** m
1ab40 65 63 68 61 6e 69 73 6d 73 20 64 6f 20 6e 6f 74  echanisms do not
1ab50 20 63 6f 75 6e 74 20 61 73 20 64 69 72 65 63 74   count as direct
1ab60 20 72 6f 77 20 63 68 61 6e 67 65 73 2e 29 5e 0a   row changes.)^.
1ab70 2a 2a 0a 2a 2a 20 41 20 22 74 72 69 67 67 65 72  **.** A "trigger
1ab80 20 63 6f 6e 74 65 78 74 22 20 69 73 20 61 20 73   context" is a s
1ab90 63 6f 70 65 20 6f 66 20 65 78 65 63 75 74 69 6f  cope of executio
1aba0 6e 20 74 68 61 74 20 62 65 67 69 6e 73 20 61 6e  n that begins an
1abb0 64 0a 2a 2a 20 65 6e 64 73 20 77 69 74 68 20 74  d.** ends with t
1abc0 68 65 20 73 63 72 69 70 74 20 6f 66 20 61 20 5b  he script of a [
1abd0 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c  CREATE TRIGGER |
1abe0 20 74 72 69 67 67 65 72 5d 2e 20 0a 2a 2a 20 4d   trigger]. .** M
1abf0 6f 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ost SQL statemen
1ac00 74 73 20 61 72 65 0a 2a 2a 20 65 76 61 6c 75 61  ts are.** evalua
1ac10 74 65 64 20 6f 75 74 73 69 64 65 20 6f 66 20 61  ted outside of a
1ac20 6e 79 20 74 72 69 67 67 65 72 2e 20 20 54 68 69  ny trigger.  Thi
1ac30 73 20 69 73 20 74 68 65 20 22 74 6f 70 20 6c 65  s is the "top le
1ac40 76 65 6c 22 0a 2a 2a 20 74 72 69 67 67 65 72 20  vel".** trigger 
1ac50 63 6f 6e 74 65 78 74 2e 20 20 49 66 20 61 20 74  context.  If a t
1ac60 72 69 67 67 65 72 20 66 69 72 65 73 20 66 72 6f  rigger fires fro
1ac70 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c  m the top level,
1ac80 20 61 0a 2a 2a 20 6e 65 77 20 74 72 69 67 67 65   a.** new trigge
1ac90 72 20 63 6f 6e 74 65 78 74 20 69 73 20 65 6e 74  r context is ent
1aca0 65 72 65 64 20 66 6f 72 20 74 68 65 20 64 75 72  ered for the dur
1acb0 61 74 69 6f 6e 20 6f 66 20 74 68 61 74 20 6f 6e  ation of that on
1acc0 65 0a 2a 2a 20 74 72 69 67 67 65 72 2e 20 20 53  e.** trigger.  S
1acd0 75 62 74 72 69 67 67 65 72 73 20 63 72 65 61 74  ubtriggers creat
1ace0 65 20 73 75 62 63 6f 6e 74 65 78 74 73 20 66 6f  e subcontexts fo
1acf0 72 20 74 68 65 69 72 20 64 75 72 61 74 69 6f 6e  r their duration
1ad00 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67  ..**.** ^Calling
1ad10 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
1ad20 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 74  ] or [sqlite3_st
1ad30 65 70 28 29 5d 20 72 65 63 75 72 73 69 76 65 6c  ep()] recursivel
1ad40 79 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 63 72  y does.** not cr
1ad50 65 61 74 65 20 61 20 6e 65 77 20 74 72 69 67 67  eate a new trigg
1ad60 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a  er context..**.*
1ad70 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  * ^This function
1ad80 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
1ad90 62 65 72 20 6f 66 20 64 69 72 65 63 74 20 72 6f  ber of direct ro
1ada0 77 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65  w changes in the
1adb0 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  .** most recent 
1adc0 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20  INSERT, UPDATE, 
1add0 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d  or DELETE statem
1ade0 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20 73  ent within the s
1adf0 61 6d 65 0a 2a 2a 20 74 72 69 67 67 65 72 20 63  ame.** trigger c
1ae00 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ontext..**.** ^T
1ae10 68 75 73 2c 20 77 68 65 6e 20 63 61 6c 6c 65 64  hus, when called
1ae20 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65   from the top le
1ae30 76 65 6c 2c 20 74 68 69 73 20 66 75 6e 63 74 69  vel, this functi
1ae40 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a  on returns the.*
1ae50 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 6e  * number of chan
1ae60 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74 20  ges in the most 
1ae70 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55  recent INSERT, U
1ae80 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45  PDATE, or DELETE
1ae90 0a 2a 2a 20 74 68 61 74 20 61 6c 73 6f 20 6f 63  .** that also oc
1aea0 63 75 72 72 65 64 20 61 74 20 74 68 65 20 74 6f  curred at the to
1aeb0 70 20 6c 65 76 65 6c 2e 20 20 5e 28 57 69 74 68  p level.  ^(With
1aec0 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20 61  in the body of a
1aed0 20 74 72 69 67 67 65 72 2c 0a 2a 2a 20 74 68 65   trigger,.** the
1aee0 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73   sqlite3_changes
1aef0 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e  () interface can
1af00 20 62 65 20 63 61 6c 6c 65 64 20 74 6f 20 66 69   be called to fi
1af10 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  nd the number of
1af20 0a 2a 2a 20 63 68 61 6e 67 65 73 20 69 6e 20 74  .** changes in t
1af30 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79  he most recently
1af40 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45 52   completed INSER
1af50 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45  T, UPDATE, or DE
1af60 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  LETE.** statemen
1af70 74 20 77 69 74 68 69 6e 20 74 68 65 20 62 6f 64  t within the bod
1af80 79 20 6f 66 20 74 68 65 20 73 61 6d 65 20 74 72  y of the same tr
1af90 69 67 67 65 72 2e 0a 2a 2a 20 48 6f 77 65 76 65  igger..** Howeve
1afa0 72 2c 20 74 68 65 20 6e 75 6d 62 65 72 20 72 65  r, the number re
1afb0 74 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f 74 20  turned does not 
1afc0 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 65 73 0a  include changes.
1afd0 2a 2a 20 63 61 75 73 65 64 20 62 79 20 73 75 62  ** caused by sub
1afe0 74 72 69 67 67 65 72 73 20 73 69 6e 63 65 20 74  triggers since t
1aff0 68 6f 73 65 20 68 61 76 65 20 74 68 65 69 72 20  hose have their 
1b000 6f 77 6e 20 63 6f 6e 74 65 78 74 2e 29 5e 0a 2a  own context.)^.*
1b010 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68  *.** See also th
1b020 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  e [sqlite3_total
1b030 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65  _changes()] inte
1b040 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63  rface, the.** [c
1b050 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61  ount_changes pra
1b060 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 63  gma], and the [c
1b070 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e  hanges() SQL fun
1b080 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66  ction]..**.** If
1b090 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65   a separate thre
1b0a0 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73  ad makes changes
1b0b0 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74   on the same dat
1b0c0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1b0d0 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74  .** while [sqlit
1b0e0 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73  e3_changes()] is
1b0f0 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68   running then th
1b100 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
1b110 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64 69 63 74  .** is unpredict
1b120 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61  able and not mea
1b130 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49  ningful..*/.SQLI
1b140 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
1b150 65 33 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74  e3_changes(sqlit
1b160 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
1b170 49 33 52 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d  I3REF: Total Num
1b180 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69  ber Of Rows Modi
1b190 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  fied.**.** ^This
1b1a0 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
1b1b0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
1b1c0 72 6f 77 20 63 68 61 6e 67 65 73 20 63 61 75 73  row changes caus
1b1d0 65 64 20 62 79 20 5b 49 4e 53 45 52 54 5d 2c 0a  ed by [INSERT],.
1b1e0 2a 2a 20 5b 55 50 44 41 54 45 5d 20 6f 72 20 5b  ** [UPDATE] or [
1b1f0 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65 6e  DELETE] statemen
1b200 74 73 20 73 69 6e 63 65 20 74 68 65 20 5b 64 61  ts since the [da
1b210 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1b220 6e 5d 20 77 61 73 20 6f 70 65 6e 65 64 2e 0a 2a  n] was opened..*
1b230 2a 20 5e 28 54 68 65 20 63 6f 75 6e 74 20 72 65  * ^(The count re
1b240 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
1b250 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
1b260 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 63  ) includes all c
1b270 68 61 6e 67 65 73 0a 2a 2a 20 66 72 6f 6d 20 61  hanges.** from a
1b280 6c 6c 20 5b 43 52 45 41 54 45 20 54 52 49 47 47  ll [CREATE TRIGG
1b290 45 52 20 7c 20 74 72 69 67 67 65 72 5d 20 63 6f  ER | trigger] co
1b2a0 6e 74 65 78 74 73 20 61 6e 64 20 63 68 61 6e 67  ntexts and chang
1b2b0 65 73 20 6d 61 64 65 20 62 79 0a 2a 2a 20 5b 66  es made by.** [f
1b2c0 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f  oreign key actio
1b2d0 6e 73 5d 2e 20 48 6f 77 65 76 65 72 2c 0a 2a 2a  ns]. However,.**
1b2e0 20 74 68 65 20 63 6f 75 6e 74 20 64 6f 65 73 20   the count does 
1b2f0 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e  not include chan
1b300 67 65 73 20 75 73 65 64 20 74 6f 20 69 6d 70 6c  ges used to impl
1b310 65 6d 65 6e 74 20 5b 52 45 50 4c 41 43 45 5d 20  ement [REPLACE] 
1b320 63 6f 6e 73 74 72 61 69 6e 74 73 2c 0a 2a 2a 20  constraints,.** 
1b330 64 6f 20 72 6f 6c 6c 62 61 63 6b 73 20 6f 72 20  do rollbacks or 
1b340 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67  ABORT processing
1b350 2c 20 6f 72 20 5b 44 52 4f 50 20 54 41 42 4c 45  , or [DROP TABLE
1b360 5d 20 70 72 6f 63 65 73 73 69 6e 67 2e 20 20 54  ] processing.  T
1b370 68 65 0a 2a 2a 20 63 6f 75 6e 74 20 64 6f 65 73  he.** count does
1b380 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 72 6f 77   not include row
1b390 73 20 6f 66 20 76 69 65 77 73 20 74 68 61 74 20  s of views that 
1b3a0 66 69 72 65 20 61 6e 20 5b 49 4e 53 54 45 41 44  fire an [INSTEAD
1b3b0 20 4f 46 20 74 72 69 67 67 65 72 5d 2c 0a 2a 2a   OF trigger],.**
1b3c0 20 74 68 6f 75 67 68 20 69 66 20 74 68 65 20 49   though if the I
1b3d0 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65  NSTEAD OF trigge
1b3e0 72 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20  r makes changes 
1b3f0 6f 66 20 69 74 73 20 6f 77 6e 2c 20 74 68 6f 73  of its own, thos
1b400 65 20 63 68 61 6e 67 65 73 20 0a 2a 2a 20 61 72  e changes .** ar
1b410 65 20 63 6f 75 6e 74 65 64 2e 29 5e 0a 2a 2a 20  e counted.)^.** 
1b420 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74 6f 74  ^The sqlite3_tot
1b430 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 66 75 6e  al_changes() fun
1b440 63 74 69 6f 6e 20 63 6f 75 6e 74 73 20 74 68 65  ction counts the
1b450 20 63 68 61 6e 67 65 73 20 61 73 20 73 6f 6f 6e   changes as soon
1b460 20 61 73 0a 2a 2a 20 74 68 65 20 73 74 61 74 65   as.** the state
1b470 6d 65 6e 74 20 74 68 61 74 20 6d 61 6b 65 73 20  ment that makes 
1b480 74 68 65 6d 20 69 73 20 63 6f 6d 70 6c 65 74 65  them is complete
1b490 64 20 28 77 68 65 6e 20 74 68 65 20 73 74 61 74  d (when the stat
1b4a0 65 6d 65 6e 74 20 68 61 6e 64 6c 65 0a 2a 2a 20  ement handle.** 
1b4b0 69 73 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71  is passed to [sq
1b4c0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
1b4d0 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  r [sqlite3_final
1b4e0 69 7a 65 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53  ize()])..**.** S
1b4f0 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c  ee also the [sql
1b500 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20  ite3_changes()] 
1b510 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a  interface, the.*
1b520 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73  * [count_changes
1b530 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68   pragma], and th
1b540 65 20 5b 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e [total_changes
1b550 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d  () SQL function]
1b560 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70  ..**.** If a sep
1b570 61 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b  arate thread mak
1b580 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68  es changes on th
1b590 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
1b5a0 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68  connection.** wh
1b5b0 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74  ile [sqlite3_tot
1b5c0 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73  al_changes()] is
1b5d0 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68   running then th
1b5e0 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72  e value.** retur
1b5f0 6e 65 64 20 69 73 20 75 6e 70 72 65 64 69 63 74  ned is unpredict
1b600 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61  able and not mea
1b610 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49  ningful..*/.SQLI
1b620 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
1b630 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
1b640 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
1b650 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 74  ** CAPI3REF: Int
1b660 65 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75  errupt A Long-Ru
1b670 6e 6e 69 6e 67 20 51 75 65 72 79 0a 2a 2a 0a 2a  nning Query.**.*
1b680 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  * ^This function
1b690 20 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e 64   causes any pend
1b6a0 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70 65  ing database ope
1b6b0 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20  ration to abort 
1b6c0 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74  and.** return at
1b6d0 20 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f 70   its earliest op
1b6e0 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69 73 20  portunity. This 
1b6f0 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69 63  routine is typic
1b700 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69  ally.** called i
1b710 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61 20  n response to a 
1b720 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63 68  user action such
1b730 20 61 73 20 70 72 65 73 73 69 6e 67 20 22 43 61   as pressing "Ca
1b740 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c  ncel".** or Ctrl
1b750 2d 43 20 77 68 65 72 65 20 74 68 65 20 75 73 65  -C where the use
1b760 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71  r wants a long q
1b770 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20 74  uery operation t
1b780 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69  o halt.** immedi
1b790 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74  ately..**.** ^It
1b7a0 20 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c 6c   is safe to call
1b7b0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66 72   this routine fr
1b7c0 6f 6d 20 61 20 74 68 72 65 61 64 20 64 69 66 66  om a thread diff
1b7d0 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a  erent from the.*
1b7e0 2a 20 74 68 72 65 61 64 20 74 68 61 74 20 69 73  * thread that is
1b7f0 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69   currently runni
1b800 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ng the database 
1b810 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74 20  operation.  But 
1b820 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66  it.** is not saf
1b830 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72  e to call this r
1b840 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20 5b 64  outine with a [d
1b850 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1b860 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20 63  on] that.** is c
1b870 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 20 63  losed or might c
1b880 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 71 6c 69  lose before sqli
1b890 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
1b8a0 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  returns..**.** ^
1b8b0 49 66 20 61 6e 20 53 51 4c 20 6f 70 65 72 61 74  If an SQL operat
1b8c0 69 6f 6e 20 69 73 20 76 65 72 79 20 6e 65 61 72  ion is very near
1b8d0 6c 79 20 66 69 6e 69 73 68 65 64 20 61 74 20 74  ly finished at t
1b8e0 68 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20  he time when.** 
1b8f0 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
1b900 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2c 20 74  t() is called, t
1b910 68 65 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f 74  hen it might not
1b920 20 68 61 76 65 20 61 6e 20 6f 70 70 6f 72 74 75   have an opportu
1b930 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e  nity.** to be in
1b940 74 65 72 72 75 70 74 65 64 20 61 6e 64 20 6d 69  terrupted and mi
1b950 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20  ght continue to 
1b960 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a  completion..**.*
1b970 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 65 72 61 74  * ^An SQL operat
1b980 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e 74 65  ion that is inte
1b990 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72 65 74  rrupted will ret
1b9a0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  urn [SQLITE_INTE
1b9b0 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74  RRUPT]..** ^If t
1b9c0 68 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 53  he interrupted S
1b9d0 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20  QL operation is 
1b9e0 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  an INSERT, UPDAT
1b9f0 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20  E, or DELETE.** 
1ba00 74 68 61 74 20 69 73 20 69 6e 73 69 64 65 20 61  that is inside a
1ba10 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73  n explicit trans
1ba20 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65  action, then the
1ba30 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61 63 74   entire transact
1ba40 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72  ion.** will be r
1ba50 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d  olled back autom
1ba60 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20  atically..**.** 
1ba70 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74  ^The sqlite3_int
1ba80 65 72 72 75 70 74 28 44 29 20 63 61 6c 6c 20 69  errupt(D) call i
1ba90 73 20 69 6e 20 65 66 66 65 63 74 20 75 6e 74 69  s in effect unti
1baa0 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c 79 20  l all currently 
1bab0 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73  running.** SQL s
1bac0 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b 64 61  tatements on [da
1bad0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1bae0 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e 20 20  n] D complete.  
1baf0 5e 41 6e 79 20 6e 65 77 20 53 51 4c 20 73 74 61  ^Any new SQL sta
1bb00 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20  tements.** that 
1bb10 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65  are started afte
1bb20 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  r the sqlite3_in
1bb30 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20 61  terrupt() call a
1bb40 6e 64 20 62 65 66 6f 72 65 20 74 68 65 20 0a 2a  nd before the .*
1bb50 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d  * running statem
1bb60 65 6e 74 73 20 72 65 61 63 68 65 73 20 7a 65 72  ents reaches zer
1bb70 6f 20 61 72 65 20 69 6e 74 65 72 72 75 70 74 65  o are interrupte
1bb80 64 20 61 73 20 69 66 20 74 68 65 79 20 68 61 64  d as if they had
1bb90 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67   been.** running
1bba0 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 73 71   prior to the sq
1bbb0 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
1bbc0 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 20 53 51  ) call.  ^New SQ
1bbd0 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
1bbe0 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64  that are started
1bbf0 20 61 66 74 65 72 20 74 68 65 20 72 75 6e 6e 69   after the runni
1bc00 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 75  ng statement cou
1bc10 6e 74 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20  nt reaches zero 
1bc20 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66 65 63  are.** not effec
1bc30 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74  ted by the sqlit
1bc40 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2e 0a  e3_interrupt()..
1bc50 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 73 71  ** ^A call to sq
1bc60 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
1bc70 44 29 20 74 68 61 74 20 6f 63 63 75 72 73 20 77  D) that occurs w
1bc80 68 65 6e 20 74 68 65 72 65 20 61 72 65 20 6e 6f  hen there are no
1bc90 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20   running.** SQL 
1bca0 73 74 61 74 65 6d 65 6e 74 73 20 69 73 20 61 20  statements is a 
1bcb0 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20 6e 6f  no-op and has no
1bcc0 20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c 20 73   effect on SQL s
1bcd0 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61  tatements.** tha
1bce0 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66  t are started af
1bcf0 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ter the sqlite3_
1bd00 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c  interrupt() call
1bd10 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20   returns..**.** 
1bd20 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  If the database 
1bd30 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65  connection close
1bd40 73 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33  s while [sqlite3
1bd50 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a  _interrupt()].**
1bd60 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e   is running then
1bd70 20 62 61 64 20 74 68 69 6e 67 73 20 77 69 6c 6c   bad things will
1bd80 20 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e 2e 0a   likely happen..
1bd90 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  */.SQLITE_API vo
1bda0 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  id sqlite3_inter
1bdb0 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a  rupt(sqlite3*);.
1bdc0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1bdd0 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e   Determine If An
1bde0 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 49   SQL Statement I
1bdf0 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a  s Complete.**.**
1be00 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
1be10 61 72 65 20 75 73 65 66 75 6c 20 64 75 72 69 6e  are useful durin
1be20 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69  g command-line i
1be30 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d 69 6e  nput to determin
1be40 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75 72 72  e if the.** curr
1be50 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 74 65  ently entered te
1be60 78 74 20 73 65 65 6d 73 20 74 6f 20 66 6f 72 6d  xt seems to form
1be70 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20   a complete SQL 
1be80 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20  statement or.** 
1be90 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  if additional in
1bea0 70 75 74 20 69 73 20 6e 65 65 64 65 64 20 62 65  put is needed be
1beb0 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74 68 65  fore sending the
1bec0 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 51   text into.** SQ
1bed0 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69 6e 67  Lite for parsing
1bee0 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  .  ^These routin
1bef0 65 73 20 72 65 74 75 72 6e 20 31 20 69 66 20 74  es return 1 if t
1bf00 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 0a  he input string.
1bf10 2a 2a 20 61 70 70 65 61 72 73 20 74 6f 20 62 65  ** appears to be
1bf20 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20   a complete SQL 
1bf30 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41 20 73  statement.  ^A s
1bf40 74 61 74 65 6d 65 6e 74 20 69 73 20 6a 75 64 67  tatement is judg
1bf50 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70  ed to be.** comp
1bf60 6c 65 74 65 20 69 66 20 69 74 20 65 6e 64 73 20  lete if it ends 
1bf70 77 69 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e  with a semicolon
1bf80 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e 6f   token and is no
1bf90 74 20 61 20 70 72 65 66 69 78 20 6f 66 20 61 0a  t a prefix of a.
1bfa0 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 20 43  ** well-formed C
1bfb0 52 45 41 54 45 20 54 52 49 47 47 45 52 20 73 74  REATE TRIGGER st
1bfc0 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d 69 63  atement.  ^Semic
1bfd0 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 20 65  olons that are e
1bfe0 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e 0a 2a  mbedded within.*
1bff0 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c  * string literal
1c000 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64 65 6e  s or quoted iden
1c010 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f 72 20  tifier names or 
1c020 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f 74  comments are not
1c030 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74 20  .** independent 
1c040 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 72 65  tokens (they are
1c050 20 70 61 72 74 20 6f 66 20 74 68 65 20 74 6f 6b   part of the tok
1c060 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68 65 79  en in which they
1c070 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65 64   are.** embedded
1c080 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20 6e 6f  ) and thus do no
1c090 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73 74 61  t count as a sta
1c0a0 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74 6f  tement terminato
1c0b0 72 2e 20 20 5e 57 68 69 74 65 73 70 61 63 65 0a  r.  ^Whitespace.
1c0c0 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 20  ** and comments 
1c0d0 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68 65 20  that follow the 
1c0e0 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20  final semicolon 
1c0f0 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a  are ignored..**.
1c100 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
1c110 65 73 20 72 65 74 75 72 6e 20 30 20 69 66 20 74  es return 0 if t
1c120 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
1c130 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 49 66  incomplete.  ^If
1c140 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c   a.** memory all
1c150 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c 20 74  ocation fails, t
1c160 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  hen SQLITE_NOMEM
1c170 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
1c180 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
1c190 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 73 65  nes do not parse
1c1a0 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
1c1b0 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c 6c  nts thus.** will
1c1c0 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79 6e 74   not detect synt
1c1d0 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72  actically incorr
1c1e0 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e  ect SQL..**.** ^
1c1f0 28 49 66 20 53 51 4c 69 74 65 20 68 61 73 20 6e  (If SQLite has n
1c200 6f 74 20 62 65 65 6e 20 69 6e 69 74 69 61 6c 69  ot been initiali
1c210 7a 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  zed using [sqlit
1c220 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d  e3_initialize()]
1c230 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e   prior .** to in
1c240 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 63  voking sqlite3_c
1c250 6f 6d 70 6c 65 74 65 31 36 28 29 20 74 68 65 6e  omplete16() then
1c260 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
1c270 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ize() is invoked
1c280 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  .** automaticall
1c290 79 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6d  y by sqlite3_com
1c2a0 70 6c 65 74 65 31 36 28 29 2e 20 20 49 66 20 74  plete16().  If t
1c2b0 68 61 74 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  hat initializati
1c2c0 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 68 65  on fails,.** the
1c2d0 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  n the return val
1c2e0 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ue from sqlite3_
1c2f0 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 77 69 6c  complete16() wil
1c300 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a  l be non-zero.**
1c310 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77   regardless of w
1c320 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
1c330 65 20 69 6e 70 75 74 20 53 51 4c 20 69 73 20 63  e input SQL is c
1c340 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a  omplete.)^.**.**
1c350 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73   The input to [s
1c360 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28  qlite3_complete(
1c370 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72  )] must be a zer
1c380 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
1c390 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a  UTF-8 string..**
1c3a0 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f  .** The input to
1c3b0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65   [sqlite3_comple
1c3c0 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62 65 20  te16()] must be 
1c3d0 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
1c3e0 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69  d.** UTF-16 stri
1c3f0 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74  ng in native byt
1c400 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 53 51 4c 49  e order..*/.SQLI
1c410 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
1c420 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73  e3_complete(cons
1c430 74 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a 53 51  t char *sql);.SQ
1c440 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
1c450 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
1c460 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 29  const void *sql)
1c470 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1c480 46 3a 20 52 65 67 69 73 74 65 72 20 41 20 43 61  F: Register A Ca
1c490 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65  llback To Handle
1c4a0 20 53 51 4c 49 54 45 5f 42 55 53 59 20 45 72 72   SQLITE_BUSY Err
1c4b0 6f 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  ors.**.** ^This 
1c4c0 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 63  routine sets a c
1c4d0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
1c4e0 20 74 68 61 74 20 6d 69 67 68 74 20 62 65 20 69   that might be i
1c4f0 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 0a  nvoked whenever.
1c500 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73  ** an attempt is
1c510 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 61 20   made to open a 
1c520 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 20 74  database table t
1c530 68 61 74 20 61 6e 6f 74 68 65 72 20 74 68 72 65  hat another thre
1c540 61 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73  ad.** or process
1c550 20 68 61 73 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 0a   has locked..**.
1c560 2a 2a 20 5e 49 66 20 74 68 65 20 62 75 73 79 20  ** ^If the busy 
1c570 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c  callback is NULL
1c580 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42  , then [SQLITE_B
1c590 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  USY] or [SQLITE_
1c5a0 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a  IOERR_BLOCKED].*
1c5b0 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d  * is returned im
1c5c0 6d 65 64 69 61 74 65 6c 79 20 75 70 6f 6e 20 65  mediately upon e
1c5d0 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74 68 65 20  ncountering the 
1c5e0 6c 6f 63 6b 2e 20 20 5e 49 66 20 74 68 65 20 62  lock.  ^If the b
1c5f0 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  usy callback.** 
1c600 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65  is not NULL, the
1c610 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6d  n the callback m
1c620 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20  ight be invoked 
1c630 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d 65 6e  with two argumen
1c640 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  ts..**.** ^The f
1c650 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
1c660 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
1c670 72 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74  r is a copy of t
1c680 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72  he void* pointer
1c690 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74 68 65   which.** is the
1c6a0 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
1c6b0 74 6f 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  to sqlite3_busy_
1c6c0 68 61 6e 64 6c 65 72 28 29 2e 20 20 5e 54 68 65  handler().  ^The
1c6d0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
1c6e0 20 74 6f 0a 2a 2a 20 74 68 65 20 62 75 73 79 20   to.** the busy 
1c6f0 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b  handler callback
1c700 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
1c710 66 20 74 69 6d 65 73 20 74 68 61 74 20 74 68 65  f times that the
1c720 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 68 61   busy handler ha
1c730 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65  s.** been invoke
1c740 64 20 66 6f 72 20 74 68 69 73 20 6c 6f 63 6b 69  d for this locki
1c750 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74  ng event.  ^If t
1c760 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62  he.** busy callb
1c770 61 63 6b 20 72 65 74 75 72 6e 73 20 30 2c 20 74  ack returns 0, t
1c780 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61  hen no additiona
1c790 6c 20 61 74 74 65 6d 70 74 73 20 61 72 65 20 6d  l attempts are m
1c7a0 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73  ade to.** access
1c7b0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e   the database an
1c7c0 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  d [SQLITE_BUSY] 
1c7d0 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  or [SQLITE_IOERR
1c7e0 5f 42 4c 4f 43 4b 45 44 5d 20 69 73 20 72 65 74  _BLOCKED] is ret
1c7f0 75 72 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68  urned..** ^If th
1c800 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
1c810 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  ns non-zero, the
1c820 6e 20 61 6e 6f 74 68 65 72 20 61 74 74 65 6d 70  n another attemp
1c830 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74 6f 20  t.** is made to 
1c840 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  open the databas
1c850 65 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e  e for reading an
1c860 64 20 74 68 65 20 63 79 63 6c 65 20 72 65 70 65  d the cycle repe
1c870 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70  ats..**.** The p
1c880 72 65 73 65 6e 63 65 20 6f 66 20 61 20 62 75 73  resence of a bus
1c890 79 20 68 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e  y handler does n
1c8a0 6f 74 20 67 75 61 72 61 6e 74 65 65 20 74 68 61  ot guarantee tha
1c8b0 74 20 69 74 20 77 69 6c 6c 20 62 65 20 69 6e 76  t it will be inv
1c8c0 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65  oked.** when the
1c8d0 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65  re is lock conte
1c8e0 6e 74 69 6f 6e 2e 20 5e 49 66 20 53 51 4c 69 74  ntion. ^If SQLit
1c8f0 65 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 61  e determines tha
1c900 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62  t invoking the b
1c910 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63  usy.** handler c
1c920 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61  ould result in a
1c930 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69   deadlock, it wi
1c940 6c 6c 20 67 6f 20 61 68 65 61 64 20 61 6e 64 20  ll go ahead and 
1c950 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42  return [SQLITE_B
1c960 55 53 59 5d 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49  USY].** or [SQLI
1c970 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
1c980 5d 20 69 6e 73 74 65 61 64 20 6f 66 20 69 6e 76  ] instead of inv
1c990 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79 20 68  oking the busy h
1c9a0 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69  andler..** Consi
1c9b0 64 65 72 20 61 20 73 63 65 6e 61 72 69 6f 20 77  der a scenario w
1c9c0 68 65 72 65 20 6f 6e 65 20 70 72 6f 63 65 73 73  here one process
1c9d0 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65   is holding a re
1c9e0 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20  ad lock that.** 
1c9f0 69 74 20 69 73 20 74 72 79 69 6e 67 20 74 6f 20  it is trying to 
1ca00 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65 73  promote to a res
1ca10 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a  erved lock and.*
1ca20 2a 20 61 20 73 65 63 6f 6e 64 20 70 72 6f 63 65  * a second proce
1ca30 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20  ss is holding a 
1ca40 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 74 68  reserved lock th
1ca50 61 74 20 69 74 20 69 73 20 74 72 79 69 6e 67 0a  at it is trying.
1ca60 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f  ** to promote to
1ca70 20 61 6e 20 65 78 63 6c 75 73 69 76 65 20 6c 6f   an exclusive lo
1ca80 63 6b 2e 20 20 54 68 65 20 66 69 72 73 74 20 70  ck.  The first p
1ca90 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20 70 72  rocess cannot pr
1caa0 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61 75 73 65  oceed.** because
1cab0 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62   it is blocked b
1cac0 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64  y the second and
1cad0 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63   the second proc
1cae0 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72  ess cannot.** pr
1caf0 6f 63 65 65 64 20 62 65 63 61 75 73 65 20 69 74  oceed because it
1cb00 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74   is blocked by t
1cb10 68 65 20 66 69 72 73 74 2e 20 20 49 66 20 62 6f  he first.  If bo
1cb20 74 68 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20  th processes.** 
1cb30 69 6e 76 6f 6b 65 20 74 68 65 20 62 75 73 79 20  invoke the busy 
1cb40 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68 65  handlers, neithe
1cb50 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20  r will make any 
1cb60 70 72 6f 67 72 65 73 73 2e 20 20 54 68 65 72 65  progress.  There
1cb70 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20  fore,.** SQLite 
1cb80 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
1cb90 42 55 53 59 5d 20 66 6f 72 20 74 68 65 20 66 69  BUSY] for the fi
1cba0 72 73 74 20 70 72 6f 63 65 73 73 2c 20 68 6f 70  rst process, hop
1cbb0 69 6e 67 20 74 68 61 74 20 74 68 69 73 0a 2a 2a  ing that this.**
1cbc0 20 77 69 6c 6c 20 69 6e 64 75 63 65 20 74 68 65   will induce the
1cbd0 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 74   first process t
1cbe0 6f 20 72 65 6c 65 61 73 65 20 69 74 73 20 72 65  o release its re
1cbf0 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f  ad lock and allo
1cc00 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20  w.** the second 
1cc10 70 72 6f 63 65 73 73 20 74 6f 20 70 72 6f 63 65  process to proce
1cc20 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64  ed..**.** ^The d
1cc30 65 66 61 75 6c 74 20 62 75 73 79 20 63 61 6c 6c  efault busy call
1cc40 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a  back is NULL..**
1cc50 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
1cc60 5f 42 55 53 59 5d 20 65 72 72 6f 72 20 69 73 20  _BUSY] error is 
1cc70 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 5b 53 51  converted to [SQ
1cc80 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
1cc90 45 44 5d 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69  ED].** when SQLi
1cca0 74 65 20 69 73 20 69 6e 20 74 68 65 20 6d 69 64  te is in the mid
1ccb0 64 6c 65 20 6f 66 20 61 20 6c 61 72 67 65 20 74  dle of a large t
1ccc0 72 61 6e 73 61 63 74 69 6f 6e 20 77 68 65 72 65  ransaction where
1ccd0 20 61 6c 6c 20 74 68 65 0a 2a 2a 20 63 68 61 6e   all the.** chan
1cce0 67 65 73 20 77 69 6c 6c 20 6e 6f 74 20 66 69 74  ges will not fit
1ccf0 20 69 6e 74 6f 20 74 68 65 20 69 6e 2d 6d 65 6d   into the in-mem
1cd00 6f 72 79 20 63 61 63 68 65 2e 20 20 53 51 4c 69  ory cache.  SQLi
1cd10 74 65 20 77 69 6c 6c 0a 2a 2a 20 61 6c 72 65 61  te will.** alrea
1cd20 64 79 20 68 6f 6c 64 20 61 20 52 45 53 45 52 56  dy hold a RESERV
1cd30 45 44 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 64  ED lock on the d
1cd40 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 62 75  atabase file, bu
1cd50 74 20 69 74 20 6e 65 65 64 73 0a 2a 2a 20 74 6f  t it needs.** to
1cd60 20 70 72 6f 6d 6f 74 65 20 74 68 69 73 20 6c 6f   promote this lo
1cd70 63 6b 20 74 6f 20 45 58 43 4c 55 53 49 56 45 20  ck to EXCLUSIVE 
1cd80 73 6f 20 74 68 61 74 20 69 74 20 63 61 6e 20 73  so that it can s
1cd90 70 69 6c 6c 20 63 61 63 68 65 0a 2a 2a 20 70 61  pill cache.** pa
1cda0 67 65 73 20 69 6e 74 6f 20 74 68 65 20 64 61 74  ges into the dat
1cdb0 61 62 61 73 65 20 66 69 6c 65 20 77 69 74 68 6f  abase file witho
1cdc0 75 74 20 68 61 72 6d 20 74 6f 20 63 6f 6e 63 75  ut harm to concu
1cdd0 72 72 65 6e 74 0a 2a 2a 20 72 65 61 64 65 72 73  rrent.** readers
1cde0 2e 20 20 5e 49 66 20 69 74 20 69 73 20 75 6e 61  .  ^If it is una
1cdf0 62 6c 65 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74  ble to promote t
1ce00 68 65 20 6c 6f 63 6b 2c 20 74 68 65 6e 20 74 68  he lock, then th
1ce10 65 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 63  e in-memory.** c
1ce20 61 63 68 65 20 77 69 6c 6c 20 62 65 20 6c 65 66  ache will be lef
1ce30 74 20 69 6e 20 61 6e 20 69 6e 63 6f 6e 73 69 73  t in an inconsis
1ce40 74 65 6e 74 20 73 74 61 74 65 20 61 6e 64 20 73  tent state and s
1ce50 6f 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 63  o the error.** c
1ce60 6f 64 65 20 69 73 20 70 72 6f 6d 6f 74 65 64 20  ode is promoted 
1ce70 66 72 6f 6d 20 74 68 65 20 72 65 6c 61 74 69 76  from the relativ
1ce80 65 6c 79 20 62 65 6e 69 67 6e 20 5b 53 51 4c 49  ely benign [SQLI
1ce90 54 45 5f 42 55 53 59 5d 20 74 6f 0a 2a 2a 20 74  TE_BUSY] to.** t
1cea0 68 65 20 6d 6f 72 65 20 73 65 76 65 72 65 20 5b  he more severe [
1ceb0 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
1cec0 43 4b 45 44 5d 2e 20 20 5e 54 68 69 73 20 65 72  CKED].  ^This er
1ced0 72 6f 72 20 63 6f 64 65 20 70 72 6f 6d 6f 74 69  ror code promoti
1cee0 6f 6e 0a 2a 2a 20 66 6f 72 63 65 73 20 61 6e 20  on.** forces an 
1cef0 61 75 74 6f 6d 61 74 69 63 20 72 6f 6c 6c 62 61  automatic rollba
1cf00 63 6b 20 6f 66 20 74 68 65 20 63 68 61 6e 67 65  ck of the change
1cf10 73 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 3c  s.  See the.** <
1cf20 61 20 68 72 65 66 3d 22 2f 63 76 73 74 72 61 63  a href="/cvstrac
1cf30 2f 77 69 6b 69 3f 70 3d 43 6f 72 72 75 70 74 69  /wiki?p=Corrupti
1cf40 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45  onFollowingBusyE
1cf50 72 72 6f 72 22 3e 0a 2a 2a 20 43 6f 72 72 75 70  rror">.** Corrup
1cf60 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73  tionFollowingBus
1cf70 79 45 72 72 6f 72 3c 2f 61 3e 20 77 69 6b 69 20  yError</a> wiki 
1cf80 70 61 67 65 20 66 6f 72 20 61 20 64 69 73 63 75  page for a discu
1cf90 73 73 69 6f 6e 20 6f 66 20 77 68 79 0a 2a 2a 20  ssion of why.** 
1cfa0 74 68 69 73 20 69 73 20 69 6d 70 6f 72 74 61 6e  this is importan
1cfb0 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65  t..**.** ^(There
1cfc0 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73   can only be a s
1cfd0 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c  ingle busy handl
1cfe0 65 72 20 64 65 66 69 6e 65 64 20 66 6f 72 20 65  er defined for e
1cff0 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  ach.** [database
1d000 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 53   connection].  S
1d010 65 74 74 69 6e 67 20 61 20 6e 65 77 20 62 75 73  etting a new bus
1d020 79 20 68 61 6e 64 6c 65 72 20 63 6c 65 61 72 73  y handler clears
1d030 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f 75 73   any.** previous
1d040 6c 79 20 73 65 74 20 68 61 6e 64 6c 65 72 2e 29  ly set handler.)
1d050 5e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 63 61  ^  ^Note that ca
1d060 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62  lling [sqlite3_b
1d070 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 0a 2a  usy_timeout()].*
1d080 2a 20 77 69 6c 6c 20 61 6c 73 6f 20 73 65 74 20  * will also set 
1d090 6f 72 20 63 6c 65 61 72 20 74 68 65 20 62 75 73  or clear the bus
1d0a0 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a  y handler..**.**
1d0b0 20 54 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61   The busy callba
1d0c0 63 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 20 74 61  ck should not ta
1d0d0 6b 65 20 61 6e 79 20 61 63 74 69 6f 6e 73 20 77  ke any actions w
1d0e0 68 69 63 68 20 6d 6f 64 69 66 79 20 74 68 65 0a  hich modify the.
1d0f0 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
1d100 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f  ection that invo
1d110 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e  ked the busy han
1d120 64 6c 65 72 2e 20 20 41 6e 79 20 73 75 63 68 20  dler.  Any such 
1d130 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c  actions.** resul
1d140 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62  t in undefined b
1d150 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20  ehavior..** .** 
1d160 41 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 6d  A busy handler m
1d170 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68  ust not close th
1d180 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1d190 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65  ction.** or [pre
1d1a0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
1d1b0 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
1d1c0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a  e busy handler..
1d1d0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
1d1e0 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68  t sqlite3_busy_h
1d1f0 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c  andler(sqlite3*,
1d200 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69 6e   int(*)(void*,in
1d210 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  t), void*);../*.
1d220 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74  ** CAPI3REF: Set
1d230 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75 74 0a   A Busy Timeout.
1d240 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74  **.** ^This rout
1d250 69 6e 65 20 73 65 74 73 20 61 20 5b 73 71 6c 69  ine sets a [sqli
1d260 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
1d270 20 7c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 5d   | busy handler]
1d280 20 74 68 61 74 20 73 6c 65 65 70 73 0a 2a 2a 20   that sleeps.** 
1d290 66 6f 72 20 61 20 73 70 65 63 69 66 69 65 64 20  for a specified 
1d2a0 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20 77  amount of time w
1d2b0 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73 20 6c  hen a table is l
1d2c0 6f 63 6b 65 64 2e 20 20 5e 54 68 65 20 68 61 6e  ocked.  ^The han
1d2d0 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65  dler.** will sle
1d2e0 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65  ep multiple time
1d2f0 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 61 73 74  s until at least
1d300 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e   "ms" millisecon
1d310 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 0a 2a  ds of sleeping.*
1d320 2a 20 68 61 76 65 20 61 63 63 75 6d 75 6c 61 74  * have accumulat
1d330 65 64 2e 20 20 5e 41 66 74 65 72 20 61 74 20 6c  ed.  ^After at l
1d340 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73  east "ms" millis
1d350 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69  econds of sleepi
1d360 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c  ng,.** the handl
1d370 65 72 20 72 65 74 75 72 6e 73 20 30 20 77 68 69  er returns 0 whi
1d380 63 68 20 63 61 75 73 65 73 20 5b 73 71 6c 69 74  ch causes [sqlit
1d390 65 33 5f 73 74 65 70 28 29 5d 20 74 6f 20 72 65  e3_step()] to re
1d3a0 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  turn.** [SQLITE_
1d3b0 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45  BUSY] or [SQLITE
1d3c0 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e  _IOERR_BLOCKED].
1d3d0 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20  .**.** ^Calling 
1d3e0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74  this routine wit
1d3f0 68 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65  h an argument le
1d400 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c  ss than or equal
1d410 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e   to zero.** turn
1d420 73 20 6f 66 66 20 61 6c 6c 20 62 75 73 79 20 68  s off all busy h
1d430 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e  andlers..**.** ^
1d440 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20  (There can only 
1d450 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79  be a single busy
1d460 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 20 70   handler for a p
1d470 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61  articular.** [da
1d480 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1d490 6e 5d 20 61 6e 79 20 61 6e 79 20 67 69 76 65 6e  n] any any given
1d4a0 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61 6e 6f   moment.  If ano
1d4b0 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65  ther busy handle
1d4c0 72 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e 65 64  r.** was defined
1d4d0 20 20 28 75 73 69 6e 67 20 5b 73 71 6c 69 74 65    (using [sqlite
1d4e0 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29  3_busy_handler()
1d4f0 5d 29 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c  ]) prior to call
1d500 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74  ing.** this rout
1d510 69 6e 65 2c 20 74 68 61 74 20 6f 74 68 65 72 20  ine, that other 
1d520 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20  busy handler is 
1d530 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2f 0a 53 51  cleared.)^.*/.SQ
1d540 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
1d550 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
1d560 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20  t(sqlite3*, int 
1d570 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ms);../*.** CAPI
1d580 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63  3REF: Convenienc
1d590 65 20 52 6f 75 74 69 6e 65 73 20 46 6f 72 20 52  e Routines For R
1d5a0 75 6e 6e 69 6e 67 20 51 75 65 72 69 65 73 0a 2a  unning Queries.*
1d5b0 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20 6c  *.** This is a l
1d5c0 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 20  egacy interface 
1d5d0 74 68 61 74 20 69 73 20 70 72 65 73 65 72 76 65  that is preserve
1d5e0 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20  d for backwards 
1d5f0 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a  compatibility..*
1d600 2a 20 55 73 65 20 6f 66 20 74 68 69 73 20 69 6e  * Use of this in
1d610 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 72  terface is not r
1d620 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a  ecommended..**.*
1d630 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20  * Definition: A 
1d640 3c 62 3e 72 65 73 75 6c 74 20 74 61 62 6c 65 3c  <b>result table<
1d650 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64 61  /b> is memory da
1d660 74 61 20 73 74 72 75 63 74 75 72 65 20 63 72 65  ta structure cre
1d670 61 74 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b  ated by the.** [
1d680 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
1d690 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20  e()] interface. 
1d6a0 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
1d6b0 72 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63  records the.** c
1d6c0 6f 6d 70 6c 65 74 65 20 71 75 65 72 79 20 72 65  omplete query re
1d6d0 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f  sults from one o
1d6e0 72 20 6d 6f 72 65 20 71 75 65 72 69 65 73 2e 0a  r more queries..
1d6f0 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20  **.** The table 
1d700 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68 61 73  conceptually has
1d710 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77   a number of row
1d720 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20  s and columns.  
1d730 42 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d  But.** these num
1d740 62 65 72 73 20 61 72 65 20 6e 6f 74 20 70 61 72  bers are not par
1d750 74 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  t of the result 
1d760 74 61 62 6c 65 20 69 74 73 65 6c 66 2e 20 20 54  table itself.  T
1d770 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20  hese.** numbers 
1d780 61 72 65 20 6f 62 74 61 69 6e 65 64 20 73 65 70  are obtained sep
1d790 61 72 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20  arately.  Let N 
1d7a0 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  be the number of
1d7b0 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62   rows.** and M b
1d7c0 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  e the number of 
1d7d0 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41  columns..**.** A
1d7e0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73   result table is
1d7f0 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
1d800 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65  nters to zero-te
1d810 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73  rminated UTF-8 s
1d820 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 65  trings..** There
1d830 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65   are (N+1)*M ele
1d840 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 61 72 72  ments in the arr
1d850 61 79 2e 20 20 54 68 65 20 66 69 72 73 74 20 4d  ay.  The first M
1d860 20 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74 0a   pointers point.
1d870 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69  ** to zero-termi
1d880 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68  nated strings th
1d890 61 74 20 20 63 6f 6e 74 61 69 6e 20 74 68 65 20  at  contain the 
1d8a0 6e 61 6d 65 73 20 6f 66 20 74 68 65 20 63 6f 6c  names of the col
1d8b0 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d  umns..** The rem
1d8c0 61 69 6e 69 6e 67 20 65 6e 74 72 69 65 73 20 61  aining entries a
1d8d0 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75 65 72  ll point to quer
1d8e0 79 20 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c  y results.  NULL
1d8f0 20 76 61 6c 75 65 73 20 72 65 73 75 6c 74 0a 2a   values result.*
1d900 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  * in NULL pointe
1d910 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 76  rs.  All other v
1d920 61 6c 75 65 73 20 61 72 65 20 69 6e 20 74 68 65  alues are in the
1d930 69 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65  ir UTF-8 zero-te
1d940 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69  rminated.** stri
1d950 6e 67 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f  ng representatio
1d960 6e 20 61 73 20 72 65 74 75 72 6e 65 64 20 62 79  n as returned by
1d970 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
1d980 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _text()]..**.** 
1d990 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 6d  A result table m
1d9a0 69 67 68 74 20 63 6f 6e 73 69 73 74 20 6f 66 20  ight consist of 
1d9b0 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f  one or more memo
1d9c0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a  ry allocations..
1d9d0 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66  ** It is not saf
1d9e0 65 20 74 6f 20 70 61 73 73 20 61 20 72 65 73 75  e to pass a resu
1d9f0 6c 74 20 74 61 62 6c 65 20 64 69 72 65 63 74 6c  lt table directl
1da00 79 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72  y to [sqlite3_fr
1da10 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75  ee()]..** A resu
1da20 6c 74 20 74 61 62 6c 65 20 73 68 6f 75 6c 64 20  lt table should 
1da30 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 75  be deallocated u
1da40 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72  sing [sqlite3_fr
1da50 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a  ee_table()]..**.
1da60 2a 2a 20 5e 28 41 73 20 61 6e 20 65 78 61 6d 70  ** ^(As an examp
1da70 6c 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  le of the result
1da80 20 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c 20 73   table format, s
1da90 75 70 70 6f 73 65 20 61 20 71 75 65 72 79 20 72  uppose a query r
1daa0 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73 20 66  esult.** is as f
1dab0 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ollows:.**.** <b
1dac0 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
1dad0 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d 65 20 20  **        Name  
1dae0 20 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20        | Age.**  
1daf0 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d        ----------
1db00 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a  -------------.**
1db10 20 20 20 20 20 20 20 20 41 6c 69 63 65 20 20 20          Alice   
1db20 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20      | 43.**     
1db30 20 20 20 42 6f 62 20 20 20 20 20 20 20 20 20 7c     Bob         |
1db40 20 32 38 0a 2a 2a 20 20 20 20 20 20 20 20 43 69   28.**        Ci
1db50 6e 64 79 20 20 20 20 20 20 20 7c 20 32 31 0a 2a  ndy       | 21.*
1db60 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
1db70 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72  uote>.**.** Ther
1db80 65 20 61 72 65 20 74 77 6f 20 63 6f 6c 75 6d 6e  e are two column
1db90 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68 72 65   (M==2) and thre
1dba0 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 20  e rows (N==3).  
1dbb0 54 68 75 73 20 74 68 65 0a 2a 2a 20 72 65 73 75  Thus the.** resu
1dbc0 6c 74 20 74 61 62 6c 65 20 68 61 73 20 38 20 65  lt table has 8 e
1dbd0 6e 74 72 69 65 73 2e 20 20 53 75 70 70 6f 73 65  ntries.  Suppose
1dbe0 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
1dbf0 65 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69  e is stored.** i
1dc00 6e 20 61 6e 20 61 72 72 61 79 20 6e 61 6d 65 73  n an array names
1dc10 20 61 7a 52 65 73 75 6c 74 2e 20 20 54 68 65 6e   azResult.  Then
1dc20 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64 73 20   azResult holds 
1dc30 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a  this content:.**
1dc40 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
1dc50 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20  <pre>.**        
1dc60 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 30 5d 20  azResult&#91;0] 
1dc70 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 20  = "Name";.**    
1dc80 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
1dc90 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20  ;1] = "Age";.** 
1dca0 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
1dcb0 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65 22  #91;2] = "Alice"
1dcc0 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
1dcd0 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22 34  sult&#91;3] = "4
1dce0 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  3";.**        az
1dcf0 52 65 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d 20  Result&#91;4] = 
1dd00 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20 20  "Bob";.**       
1dd10 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 35 5d   azResult&#91;5]
1dd20 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20   = "28";.**     
1dd30 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
1dd40 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a  6] = "Cindy";.**
1dd50 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
1dd60 26 23 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b 0a  &#91;7] = "21";.
1dd70 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
1dd80 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  quote>)^.**.** ^
1dd90 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
1dda0 74 61 62 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e  table() function
1ddb0 20 65 76 61 6c 75 61 74 65 73 20 6f 6e 65 20 6f   evaluates one o
1ddc0 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 6f  r more.** semico
1ddd0 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 20 53 51  lon-separated SQ
1dde0 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20  L statements in 
1ddf0 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  the zero-termina
1de00 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72  ted UTF-8.** str
1de10 69 6e 67 20 6f 66 20 69 74 73 20 32 6e 64 20 70  ing of its 2nd p
1de20 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74  arameter and ret
1de30 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20 74 61  urns a result ta
1de40 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20 70 6f  ble to the.** po
1de50 69 6e 74 65 72 20 67 69 76 65 6e 20 69 6e 20 69  inter given in i
1de60 74 73 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  ts 3rd parameter
1de70 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68  ..**.** After th
1de80 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 68 61  e application ha
1de90 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20  s finished with 
1dea0 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 20  the result from 
1deb0 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
1dec0 65 28 29 2c 0a 2a 2a 20 69 74 20 6d 75 73 74 20  e(),.** it must 
1ded0 70 61 73 73 20 74 68 65 20 72 65 73 75 6c 74 20  pass the result 
1dee0 74 61 62 6c 65 20 70 6f 69 6e 74 65 72 20 74 6f  table pointer to
1def0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61   sqlite3_free_ta
1df00 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 72 20 74  ble() in order t
1df10 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74 68 65  o.** release the
1df20 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 77 61 73   memory that was
1df30 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61   malloced.  Beca
1df40 75 73 65 20 6f 66 20 74 68 65 20 77 61 79 20 74  use of the way t
1df50 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  he.** [sqlite3_m
1df60 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e 73  alloc()] happens
1df70 20 77 69 74 68 69 6e 20 73 71 6c 69 74 65 33 5f   within sqlite3_
1df80 67 65 74 5f 74 61 62 6c 65 28 29 2c 20 74 68 65  get_table(), the
1df90 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63   calling.** func
1dfa0 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72  tion must not tr
1dfb0 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74  y to call [sqlit
1dfc0 65 33 5f 66 72 65 65 28 29 5d 20 64 69 72 65 63  e3_free()] direc
1dfd0 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73  tly.  Only.** [s
1dfe0 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c  qlite3_free_tabl
1dff0 65 28 29 5d 20 69 73 20 61 62 6c 65 20 74 6f 20  e()] is able to 
1e000 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f  release the memo
1e010 72 79 20 70 72 6f 70 65 72 6c 79 20 61 6e 64 20  ry properly and 
1e020 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68  safely..**.** Th
1e030 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  e sqlite3_get_ta
1e040 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  ble() interface 
1e050 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61  is implemented a
1e060 73 20 61 20 77 72 61 70 70 65 72 20 61 72 6f 75  s a wrapper arou
1e070 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  nd.** [sqlite3_e
1e080 78 65 63 28 29 5d 2e 20 20 54 68 65 20 73 71 6c  xec()].  The sql
1e090 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
1e0a0 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f   routine does no
1e0b0 74 20 68 61 76 65 20 61 63 63 65 73 73 0a 2a 2a  t have access.**
1e0c0 20 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c   to any internal
1e0d0 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65 73   data structures
1e0e0 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 49 74 20   of SQLite.  It 
1e0f0 75 73 65 73 20 6f 6e 6c 79 20 74 68 65 20 70 75  uses only the pu
1e100 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63  blic.** interfac
1e110 65 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 20  e defined here. 
1e120 20 41 73 20 61 20 63 6f 6e 73 65 71 75 65 6e 63   As a consequenc
1e130 65 2c 20 65 72 72 6f 72 73 20 74 68 61 74 20 6f  e, errors that o
1e140 63 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77  ccur in the.** w
1e150 72 61 70 70 65 72 20 6c 61 79 65 72 20 6f 75 74  rapper layer out
1e160 73 69 64 65 20 6f 66 20 74 68 65 20 69 6e 74 65  side of the inte
1e170 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78  rnal [sqlite3_ex
1e180 65 63 28 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e  ec()] call are n
1e190 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64 20  ot.** reflected 
1e1a0 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  in subsequent ca
1e1b0 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
1e1c0 65 72 72 63 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a  errcode()] or.**
1e1d0 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
1e1e0 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ()]..*/.SQLITE_A
1e1f0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 67  PI int sqlite3_g
1e200 65 74 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c 69  et_table(.  sqli
1e210 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
1e220 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74    /* An open dat
1e230 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  abase */.  const
1e240 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20   char *zSql,    
1e250 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76   /* SQL to be ev
1e260 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63 68 61  aluated */.  cha
1e270 72 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c 20  r ***pazResult, 
1e280 20 20 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66     /* Results of
1e290 20 74 68 65 20 71 75 65 72 79 20 2a 2f 0a 20 20   the query */.  
1e2a0 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20 20  int *pnRow,     
1e2b0 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20        /* Number 
1e2c0 6f 66 20 72 65 73 75 6c 74 20 72 6f 77 73 20 77  of result rows w
1e2d0 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20  ritten here */. 
1e2e0 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20   int *pnColumn, 
1e2f0 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72         /* Number
1e300 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d   of result colum
1e310 6e 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20  ns written here 
1e320 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72  */.  char **pzEr
1e330 72 6d 73 67 20 20 20 20 20 20 20 2f 2a 20 45 72  rmsg       /* Er
1e340 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20  ror msg written 
1e350 68 65 72 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54  here */.);.SQLIT
1e360 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74  E_API void sqlit
1e370 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 63 68  e3_free_table(ch
1e380 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f  ar **result);../
1e390 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
1e3a0 6f 72 6d 61 74 74 65 64 20 53 74 72 69 6e 67 20  ormatted String 
1e3b0 50 72 69 6e 74 69 6e 67 20 46 75 6e 63 74 69 6f  Printing Functio
1e3c0 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  ns.**.** These r
1e3d0 6f 75 74 69 6e 65 73 20 61 72 65 20 77 6f 72 6b  outines are work
1e3e0 2d 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 20 22  -alikes of the "
1e3f0 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69 6c 79  printf()" family
1e400 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a   of functions.**
1e410 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61   from the standa
1e420 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a  rd C library..**
1e430 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1e440 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73  _mprintf() and s
1e450 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28  qlite3_vmprintf(
1e460 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74 65  ) routines write
1e470 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74   their.** result
1e480 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  s into memory ob
1e490 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
1e4a0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a  ite3_malloc()]..
1e4b0 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20 72  ** The strings r
1e4c0 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65  eturned by these
1e4d0 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 68   two routines sh
1e4e0 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61  ould be.** relea
1e4f0 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  sed by [sqlite3_
1e500 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74 68 20  free()].  ^Both 
1e510 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
1e520 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  a.** NULL pointe
1e530 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61  r if [sqlite3_ma
1e540 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62 6c  lloc()] is unabl
1e550 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e  e to allocate en
1e560 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74  ough.** memory t
1e570 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c  o hold the resul
1e580 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a  ting string..**.
1e590 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33  ** ^(The sqlite3
1e5a0 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74  _snprintf() rout
1e5b0 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74  ine is similar t
1e5c0 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 22 20 66  o "snprintf()" f
1e5d0 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64  rom.** the stand
1e5e0 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20 20  ard C library.  
1e5f0 54 68 65 20 72 65 73 75 6c 74 20 69 73 20 77 72  The result is wr
1e600 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a  itten into the.*
1e610 2a 20 62 75 66 66 65 72 20 73 75 70 70 6c 69 65  * buffer supplie
1e620 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
1e630 70 61 72 61 6d 65 74 65 72 20 77 68 6f 73 65 20  parameter whose 
1e640 73 69 7a 65 20 69 73 20 67 69 76 65 6e 20 62 79  size is given by
1e650 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70 61  .** the first pa
1e660 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74 68  rameter. Note th
1e670 61 74 20 74 68 65 20 6f 72 64 65 72 20 6f 66 20  at the order of 
1e680 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f  the.** first two
1e690 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 72   parameters is r
1e6a0 65 76 65 72 73 65 64 20 66 72 6f 6d 20 73 6e 70  eversed from snp
1e6b0 72 69 6e 74 66 28 29 2e 29 5e 20 20 54 68 69 73  rintf().)^  This
1e6c0 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72   is an.** histor
1e6d0 69 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74 68  ical accident th
1e6e0 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69 78  at cannot be fix
1e6f0 65 64 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b  ed without break
1e700 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73  ing.** backwards
1e710 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 20   compatibility. 
1e720 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61   ^(Note also tha
1e730 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  t sqlite3_snprin
1e740 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20  tf().** returns 
1e750 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 73  a pointer to its
1e760 20 62 75 66 66 65 72 20 69 6e 73 74 65 61 64 20   buffer instead 
1e770 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  of the number of
1e780 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 61  .** characters a
1e790 63 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e 20  ctually written 
1e7a0 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72 2e  into the buffer.
1e7b0 29 5e 20 20 57 65 20 61 64 6d 69 74 20 74 68 61  )^  We admit tha
1e7c0 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20  t.** the number 
1e7d0 6f 66 20 63 68 61 72 61 63 74 65 72 73 20 77 72  of characters wr
1e7e0 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20 61  itten would be a
1e7f0 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65 74   more useful ret
1e800 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74  urn.** value but
1e810 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67   we cannot chang
1e820 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  e the implementa
1e830 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f  tion of sqlite3_
1e840 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f  snprintf().** no
1e850 77 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69  w without breaki
1e860 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ng compatibility
1e870 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67  ..**.** ^As long
1e880 20 61 73 20 74 68 65 20 62 75 66 66 65 72 20 73   as the buffer s
1e890 69 7a 65 20 69 73 20 67 72 65 61 74 65 72 20 74  ize is greater t
1e8a0 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65  han zero, sqlite
1e8b0 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20  3_snprintf().** 
1e8c0 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20  guarantees that 
1e8d0 74 68 65 20 62 75 66 66 65 72 20 69 73 20 61 6c  the buffer is al
1e8e0 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  ways zero-termin
1e8f0 61 74 65 64 2e 20 20 5e 54 68 65 20 66 69 72 73  ated.  ^The firs
1e900 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 22  t.** parameter "
1e910 6e 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c 20  n" is the total 
1e920 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66  size of the buff
1e930 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73 70  er, including sp
1e940 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a  ace for.** the z
1e950 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20  ero terminator. 
1e960 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74 20   So the longest 
1e970 73 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e 20  string that can 
1e980 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a  be completely.**
1e990 20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62 65   written will be
1e9a0 20 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73 2e   n-1 characters.
1e9b0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1e9c0 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 29 20  te3_vsnprintf() 
1e9d0 72 6f 75 74 69 6e 65 20 69 73 20 61 20 76 61 72  routine is a var
1e9e0 61 72 67 73 20 76 65 72 73 69 6f 6e 20 6f 66 20  args version of 
1e9f0 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
1ea00 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ()..**.** These 
1ea10 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70  routines all imp
1ea20 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64 69  lement some addi
1ea30 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e  tional formattin
1ea40 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61  g.** options tha
1ea50 74 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72  t are useful for
1ea60 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53 51   constructing SQ
1ea70 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  L statements..**
1ea80 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75 61   All of the usua
1ea90 6c 20 70 72 69 6e 74 66 28 29 20 66 6f 72 6d 61  l printf() forma
1eaa0 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70  tting options ap
1eab0 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69 6f  ply.  In additio
1eac0 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20 61  n, there.** is a
1ead0 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20 61  re "%q", "%Q", a
1eae0 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73 2e  nd "%z" options.
1eaf0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 71 20  .**.** ^(The %q 
1eb00 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b  option works lik
1eb10 65 20 25 73 20 69 6e 20 74 68 61 74 20 69 74 20  e %s in that it 
1eb20 73 75 62 73 74 69 74 75 74 65 73 20 61 20 6e 75  substitutes a nu
1eb30 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  l-terminated.** 
1eb40 73 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 65 20  string from the 
1eb50 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20  argument list.  
1eb60 42 75 74 20 25 71 20 61 6c 73 6f 20 64 6f 75 62  But %q also doub
1eb70 6c 65 73 20 65 76 65 72 79 20 27 5c 27 27 20 63  les every '\'' c
1eb80 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20  haracter..** %q 
1eb90 69 73 20 64 65 73 69 67 6e 65 64 20 66 6f 72 20  is designed for 
1eba0 75 73 65 20 69 6e 73 69 64 65 20 61 20 73 74 72  use inside a str
1ebb0 69 6e 67 20 6c 69 74 65 72 61 6c 2e 29 5e 20 20  ing literal.)^  
1ebc0 42 79 20 64 6f 75 62 6c 69 6e 67 20 65 61 63 68  By doubling each
1ebd0 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63 74   '\''.** charact
1ebe0 65 72 20 69 74 20 65 73 63 61 70 65 73 20 74 68  er it escapes th
1ebf0 61 74 20 63 68 61 72 61 63 74 65 72 20 61 6e 64  at character and
1ec00 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62 65   allows it to be
1ec10 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a   inserted into.*
1ec20 2a 20 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a  * the string..**
1ec30 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c  .** For example,
1ec40 20 61 73 73 75 6d 65 20 74 68 65 20 73 74 72 69   assume the stri
1ec50 6e 67 20 76 61 72 69 61 62 6c 65 20 7a 54 65 78  ng variable zTex
1ec60 74 20 63 6f 6e 74 61 69 6e 73 20 74 65 78 74 20  t contains text 
1ec70 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a  as follows:.**.*
1ec80 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
1ec90 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54  re>.**  char *zT
1eca0 65 78 74 20 3d 20 22 49 74 27 73 20 61 20 68 61  ext = "It's a ha
1ecb0 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f  ppy day!";.** </
1ecc0 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
1ecd0 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20  >.**.** One can 
1ece0 75 73 65 20 74 68 69 73 20 74 65 78 74 20 69 6e  use this text in
1ecf0 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
1ed00 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  t as follows:.**
1ed10 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
1ed20 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a  <pre>.**  char *
1ed30 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d  zSQL = sqlite3_m
1ed40 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49  printf("INSERT I
1ed50 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53  NTO table VALUES
1ed60 28 27 25 71 27 29 22 2c 20 7a 54 65 78 74 29 3b  ('%q')", zText);
1ed70 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65  .**  sqlite3_exe
1ed80 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30  c(db, zSQL, 0, 0
1ed90 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65  , 0);.**  sqlite
1eda0 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a  3_free(zSQL);.**
1edb0 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
1edc0 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75  ote>.**.** Becau
1edd0 73 65 20 74 68 65 20 25 71 20 66 6f 72 6d 61 74  se the %q format
1ede0 20 73 74 72 69 6e 67 20 69 73 20 75 73 65 64 2c   string is used,
1edf0 20 74 68 65 20 27 5c 27 27 20 63 68 61 72 61 63   the '\'' charac
1ee00 74 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20  ter in zText.** 
1ee10 69 73 20 65 73 63 61 70 65 64 20 61 6e 64 20 74  is escaped and t
1ee20 68 65 20 53 51 4c 20 67 65 6e 65 72 61 74 65 64  he SQL generated
1ee30 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a   is as follows:.
1ee40 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
1ee50 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45  e><pre>.**  INSE
1ee60 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56  RT INTO table1 V
1ee70 41 4c 55 45 53 28 27 49 74 27 27 73 20 61 20 68  ALUES('It''s a h
1ee80 61 70 70 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c  appy day!').** <
1ee90 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1eea0 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73  e>.**.** This is
1eeb0 20 63 6f 72 72 65 63 74 2e 20 20 48 61 64 20 77   correct.  Had w
1eec0 65 20 75 73 65 64 20 25 73 20 69 6e 73 74 65 61  e used %s instea
1eed0 64 20 6f 66 20 25 71 2c 20 74 68 65 20 67 65 6e  d of %q, the gen
1eee0 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f  erated SQL.** wo
1eef0 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20  uld have looked 
1ef00 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a  like this:.**.**
1ef10 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
1ef20 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e  e>.**  INSERT IN
1ef30 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53  TO table1 VALUES
1ef40 28 27 49 74 27 73 20 61 20 68 61 70 70 79 20 64  ('It's a happy d
1ef50 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  ay!');.** </pre>
1ef60 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
1ef70 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e 64 20  .** This second 
1ef80 65 78 61 6d 70 6c 65 20 69 73 20 61 6e 20 53 51  example is an SQ
1ef90 4c 20 73 79 6e 74 61 78 20 65 72 72 6f 72 2e 20  L syntax error. 
1efa0 20 41 73 20 61 20 67 65 6e 65 72 61 6c 20 72 75   As a general ru
1efb0 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a  le you should.**
1efc0 20 61 6c 77 61 79 73 20 75 73 65 20 25 71 20 69   always use %q i
1efd0 6e 73 74 65 61 64 20 6f 66 20 25 73 20 77 68 65  nstead of %s whe
1efe0 6e 20 69 6e 73 65 72 74 69 6e 67 20 74 65 78 74  n inserting text
1eff0 20 69 6e 74 6f 20 61 20 73 74 72 69 6e 67 20 6c   into a string l
1f000 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28  iteral..**.** ^(
1f010 54 68 65 20 25 51 20 6f 70 74 69 6f 6e 20 77 6f  The %Q option wo
1f020 72 6b 73 20 6c 69 6b 65 20 25 71 20 65 78 63 65  rks like %q exce
1f030 70 74 20 69 74 20 61 6c 73 6f 20 61 64 64 73 20  pt it also adds 
1f040 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 20 61 72  single quotes ar
1f050 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74 73  ound.** the outs
1f060 69 64 65 20 6f 66 20 74 68 65 20 74 6f 74 61 6c  ide of the total
1f070 20 73 74 72 69 6e 67 2e 20 20 41 64 64 69 74 69   string.  Additi
1f080 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68 65 20 70  onally, if the p
1f090 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65 0a  arameter in the.
1f0a0 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74  ** argument list
1f0b0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
1f0c0 65 72 2c 20 25 51 20 73 75 62 73 74 69 74 75 74  er, %Q substitut
1f0d0 65 73 20 74 68 65 20 74 65 78 74 20 22 4e 55 4c  es the text "NUL
1f0e0 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a 2a 20 73  L" (without.** s
1f0f0 69 6e 67 6c 65 20 71 75 6f 74 65 73 29 2e 29 5e  ingle quotes).)^
1f100 20 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c    So, for exampl
1f110 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61 79  e, one could say
1f120 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
1f130 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68  ote><pre>.**  ch
1f140 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74  ar *zSQL = sqlit
1f150 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45  e3_mprintf("INSE
1f160 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41  RT INTO table VA
1f170 4c 55 45 53 28 25 51 29 22 2c 20 7a 54 65 78 74  LUES(%Q)", zText
1f180 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65  );.**  sqlite3_e
1f190 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c  xec(db, zSQL, 0,
1f1a0 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69   0, 0);.**  sqli
1f1b0 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a  te3_free(zSQL);.
1f1c0 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
1f1d0 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  quote>.**.** The
1f1e0 20 63 6f 64 65 20 61 62 6f 76 65 20 77 69 6c 6c   code above will
1f1f0 20 72 65 6e 64 65 72 20 61 20 63 6f 72 72 65 63   render a correc
1f200 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  t SQL statement 
1f210 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 76  in the zSQL.** v
1f220 61 72 69 61 62 6c 65 20 65 76 65 6e 20 69 66 20  ariable even if 
1f230 74 68 65 20 7a 54 65 78 74 20 76 61 72 69 61 62  the zText variab
1f240 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  le is a NULL poi
1f250 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  nter..**.** ^(Th
1f260 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e  e "%z" formattin
1f270 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c  g option works l
1f280 69 6b 65 20 22 25 73 22 20 62 75 74 20 77 69 74  ike "%s" but wit
1f290 68 20 74 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f  h the.** additio
1f2a0 6e 20 74 68 61 74 20 61 66 74 65 72 20 74 68 65  n that after the
1f2b0 20 73 74 72 69 6e 67 20 68 61 73 20 62 65 65 6e   string has been
1f2c0 20 72 65 61 64 20 61 6e 64 20 63 6f 70 69 65 64   read and copied
1f2d0 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73   into.** the res
1f2e0 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72  ult, [sqlite3_fr
1f2f0 65 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20  ee()] is called 
1f300 6f 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72  on the input str
1f310 69 6e 67 2e 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45  ing.)^.*/.SQLITE
1f320 5f 41 50 49 20 63 68 61 72 20 2a 73 71 6c 69 74  _API char *sqlit
1f330 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74  e3_mprintf(const
1f340 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 53 51 4c   char*,...);.SQL
1f350 49 54 45 5f 41 50 49 20 63 68 61 72 20 2a 73 71  ITE_API char *sq
1f360 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 63  lite3_vmprintf(c
1f370 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c  onst char*, va_l
1f380 69 73 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ist);.SQLITE_API
1f390 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73   char *sqlite3_s
1f3a0 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72  nprintf(int,char
1f3b0 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e  *,const char*, .
1f3c0 2e 2e 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..);.SQLITE_API 
1f3d0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 73  char *sqlite3_vs
1f3e0 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72  nprintf(int,char
1f3f0 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76  *,const char*, v
1f400 61 5f 6c 69 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  a_list);../*.** 
1f410 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79  CAPI3REF: Memory
1f420 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73   Allocation Subs
1f430 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ystem.**.** The 
1f440 53 51 4c 69 74 65 20 63 6f 72 65 20 75 73 65 73  SQLite core uses
1f450 20 74 68 65 73 65 20 74 68 72 65 65 20 72 6f 75   these three rou
1f460 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66  tines for all of
1f470 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65   its own.** inte
1f480 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  rnal memory allo
1f490 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43  cation needs. "C
1f4a0 6f 72 65 22 20 69 6e 20 74 68 65 20 70 72 65 76  ore" in the prev
1f4b0 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a  ious sentence.**
1f4c0 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64   does not includ
1f4d0 65 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74  e operating-syst
1f4e0 65 6d 20 73 70 65 63 69 66 69 63 20 56 46 53 20  em specific VFS 
1f4f0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20  implementation. 
1f500 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20   The.** Windows 
1f510 56 46 53 20 75 73 65 73 20 6e 61 74 69 76 65 20  VFS uses native 
1f520 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65  malloc() and fre
1f530 65 28 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65  e() for some ope
1f540 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  rations..**.** ^
1f550 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  The sqlite3_mall
1f560 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  oc() routine ret
1f570 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
1f580 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20  o a block.** of 
1f590 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61 73 74 20  memory at least 
1f5a0 4e 20 62 79 74 65 73 20 69 6e 20 6c 65 6e 67 74  N bytes in lengt
1f5b0 68 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  h, where N is th
1f5c0 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  e parameter..** 
1f5d0 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ^If sqlite3_mall
1f5e0 6f 63 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74  oc() is unable t
1f5f0 6f 20 6f 62 74 61 69 6e 20 73 75 66 66 69 63 69  o obtain suffici
1f600 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f  ent free.** memo
1f610 72 79 2c 20 69 74 20 72 65 74 75 72 6e 73 20 61  ry, it returns a
1f620 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20   NULL pointer.  
1f630 5e 49 66 20 74 68 65 20 70 61 72 61 6d 65 74 65  ^If the paramete
1f640 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  r N to.** sqlite
1f650 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65  3_malloc() is ze
1f660 72 6f 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74  ro or negative t
1f670 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  hen sqlite3_mall
1f680 6f 63 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20  oc() returns.** 
1f690 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
1f6a0 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73  **.** ^Calling s
1f6b0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 77 69  qlite3_free() wi
1f6c0 74 68 20 61 20 70 6f 69 6e 74 65 72 20 70 72 65  th a pointer pre
1f6d0 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64  viously returned
1f6e0 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 6d  .** by sqlite3_m
1f6f0 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74  alloc() or sqlit
1f700 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c  e3_realloc() rel
1f710 65 61 73 65 73 20 74 68 61 74 20 6d 65 6d 6f 72  eases that memor
1f720 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20  y so.** that it 
1f730 6d 69 67 68 74 20 62 65 20 72 65 75 73 65 64 2e  might be reused.
1f740 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66    ^The sqlite3_f
1f750 72 65 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73  ree() routine is
1f760 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69  .** a no-op if i
1f770 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20  s called with a 
1f780 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50  NULL pointer.  P
1f790 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f  assing a NULL po
1f7a0 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69  inter.** to sqli
1f7b0 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 68 61  te3_free() is ha
1f7c0 72 6d 6c 65 73 73 2e 20 20 41 66 74 65 72 20 62  rmless.  After b
1f7d0 65 69 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f  eing freed, memo
1f7e0 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69  ry.** should nei
1f7f0 74 68 65 72 20 62 65 20 72 65 61 64 20 6e 6f 72  ther be read nor
1f800 20 77 72 69 74 74 65 6e 2e 20 20 45 76 65 6e 20   written.  Even 
1f810 72 65 61 64 69 6e 67 20 70 72 65 76 69 6f 75 73  reading previous
1f820 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f  ly freed.** memo
1f830 72 79 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20  ry might result 
1f840 69 6e 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f  in a segmentatio
1f850 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74 68 65 72  n fault or other
1f860 20 73 65 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a   severe error..*
1f870 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70 74  * Memory corrupt
1f880 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61 74  ion, a segmentat
1f890 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74  ion fault, or ot
1f8a0 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72  her severe error
1f8b0 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73 75 6c 74  .** might result
1f8c0 20 69 66 20 73 71 6c 69 74 65 33 5f 66 72 65 65   if sqlite3_free
1f8d0 28 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74  () is called wit
1f8e0 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69  h a non-NULL poi
1f8f0 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20 77 61 73  nter that.** was
1f900 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20 66 72   not obtained fr
1f910 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  om sqlite3_mallo
1f920 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  c() or sqlite3_r
1f930 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20  ealloc()..**.** 
1f940 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  ^(The sqlite3_re
1f950 61 6c 6c 6f 63 28 29 20 69 6e 74 65 72 66 61 63  alloc() interfac
1f960 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65  e attempts to re
1f970 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20  size a.** prior 
1f980 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
1f990 6e 20 74 6f 20 62 65 20 61 74 20 6c 65 61 73 74  n to be at least
1f9a0 20 4e 20 62 79 74 65 73 2c 20 77 68 65 72 65 20   N bytes, where 
1f9b0 4e 20 69 73 20 74 68 65 0a 2a 2a 20 73 65 63 6f  N is the.** seco
1f9c0 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54  nd parameter.  T
1f9d0 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
1f9e0 74 69 6f 6e 20 74 6f 20 62 65 20 72 65 73 69 7a  tion to be resiz
1f9f0 65 64 20 69 73 20 74 68 65 20 66 69 72 73 74 0a  ed is the first.
1fa00 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 29 5e 20  ** parameter.)^ 
1fa10 5e 20 49 66 20 74 68 65 20 66 69 72 73 74 20 70  ^ If the first p
1fa20 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
1fa30 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a  te3_realloc().**
1fa40 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
1fa50 65 72 20 74 68 65 6e 20 69 74 73 20 62 65 68 61  er then its beha
1fa60 76 69 6f 72 20 69 73 20 69 64 65 6e 74 69 63 61  vior is identica
1fa70 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20  l to calling.** 
1fa80 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e  sqlite3_malloc(N
1fa90 29 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  ) where N is the
1faa0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
1fab0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61  r to sqlite3_rea
1fac0 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 49 66 20 74  lloc()..** ^If t
1fad0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
1fae0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
1faf0 65 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f  ealloc() is zero
1fb00 20 6f 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20   or.** negative 
1fb10 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
1fb20 72 20 69 73 20 65 78 61 63 74 6c 79 20 74 68 65  r is exactly the
1fb30 20 73 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67   same as calling
1fb40 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65  .** sqlite3_free
1fb50 28 50 29 20 77 68 65 72 65 20 50 20 69 73 20 74  (P) where P is t
1fb60 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
1fb70 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  er to sqlite3_re
1fb80 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 73 71 6c  alloc()..** ^sql
1fb90 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72  ite3_realloc() r
1fba0 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
1fbb0 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c   to a memory all
1fbc0 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74  ocation.** of at
1fbd0 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69   least N bytes i
1fbe0 6e 20 73 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69  n size or NULL i
1fbf0 66 20 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d  f sufficient mem
1fc00 6f 72 79 20 69 73 20 75 6e 61 76 61 69 6c 61 62  ory is unavailab
1fc10 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d 20 69 73 20  le..** ^If M is 
1fc20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
1fc30 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
1fc40 2c 20 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20  , then min(N,M) 
1fc50 62 79 74 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20  bytes.** of the 
1fc60 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
1fc70 20 61 72 65 20 63 6f 70 69 65 64 20 69 6e 74 6f   are copied into
1fc80 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f   the beginning o
1fc90 66 20 62 75 66 66 65 72 20 72 65 74 75 72 6e 65  f buffer returne
1fca0 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f  d.** by sqlite3_
1fcb0 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 74 68  realloc() and th
1fcc0 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  e prior allocati
1fcd0 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20  on is freed..** 
1fce0 5e 49 66 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  ^If sqlite3_real
1fcf0 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 20 4e 55  loc() returns NU
1fd00 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 70 72 69  LL, then the pri
1fd10 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  or allocation.**
1fd20 20 69 73 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a   is not freed..*
1fd30 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79  *.** ^The memory
1fd40 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
1fd50 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 61 6e  ite3_malloc() an
1fd60 64 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  d sqlite3_reallo
1fd70 63 28 29 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73  c().** is always
1fd80 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 74 20 6c   aligned to at l
1fd90 65 61 73 74 20 61 6e 20 38 20 62 79 74 65 20 62  east an 8 byte b
1fda0 6f 75 6e 64 61 72 79 2c 20 6f 72 20 74 6f 20 61  oundary, or to a
1fdb0 0a 2a 2a 20 34 20 62 79 74 65 20 62 6f 75 6e 64  .** 4 byte bound
1fdc0 61 72 79 20 69 66 20 74 68 65 20 5b 53 51 4c 49  ary if the [SQLI
1fdd0 54 45 5f 34 5f 42 59 54 45 5f 41 4c 49 47 4e 45  TE_4_BYTE_ALIGNE
1fde0 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f 6d 70 69 6c  D_MALLOC] compil
1fdf0 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e  e-time.** option
1fe00 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20   is used..**.** 
1fe10 49 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  In SQLite versio
1fe20 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e 35 2e  n 3.5.0 and 3.5.
1fe30 31 2c 20 69 74 20 77 61 73 20 70 6f 73 73 69 62  1, it was possib
1fe40 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a 20  le to define.** 
1fe50 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  the SQLITE_OMIT_
1fe60 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 4f  MEMORY_ALLOCATIO
1fe70 4e 20 77 68 69 63 68 20 77 6f 75 6c 64 20 63 61  N which would ca
1fe80 75 73 65 20 74 68 65 20 62 75 69 6c 74 2d 69 6e  use the built-in
1fe90 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
1fea0 6f 6e 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  on of these rout
1feb0 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69 74 74  ines to be omitt
1fec0 65 64 2e 20 20 54 68 61 74 20 63 61 70 61 62 69  ed.  That capabi
1fed0 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f  lity.** is no lo
1fee0 6e 67 65 72 20 70 72 6f 76 69 64 65 64 2e 20 20  nger provided.  
1fef0 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20 6d 65  Only built-in me
1ff00 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 20  mory allocators 
1ff10 63 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a 2a 0a  can be used..**.
1ff20 2a 2a 20 50 72 69 6f 72 20 74 6f 20 53 51 4c 69  ** Prior to SQLi
1ff30 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 31  te version 3.7.1
1ff40 30 2c 20 74 68 65 20 57 69 6e 64 6f 77 73 20 4f  0, the Windows O
1ff50 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65  S interface laye
1ff60 72 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 68 65 20  r called.** the 
1ff70 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20  system malloc() 
1ff80 61 6e 64 20 66 72 65 65 28 29 20 64 69 72 65 63  and free() direc
1ff90 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65 72 74  tly when convert
1ffa0 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 73  ing.** filenames
1ffb0 20 62 65 74 77 65 65 6e 20 74 68 65 20 55 54 46   between the UTF
1ffc0 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64  -8 encoding used
1ffd0 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e   by SQLite.** an
1ffe0 64 20 77 68 61 74 65 76 65 72 20 66 69 6c 65 6e  d whatever filen
1fff0 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  ame encoding is 
20000 75 73 65 64 20 62 79 20 74 68 65 20 70 61 72 74  used by the part
20010 69 63 75 6c 61 72 20 57 69 6e 64 6f 77 73 0a 2a  icular Windows.*
20020 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e 20  * installation. 
20030 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   Memory allocati
20040 6f 6e 20 65 72 72 6f 72 73 20 77 65 72 65 20 64  on errors were d
20050 65 74 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a 20  etected, but.** 
20060 74 68 65 79 20 77 65 72 65 20 72 65 70 6f 72 74  they were report
20070 65 64 20 62 61 63 6b 20 61 73 20 5b 53 51 4c 49  ed back as [SQLI
20080 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a  TE_CANTOPEN] or.
20090 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  ** [SQLITE_IOERR
200a0 5d 20 72 61 74 68 65 72 20 74 68 61 6e 20 5b 53  ] rather than [S
200b0 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a  QLITE_NOMEM]..**
200c0 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 20  .** The pointer 
200d0 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b 73 71  arguments to [sq
200e0 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 61 6e  lite3_free()] an
200f0 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  d [sqlite3_reall
20100 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65  oc()].** must be
20110 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f 72 20   either NULL or 
20120 65 6c 73 65 20 70 6f 69 6e 74 65 72 73 20 6f 62  else pointers ob
20130 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 20 70 72  tained from a pr
20140 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f  ior.** invocatio
20150 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61  n of [sqlite3_ma
20160 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69  lloc()] or [sqli
20170 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 74  te3_realloc()] t
20180 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e 6f 74 20  hat have.** not 
20190 79 65 74 20 62 65 65 6e 20 72 65 6c 65 61 73 65  yet been release
201a0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70  d..**.** The app
201b0 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  lication must no
201c0 74 20 72 65 61 64 20 6f 72 20 77 72 69 74 65 20  t read or write 
201d0 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a 20 61  any part of.** a
201e0 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79   block of memory
201f0 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65   after it has be
20200 65 6e 20 72 65 6c 65 61 73 65 64 20 75 73 69 6e  en released usin
20210 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72  g.** [sqlite3_fr
20220 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ee()] or [sqlite
20230 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f  3_realloc()]..*/
20240 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
20250 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   *sqlite3_malloc
20260 28 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50  (int);.SQLITE_AP
20270 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  I void *sqlite3_
20280 72 65 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69  realloc(void*, i
20290 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  nt);.SQLITE_API 
202a0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65  void sqlite3_fre
202b0 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  e(void*);../*.**
202c0 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72   CAPI3REF: Memor
202d0 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74  y Allocator Stat
202e0 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c  istics.**.** SQL
202f0 69 74 65 20 70 72 6f 76 69 64 65 73 20 74 68 65  ite provides the
20300 73 65 20 74 77 6f 20 69 6e 74 65 72 66 61 63 65  se two interface
20310 73 20 66 6f 72 20 72 65 70 6f 72 74 69 6e 67 20  s for reporting 
20320 6f 6e 20 74 68 65 20 73 74 61 74 75 73 0a 2a 2a  on the status.**
20330 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
20340 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c  _malloc()], [sql
20350 69 74 65 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e  ite3_free()], an
20360 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  d [sqlite3_reall
20370 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65  oc()].** routine
20380 73 2c 20 77 68 69 63 68 20 66 6f 72 6d 20 74 68  s, which form th
20390 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72  e built-in memor
203a0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62  y allocation sub
203b0 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54  system..**.** ^T
203c0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  he [sqlite3_memo
203d0 72 79 5f 75 73 65 64 28 29 5d 20 72 6f 75 74 69  ry_used()] routi
203e0 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ne returns the n
203f0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 0a 2a  umber of bytes.*
20400 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72 72  * of memory curr
20410 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e  ently outstandin
20420 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20  g (malloced but 
20430 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a 20 5e  not freed)..** ^
20440 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  The [sqlite3_mem
20450 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d  ory_highwater()]
20460 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
20470 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20   the maximum.** 
20480 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65  value of [sqlite
20490 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
204a0 20 73 69 6e 63 65 20 74 68 65 20 68 69 67 68 2d   since the high-
204b0 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 77 61  water mark.** wa
204c0 73 20 6c 61 73 74 20 72 65 73 65 74 2e 20 20 5e  s last reset.  ^
204d0 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72  The values retur
204e0 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
204f0 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 61  memory_used()] a
20500 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  nd.** [sqlite3_m
20510 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
20520 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f  )] include any o
20530 76 65 72 68 65 61 64 0a 2a 2a 20 61 64 64 65 64  verhead.** added
20540 20 62 79 20 53 51 4c 69 74 65 20 69 6e 20 69 74   by SQLite in it
20550 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  s implementation
20560 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   of [sqlite3_mal
20570 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e  loc()],.** but n
20580 6f 74 20 6f 76 65 72 68 65 61 64 20 61 64 64 65  ot overhead adde
20590 64 20 62 79 20 74 68 65 20 61 6e 79 20 75 6e 64  d by the any und
205a0 65 72 6c 79 69 6e 67 20 73 79 73 74 65 6d 20 6c  erlying system l
205b0 69 62 72 61 72 79 0a 2a 2a 20 72 6f 75 74 69 6e  ibrary.** routin
205c0 65 73 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33  es that [sqlite3
205d0 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63  _malloc()] may c
205e0 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  all..**.** ^The 
205f0 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77 61 74 65  memory high-wate
20600 72 20 6d 61 72 6b 20 69 73 20 72 65 73 65 74 20  r mark is reset 
20610 74 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20 76  to the current v
20620 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69  alue of.** [sqli
20630 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
20640 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69  )] if and only i
20650 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
20660 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  to.** [sqlite3_m
20670 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
20680 29 5d 20 69 73 20 74 72 75 65 2e 20 20 5e 54 68  )] is true.  ^Th
20690 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
206a0 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  .** by [sqlite3_
206b0 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
206c0 28 31 29 5d 20 69 73 20 74 68 65 20 68 69 67 68  (1)] is the high
206d0 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 70  -water mark.** p
206e0 72 69 6f 72 20 74 6f 20 74 68 65 20 72 65 73 65  rior to the rese
206f0 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  t..*/.SQLITE_API
20700 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73   sqlite3_int64 s
20710 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
20720 65 64 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45  ed(void);.SQLITE
20730 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74  _API sqlite3_int
20740 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  64 sqlite3_memor
20750 79 5f 68 69 67 68 77 61 74 65 72 28 69 6e 74 20  y_highwater(int 
20760 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a  resetFlag);../*.
20770 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50 73 65  ** CAPI3REF: Pse
20780 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65  udo-Random Numbe
20790 72 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a  r Generator.**.*
207a0 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e  * SQLite contain
207b0 73 20 61 20 68 69 67 68 2d 71 75 61 6c 69 74 79  s a high-quality
207c0 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e   pseudo-random n
207d0 75 6d 62 65 72 20 67 65 6e 65 72 61 74 6f 72 20  umber generator 
207e0 28 50 52 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a  (PRNG) used to.*
207f0 2a 20 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20  * select random 
20800 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49 44 73 5d  [ROWID | ROWIDs]
20810 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20   when inserting 
20820 6e 65 77 20 72 65 63 6f 72 64 73 20 69 6e 74 6f  new records into
20830 20 61 20 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a   a table that.**
20840 20 61 6c 72 65 61 64 79 20 75 73 65 73 20 74 68   already uses th
20850 65 20 6c 61 72 67 65 73 74 20 70 6f 73 73 69 62  e largest possib
20860 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68 65  le [ROWID].  The
20870 20 50 52 4e 47 20 69 73 20 61 6c 73 6f 20 75 73   PRNG is also us
20880 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75  ed for.** the bu
20890 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20  ild-in random() 
208a0 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29  and randomblob()
208b0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20   SQL functions. 
208c0 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   This interface 
208d0 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63  allows.** applic
208e0 61 74 69 6f 6e 73 20 74 6f 20 61 63 63 65 73 73  ations to access
208f0 20 74 68 65 20 73 61 6d 65 20 50 52 4e 47 20 66   the same PRNG f
20900 6f 72 20 6f 74 68 65 72 20 70 75 72 70 6f 73 65  or other purpose
20910 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c  s..**.** ^A call
20920 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65   to this routine
20930 20 73 74 6f 72 65 73 20 4e 20 62 79 74 65 73 20   stores N bytes 
20940 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e  of randomness in
20950 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a 0a  to buffer P..**.
20960 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 74 69  ** ^The first ti
20970 6d 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  me this routine 
20980 69 73 20 69 6e 76 6f 6b 65 64 20 28 65 69 74 68  is invoked (eith
20990 65 72 20 69 6e 74 65 72 6e 61 6c 6c 79 20 6f 72  er internally or
209a0 20 62 79 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69   by.** the appli
209b0 63 61 74 69 6f 6e 29 20 74 68 65 20 50 52 4e 47  cation) the PRNG
209c0 20 69 73 20 73 65 65 64 65 64 20 75 73 69 6e 67   is seeded using
209d0 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61   randomness obta
209e0 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 74 68 65  ined.** from the
209f0 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d 65 74   xRandomness met
20a00 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61 75  hod of the defau
20a10 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  lt [sqlite3_vfs]
20a20 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 4f 6e 20   object..** ^On 
20a30 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20 69  all subsequent i
20a40 6e 76 6f 63 61 74 69 6f 6e 73 2c 20 74 68 65 20  nvocations, the 
20a50 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73  pseudo-randomnes
20a60 73 20 69 73 20 67 65 6e 65 72 61 74 65 64 0a 2a  s is generated.*
20a70 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 20 61 6e 64  * internally and
20a80 20 77 69 74 68 6f 75 74 20 72 65 63 6f 75 72 73   without recours
20a90 65 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  e to the [sqlite
20aa0 33 5f 76 66 73 5d 20 78 52 61 6e 64 6f 6d 6e 65  3_vfs] xRandomne
20ab0 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f  ss.** method..*/
20ac0 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
20ad0 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e   sqlite3_randomn
20ae0 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20  ess(int N, void 
20af0 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  *P);../*.** CAPI
20b00 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69  3REF: Compile-Ti
20b10 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e  me Authorization
20b20 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a   Callbacks.**.**
20b30 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72   ^This routine r
20b40 65 67 69 73 74 65 72 73 20 61 6e 20 61 75 74 68  egisters an auth
20b50 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
20b60 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61  with a particula
20b70 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  r.** [database c
20b80 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70  onnection], supp
20b90 6c 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 73  lied in the firs
20ba0 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e  t argument..** ^
20bb0 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  The authorizer c
20bc0 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
20bd0 65 64 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d  ed as SQL statem
20be0 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67 20 63  ents are being c
20bf0 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73  ompiled.** by [s
20c00 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
20c10 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74  ] or its variant
20c20 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  s [sqlite3_prepa
20c30 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71  re_v2()],.** [sq
20c40 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
20c50 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
20c60 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e  prepare16_v2()].
20c70 20 20 5e 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a    ^At various.**
20c80 20 70 6f 69 6e 74 73 20 64 75 72 69 6e 67 20 74   points during t
20c90 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70  he compilation p
20ca0 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67 69 63  rocess, as logic
20cb0 20 69 73 20 62 65 69 6e 67 20 63 72 65 61 74 65   is being create
20cc0 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20  d.** to perform 
20cd0 76 61 72 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c  various actions,
20ce0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
20cf0 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
20d00 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66  ked to.** see if
20d10 20 74 68 6f 73 65 20 61 63 74 69 6f 6e 73 20 61   those actions a
20d20 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20 5e 54 68  re allowed.  ^Th
20d30 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
20d40 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20  lback should.** 
20d50 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f  return [SQLITE_O
20d60 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20  K] to allow the 
20d70 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f  action, [SQLITE_
20d80 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c  IGNORE] to disal
20d90 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65 63 69  low the.** speci
20da0 66 69 63 20 61 63 74 69 6f 6e 20 62 75 74 20 61  fic action but a
20db0 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20 73 74 61  llow the SQL sta
20dc0 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e  tement to contin
20dd0 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70  ue to be.** comp
20de0 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45  iled, or [SQLITE
20df0 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75 73 65 20  _DENY] to cause 
20e00 74 68 65 20 65 6e 74 69 72 65 20 53 51 4c 20 73  the entire SQL s
20e10 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a  tatement to be.*
20e20 2a 20 72 65 6a 65 63 74 65 64 20 77 69 74 68 20  * rejected with 
20e30 61 6e 20 65 72 72 6f 72 2e 20 20 5e 49 66 20 74  an error.  ^If t
20e40 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
20e50 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a  llback returns.*
20e60 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65  * any value othe
20e70 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49  r than [SQLITE_I
20e80 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f  GNORE], [SQLITE_
20e90 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  OK], or [SQLITE_
20ea0 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68  DENY].** then th
20eb0 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  e [sqlite3_prepa
20ec0 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69  re_v2()] or equi
20ed0 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74  valent call that
20ee0 20 74 72 69 67 67 65 72 65 64 0a 2a 2a 20 74 68   triggered.** th
20ef0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c  e authorizer wil
20f00 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65  l fail with an e
20f10 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a  rror message..**
20f20 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c  .** When the cal
20f30 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53  lback returns [S
20f40 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20  QLITE_OK], that 
20f50 6d 65 61 6e 73 20 74 68 65 20 6f 70 65 72 61 74  means the operat
20f60 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65 64  ion.** requested
20f70 20 69 73 20 6f 6b 2e 20 20 5e 57 68 65 6e 20 74   is ok.  ^When t
20f80 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
20f90 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59  rns [SQLITE_DENY
20fa0 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ], the.** [sqlit
20fb0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
20fc0 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63   or equivalent c
20fd0 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72  all that trigger
20fe0 65 64 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72  ed the.** author
20ff0 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77  izer will fail w
21000 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73  ith an error mes
21010 73 61 67 65 20 65 78 70 6c 61 69 6e 69 6e 67 20  sage explaining 
21020 74 68 61 74 0a 2a 2a 20 61 63 63 65 73 73 20 69  that.** access i
21030 73 20 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a  s denied. .**.**
21040 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61   ^The first para
21050 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74  meter to the aut
21060 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
21070 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68   is a copy of th
21080 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d  e third.** param
21090 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
210a0 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
210b0 65 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e 20  er() interface. 
210c0 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61  ^The second para
210d0 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  meter.** to the 
210e0 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69  callback is an i
210f0 6e 74 65 67 65 72 20 5b 53 51 4c 49 54 45 5f 43  nteger [SQLITE_C
21100 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64  OPY | action cod
21110 65 5d 20 74 68 61 74 20 73 70 65 63 69 66 69 65  e] that specifie
21120 73 0a 2a 2a 20 74 68 65 20 70 61 72 74 69 63 75  s.** the particu
21130 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f 20 62 65  lar action to be
21140 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 5e 54 68   authorized. ^Th
21150 65 20 74 68 69 72 64 20 74 68 72 6f 75 67 68 20  e third through 
21160 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 73  sixth parameters
21170 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  .** to the callb
21180 61 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65 72  ack are zero-ter
21190 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20  minated strings 
211a0 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 64 64  that contain add
211b0 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69  itional.** detai
211c0 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61 63 74  ls about the act
211d0 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72  ion to be author
211e0 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ized..**.** ^If 
211f0 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20  the action code 
21200 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d  is [SQLITE_READ]
21210 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63 61 6c 6c  .** and the call
21220 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51  back returns [SQ
21230 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65  LITE_IGNORE] the
21240 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  n the.** [prepar
21250 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 73 74  ed statement] st
21260 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74  atement is const
21270 72 75 63 74 65 64 20 74 6f 20 73 75 62 73 74 69  ructed to substi
21280 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76  tute.** a NULL v
21290 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20 6f 66  alue in place of
212a0 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d   the table colum
212b0 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76  n that would hav
212c0 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64 20 69  e.** been read i
212d0 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61  f [SQLITE_OK] ha
212e0 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64 2e  d been returned.
212f0 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 47    The [SQLITE_IG
21300 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20  NORE].** return 
21310 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64  can be used to d
21320 65 6e 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64  eny an untrusted
21330 20 75 73 65 72 20 61 63 63 65 73 73 20 74 6f 20   user access to 
21340 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f  individual.** co
21350 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c 65  lumns of a table
21360 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74  ..** ^If the act
21370 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c  ion code is [SQL
21380 49 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20  ITE_DELETE] and 
21390 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
213a0 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  urns.** [SQLITE_
213b0 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65  IGNORE] then the
213c0 20 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72 61 74   [DELETE] operat
213d0 69 6f 6e 20 70 72 6f 63 65 65 64 73 20 62 75 74  ion proceeds but
213e0 20 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74   the.** [truncat
213f0 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20  e optimization] 
21400 69 73 20 64 69 73 61 62 6c 65 64 20 61 6e 64 20  is disabled and 
21410 61 6c 6c 20 72 6f 77 73 20 61 72 65 20 64 65 6c  all rows are del
21420 65 74 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c  eted individuall
21430 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68  y..**.** An auth
21440 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64 20 77  orizer is used w
21450 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  hen [sqlite3_pre
21460 70 61 72 65 20 7c 20 70 72 65 70 61 72 69 6e 67  pare | preparing
21470 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  ].** SQL stateme
21480 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72  nts from an untr
21490 75 73 74 65 64 20 73 6f 75 72 63 65 2c 20 74 6f  usted source, to
214a0 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65   ensure that the
214b0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
214c0 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f  ** do not try to
214d0 20 61 63 63 65 73 73 20 64 61 74 61 20 74 68 65   access data the
214e0 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65  y are not allowe
214f0 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 61  d to see, or tha
21500 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a  t they do not.**
21510 20 74 72 79 20 74 6f 20 65 78 65 63 75 74 65 20   try to execute 
21520 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 74 65 6d  malicious statem
21530 65 6e 74 73 20 74 68 61 74 20 64 61 6d 61 67 65  ents that damage
21540 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 20   the database.  
21550 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20  For.** example, 
21560 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  an application m
21570 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20  ay allow a user 
21580 74 6f 20 65 6e 74 65 72 20 61 72 62 69 74 72 61  to enter arbitra
21590 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 65  ry.** SQL querie
215a0 73 20 66 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e  s for evaluation
215b0 20 62 79 20 61 20 64 61 74 61 62 61 73 65 2e 20   by a database. 
215c0 20 42 75 74 20 74 68 65 20 61 70 70 6c 69 63 61   But the applica
215d0 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74  tion does.** not
215e0 20 77 61 6e 74 20 74 68 65 20 75 73 65 72 20 74   want the user t
215f0 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b  o be able to mak
21600 65 20 61 72 62 69 74 72 61 72 79 20 63 68 61 6e  e arbitrary chan
21610 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61  ges to the.** da
21620 74 61 62 61 73 65 2e 20 20 41 6e 20 61 75 74 68  tabase.  An auth
21630 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 65  orizer could the
21640 6e 20 62 65 20 70 75 74 20 69 6e 20 70 6c 61 63  n be put in plac
21650 65 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75  e while the.** u
21660 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 20  ser-entered SQL 
21670 69 73 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 65  is being [sqlite
21680 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70  3_prepare | prep
21690 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69  ared] that.** di
216a0 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69  sallows everythi
216b0 6e 67 20 65 78 63 65 70 74 20 5b 53 45 4c 45 43  ng except [SELEC
216c0 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  T] statements..*
216d0 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e  *.** Application
216e0 73 20 74 68 61 74 20 6e 65 65 64 20 74 6f 20 70  s that need to p
216f0 72 6f 63 65 73 73 20 53 51 4c 20 66 72 6f 6d 20  rocess SQL from 
21700 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65  untrusted source
21710 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20  s.** might also 
21720 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 6e  consider lowerin
21730 67 20 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 74  g resource limit
21740 73 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  s using [sqlite3
21750 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64  _limit()].** and
21760 20 6c 69 6d 69 74 69 6e 67 20 64 61 74 61 62 61   limiting databa
21770 73 65 20 73 69 7a 65 20 75 73 69 6e 67 20 74 68  se size using th
21780 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e  e [max_page_coun
21790 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69  t] [PRAGMA].** i
217a0 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 73  n addition to us
217b0 69 6e 67 20 61 6e 20 61 75 74 68 6f 72 69 7a 65  ing an authorize
217c0 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20  r..**.** ^(Only 
217d0 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 69  a single authori
217e0 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20 70 6c  zer can be in pl
217f0 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73  ace on a databas
21800 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
21810 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68  at a time.  Each
21820 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
21830 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20  _set_authorizer 
21840 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a  overrides the.**
21850 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29   previous call.)
21860 5e 20 20 5e 44 69 73 61 62 6c 65 20 74 68 65 20  ^  ^Disable the 
21870 61 75 74 68 6f 72 69 7a 65 72 20 62 79 20 69 6e  authorizer by in
21880 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20  stalling a NULL 
21890 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65  callback..** The
218a0 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 64   authorizer is d
218b0 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  isabled by defau
218c0 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75  lt..**.** The au
218d0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
218e0 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e  k must not do an
218f0 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c  ything that will
21900 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64   modify.** the d
21910 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
21920 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  on that invoked 
21930 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
21940 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65  allback..** Note
21950 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70   that [sqlite3_p
21960 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
21970 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
21980 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68  ] both modify th
21990 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  eir.** database 
219a0 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20  connections for 
219b0 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22  the meaning of "
219c0 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20  modify" in this 
219d0 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a  paragraph..**.**
219e0 20 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f   ^When [sqlite3_
219f0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69 73  prepare_v2()] is
21a00 20 75 73 65 64 20 74 6f 20 70 72 65 70 61 72 65   used to prepare
21a10 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 68   a statement, th
21a20 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d  e.** statement m
21a30 69 67 68 74 20 62 65 20 72 65 2d 70 72 65 70 61  ight be re-prepa
21a40 72 65 64 20 64 75 72 69 6e 67 20 5b 73 71 6c 69  red during [sqli
21a50 74 65 33 5f 73 74 65 70 28 29 5d 20 64 75 65 20  te3_step()] due 
21a60 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20  to a .** schema 
21a70 63 68 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20  change.  Hence, 
21a80 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
21a90 73 68 6f 75 6c 64 20 65 6e 73 75 72 65 20 74 68  should ensure th
21aa0 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63  at the.** correc
21ab0 74 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  t authorizer cal
21ac0 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e  lback remains in
21ad0 20 70 6c 61 63 65 20 64 75 72 69 6e 67 20 74 68   place during th
21ae0 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  e [sqlite3_step(
21af0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20  )]..**.** ^Note 
21b00 74 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 69  that the authori
21b10 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
21b20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72  invoked only dur
21b30 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
21b40 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74  prepare()] or it
21b50 73 20 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74  s variants.  Aut
21b60 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f  horization is no
21b70 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64  t.** performed d
21b80 75 72 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20  uring statement 
21b90 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73  evaluation in [s
21ba0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20  qlite3_step()], 
21bb0 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74 61  unless.** as sta
21bc0 74 65 64 20 69 6e 20 74 68 65 20 70 72 65 76 69  ted in the previ
21bd0 6f 75 73 20 70 61 72 61 67 72 61 70 68 2c 20 73  ous paragraph, s
21be0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e  qlite3_step() in
21bf0 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33  vokes.** sqlite3
21c00 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 74 6f  _prepare_v2() to
21c10 20 72 65 70 72 65 70 61 72 65 20 61 20 73 74 61   reprepare a sta
21c20 74 65 6d 65 6e 74 20 61 66 74 65 72 20 61 20 73  tement after a s
21c30 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f  chema change..*/
21c40 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
21c50 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
21c60 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c 69 74 65  orizer(.  sqlite
21c70 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75 74  3*,.  int (*xAut
21c80 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  h)(void*,int,con
21c90 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  st char*,const c
21ca0 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
21cb0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20  ,const char*),. 
21cc0 20 76 6f 69 64 20 2a 70 55 73 65 72 44 61 74 61   void *pUserData
21cd0 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
21ce0 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20  REF: Authorizer 
21cf0 52 65 74 75 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a  Return Codes.**.
21d00 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
21d10 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c  set_authorizer |
21d20 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
21d30 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d  back function] m
21d40 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69  ust.** return ei
21d50 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  ther [SQLITE_OK]
21d60 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 73 65   or one of these
21d70 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69   two constants i
21d80 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69  n order.** to si
21d90 67 6e 61 6c 20 53 51 4c 69 74 65 20 77 68 65 74  gnal SQLite whet
21da0 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 61  her or not the a
21db0 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74  ction is permitt
21dc0 65 64 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20  ed.  See the.** 
21dd0 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
21de0 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72  horizer | author
21df0 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61 74 69  izer documentati
21e00 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  on] for addition
21e10 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  al.** informatio
21e20 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  n..**.** Note th
21e30 61 74 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  at SQLITE_IGNORE
21e40 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20 61 73   is also used as
21e50 20 61 20 5b 53 51 4c 49 54 45 5f 52 4f 4c 4c 42   a [SQLITE_ROLLB
21e60 41 43 4b 20 7c 20 72 65 74 75 72 6e 20 63 6f 64  ACK | return cod
21e70 65 5d 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 5b  e].** from the [
21e80 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 6f 6e 5f  sqlite3_vtab_on_
21e90 63 6f 6e 66 6c 69 63 74 28 29 5d 20 69 6e 74 65  conflict()] inte
21ea0 72 66 61 63 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e  rface..*/.#defin
21eb0 65 20 53 51 4c 49 54 45 5f 44 45 4e 59 20 20 20  e SQLITE_DENY   
21ec0 31 20 20 20 2f 2a 20 41 62 6f 72 74 20 74 68 65  1   /* Abort the
21ed0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77   SQL statement w
21ee0 69 74 68 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a  ith an error */.
21ef0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
21f00 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20 44 6f 6e  GNORE 2   /* Don
21f10 27 74 20 61 6c 6c 6f 77 20 61 63 63 65 73 73 2c  't allow access,
21f20 20 62 75 74 20 64 6f 6e 27 74 20 67 65 6e 65 72   but don't gener
21f30 61 74 65 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a  ate an error */.
21f40 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
21f50 20 41 75 74 68 6f 72 69 7a 65 72 20 41 63 74 69   Authorizer Acti
21f60 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54  on Codes.**.** T
21f70 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  he [sqlite3_set_
21f80 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e  authorizer()] in
21f90 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72  terface register
21fa0 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  s a callback fun
21fb0 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 73  ction.** that is
21fc0 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61 75 74 68   invoked to auth
21fd0 6f 72 69 7a 65 20 63 65 72 74 61 69 6e 20 53 51  orize certain SQ
21fe0 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 63 74 69  L statement acti
21ff0 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63  ons.  The.** sec
22000 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ond parameter to
22010 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   the callback is
22020 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65   an integer code
22030 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73 0a   that specifies.
22040 2a 2a 20 77 68 61 74 20 61 63 74 69 6f 6e 20 69  ** what action i
22050 73 20 62 65 69 6e 67 20 61 75 74 68 6f 72 69 7a  s being authoriz
22060 65 64 2e 20 20 54 68 65 73 65 20 61 72 65 20 74  ed.  These are t
22070 68 65 20 69 6e 74 65 67 65 72 20 61 63 74 69 6f  he integer actio
22080 6e 20 63 6f 64 65 73 20 74 68 61 74 0a 2a 2a 20  n codes that.** 
22090 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
220a0 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65 20 70  allback may be p
220b0 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  assed..**.** The
220c0 73 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 76  se action code v
220d0 61 6c 75 65 73 20 73 69 67 6e 69 66 79 20 77 68  alues signify wh
220e0 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65 72 61  at kind of opera
220f0 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 0a 2a 2a  tion is to be.**
22100 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68   authorized.  Th
22110 65 20 33 72 64 20 61 6e 64 20 34 74 68 20 70 61  e 3rd and 4th pa
22120 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65 20  rameters to the 
22130 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a  authorization.**
22140 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
22150 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61 72 61 6d  on will be param
22160 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64 65  eters or NULL de
22170 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63 68  pending on which
22180 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 63 6f 64   of these.** cod
22190 65 73 20 69 73 20 75 73 65 64 20 61 73 20 74 68  es is used as th
221a0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
221b0 65 72 2e 20 20 5e 28 54 68 65 20 35 74 68 20 70  er.  ^(The 5th p
221c0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 0a  arameter to the.
221d0 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  ** authorizer ca
221e0 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e 61  llback is the na
221f0 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  me of the databa
22200 73 65 20 28 22 6d 61 69 6e 22 2c 20 22 74 65 6d  se ("main", "tem
22210 70 22 2c 0a 2a 2a 20 65 74 63 2e 29 20 69 66 20  p",.** etc.) if 
22220 61 70 70 6c 69 63 61 62 6c 65 2e 29 5e 20 20 5e  applicable.)^  ^
22230 54 68 65 20 36 74 68 20 70 61 72 61 6d 65 74 65  The 6th paramete
22240 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69  r to the authori
22250 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  zer callback.** 
22260 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
22270 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72  he inner-most tr
22280 69 67 67 65 72 20 6f 72 20 76 69 65 77 20 74 68  igger or view th
22290 61 74 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c  at is responsibl
222a0 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 63 63  e for.** the acc
222b0 65 73 73 20 61 74 74 65 6d 70 74 20 6f 72 20 4e  ess attempt or N
222c0 55 4c 4c 20 69 66 20 74 68 69 73 20 61 63 63 65  ULL if this acce
222d0 73 73 20 61 74 74 65 6d 70 74 20 69 73 20 64 69  ss attempt is di
222e0 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74  rectly from.** t
222f0 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64  op-level SQL cod
22300 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a  e..*/./*********
22310 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
22320 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
22330 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a  ** 3rd *********
22340 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a  *** 4th ********
22350 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ***/.#define SQL
22360 49 54 45 5f 43 52 45 41 54 45 5f 49 4e 44 45 58  ITE_CREATE_INDEX
22370 20 20 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a            1   /*
22380 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
22390 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
223a0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
223b0 54 45 5f 43 52 45 41 54 45 5f 54 41 42 4c 45 20  TE_CREATE_TABLE 
223c0 20 20 20 20 20 20 20 20 20 32 20 20 20 2f 2a 20           2   /* 
223d0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
223e0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
223f0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
22400 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e  E_CREATE_TEMP_IN
22410 44 45 58 20 20 20 20 20 33 20 20 20 2f 2a 20 49  DEX     3   /* I
22420 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54  ndex Name      T
22430 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
22440 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
22450 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 41 42  _CREATE_TEMP_TAB
22460 4c 45 20 20 20 20 20 34 20 20 20 2f 2a 20 54 61  LE     4   /* Ta
22470 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
22480 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
22490 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
224a0 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 52 49 47  CREATE_TEMP_TRIG
224b0 47 45 52 20 20 20 35 20 20 20 2f 2a 20 54 72 69  GER   5   /* Tri
224c0 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62  gger Name    Tab
224d0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
224e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
224f0 52 45 41 54 45 5f 54 45 4d 50 5f 56 49 45 57 20  REATE_TEMP_VIEW 
22500 20 20 20 20 20 36 20 20 20 2f 2a 20 56 69 65 77       6   /* View
22510 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c   Name       NULL
22520 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
22530 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
22540 45 41 54 45 5f 54 52 49 47 47 45 52 20 20 20 20  EATE_TRIGGER    
22550 20 20 20 20 37 20 20 20 2f 2a 20 54 72 69 67 67      7   /* Trigg
22560 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65  er Name    Table
22570 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
22580 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
22590 41 54 45 5f 56 49 45 57 20 20 20 20 20 20 20 20  ATE_VIEW        
225a0 20 20 20 38 20 20 20 2f 2a 20 56 69 65 77 20 4e     8   /* View N
225b0 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  ame       NULL  
225c0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
225d0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c 45  fine SQLITE_DELE
225e0 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TE              
225f0 20 20 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e    9   /* Table N
22600 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
22610 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
22620 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
22630 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20  INDEX           
22640 31 30 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61  10   /* Index Na
22650 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61  me      Table Na
22660 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
22670 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
22680 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 20 31  ABLE           1
22690 31 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  1   /* Table Nam
226a0 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
226b0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
226c0 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45  e SQLITE_DROP_TE
226d0 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 20 31 32  MP_INDEX      12
226e0 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
226f0 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65        Table Name
22700 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
22710 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d   SQLITE_DROP_TEM
22720 50 5f 54 41 42 4c 45 20 20 20 20 20 20 31 33 20  P_TABLE      13 
22730 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
22740 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
22750 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
22760 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50  SQLITE_DROP_TEMP
22770 5f 54 52 49 47 47 45 52 20 20 20 20 31 34 20 20  _TRIGGER    14  
22780 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65   /* Trigger Name
22790 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
227a0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
227b0 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f  QLITE_DROP_TEMP_
227c0 56 49 45 57 20 20 20 20 20 20 20 31 35 20 20 20  VIEW       15   
227d0 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20  /* View Name    
227e0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
227f0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
22800 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49 47 47 45  LITE_DROP_TRIGGE
22810 52 20 20 20 20 20 20 20 20 20 31 36 20 20 20 2f  R         16   /
22820 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20  * Trigger Name  
22830 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
22840 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
22850 49 54 45 5f 44 52 4f 50 5f 56 49 45 57 20 20 20  ITE_DROP_VIEW   
22860 20 20 20 20 20 20 20 20 20 31 37 20 20 20 2f 2a           17   /*
22870 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20   View Name      
22880 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
22890 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
228a0 54 45 5f 49 4e 53 45 52 54 20 20 20 20 20 20 20  TE_INSERT       
228b0 20 20 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20          18   /* 
228c0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
228d0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
228e0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
228f0 45 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20 20  E_PRAGMA        
22900 20 20 20 20 20 20 20 31 39 20 20 20 2f 2a 20 50         19   /* P
22910 72 61 67 6d 61 20 4e 61 6d 65 20 20 20 20 20 31  ragma Name     1
22920 73 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a  st arg or NULL *
22930 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
22940 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20 20  _READ           
22950 20 20 20 20 20 20 32 30 20 20 20 2f 2a 20 54 61        20   /* Ta
22960 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f  ble Name      Co
22970 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f  lumn Name     */
22980 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
22990 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 20 20  SELECT          
229a0 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c       21   /* NUL
229b0 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c  L            NUL
229c0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
229d0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
229e0 52 41 4e 53 41 43 54 49 4f 4e 20 20 20 20 20 20  RANSACTION      
229f0 20 20 20 20 32 32 20 20 20 2f 2a 20 4f 70 65 72      22   /* Oper
22a00 61 74 69 6f 6e 20 20 20 20 20 20 20 4e 55 4c 4c  ation       NULL
22a10 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
22a20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 50  define SQLITE_UP
22a30 44 41 54 45 20 20 20 20 20 20 20 20 20 20 20 20  DATE            
22a40 20 20 20 32 33 20 20 20 2f 2a 20 54 61 62 6c 65     23   /* Table
22a50 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d   Name      Colum
22a60 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64  n Name     */.#d
22a70 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 54 54  efine SQLITE_ATT
22a80 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20  ACH             
22a90 20 20 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61    24   /* Filena
22aa0 6d 65 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  me        NULL  
22ab0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
22ac0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 41  fine SQLITE_DETA
22ad0 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CH              
22ae0 20 32 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73   25   /* Databas
22af0 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20  e Name   NULL   
22b00 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
22b10 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54 45 52  ine SQLITE_ALTER
22b20 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20  _TABLE          
22b30 32 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  26   /* Database
22b40 20 4e 61 6d 65 20 20 20 54 61 62 6c 65 20 4e 61   Name   Table Na
22b50 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
22b60 6e 65 20 53 51 4c 49 54 45 5f 52 45 49 4e 44 45  ne SQLITE_REINDE
22b70 58 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32  X              2
22b80 37 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  7   /* Index Nam
22b90 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
22ba0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
22bb0 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a 45  e SQLITE_ANALYZE
22bc0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 38                28
22bd0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
22be0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
22bf0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
22c00 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56   SQLITE_CREATE_V
22c10 54 41 42 4c 45 20 20 20 20 20 20 20 20 32 39 20  TABLE        29 
22c20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
22c30 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65       Module Name
22c40 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
22c50 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41 42  SQLITE_DROP_VTAB
22c60 4c 45 20 20 20 20 20 20 20 20 20 20 33 30 20 20  LE          30  
22c70 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
22c80 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20      Module Name 
22c90 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
22ca0 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20 20  QLITE_FUNCTION  
22cb0 20 20 20 20 20 20 20 20 20 20 20 33 31 20 20 20             31   
22cc0 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20  /* NULL         
22cd0 20 20 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d 65     Function Name
22ce0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
22cf0 4c 49 54 45 5f 53 41 56 45 50 4f 49 4e 54 20 20  LITE_SAVEPOINT  
22d00 20 20 20 20 20 20 20 20 20 20 33 32 20 20 20 2f            32   /
22d10 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20  * Operation     
22d20 20 20 53 61 76 65 70 6f 69 6e 74 20 4e 61 6d 65    Savepoint Name
22d30 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
22d40 49 54 45 5f 43 4f 50 59 20 20 20 20 20 20 20 20  ITE_COPY        
22d50 20 20 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a            0   /*
22d60 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64 20   No longer used 
22d70 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
22d80 45 46 3a 20 54 72 61 63 69 6e 67 20 41 6e 64 20  EF: Tracing And 
22d90 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74 69  Profiling Functi
22da0 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ons.**.** These 
22db0 72 6f 75 74 69 6e 65 73 20 72 65 67 69 73 74 65  routines registe
22dc0 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  r callback funct
22dd0 69 6f 6e 73 20 74 68 61 74 20 63 61 6e 20 62 65  ions that can be
22de0 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61   used for.** tra
22df0 63 69 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c 69  cing and profili
22e00 6e 67 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e  ng the execution
22e10 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   of SQL statemen
22e20 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63  ts..**.** ^The c
22e30 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
22e40 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73   registered by s
22e50 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 69  qlite3_trace() i
22e60 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20  s invoked at.** 
22e70 76 61 72 69 6f 75 73 20 74 69 6d 65 73 20 77 68  various times wh
22e80 65 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  en an SQL statem
22e90 65 6e 74 20 69 73 20 62 65 69 6e 67 20 72 75 6e  ent is being run
22ea0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   by [sqlite3_ste
22eb0 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  p()]..** ^The sq
22ec0 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 63 61  lite3_trace() ca
22ed0 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
22ee0 64 20 77 69 74 68 20 61 20 55 54 46 2d 38 20 72  d with a UTF-8 r
22ef0 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 0a  endering of the.
22f00 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
22f10 20 74 65 78 74 20 61 73 20 74 68 65 20 73 74 61   text as the sta
22f20 74 65 6d 65 6e 74 20 66 69 72 73 74 20 62 65 67  tement first beg
22f30 69 6e 73 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a  ins executing..*
22f40 2a 20 5e 28 41 64 64 69 74 69 6f 6e 61 6c 20 73  * ^(Additional s
22f50 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 63  qlite3_trace() c
22f60 61 6c 6c 62 61 63 6b 73 20 6d 69 67 68 74 20 6f  allbacks might o
22f70 63 63 75 72 0a 2a 2a 20 61 73 20 65 61 63 68 20  ccur.** as each 
22f80 74 72 69 67 67 65 72 65 64 20 73 75 62 70 72 6f  triggered subpro
22f90 67 72 61 6d 20 69 73 20 65 6e 74 65 72 65 64 2e  gram is entered.
22fa0 20 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 73 20    The callbacks 
22fb0 66 6f 72 20 74 72 69 67 67 65 72 73 0a 2a 2a 20  for triggers.** 
22fc0 63 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d 38 20  contain a UTF-8 
22fd0 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74  SQL comment that
22fe0 20 69 64 65 6e 74 69 66 69 65 73 20 74 68 65 20   identifies the 
22ff0 74 72 69 67 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a  trigger.)^.**.**
23000 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66   ^The callback f
23010 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72  unction register
23020 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70 72  ed by sqlite3_pr
23030 6f 66 69 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b  ofile() is invok
23040 65 64 0a 2a 2a 20 61 73 20 65 61 63 68 20 53 51  ed.** as each SQ
23050 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69  L statement fini
23060 73 68 65 73 2e 20 20 5e 54 68 65 20 70 72 6f 66  shes.  ^The prof
23070 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e  ile callback con
23080 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69  tains.** the ori
23090 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 20  ginal statement 
230a0 74 65 78 74 20 61 6e 64 20 61 6e 20 65 73 74 69  text and an esti
230b0 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f  mate of wall-clo
230c0 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f  ck time.** of ho
230d0 77 20 6c 6f 6e 67 20 74 68 61 74 20 73 74 61 74  w long that stat
230e0 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75  ement took to ru
230f0 6e 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65  n.  ^The profile
23100 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d   callback.** tim
23110 65 20 69 73 20 69 6e 20 75 6e 69 74 73 20 6f 66  e is in units of
23120 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c 20 68 6f   nanoseconds, ho
23130 77 65 76 65 72 20 74 68 65 20 63 75 72 72 65 6e  wever the curren
23140 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  t implementation
23150 0a 2a 2a 20 69 73 20 6f 6e 6c 79 20 63 61 70 61  .** is only capa
23160 62 6c 65 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f  ble of milliseco
23170 6e 64 20 72 65 73 6f 6c 75 74 69 6f 6e 20 73 6f  nd resolution so
23180 20 74 68 65 20 73 69 78 20 6c 65 61 73 74 20 73   the six least s
23190 69 67 6e 69 66 69 63 61 6e 74 0a 2a 2a 20 64 69  ignificant.** di
231a0 67 69 74 73 20 69 6e 20 74 68 65 20 74 69 6d 65  gits in the time
231b0 20 61 72 65 20 6d 65 61 6e 69 6e 67 6c 65 73 73   are meaningless
231c0 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f  .  Future versio
231d0 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20  ns of SQLite.** 
231e0 6d 69 67 68 74 20 70 72 6f 76 69 64 65 20 67 72  might provide gr
231f0 65 61 74 65 72 20 72 65 73 6f 6c 75 74 69 6f 6e  eater resolution
23200 20 6f 6e 20 74 68 65 20 70 72 6f 66 69 6c 65 72   on the profiler
23210 20 63 61 6c 6c 62 61 63 6b 2e 20 20 54 68 65 0a   callback.  The.
23220 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69  ** sqlite3_profi
23230 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73  le() function is
23240 20 63 6f 6e 73 69 64 65 72 65 64 20 65 78 70 65   considered expe
23250 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 0a  rimental and is.
23260 2a 2a 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68  ** subject to ch
23270 61 6e 67 65 20 69 6e 20 66 75 74 75 72 65 20 76  ange in future v
23280 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
23290 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  e..*/.SQLITE_API
232a0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 74   void *sqlite3_t
232b0 72 61 63 65 28 73 71 6c 69 74 65 33 2a 2c 20 76  race(sqlite3*, v
232c0 6f 69 64 28 2a 78 54 72 61 63 65 29 28 76 6f 69  oid(*xTrace)(voi
232d0 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c  d*,const char*),
232e0 20 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f   void*);.SQLITE_
232f0 41 50 49 20 53 51 4c 49 54 45 5f 45 58 50 45 52  API SQLITE_EXPER
23300 49 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a 73 71  IMENTAL void *sq
23310 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 73 71  lite3_profile(sq
23320 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28  lite3*,.   void(
23330 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a  *xProfile)(void*
23340 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c  ,const char*,sql
23350 69 74 65 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f  ite3_uint64), vo
23360 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
23370 49 33 52 45 46 3a 20 51 75 65 72 79 20 50 72 6f  I3REF: Query Pro
23380 67 72 65 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a  gress Callbacks.
23390 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
233a0 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64  e3_progress_hand
233b0 6c 65 72 28 44 2c 4e 2c 58 2c 50 29 20 69 6e 74  ler(D,N,X,P) int
233c0 65 72 66 61 63 65 20 63 61 75 73 65 73 20 74 68  erface causes th
233d0 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75  e callback.** fu
233e0 6e 63 74 69 6f 6e 20 58 20 74 6f 20 62 65 20 69  nction X to be i
233f0 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 61  nvoked periodica
23400 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 20  lly during long 
23410 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f  running calls to
23420 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  .** [sqlite3_exe
23430 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73  c()], [sqlite3_s
23440 74 65 70 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  tep()] and [sqli
23450 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d  te3_get_table()]
23460 20 66 6f 72 0a 2a 2a 20 64 61 74 61 62 61 73 65   for.** database
23470 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 20   connection D.  
23480 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 20 66  An example use f
23490 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72  or this.** inter
234a0 66 61 63 65 20 69 73 20 74 6f 20 6b 65 65 70 20  face is to keep 
234b0 61 20 47 55 49 20 75 70 64 61 74 65 64 20 64 75  a GUI updated du
234c0 72 69 6e 67 20 61 20 6c 61 72 67 65 20 71 75 65  ring a large que
234d0 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70  ry..**.** ^The p
234e0 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 70 61  arameter P is pa
234f0 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 20  ssed through as 
23500 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74  the only paramet
23510 65 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20 63 61  er to the .** ca
23520 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
23530 58 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74  X.  ^The paramet
23540 65 72 20 4e 20 69 73 20 74 68 65 20 6e 75 6d 62  er N is the numb
23550 65 72 20 6f 66 20 0a 2a 2a 20 5b 76 69 72 74 75  er of .** [virtu
23560 61 6c 20 6d 61 63 68 69 6e 65 20 69 6e 73 74 72  al machine instr
23570 75 63 74 69 6f 6e 73 5d 20 74 68 61 74 20 61 72  uctions] that ar
23580 65 20 65 76 61 6c 75 61 74 65 64 20 62 65 74 77  e evaluated betw
23590 65 65 6e 20 73 75 63 63 65 73 73 69 76 65 0a 2a  een successive.*
235a0 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66  * invocations of
235b0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 58 2e   the callback X.
235c0 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61 20 73  .**.** ^Only a s
235d0 69 6e 67 6c 65 20 70 72 6f 67 72 65 73 73 20 68  ingle progress h
235e0 61 6e 64 6c 65 72 20 6d 61 79 20 62 65 20 64 65  andler may be de
235f0 66 69 6e 65 64 20 61 74 20 6f 6e 65 20 74 69 6d  fined at one tim
23600 65 20 70 65 72 0a 2a 2a 20 5b 64 61 74 61 62 61  e per.** [databa
23610 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 3b 20  se connection]; 
23620 73 65 74 74 69 6e 67 20 61 20 6e 65 77 20 70 72  setting a new pr
23630 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63  ogress handler c
23640 61 6e 63 65 6c 73 20 74 68 65 0a 2a 2a 20 6f 6c  ancels the.** ol
23650 64 20 6f 6e 65 2e 20 20 5e 53 65 74 74 69 6e 67  d one.  ^Setting
23660 20 70 61 72 61 6d 65 74 65 72 20 58 20 74 6f 20   parameter X to 
23670 4e 55 4c 4c 20 64 69 73 61 62 6c 65 73 20 74 68  NULL disables th
23680 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  e progress handl
23690 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 70 72 6f 67  er..** ^The prog
236a0 72 65 73 73 20 68 61 6e 64 6c 65 72 20 69 73 20  ress handler is 
236b0 61 6c 73 6f 20 64 69 73 61 62 6c 65 64 20 62 79  also disabled by
236c0 20 73 65 74 74 69 6e 67 20 4e 20 74 6f 20 61 20   setting N to a 
236d0 76 61 6c 75 65 20 6c 65 73 73 0a 2a 2a 20 74 68  value less.** th
236e0 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  an 1..**.** ^If 
236f0 74 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c  the progress cal
23700 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f  lback returns no
23710 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65 72  n-zero, the oper
23720 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65  ation is.** inte
23730 72 72 75 70 74 65 64 2e 20 20 54 68 69 73 20 66  rrupted.  This f
23740 65 61 74 75 72 65 20 63 61 6e 20 62 65 20 75 73  eature can be us
23750 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  ed to implement 
23760 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62 75  a.** "Cancel" bu
23770 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70 72  tton on a GUI pr
23780 6f 67 72 65 73 73 20 64 69 61 6c 6f 67 20 62 6f  ogress dialog bo
23790 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f  x..**.** The pro
237a0 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61  gress handler ca
237b0 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20  llback must not 
237c0 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74  do anything that
237d0 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20   will modify.** 
237e0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
237f0 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76  nection that inv
23800 6f 6b 65 64 20 74 68 65 20 70 72 6f 67 72 65 73  oked the progres
23810 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f  s handler..** No
23820 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33  te that [sqlite3
23830 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
23840 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  nd [sqlite3_step
23850 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20  ()] both modify 
23860 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73  their.** databas
23870 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f  e connections fo
23880 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66  r the meaning of
23890 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69   "modify" in thi
238a0 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a  s paragraph..**.
238b0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  */.SQLITE_API vo
238c0 69 64 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72  id sqlite3_progr
238d0 65 73 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69  ess_handler(sqli
238e0 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a  te3*, int, int(*
238f0 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29  )(void*), void*)
23900 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
23910 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77  F: Opening A New
23920 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63   Database Connec
23930 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  tion.**.** ^Thes
23940 65 20 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20  e routines open 
23950 61 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 61  an SQLite databa
23960 73 65 20 66 69 6c 65 20 61 73 20 73 70 65 63 69  se file as speci
23970 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20  fied by the .** 
23980 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
23990 74 2e 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65  t. ^The filename
239a0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e 74   argument is int
239b0 65 72 70 72 65 74 65 64 20 61 73 20 55 54 46 2d  erpreted as UTF-
239c0 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  8 for.** sqlite3
239d0 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69  _open() and sqli
239e0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61 6e  te3_open_v2() an
239f0 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 74  d as UTF-16 in t
23a00 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 0a 2a  he native byte.*
23a10 2a 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69  * order for sqli
23a20 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20 5e 28  te3_open16(). ^(
23a30 41 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  A [database conn
23a40 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69  ection] handle i
23a50 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74  s usually.** ret
23a60 75 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c 20  urned in *ppDb, 
23a70 65 76 65 6e 20 69 66 20 61 6e 20 65 72 72 6f 72  even if an error
23a80 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20 6f 6e   occurs.  The on
23a90 6c 79 20 65 78 63 65 70 74 69 6f 6e 20 69 73 20  ly exception is 
23aa0 74 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74  that.** if SQLit
23ab0 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61  e is unable to a
23ac0 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74  llocate memory t
23ad0 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69  o hold the [sqli
23ae0 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20  te3] object,.** 
23af0 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77  a NULL will be w
23b00 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44  ritten into *ppD
23b10 62 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 70  b instead of a p
23b20 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ointer to the [s
23b30 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63  qlite3].** objec
23b40 74 2e 29 5e 20 5e 28 49 66 20 74 68 65 20 64 61  t.)^ ^(If the da
23b50 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
23b60 20 28 61 6e 64 2f 6f 72 20 63 72 65 61 74 65 64   (and/or created
23b70 29 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2c 20  ) successfully, 
23b80 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  then.** [SQLITE_
23b90 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  OK] is returned.
23ba0 20 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20 5b    Otherwise an [
23bb0 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72  error code] is r
23bc0 65 74 75 72 6e 65 64 2e 29 5e 20 5e 54 68 65 0a  eturned.)^ ^The.
23bd0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  ** [sqlite3_errm
23be0 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  sg()] or [sqlite
23bf0 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 72 6f  3_errmsg16()] ro
23c00 75 74 69 6e 65 73 20 63 61 6e 20 62 65 20 75 73  utines can be us
23c10 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20  ed to obtain.** 
23c20 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75  an English langu
23c30 61 67 65 20 64 65 73 63 72 69 70 74 69 6f 6e 20  age description 
23c40 6f 66 20 74 68 65 20 65 72 72 6f 72 20 66 6f 6c  of the error fol
23c50 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 75 72 65  lowing a failure
23c60 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68   of any.** of th
23c70 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  e sqlite3_open()
23c80 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a   routines..**.**
23c90 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e   ^The default en
23ca0 63 6f 64 69 6e 67 20 66 6f 72 20 74 68 65 20 64  coding for the d
23cb0 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20  atabase will be 
23cc0 55 54 46 2d 38 20 69 66 0a 2a 2a 20 73 71 6c 69  UTF-8 if.** sqli
23cd0 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71  te3_open() or sq
23ce0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
23cf0 69 73 20 63 61 6c 6c 65 64 20 61 6e 64 0a 2a 2a  is called and.**
23d00 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e   UTF-16 in the n
23d10 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
23d20 20 69 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   if sqlite3_open
23d30 31 36 28 29 20 69 73 20 75 73 65 64 2e 0a 2a 2a  16() is used..**
23d40 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f 72 20 6e  .** Whether or n
23d50 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75  ot an error occu
23d60 72 73 20 77 68 65 6e 20 69 74 20 69 73 20 6f 70  rs when it is op
23d70 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 65 73 0a  ened, resources.
23d80 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ** associated wi
23d90 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  th the [database
23da0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e   connection] han
23db0 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 72 65  dle should be re
23dc0 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20 70 61 73  leased by.** pas
23dd0 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69  sing it to [sqli
23de0 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65  te3_close()] whe
23df0 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65  n it is no longe
23e00 72 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a  r required..**.*
23e10 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 70  * The sqlite3_op
23e20 65 6e 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63  en_v2() interfac
23e30 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c  e works like sql
23e40 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65  ite3_open().** e
23e50 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61 63  xcept that it ac
23e60 63 65 70 74 73 20 74 77 6f 20 61 64 64 69 74 69  cepts two additi
23e70 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73 20  onal parameters 
23e80 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 63  for additional c
23e90 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74  ontrol.** over t
23ea0 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20  he new database 
23eb0 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28 54  connection.  ^(T
23ec0 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74  he flags paramet
23ed0 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  er to.** sqlite3
23ee0 5f 6f 70 65 6e 5f 76 32 28 29 20 63 61 6e 20 74  _open_v2() can t
23ef0 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68  ake one of.** th
23f00 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65  e following thre
23f10 65 20 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e  e values, option
23f20 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69  ally combined wi
23f30 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49  th the .** [SQLI
23f40 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d  TE_OPEN_NOMUTEX]
23f50 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46  , [SQLITE_OPEN_F
23f60 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49  ULLMUTEX], [SQLI
23f70 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
23f80 43 48 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  CHE],.** [SQLITE
23f90 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43  _OPEN_PRIVATECAC
23fa0 48 45 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53 51 4c  HE], and/or [SQL
23fb0 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c  ITE_OPEN_URI] fl
23fc0 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c  ags:)^.**.** <dl
23fd0 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49  >.** ^(<dt>[SQLI
23fe0 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
23ff0 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  ]</dt>.** <dd>Th
24000 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
24010 65 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c  ened in read-onl
24020 79 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20  y mode.  If the 
24030 64 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f  database does no
24040 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65 78 69  t.** already exi
24050 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20  st, an error is 
24060 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e  returned.</dd>)^
24070 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51  .**.** ^(<dt>[SQ
24080 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
24090 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ITE]</dt>.** <dd
240a0 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73  >The database is
240b0 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64   opened for read
240c0 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20  ing and writing 
240d0 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20  if possible, or 
240e0 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20  reading.** only 
240f0 69 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 77  if the file is w
24100 72 69 74 65 20 70 72 6f 74 65 63 74 65 64 20 62  rite protected b
24110 79 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  y the operating 
24120 73 79 73 74 65 6d 2e 20 20 49 6e 20 65 69 74 68  system.  In eith
24130 65 72 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 64  er.** case the d
24140 61 74 61 62 61 73 65 20 6d 75 73 74 20 61 6c 72  atabase must alr
24150 65 61 64 79 20 65 78 69 73 74 2c 20 6f 74 68 65  eady exist, othe
24160 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20 69  rwise an error i
24170 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e  s returned.</dd>
24180 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b  )^.**.** ^(<dt>[
24190 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
241a0 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45  WRITE] | [SQLITE
241b0 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64  _OPEN_CREATE]</d
241c0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61  t>.** <dd>The da
241d0 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
241e0 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64   for reading and
241f0 20 77 72 69 74 69 6e 67 2c 20 61 6e 64 20 69 73   writing, and is
24200 20 63 72 65 61 74 65 64 20 69 66 0a 2a 2a 20 69   created if.** i
24210 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61  t does not alrea
24220 64 79 20 65 78 69 73 74 2e 20 54 68 69 73 20 69  dy exist. This i
24230 73 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 74  s the behavior t
24240 68 61 74 20 69 73 20 61 6c 77 61 79 73 20 75 73  hat is always us
24250 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  ed for.** sqlite
24260 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c  3_open() and sql
24270 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f  ite3_open16().</
24280 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  dd>)^.** </dl>.*
24290 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20  *.** If the 3rd 
242a0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
242b0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
242c0 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65  s not one of the
242d0 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73  .** combinations
242e0 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f 70 74   shown above opt
242f0 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64  ionally combined
24300 20 77 69 74 68 20 6f 74 68 65 72 0a 2a 2a 20 5b   with other.** [
24310 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
24320 4f 4e 4c 59 20 7c 20 53 51 4c 49 54 45 5f 4f 50  ONLY | SQLITE_OP
24330 45 4e 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20 74 68  EN_* bits].** th
24340 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
24350 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
24360 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c  .** ^If the [SQL
24370 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58  ITE_OPEN_NOMUTEX
24380 5d 20 66 6c 61 67 20 69 73 20 73 65 74 2c 20 74  ] flag is set, t
24390 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
243a0 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f   connection.** o
243b0 70 65 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c 74  pens in the mult
243c0 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 64  i-thread [thread
243d0 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e  ing mode] as lon
243e0 67 20 61 73 20 74 68 65 20 73 69 6e 67 6c 65 2d  g as the single-
243f0 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68  thread.** mode h
24400 61 73 20 6e 6f 74 20 62 65 65 6e 20 73 65 74 20  as not been set 
24410 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  at compile-time 
24420 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 20 20  or start-time.  
24430 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ^If the.** [SQLI
24440 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45  TE_OPEN_FULLMUTE
24450 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20 74  X] flag is set t
24460 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
24470 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e   connection open
24480 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65 72 69  s.** in the seri
24490 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e  alized [threadin
244a0 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73  g mode] unless s
244b0 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 77 61 73  ingle-thread was
244c0 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73  .** previously s
244d0 65 6c 65 63 74 65 64 20 61 74 20 63 6f 6d 70 69  elected at compi
244e0 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74  le-time or start
244f0 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b  -time..** ^The [
24500 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52  SQLITE_OPEN_SHAR
24510 45 44 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61  EDCACHE] flag ca
24520 75 73 65 73 20 74 68 65 20 64 61 74 61 62 61 73  uses the databas
24530 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20  e connection to 
24540 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c 65 20 74  be.** eligible t
24550 6f 20 75 73 65 20 5b 73 68 61 72 65 64 20 63 61  o use [shared ca
24560 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65 67 61 72  che mode], regar
24570 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72  dless of whether
24580 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 0a 2a   or not shared.*
24590 2a 20 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c  * cache is enabl
245a0 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
245b0 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f  3_enable_shared_
245c0 63 61 63 68 65 28 29 5d 2e 20 20 5e 54 68 65 0a  cache()].  ^The.
245d0 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
245e0 50 52 49 56 41 54 45 43 41 43 48 45 5d 20 66 6c  PRIVATECACHE] fl
245f0 61 67 20 63 61 75 73 65 73 20 74 68 65 20 64 61  ag causes the da
24600 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
24610 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72 74  n to not.** part
24620 69 63 69 70 61 74 65 20 69 6e 20 5b 73 68 61 72  icipate in [shar
24630 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 20 65  ed cache mode] e
24640 76 65 6e 20 69 66 20 69 74 20 69 73 20 65 6e 61  ven if it is ena
24650 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  bled..**.** ^The
24660 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
24670 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  r to sqlite3_ope
24680 6e 5f 76 32 28 29 20 69 73 20 74 68 65 20 6e 61  n_v2() is the na
24690 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  me of the.** [sq
246a0 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
246b0 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 74  t that defines t
246c0 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  he operating sys
246d0 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68  tem interface th
246e0 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 61  at.** the new da
246f0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
24700 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 5e  n should use.  ^
24710 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  If the fourth pa
24720 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61 20  rameter is.** a 
24730 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65  NULL pointer the
24740 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73  n the default [s
24750 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
24760 63 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a  ct is used..**.*
24770 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61  * ^If the filena
24780 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22  me is ":memory:"
24790 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65  , then a private
247a0 2c 20 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d  , temporary in-m
247b0 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 0a 2a  emory database.*
247c0 2a 20 69 73 20 63 72 65 61 74 65 64 20 66 6f 72  * is created for
247d0 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e   the connection.
247e0 20 20 5e 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72    ^This in-memor
247f0 79 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20  y database will 
24800 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74  vanish when.** t
24810 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
24820 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64  ection is closed
24830 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f  .  Future versio
24840 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67  ns of SQLite mig
24850 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f  ht.** make use o
24860 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 70 65  f additional spe
24870 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74  cial filenames t
24880 68 61 74 20 62 65 67 69 6e 20 77 69 74 68 20 74  hat begin with t
24890 68 65 20 22 3a 22 20 63 68 61 72 61 63 74 65 72  he ":" character
248a0 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65 63 6f 6d  ..** It is recom
248b0 6d 65 6e 64 65 64 20 74 68 61 74 20 77 68 65 6e  mended that when
248c0 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65   a database file
248d0 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79 20 64 6f  name actually do
248e0 65 73 20 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a  es begin with.**
248f0 20 61 20 22 3a 22 20 63 68 61 72 61 63 74 65 72   a ":" character
24900 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 72 65 66   you should pref
24910 69 78 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  ix the filename 
24920 77 69 74 68 20 61 20 70 61 74 68 6e 61 6d 65 20  with a pathname 
24930 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20  such as.** "./" 
24940 74 6f 20 61 76 6f 69 64 20 61 6d 62 69 67 75 69  to avoid ambigui
24950 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ty..**.** ^If th
24960 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e  e filename is an
24970 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74   empty string, t
24980 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74  hen a private, t
24990 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64  emporary.** on-d
249a0 69 73 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c  isk database wil
249b0 6c 20 62 65 20 63 72 65 61 74 65 64 2e 20 20 5e  l be created.  ^
249c0 54 68 69 73 20 70 72 69 76 61 74 65 20 64 61 74  This private dat
249d0 61 62 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a  abase will be.**
249e0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64   automatically d
249f0 65 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61  eleted as soon a
24a00 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  s the database c
24a10 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f  onnection is clo
24a20 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49  sed..**.** [[URI
24a30 20 66 69 6c 65 6e 61 6d 65 73 20 69 6e 20 73 71   filenames in sq
24a40 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 5d 20 3c  lite3_open()]] <
24a50 68 33 3e 55 52 49 20 46 69 6c 65 6e 61 6d 65 73  h3>URI Filenames
24a60 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  </h3>.**.** ^If 
24a70 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 5d 20 69  [URI filename] i
24a80 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73  nterpretation is
24a90 20 65 6e 61 62 6c 65 64 2c 20 61 6e 64 20 74 68   enabled, and th
24aa0 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  e filename argum
24ab0 65 6e 74 0a 2a 2a 20 62 65 67 69 6e 73 20 77 69  ent.** begins wi
24ac0 74 68 20 22 66 69 6c 65 3a 22 2c 20 74 68 65 6e  th "file:", then
24ad0 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73   the filename is
24ae0 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
24af0 61 20 55 52 49 2e 20 5e 55 52 49 0a 2a 2a 20 66  a URI. ^URI.** f
24b00 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65  ilename interpre
24b10 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65  tation is enable
24b20 64 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45  d if the [SQLITE
24b30 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20  _OPEN_URI] flag 
24b40 69 73 0a 2a 2a 20 73 65 74 20 69 6e 20 74 68 65  is.** set in the
24b50 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
24b60 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
24b70 5f 76 32 28 29 2c 20 6f 72 20 69 66 20 69 74 20  _v2(), or if it 
24b80 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65 6e 61 62  has.** been enab
24b90 6c 65 64 20 67 6c 6f 62 61 6c 6c 79 20 75 73 69  led globally usi
24ba0 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43  ng the [SQLITE_C
24bb0 4f 4e 46 49 47 5f 55 52 49 5d 20 6f 70 74 69 6f  ONFIG_URI] optio
24bc0 6e 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 73  n with the.** [s
24bd0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
24be0 20 6d 65 74 68 6f 64 20 6f 72 20 62 79 20 74 68   method or by th
24bf0 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52  e [SQLITE_USE_UR
24c00 49 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  I] compile-time 
24c10 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 41 73 20 6f 66  option..** As of
24c20 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
24c30 33 2e 37 2e 37 2c 20 55 52 49 20 66 69 6c 65 6e  3.7.7, URI filen
24c40 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74 69  ame interpretati
24c50 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 66 66  on is turned off
24c60 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c 74 2c 20  .** by default, 
24c70 62 75 74 20 66 75 74 75 72 65 20 72 65 6c 65 61  but future relea
24c80 73 65 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69  ses of SQLite mi
24c90 67 68 74 20 65 6e 61 62 6c 65 20 55 52 49 20 66  ght enable URI f
24ca0 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74 65 72  ilename.** inter
24cb0 70 72 65 74 61 74 69 6f 6e 20 62 79 20 64 65 66  pretation by def
24cc0 61 75 6c 74 2e 20 20 53 65 65 20 22 5b 55 52 49  ault.  See "[URI
24cd0 20 66 69 6c 65 6e 61 6d 65 73 5d 22 20 66 6f 72   filenames]" for
24ce0 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69   additional.** i
24cf0 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
24d00 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20  * URI filenames 
24d10 61 72 65 20 70 61 72 73 65 64 20 61 63 63 6f 72  are parsed accor
24d20 64 69 6e 67 20 74 6f 20 52 46 43 20 33 39 38 36  ding to RFC 3986
24d30 2e 20 5e 49 66 20 74 68 65 20 55 52 49 20 63 6f  . ^If the URI co
24d40 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a 20 61 75 74  ntains an.** aut
24d50 68 6f 72 69 74 79 2c 20 74 68 65 6e 20 69 74 20  hority, then it 
24d60 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61  must be either a
24d70 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f  n empty string o
24d80 72 20 74 68 65 20 73 74 72 69 6e 67 20 0a 2a 2a  r the string .**
24d90 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2e 20 5e 49   "localhost". ^I
24da0 66 20 74 68 65 20 61 75 74 68 6f 72 69 74 79 20  f the authority 
24db0 69 73 20 6e 6f 74 20 61 6e 20 65 6d 70 74 79 20  is not an empty 
24dc0 73 74 72 69 6e 67 20 6f 72 20 22 6c 6f 63 61 6c  string or "local
24dd0 68 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a 20 65 72  host", an .** er
24de0 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 20  ror is returned 
24df0 74 6f 20 74 68 65 20 63 61 6c 6c 65 72 2e 20 5e  to the caller. ^
24e00 54 68 65 20 66 72 61 67 6d 65 6e 74 20 63 6f 6d  The fragment com
24e10 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 2c  ponent of a URI,
24e20 20 69 66 20 0a 2a 2a 20 70 72 65 73 65 6e 74 2c   if .** present,
24e30 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a   is ignored..**.
24e40 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20  ** ^SQLite uses 
24e50 74 68 65 20 70 61 74 68 20 63 6f 6d 70 6f 6e 65  the path compone
24e60 6e 74 20 6f 66 20 74 68 65 20 55 52 49 20 61 73  nt of the URI as
24e70 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
24e80 20 64 69 73 6b 20 66 69 6c 65 0a 2a 2a 20 77 68   disk file.** wh
24e90 69 63 68 20 63 6f 6e 74 61 69 6e 73 20 74 68 65  ich contains the
24ea0 20 64 61 74 61 62 61 73 65 2e 20 5e 49 66 20 74   database. ^If t
24eb0 68 65 20 70 61 74 68 20 62 65 67 69 6e 73 20 77  he path begins w
24ec0 69 74 68 20 61 20 27 2f 27 20 63 68 61 72 61 63  ith a '/' charac
24ed0 74 65 72 2c 20 0a 2a 2a 20 74 68 65 6e 20 69 74  ter, .** then it
24ee0 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20   is interpreted 
24ef0 61 73 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70  as an absolute p
24f00 61 74 68 2e 20 5e 49 66 20 74 68 65 20 70 61 74  ath. ^If the pat
24f10 68 20 64 6f 65 73 20 6e 6f 74 20 62 65 67 69 6e  h does not begin
24f20 20 0a 2a 2a 20 77 69 74 68 20 61 20 27 2f 27 20   .** with a '/' 
24f30 28 6d 65 61 6e 69 6e 67 20 74 68 61 74 20 74 68  (meaning that th
24f40 65 20 61 75 74 68 6f 72 69 74 79 20 73 65 63 74  e authority sect
24f50 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 20 66  ion is omitted f
24f60 72 6f 6d 20 74 68 65 20 55 52 49 29 0a 2a 2a 20  rom the URI).** 
24f70 74 68 65 6e 20 74 68 65 20 70 61 74 68 20 69 73  then the path is
24f80 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
24f90 61 20 72 65 6c 61 74 69 76 65 20 70 61 74 68 2e  a relative path.
24fa0 20 0a 2a 2a 20 5e 4f 6e 20 77 69 6e 64 6f 77 73   .** ^On windows
24fb0 2c 20 74 68 65 20 66 69 72 73 74 20 63 6f 6d 70  , the first comp
24fc0 6f 6e 65 6e 74 20 6f 66 20 61 6e 20 61 62 73 6f  onent of an abso
24fd0 6c 75 74 65 20 70 61 74 68 20 0a 2a 2a 20 69 73  lute path .** is
24fe0 20 61 20 64 72 69 76 65 20 73 70 65 63 69 66 69   a drive specifi
24ff0 63 61 74 69 6f 6e 20 28 65 2e 67 2e 20 22 43 3a  cation (e.g. "C:
25000 22 29 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72 65  ")..**.** [[core
25010 20 55 52 49 20 71 75 65 72 79 20 70 61 72 61 6d   URI query param
25020 65 74 65 72 73 5d 5d 0a 2a 2a 20 54 68 65 20 71  eters]].** The q
25030 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f  uery component o
25040 66 20 61 20 55 52 49 20 6d 61 79 20 63 6f 6e 74  f a URI may cont
25050 61 69 6e 20 70 61 72 61 6d 65 74 65 72 73 20 74  ain parameters t
25060 68 61 74 20 61 72 65 20 69 6e 74 65 72 70 72 65  hat are interpre
25070 74 65 64 0a 2a 2a 20 65 69 74 68 65 72 20 62 79  ted.** either by
25080 20 53 51 4c 69 74 65 20 69 74 73 65 6c 66 2c 20   SQLite itself, 
25090 6f 72 20 62 79 20 61 20 5b 56 46 53 20 7c 20 63  or by a [VFS | c
250a0 75 73 74 6f 6d 20 56 46 53 20 69 6d 70 6c 65 6d  ustom VFS implem
250b0 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 53 51  entation]..** SQ
250c0 4c 69 74 65 20 69 6e 74 65 72 70 72 65 74 73 20  Lite interprets 
250d0 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68  the following th
250e0 72 65 65 20 71 75 65 72 79 20 70 61 72 61 6d 65  ree query parame
250f0 74 65 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ters:.**.** <ul>
25100 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 76 66  .**   <li> <b>vf
25110 73 3c 2f 62 3e 3a 20 5e 54 68 65 20 22 76 66 73  s</b>: ^The "vfs
25120 22 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  " parameter may 
25130 62 65 20 75 73 65 64 20 74 6f 20 73 70 65 63 69  be used to speci
25140 66 79 20 74 68 65 20 6e 61 6d 65 20 6f 66 0a 2a  fy the name of.*
25150 2a 20 20 20 20 20 61 20 56 46 53 20 6f 62 6a 65  *     a VFS obje
25160 63 74 20 74 68 61 74 20 70 72 6f 76 69 64 65 73  ct that provides
25170 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73   the operating s
25180 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20  ystem interface 
25190 74 68 61 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 20  that should.**  
251a0 20 20 20 62 65 20 75 73 65 64 20 74 6f 20 61 63     be used to ac
251b0 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73  cess the databas
251c0 65 20 66 69 6c 65 20 6f 6e 20 64 69 73 6b 2e 20  e file on disk. 
251d0 5e 49 66 20 74 68 69 73 20 6f 70 74 69 6f 6e 20  ^If this option 
251e0 69 73 20 73 65 74 20 74 6f 0a 2a 2a 20 20 20 20  is set to.**    
251f0 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
25200 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 53   the default VFS
25210 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e   object is used.
25220 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e 20   ^Specifying an 
25230 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20 20 20 20 56  unknown.**     V
25240 46 53 20 69 73 20 61 6e 20 65 72 72 6f 72 2e 20  FS is an error. 
25250 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ^If sqlite3_open
25260 5f 76 32 28 29 20 69 73 20 75 73 65 64 20 61 6e  _v2() is used an
25270 64 20 74 68 65 20 76 66 73 20 6f 70 74 69 6f 6e  d the vfs option
25280 20 69 73 0a 2a 2a 20 20 20 20 20 70 72 65 73 65   is.**     prese
25290 6e 74 2c 20 74 68 65 6e 20 74 68 65 20 56 46 53  nt, then the VFS
252a0 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68   specified by th
252b0 65 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 70  e option takes p
252c0 72 65 63 65 64 65 6e 63 65 20 6f 76 65 72 0a 2a  recedence over.*
252d0 2a 20 20 20 20 20 74 68 65 20 76 61 6c 75 65 20  *     the value 
252e0 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66 6f  passed as the fo
252f0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
25300 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
25310 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69  2()..**.**   <li
25320 3e 20 3c 62 3e 6d 6f 64 65 3c 2f 62 3e 3a 20 5e  > <b>mode</b>: ^
25330 28 54 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65  (The mode parame
25340 74 65 72 20 6d 61 79 20 62 65 20 73 65 74 20 74  ter may be set t
25350 6f 20 65 69 74 68 65 72 20 22 72 6f 22 2c 20 22  o either "ro", "
25360 72 77 22 2c 0a 2a 2a 20 20 20 20 20 22 72 77 63  rw",.**     "rwc
25370 22 2c 20 6f 72 20 22 6d 65 6d 6f 72 79 22 2e 20  ", or "memory". 
25380 41 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 73 65  Attempting to se
25390 74 20 69 74 20 74 6f 20 61 6e 79 20 6f 74 68 65  t it to any othe
253a0 72 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 20 20  r value is.**   
253b0 20 20 61 6e 20 65 72 72 6f 72 29 5e 2e 20 0a 2a    an error)^. .*
253c0 2a 20 20 20 20 20 5e 49 66 20 22 72 6f 22 20 69  *     ^If "ro" i
253d0 73 20 73 70 65 63 69 66 69 65 64 2c 20 74 68 65  s specified, the
253e0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  n the database i
253f0 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61  s opened for rea
25400 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 20 20 20 61  d-only .**     a
25410 63 63 65 73 73 2c 20 6a 75 73 74 20 61 73 20 69  ccess, just as i
25420 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  f the [SQLITE_OP
25430 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20 66 6c 61  EN_READONLY] fla
25440 67 20 68 61 64 20 62 65 65 6e 20 73 65 74 20 69  g had been set i
25450 6e 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 74 68  n the .**     th
25460 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ird argument to 
25470 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
25480 29 2e 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20  ). ^If the mode 
25490 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f  option is set to
254a0 20 0a 2a 2a 20 20 20 20 20 22 72 77 22 2c 20 74   .**     "rw", t
254b0 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
254c0 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72   is opened for r
254d0 65 61 64 2d 77 72 69 74 65 20 28 62 75 74 20 6e  ead-write (but n
254e0 6f 74 20 63 72 65 61 74 65 29 20 0a 2a 2a 20 20  ot create) .**  
254f0 20 20 20 61 63 63 65 73 73 2c 20 61 73 20 69 66     access, as if
25500 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41   SQLITE_OPEN_REA
25510 44 57 52 49 54 45 20 28 62 75 74 20 6e 6f 74 20  DWRITE (but not 
25520 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
25530 54 45 29 20 68 61 64 20 0a 2a 2a 20 20 20 20 20  TE) had .**     
25540 62 65 65 6e 20 73 65 74 2e 20 5e 56 61 6c 75 65  been set. ^Value
25550 20 22 72 77 63 22 20 69 73 20 65 71 75 69 76 61   "rwc" is equiva
25560 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20  lent to setting 
25570 62 6f 74 68 20 0a 2a 2a 20 20 20 20 20 53 51 4c  both .**     SQL
25580 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
25590 54 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 4f 50  TE and SQLITE_OP
255a0 45 4e 5f 43 52 45 41 54 45 2e 20 20 5e 49 66 20  EN_CREATE.  ^If 
255b0 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20  the mode option 
255c0 69 73 0a 2a 2a 20 20 20 20 20 73 65 74 20 74 6f  is.**     set to
255d0 20 22 6d 65 6d 6f 72 79 22 20 74 68 65 6e 20 61   "memory" then a
255e0 20 70 75 72 65 20 5b 69 6e 2d 6d 65 6d 6f 72 79   pure [in-memory
255f0 20 64 61 74 61 62 61 73 65 5d 20 74 68 61 74 20   database] that 
25600 6e 65 76 65 72 20 72 65 61 64 73 0a 2a 2a 20 20  never reads.**  
25610 20 20 20 6f 72 20 77 72 69 74 65 73 20 66 72 6f     or writes fro
25620 6d 20 64 69 73 6b 20 69 73 20 75 73 65 64 2e 20  m disk is used. 
25630 5e 49 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20  ^It is an error 
25640 74 6f 20 73 70 65 63 69 66 79 20 61 20 76 61 6c  to specify a val
25650 75 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 74 68  ue for.**     th
25660 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72  e mode parameter
25670 20 74 68 61 74 20 69 73 20 6c 65 73 73 20 72 65   that is less re
25680 73 74 72 69 63 74 69 76 65 20 74 68 61 6e 20 74  strictive than t
25690 68 61 74 20 73 70 65 63 69 66 69 65 64 20 62 79  hat specified by
256a0 0a 2a 2a 20 20 20 20 20 74 68 65 20 66 6c 61 67  .**     the flag
256b0 73 20 70 61 73 73 65 64 20 69 6e 20 74 68 65 20  s passed in the 
256c0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
256d0 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
256e0 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c  v2()..**.**   <l
256f0 69 3e 20 3c 62 3e 63 61 63 68 65 3c 2f 62 3e 3a  i> <b>cache</b>:
25700 20 5e 54 68 65 20 63 61 63 68 65 20 70 61 72 61   ^The cache para
25710 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73 65 74  meter may be set
25720 20 74 6f 20 65 69 74 68 65 72 20 22 73 68 61 72   to either "shar
25730 65 64 22 20 6f 72 0a 2a 2a 20 20 20 20 20 22 70  ed" or.**     "p
25740 72 69 76 61 74 65 22 2e 20 5e 53 65 74 74 69 6e  rivate". ^Settin
25750 67 20 69 74 20 74 6f 20 22 73 68 61 72 65 64 22  g it to "shared"
25760 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74   is equivalent t
25770 6f 20 73 65 74 74 69 6e 67 20 74 68 65 0a 2a 2a  o setting the.**
25780 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e       SQLITE_OPEN
25790 5f 53 48 41 52 45 44 43 41 43 48 45 20 62 69 74  _SHAREDCACHE bit
257a0 20 69 6e 20 74 68 65 20 66 6c 61 67 73 20 61 72   in the flags ar
257b0 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 74 6f  gument passed to
257c0 0a 2a 2a 20 20 20 20 20 73 71 6c 69 74 65 33 5f  .**     sqlite3_
257d0 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 53 65 74 74  open_v2(). ^Sett
257e0 69 6e 67 20 74 68 65 20 63 61 63 68 65 20 70 61  ing the cache pa
257f0 72 61 6d 65 74 65 72 20 74 6f 20 22 70 72 69 76  rameter to "priv
25800 61 74 65 22 20 69 73 20 0a 2a 2a 20 20 20 20 20  ate" is .**     
25810 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65  equivalent to se
25820 74 74 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45  tting the SQLITE
25830 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43  _OPEN_PRIVATECAC
25840 48 45 20 62 69 74 2e 0a 2a 2a 20 20 20 20 20 5e  HE bit..**     ^
25850 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  If sqlite3_open_
25860 76 32 28 29 20 69 73 20 75 73 65 64 20 61 6e 64  v2() is used and
25870 20 74 68 65 20 22 63 61 63 68 65 22 20 70 61 72   the "cache" par
25880 61 6d 65 74 65 72 20 69 73 20 70 72 65 73 65 6e  ameter is presen
25890 74 20 69 6e 0a 2a 2a 20 20 20 20 20 61 20 55 52  t in.**     a UR
258a0 49 20 66 69 6c 65 6e 61 6d 65 2c 20 69 74 73 20  I filename, its 
258b0 76 61 6c 75 65 20 6f 76 65 72 72 69 64 65 73 20  value overrides 
258c0 61 6e 79 20 62 65 68 61 76 69 6f 75 72 20 72 65  any behaviour re
258d0 71 75 65 73 74 65 64 20 62 79 20 73 65 74 74 69  quested by setti
258e0 6e 67 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45  ng.**     SQLITE
258f0 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43  _OPEN_PRIVATECAC
25900 48 45 20 6f 72 20 53 51 4c 49 54 45 5f 4f 50 45  HE or SQLITE_OPE
25910 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 66 6c  N_SHAREDCACHE fl
25920 61 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  ag..** </ul>.**.
25930 2a 2a 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61  ** ^Specifying a
25940 6e 20 75 6e 6b 6e 6f 77 6e 20 70 61 72 61 6d 65  n unknown parame
25950 74 65 72 20 69 6e 20 74 68 65 20 71 75 65 72 79  ter in the query
25960 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20   component of a 
25970 55 52 49 20 69 73 20 6e 6f 74 20 61 6e 0a 2a 2a  URI is not an.**
25980 20 65 72 72 6f 72 2e 20 20 46 75 74 75 72 65 20   error.  Future 
25990 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
259a0 74 65 20 6d 69 67 68 74 20 75 6e 64 65 72 73 74  te might underst
259b0 61 6e 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 71  and additional q
259c0 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65  uery.** paramete
259d0 72 73 2e 20 20 53 65 65 20 22 5b 71 75 65 72 79  rs.  See "[query
259e0 20 70 61 72 61 6d 65 74 65 72 73 20 77 69 74 68   parameters with
259f0 20 73 70 65 63 69 61 6c 20 6d 65 61 6e 69 6e 67   special meaning
25a00 20 74 6f 20 53 51 4c 69 74 65 5d 22 20 66 6f 72   to SQLite]" for
25a10 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 69  .** additional i
25a20 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
25a30 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65  * [[URI filename
25a40 20 65 78 61 6d 70 6c 65 73 5d 5d 20 3c 68 33 3e   examples]] <h3>
25a50 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61  URI filename exa
25a60 6d 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a  mples</h3>.**.**
25a70 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22   <table border="
25a80 31 22 20 61 6c 69 67 6e 3d 63 65 6e 74 65 72 20  1" align=center 
25a90 63 65 6c 6c 70 61 64 64 69 6e 67 3d 35 3e 0a 2a  cellpadding=5>.*
25aa0 2a 20 3c 74 72 3e 3c 74 68 3e 20 55 52 49 20 66  * <tr><th> URI f
25ab0 69 6c 65 6e 61 6d 65 73 20 3c 74 68 3e 20 52 65  ilenames <th> Re
25ac0 73 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64  sults.** <tr><td
25ad0 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 20 3c  > file:data.db <
25ae0 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  td> .**         
25af0 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22   Open the file "
25b00 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20  data.db" in the 
25b10 63 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72  current director
25b20 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66  y..** <tr><td> f
25b30 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  ile:/home/fred/d
25b40 61 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a 20 20 20  ata.db<br>.**   
25b50 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 68         file:///h
25b60 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
25b70 20 3c 62 72 3e 20 0a 2a 2a 20 20 20 20 20 20 20   <br> .**       
25b80 20 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63 61 6c 68     file://localh
25b90 6f 73 74 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61  ost/home/fred/da
25ba0 74 61 2e 64 62 20 3c 62 72 3e 20 3c 74 64 3e 20  ta.db <br> <td> 
25bb0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65  .**          Ope
25bc0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  n the database f
25bd0 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f  ile "/home/fred/
25be0 64 61 74 61 2e 64 62 22 2e 0a 2a 2a 20 3c 74 72  data.db"..** <tr
25bf0 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f 64 61 72  ><td> file://dar
25c00 6b 73 74 61 72 2f 68 6f 6d 65 2f 66 72 65 64 2f  kstar/home/fred/
25c10 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a  data.db <td> .**
25c20 20 20 20 20 20 20 20 20 20 20 41 6e 20 65 72 72            An err
25c30 6f 72 2e 20 22 64 61 72 6b 73 74 61 72 22 20 69  or. "darkstar" i
25c40 73 20 6e 6f 74 20 61 20 72 65 63 6f 67 6e 69 7a  s not a recogniz
25c50 65 64 20 61 75 74 68 6f 72 69 74 79 2e 0a 2a 2a  ed authority..**
25c60 20 3c 74 72 3e 3c 74 64 20 73 74 79 6c 65 3d 22   <tr><td style="
25c70 77 68 69 74 65 2d 73 70 61 63 65 3a 6e 6f 77 72  white-space:nowr
25c80 61 70 22 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  ap"> .**        
25c90 20 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f 63    file:///C:/Doc
25ca0 75 6d 65 6e 74 73 25 32 30 61 6e 64 25 32 30 53  uments%20and%20S
25cb0 65 74 74 69 6e 67 73 2f 66 72 65 64 2f 44 65 73  ettings/fred/Des
25cc0 6b 74 6f 70 2f 64 61 74 61 2e 64 62 0a 2a 2a 20  ktop/data.db.** 
25cd0 20 20 20 20 3c 74 64 3e 20 57 69 6e 64 6f 77 73      <td> Windows
25ce0 20 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74 68 65 20   only: Open the 
25cf0 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 6f  file "data.db" o
25d00 6e 20 66 72 65 64 27 73 20 64 65 73 6b 74 6f 70  n fred's desktop
25d10 20 6f 6e 20 64 72 69 76 65 0a 2a 2a 20 20 20 20   on drive.**    
25d20 20 20 20 20 20 20 43 3a 2e 20 4e 6f 74 65 20 74        C:. Note t
25d30 68 61 74 20 74 68 65 20 25 32 30 20 65 73 63 61  hat the %20 esca
25d40 70 69 6e 67 20 69 6e 20 74 68 69 73 20 65 78 61  ping in this exa
25d50 6d 70 6c 65 20 69 73 20 6e 6f 74 20 73 74 72 69  mple is not stri
25d60 63 74 6c 79 20 0a 2a 2a 20 20 20 20 20 20 20 20  ctly .**        
25d70 20 20 6e 65 63 65 73 73 61 72 79 20 2d 20 73 70    necessary - sp
25d80 61 63 65 20 63 68 61 72 61 63 74 65 72 73 20 63  ace characters c
25d90 61 6e 20 62 65 20 75 73 65 64 20 6c 69 74 65 72  an be used liter
25da0 61 6c 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20  ally.**         
25db0 20 69 6e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65   in URI filename
25dc0 73 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66  s..** <tr><td> f
25dd0 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65  ile:data.db?mode
25de0 3d 72 6f 26 63 61 63 68 65 3d 70 72 69 76 61 74  =ro&cache=privat
25df0 65 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20  e <td> .**      
25e00 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 64      Open file "d
25e10 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63  ata.db" in the c
25e20 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79  urrent directory
25e30 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 61   for read-only a
25e40 63 63 65 73 73 2e 0a 2a 2a 20 20 20 20 20 20 20  ccess..**       
25e50 20 20 20 52 65 67 61 72 64 6c 65 73 73 20 6f 66     Regardless of
25e60 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
25e70 73 68 61 72 65 64 2d 63 61 63 68 65 20 6d 6f 64  shared-cache mod
25e80 65 20 69 73 20 65 6e 61 62 6c 65 64 20 62 79 0a  e is enabled by.
25e90 2a 2a 20 20 20 20 20 20 20 20 20 20 64 65 66 61  **          defa
25ea0 75 6c 74 2c 20 75 73 65 20 61 20 70 72 69 76 61  ult, use a priva
25eb0 74 65 20 63 61 63 68 65 2e 0a 2a 2a 20 3c 74 72  te cache..** <tr
25ec0 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65  ><td> file:/home
25ed0 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3f 76 66  /fred/data.db?vf
25ee0 73 3d 75 6e 69 78 2d 6e 6f 6c 6f 63 6b 20 3c 74  s=unix-nolock <t
25ef0 64 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f  d>.**          O
25f00 70 65 6e 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f  pen file "/home/
25f10 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 20 55  fred/data.db". U
25f20 73 65 20 74 68 65 20 73 70 65 63 69 61 6c 20 56  se the special V
25f30 46 53 20 22 75 6e 69 78 2d 6e 6f 6c 6f 63 6b 22  FS "unix-nolock"
25f40 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  ..** <tr><td> fi
25f50 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d  le:data.db?mode=
25f60 72 65 61 64 6f 6e 6c 79 20 3c 74 64 3e 20 0a 2a  readonly <td> .*
25f70 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20 65 72  *          An er
25f80 72 6f 72 2e 20 22 72 65 61 64 6f 6e 6c 79 22 20  ror. "readonly" 
25f90 69 73 20 6e 6f 74 20 61 20 76 61 6c 69 64 20 6f  is not a valid o
25fa0 70 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 22 6d  ption for the "m
25fb0 6f 64 65 22 20 70 61 72 61 6d 65 74 65 72 2e 0a  ode" parameter..
25fc0 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 0a 2a  ** </table>.**.*
25fd0 2a 20 5e 55 52 49 20 68 65 78 61 64 65 63 69 6d  * ^URI hexadecim
25fe0 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e  al escape sequen
25ff0 63 65 73 20 28 25 48 48 29 20 61 72 65 20 73 75  ces (%HH) are su
26000 70 70 6f 72 74 65 64 20 77 69 74 68 69 6e 20 74  pported within t
26010 68 65 20 70 61 74 68 20 61 6e 64 0a 2a 2a 20 71  he path and.** q
26020 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20  uery components 
26030 6f 66 20 61 20 55 52 49 2e 20 41 20 68 65 78 61  of a URI. A hexa
26040 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73  decimal escape s
26050 65 71 75 65 6e 63 65 20 63 6f 6e 73 69 73 74 73  equence consists
26060 20 6f 66 20 61 0a 2a 2a 20 70 65 72 63 65 6e 74   of a.** percent
26070 20 73 69 67 6e 20 2d 20 22 25 22 20 2d 20 66 6f   sign - "%" - fo
26080 6c 6c 6f 77 65 64 20 62 79 20 65 78 61 63 74 6c  llowed by exactl
26090 79 20 74 77 6f 20 68 65 78 61 64 65 63 69 6d 61  y two hexadecima
260a0 6c 20 64 69 67 69 74 73 20 0a 2a 2a 20 73 70 65  l digits .** spe
260b0 63 69 66 79 69 6e 67 20 61 6e 20 6f 63 74 65 74  cifying an octet
260c0 20 76 61 6c 75 65 2e 20 5e 42 65 66 6f 72 65 20   value. ^Before 
260d0 74 68 65 20 70 61 74 68 20 6f 72 20 71 75 65 72  the path or quer
260e0 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20  y components of 
260f0 61 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d  a.** URI filenam
26100 65 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65  e are interprete
26110 64 2c 20 74 68 65 79 20 61 72 65 20 65 6e 63 6f  d, they are enco
26120 64 65 64 20 75 73 69 6e 67 20 55 54 46 2d 38 20  ded using UTF-8 
26130 61 6e 64 20 61 6c 6c 20 0a 2a 2a 20 68 65 78 61  and all .** hexa
26140 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73  decimal escape s
26150 65 71 75 65 6e 63 65 73 20 72 65 70 6c 61 63 65  equences replace
26160 64 20 62 79 20 61 20 73 69 6e 67 6c 65 20 62 79  d by a single by
26170 74 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  te containing th
26180 65 0a 2a 2a 20 63 6f 72 72 65 73 70 6f 6e 64 69  e.** correspondi
26190 6e 67 20 6f 63 74 65 74 2e 20 49 66 20 74 68 69  ng octet. If thi
261a0 73 20 70 72 6f 63 65 73 73 20 67 65 6e 65 72 61  s process genera
261b0 74 65 73 20 61 6e 20 69 6e 76 61 6c 69 64 20 55  tes an invalid U
261c0 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 2c 0a 2a  TF-8 encoding,.*
261d0 2a 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  * the results ar
261e0 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  e undefined..**.
261f0 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69  ** <b>Note to Wi
26200 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e  ndows users:</b>
26210 20 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 20 75    The encoding u
26220 73 65 64 20 66 6f 72 20 74 68 65 20 66 69 6c 65  sed for the file
26230 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  name argument.**
26240 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   of sqlite3_open
26250 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f  () and sqlite3_o
26260 70 65 6e 5f 76 32 28 29 20 6d 75 73 74 20 62 65  pen_v2() must be
26270 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74   UTF-8, not what
26280 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65  ever.** codepage
26290 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 64 65   is currently de
262a0 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65  fined.  Filename
262b0 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74  s containing int
262c0 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68  ernational.** ch
262d0 61 72 61 63 74 65 72 73 20 6d 75 73 74 20 62 65  aracters must be
262e0 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 55 54   converted to UT
262f0 46 2d 38 20 70 72 69 6f 72 20 74 6f 20 70 61 73  F-8 prior to pas
26300 73 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a  sing them into.*
26310 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  * sqlite3_open()
26320 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   or sqlite3_open
26330 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e  _v2()..**.** <b>
26340 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20  Note to Windows 
26350 52 75 6e 74 69 6d 65 20 75 73 65 72 73 3a 3c 2f  Runtime users:</
26360 62 3e 20 20 54 68 65 20 74 65 6d 70 6f 72 61 72  b>  The temporar
26370 79 20 64 69 72 65 63 74 6f 72 79 20 6d 75 73 74  y directory must
26380 20 62 65 20 73 65 74 0a 2a 2a 20 70 72 69 6f 72   be set.** prior
26390 20 74 6f 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69   to calling sqli
263a0 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71  te3_open() or sq
263b0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
263c0 20 20 4f 74 68 65 72 77 69 73 65 2c 20 76 61 72    Otherwise, var
263d0 69 6f 75 73 0a 2a 2a 20 66 65 61 74 75 72 65 73  ious.** features
263e0 20 74 68 61 74 20 72 65 71 75 69 72 65 20 74 68   that require th
263f0 65 20 75 73 65 20 6f 66 20 74 65 6d 70 6f 72 61  e use of tempora
26400 72 79 20 66 69 6c 65 73 20 6d 61 79 20 66 61 69  ry files may fai
26410 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  l..**.** See als
26420 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 74 65 6d 70  o: [sqlite3_temp
26430 5f 64 69 72 65 63 74 6f 72 79 5d 0a 2a 2f 0a 53  _directory].*/.S
26440 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
26450 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f  lite3_open(.  co
26460 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61  nst char *filena
26470 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73  me,   /* Databas
26480 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d  e filename (UTF-
26490 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20  8) */.  sqlite3 
264a0 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20  **ppDb          
264b0 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64  /* OUT: SQLite d
264c0 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 53  b handle */.);.S
264d0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
264e0 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20  lite3_open16(.  
264f0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c 65  const void *file
26500 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62  name,   /* Datab
26510 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54  ase filename (UT
26520 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74  F-16) */.  sqlit
26530 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20  e3 **ppDb       
26540 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74     /* OUT: SQLit
26550 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29  e db handle */.)
26560 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
26570 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
26580 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  (.  const char *
26590 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44  filename,   /* D
265a0 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
265b0 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71   (UTF-8) */.  sq
265c0 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 20  lite3 **ppDb,   
265d0 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51        /* OUT: SQ
265e0 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a  Lite db handle *
265f0 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 20  /.  int flags,  
26600 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46              /* F
26610 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  lags */.  const 
26620 63 68 61 72 20 2a 7a 56 66 73 20 20 20 20 20 20  char *zVfs      
26630 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53    /* Name of VFS
26640 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 2a   module to use *
26650 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.);../*.** CAPI
26660 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 56 61 6c  3REF: Obtain Val
26670 75 65 73 20 46 6f 72 20 55 52 49 20 50 61 72 61  ues For URI Para
26680 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65  meters.**.** The
26690 73 65 20 61 72 65 20 75 74 69 6c 69 74 79 20 72  se are utility r
266a0 6f 75 74 69 6e 65 73 2c 20 75 73 65 66 75 6c 20  outines, useful 
266b0 74 6f 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  to VFS implement
266c0 61 74 69 6f 6e 73 2c 20 74 68 61 74 20 63 68 65  ations, that che
266d0 63 6b 0a 2a 2a 20 74 6f 20 73 65 65 20 69 66 20  ck.** to see if 
266e0 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  a database file 
266f0 77 61 73 20 61 20 55 52 49 20 74 68 61 74 20 63  was a URI that c
26700 6f 6e 74 61 69 6e 65 64 20 61 20 73 70 65 63 69  ontained a speci
26710 66 69 63 20 71 75 65 72 79 20 0a 2a 2a 20 70 61  fic query .** pa
26720 72 61 6d 65 74 65 72 2c 20 61 6e 64 20 69 66 20  rameter, and if 
26730 73 6f 20 6f 62 74 61 69 6e 73 20 74 68 65 20 76  so obtains the v
26740 61 6c 75 65 20 6f 66 20 74 68 61 74 20 71 75 65  alue of that que
26750 72 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  ry parameter..**
26760 0a 2a 2a 20 49 66 20 46 20 69 73 20 74 68 65 20  .** If F is the 
26770 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  database filenam
26780 65 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64  e pointer passed
26790 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 28   into the xOpen(
267a0 29 20 6d 65 74 68 6f 64 20 6f 66 20 0a 2a 2a 20  ) method of .** 
267b0 61 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  a VFS implementa
267c0 74 69 6f 6e 20 77 68 65 6e 20 74 68 65 20 66 6c  tion when the fl
267d0 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ags parameter to
267e0 20 78 4f 70 65 6e 28 29 20 68 61 73 20 6f 6e 65   xOpen() has one
267f0 20 6f 72 20 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20   or .** more of 
26800 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  the [SQLITE_OPEN
26810 5f 55 52 49 5d 20 6f 72 20 5b 53 51 4c 49 54 45  _URI] or [SQLITE
26820 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 20 62  _OPEN_MAIN_DB] b
26830 69 74 73 20 73 65 74 20 61 6e 64 0a 2a 2a 20 50  its set and.** P
26840 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
26850 74 68 65 20 71 75 65 72 79 20 70 61 72 61 6d 65  the query parame
26860 74 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c  ter, then.** sql
26870 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74  ite3_uri_paramet
26880 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20  er(F,P) returns 
26890 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65  the value of the
268a0 20 50 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20   P.** parameter 
268b0 69 66 20 69 74 20 65 78 69 73 74 73 20 6f 72 20  if it exists or 
268c0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  a NULL pointer i
268d0 66 20 50 20 64 6f 65 73 20 6e 6f 74 20 61 70 70  f P does not app
268e0 65 61 72 20 61 73 20 61 20 0a 2a 2a 20 71 75 65  ear as a .** que
268f0 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20  ry parameter on 
26900 46 2e 20 20 49 66 20 50 20 69 73 20 61 20 71 75  F.  If P is a qu
26910 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f 66  ery parameter of
26920 20 46 0a 2a 2a 20 68 61 73 20 6e 6f 20 65 78 70   F.** has no exp
26930 6c 69 63 69 74 20 76 61 6c 75 65 2c 20 74 68 65  licit value, the
26940 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61  n sqlite3_uri_pa
26950 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74  rameter(F,P) ret
26960 75 72 6e 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65  urns.** a pointe
26970 72 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74  r to an empty st
26980 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ring..**.** The 
26990 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c  sqlite3_uri_bool
269a0 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69  ean(F,P,B) routi
269b0 6e 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20  ne assumes that 
269c0 50 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 0a 2a  P is a boolean.*
269d0 2a 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20  * parameter and 
269e0 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 31 29  returns true (1)
269f0 20 6f 72 20 66 61 6c 73 65 20 28 30 29 20 61 63   or false (0) ac
26a00 63 6f 72 64 69 6e 67 20 74 6f 20 74 68 65 20 76  cording to the v
26a10 61 6c 75 65 0a 2a 2a 20 6f 66 20 50 2e 20 20 54  alue.** of P.  T
26a20 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  he sqlite3_uri_b
26a30 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f  oolean(F,P,B) ro
26a40 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 72  utine returns tr
26a50 75 65 20 28 31 29 20 69 66 20 74 68 65 0a 2a 2a  ue (1) if the.**
26a60 20 76 61 6c 75 65 20 6f 66 20 71 75 65 72 79 20   value of query 
26a70 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f  parameter P is o
26a80 6e 65 20 6f 66 20 22 79 65 73 22 2c 20 22 74 72  ne of "yes", "tr
26a90 75 65 22 2c 20 6f 72 20 22 6f 6e 22 20 69 6e 20  ue", or "on" in 
26aa0 61 6e 79 0a 2a 2a 20 63 61 73 65 20 6f 72 20 69  any.** case or i
26ab0 66 20 74 68 65 20 76 61 6c 75 65 20 62 65 67 69  f the value begi
26ac0 6e 73 20 77 69 74 68 20 61 20 6e 6f 6e 2d 7a 65  ns with a non-ze
26ad0 72 6f 20 6e 75 6d 62 65 72 2e 20 20 54 68 65 20  ro number.  The 
26ae0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  .** sqlite3_uri_
26af0 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72  boolean(F,P,B) r
26b00 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 73 20  outines returns 
26b10 66 61 6c 73 65 20 28 30 29 20 69 66 20 74 68 65  false (0) if the
26b20 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 71 75 65   value of.** que
26b30 72 79 20 70 61 72 61 6d 65 74 65 72 20 50 20 69  ry parameter P i
26b40 73 20 6f 6e 65 20 6f 66 20 22 6e 6f 22 2c 20 22  s one of "no", "
26b50 66 61 6c 73 65 22 2c 20 6f 72 20 22 6f 66 66 22  false", or "off"
26b60 20 69 6e 20 61 6e 79 20 63 61 73 65 20 6f 72 0a   in any case or.
26b70 2a 2a 20 69 66 20 74 68 65 20 76 61 6c 75 65 20  ** if the value 
26b80 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e 75  begins with a nu
26b90 6d 65 72 69 63 20 7a 65 72 6f 2e 20 20 49 66 20  meric zero.  If 
26ba0 50 20 69 73 20 6e 6f 74 20 61 20 71 75 65 72 79  P is not a query
26bb0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 6e  .** parameter on
26bc0 20 46 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c   F or if the val
26bd0 75 65 20 6f 66 20 50 20 69 73 20 64 6f 65 73 20  ue of P is does 
26be0 6e 6f 74 20 6d 61 74 63 68 20 61 6e 79 20 6f 66  not match any of
26bf0 20 74 68 65 0a 2a 2a 20 61 62 6f 76 65 2c 20 74   the.** above, t
26c00 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  hen sqlite3_uri_
26c10 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72  boolean(F,P,B) r
26c20 65 74 75 72 6e 73 20 28 42 21 3d 30 29 2e 0a 2a  eturns (B!=0)..*
26c30 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
26c40 5f 75 72 69 5f 69 6e 74 36 34 28 46 2c 50 2c 44  _uri_int64(F,P,D
26c50 29 20 72 6f 75 74 69 6e 65 20 63 6f 6e 76 65 72  ) routine conver
26c60 74 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  ts the value of 
26c70 50 20 69 6e 74 6f 20 61 0a 2a 2a 20 36 34 2d 62  P into a.** 64-b
26c80 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65  it signed intege
26c90 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 74 68  r and returns th
26ca0 61 74 20 69 6e 74 65 67 65 72 2c 20 6f 72 20 44  at integer, or D
26cb0 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 0a 2a   if P does not.*
26cc0 2a 20 65 78 69 73 74 2e 20 20 49 66 20 74 68 65  * exist.  If the
26cd0 20 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20 73   value of P is s
26ce0 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74  omething other t
26cf0 68 61 6e 20 61 6e 20 69 6e 74 65 67 65 72 2c 20  han an integer, 
26d00 74 68 65 6e 0a 2a 2a 20 7a 65 72 6f 20 69 73 20  then.** zero is 
26d10 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a  returned..** .**
26d20 20 49 66 20 46 20 69 73 20 61 20 4e 55 4c 4c 20   If F is a NULL 
26d30 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 73 71  pointer, then sq
26d40 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65  lite3_uri_parame
26d50 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73  ter(F,P) returns
26d60 20 4e 55 4c 4c 20 61 6e 64 0a 2a 2a 20 73 71 6c   NULL and.** sql
26d70 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e  ite3_uri_boolean
26d80 28 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20  (F,P,B) returns 
26d90 42 2e 20 20 49 66 20 46 20 69 73 20 6e 6f 74 20  B.  If F is not 
26da0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61  a NULL pointer a
26db0 6e 64 0a 2a 2a 20 69 73 20 6e 6f 74 20 61 20 64  nd.** is not a d
26dc0 61 74 61 62 61 73 65 20 66 69 6c 65 20 70 61 74  atabase file pat
26dd0 68 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 74 68  hname pointer th
26de0 61 74 20 53 51 4c 69 74 65 20 70 61 73 73 65 64  at SQLite passed
26df0 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 0a   into the xOpen.
26e00 2a 2a 20 56 46 53 20 6d 65 74 68 6f 64 2c 20 74  ** VFS method, t
26e10 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
26e20 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65   of this routine
26e30 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e   is undefined an
26e40 64 20 70 72 6f 62 61 62 6c 79 0a 2a 2a 20 75 6e  d probably.** un
26e50 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2f 0a 53 51  desirable..*/.SQ
26e60 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63  LITE_API const c
26e70 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 75 72 69  har *sqlite3_uri
26e80 5f 70 61 72 61 6d 65 74 65 72 28 63 6f 6e 73 74  _parameter(const
26e90 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65   char *zFilename
26ea0 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50  , const char *zP
26eb0 61 72 61 6d 29 3b 0a 53 51 4c 49 54 45 5f 41 50  aram);.SQLITE_AP
26ec0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 75 72  I int sqlite3_ur
26ed0 69 5f 62 6f 6f 6c 65 61 6e 28 63 6f 6e 73 74 20  i_boolean(const 
26ee0 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20 63 6f 6e  char *zFile, con
26ef0 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61 6d 2c  st char *zParam,
26f00 20 69 6e 74 20 62 44 65 66 61 75 6c 74 29 3b 0a   int bDefault);.
26f10 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74  SQLITE_API sqlit
26f20 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
26f30 5f 75 72 69 5f 69 6e 74 36 34 28 63 6f 6e 73 74  _uri_int64(const
26f40 20 63 68 61 72 2a 2c 20 63 6f 6e 73 74 20 63 68   char*, const ch
26f50 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  ar*, sqlite3_int
26f60 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  64);.../*.** CAP
26f70 49 33 52 45 46 3a 20 45 72 72 6f 72 20 43 6f 64  I3REF: Error Cod
26f80 65 73 20 41 6e 64 20 4d 65 73 73 61 67 65 73 0a  es And Messages.
26f90 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
26fa0 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69 6e 74  e3_errcode() int
26fb0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
26fc0 68 65 20 6e 75 6d 65 72 69 63 20 5b 72 65 73 75  he numeric [resu
26fd0 6c 74 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b  lt code] or.** [
26fe0 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
26ff0 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f  code] for the mo
27000 73 74 20 72 65 63 65 6e 74 20 66 61 69 6c 65 64  st recent failed
27010 20 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63   sqlite3_* API c
27020 61 6c 6c 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65  all.** associate
27030 64 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 61  d with a [databa
27040 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20  se connection]. 
27050 49 66 20 61 20 70 72 69 6f 72 20 41 50 49 20 63  If a prior API c
27060 61 6c 6c 20 66 61 69 6c 65 64 0a 2a 2a 20 62 75  all failed.** bu
27070 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  t the most recen
27080 74 20 41 50 49 20 63 61 6c 6c 20 73 75 63 63 65  t API call succe
27090 65 64 65 64 2c 20 74 68 65 20 72 65 74 75 72 6e  eded, the return
270a0 20 76 61 6c 75 65 20 66 72 6f 6d 0a 2a 2a 20 73   value from.** s
270b0 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
270c0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20   is undefined.  
270d0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74  ^The sqlite3_ext
270e0 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 0a  ended_errcode().
270f0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  ** interface is 
27100 74 68 65 20 73 61 6d 65 20 65 78 63 65 70 74 20  the same except 
27110 74 68 61 74 20 69 74 20 61 6c 77 61 79 73 20 72  that it always r
27120 65 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b  eturns the .** [
27130 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
27140 63 6f 64 65 5d 20 65 76 65 6e 20 77 68 65 6e 20  code] even when 
27150 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
27160 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64 69 73  codes are.** dis
27170 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  abled..**.** ^Th
27180 65 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67  e sqlite3_errmsg
27190 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 65  () and sqlite3_e
271a0 72 72 6d 73 67 31 36 28 29 20 72 65 74 75 72 6e  rrmsg16() return
271b0 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67   English-languag
271c0 65 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20 64  e.** text that d
271d0 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72  escribes the err
271e0 6f 72 2c 20 61 73 20 65 69 74 68 65 72 20 55 54  or, as either UT
271f0 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72 65  F-8 or UTF-16 re
27200 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e  spectively..** ^
27210 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20  (Memory to hold 
27220 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
27230 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61  e string is mana
27240 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a  ged internally..
27250 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
27260 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  on does not need
27270 20 74 6f 20 77 6f 72 72 79 20 61 62 6f 75 74 20   to worry about 
27280 66 72 65 65 69 6e 67 20 74 68 65 20 72 65 73 75  freeing the resu
27290 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20  lt..** However, 
272a0 74 68 65 20 65 72 72 6f 72 20 73 74 72 69 6e 67  the error string
272b0 20 6d 69 67 68 74 20 62 65 20 6f 76 65 72 77 72   might be overwr
272c0 69 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63  itten or dealloc
272d0 61 74 65 64 20 62 79 0a 2a 2a 20 73 75 62 73 65  ated by.** subse
272e0 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f  quent calls to o
272f0 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65  ther SQLite inte
27300 72 66 61 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e  rface functions.
27310 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  )^.**.** ^The sq
27320 6c 69 74 65 33 5f 65 72 72 73 74 72 28 29 20 69  lite3_errstr() i
27330 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
27340 20 74 68 65 20 45 6e 67 6c 69 73 68 2d 6c 61 6e   the English-lan
27350 67 75 61 67 65 20 74 65 78 74 0a 2a 2a 20 74 68  guage text.** th
27360 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68 65  at describes the
27370 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 2c 20   [result code], 
27380 61 73 20 55 54 46 2d 38 2e 0a 2a 2a 20 5e 28 4d  as UTF-8..** ^(M
27390 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68  emory to hold th
273a0 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  e error message 
273b0 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65  string is manage
273c0 64 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20  d internally.** 
273d0 61 6e 64 20 6d 75 73 74 20 6e 6f 74 20 62 65 20  and must not be 
273e0 66 72 65 65 64 20 62 79 20 74 68 65 20 61 70 70  freed by the app
273f0 6c 69 63 61 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a 2a  lication)^..**.*
27400 2a 20 57 68 65 6e 20 74 68 65 20 73 65 72 69 61  * When the seria
27410 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67  lized [threading
27420 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75 73 65   mode] is in use
27430 2c 20 69 74 20 6d 69 67 68 74 20 62 65 20 74 68  , it might be th
27440 65 0a 2a 2a 20 63 61 73 65 20 74 68 61 74 20 61  e.** case that a
27450 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63   second error oc
27460 63 75 72 73 20 6f 6e 20 61 20 73 65 70 61 72 61  curs on a separa
27470 74 65 20 74 68 72 65 61 64 20 69 6e 20 62 65 74  te thread in bet
27480 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65  ween.** the time
27490 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 65 72   of the first er
274a0 72 6f 72 20 61 6e 64 20 74 68 65 20 63 61 6c 6c  ror and the call
274b0 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66   to these interf
274c0 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68  aces..** When th
274d0 61 74 20 68 61 70 70 65 6e 73 2c 20 74 68 65 20  at happens, the 
274e0 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c  second error wil
274f0 6c 20 62 65 20 72 65 70 6f 72 74 65 64 20 73 69  l be reported si
27500 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74  nce these.** int
27510 65 72 66 61 63 65 73 20 61 6c 77 61 79 73 20 72  erfaces always r
27520 65 70 6f 72 74 20 74 68 65 20 6d 6f 73 74 20 72  eport the most r
27530 65 63 65 6e 74 20 72 65 73 75 6c 74 2e 20 20 54  ecent result.  T
27540 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c  o avoid.** this,
27550 20 65 61 63 68 20 74 68 72 65 61 64 20 63 61 6e   each thread can
27560 20 6f 62 74 61 69 6e 20 65 78 63 6c 75 73 69 76   obtain exclusiv
27570 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b 64 61  e use of the [da
27580 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
27590 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b  n] D.** by invok
275a0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  ing [sqlite3_mut
275b0 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74  ex_enter]([sqlit
275c0 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29  e3_db_mutex](D))
275d0 20 62 65 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e   before beginnin
275e0 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20 61 6e  g.** to use D an
275f0 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69  d invoking [sqli
27600 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d  te3_mutex_leave]
27610 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74  ([sqlite3_db_mut
27620 65 78 5d 28 44 29 29 20 61 66 74 65 72 0a 2a 2a  ex](D)) after.**
27630 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68   all calls to th
27640 65 20 69 6e 74 65 72 66 61 63 65 73 20 6c 69 73  e interfaces lis
27650 74 65 64 20 68 65 72 65 20 61 72 65 20 63 6f 6d  ted here are com
27660 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66  pleted..**.** If
27670 20 61 6e 20 69 6e 74 65 72 66 61 63 65 20 66 61   an interface fa
27680 69 6c 73 20 77 69 74 68 20 53 51 4c 49 54 45 5f  ils with SQLITE_
27690 4d 49 53 55 53 45 2c 20 74 68 61 74 20 6d 65 61  MISUSE, that mea
276a0 6e 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  ns the interface
276b0 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64 20  .** was invoked 
276c0 69 6e 63 6f 72 72 65 63 74 6c 79 20 62 79 20 74  incorrectly by t
276d0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20  he application. 
276e0 20 49 6e 20 74 68 61 74 20 63 61 73 65 2c 20 74   In that case, t
276f0 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65  he.** error code
27700 20 61 6e 64 20 6d 65 73 73 61 67 65 20 6d 61 79   and message may
27710 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65 20 73   or may not be s
27720 65 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  et..*/.SQLITE_AP
27730 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 72  I int sqlite3_er
27740 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64  rcode(sqlite3 *d
27750 62 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  b);.SQLITE_API i
27760 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  nt sqlite3_exten
27770 64 65 64 5f 65 72 72 63 6f 64 65 28 73 71 6c 69  ded_errcode(sqli
27780 74 65 33 20 2a 64 62 29 3b 0a 53 51 4c 49 54 45  te3 *db);.SQLITE
27790 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20  _API const char 
277a0 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  *sqlite3_errmsg(
277b0 73 71 6c 69 74 65 33 2a 29 3b 0a 53 51 4c 49 54  sqlite3*);.SQLIT
277c0 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64  E_API const void
277d0 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   *sqlite3_errmsg
277e0 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 53 51  16(sqlite3*);.SQ
277f0 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63  LITE_API const c
27800 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72  har *sqlite3_err
27810 73 74 72 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  str(int);../*.**
27820 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 53   CAPI3REF: SQL S
27830 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a  tatement Object.
27840 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72  ** KEYWORDS: {pr
27850 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
27860 7d 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74  } {prepared stat
27870 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e  ements}.**.** An
27880 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
27890 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65  s object represe
278a0 6e 74 73 20 61 20 73 69 6e 67 6c 65 20 53 51 4c  nts a single SQL
278b0 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54   statement..** T
278c0 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 76 61  his object is va
278d0 72 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20 61 73  riously known as
278e0 20 61 20 22 70 72 65 70 61 72 65 64 20 73 74 61   a "prepared sta
278f0 74 65 6d 65 6e 74 22 20 6f 72 20 61 0a 2a 2a 20  tement" or a.** 
27900 22 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74  "compiled SQL st
27910 61 74 65 6d 65 6e 74 22 20 6f 72 20 73 69 6d 70  atement" or simp
27920 6c 79 20 61 73 20 61 20 22 73 74 61 74 65 6d 65  ly as a "stateme
27930 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c  nt"..**.** The l
27940 69 66 65 20 6f 66 20 61 20 73 74 61 74 65 6d 65  ife of a stateme
27950 6e 74 20 6f 62 6a 65 63 74 20 67 6f 65 73 20 73  nt object goes s
27960 6f 6d 65 74 68 69 6e 67 20 6c 69 6b 65 20 74 68  omething like th
27970 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a  is:.**.** <ol>.*
27980 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 68  * <li> Create th
27990 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b  e object using [
279a0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
279b0 76 32 28 29 5d 20 6f 72 20 61 20 72 65 6c 61 74  v2()] or a relat
279c0 65 64 0a 2a 2a 20 20 20 20 20 20 66 75 6e 63 74  ed.**      funct
279d0 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e  ion..** <li> Bin
279e0 64 20 76 61 6c 75 65 73 20 74 6f 20 5b 68 6f 73  d values to [hos
279f0 74 20 70 61 72 61 6d 65 74 65 72 73 5d 20 75 73  t parameters] us
27a00 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ing the sqlite3_
27a10 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20  bind_*().**     
27a20 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20   interfaces..** 
27a30 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 51 4c  <li> Run the SQL
27a40 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c   by calling [sql
27a50 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65  ite3_step()] one
27a60 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a   or more times..
27a70 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 74 68  ** <li> Reset th
27a80 65 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e  e statement usin
27a90 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
27aa0 28 29 5d 20 74 68 65 6e 20 67 6f 20 62 61 63 6b  ()] then go back
27ab0 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73 74 65 70  .**      to step
27ac0 20 32 2e 20 20 44 6f 20 74 68 69 73 20 7a 65 72   2.  Do this zer
27ad0 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e  o or more times.
27ae0 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79  .** <li> Destroy
27af0 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e   the object usin
27b00 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  g [sqlite3_final
27b10 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e  ize()]..** </ol>
27b20 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20  .**.** Refer to 
27b30 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e  documentation on
27b40 20 69 6e 64 69 76 69 64 75 61 6c 20 6d 65 74 68   individual meth
27b50 6f 64 73 20 61 62 6f 76 65 20 66 6f 72 20 61 64  ods above for ad
27b60 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f  ditional.** info
27b70 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65  rmation..*/.type
27b80 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
27b90 65 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 33 5f  e3_stmt sqlite3_
27ba0 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  stmt;../*.** CAP
27bb0 49 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65 20  I3REF: Run-time 
27bc0 4c 69 6d 69 74 73 0a 2a 2a 0a 2a 2a 20 5e 28 54  Limits.**.** ^(T
27bd0 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c  his interface al
27be0 6c 6f 77 73 20 74 68 65 20 73 69 7a 65 20 6f 66  lows the size of
27bf0 20 76 61 72 69 6f 75 73 20 63 6f 6e 73 74 72 75   various constru
27c00 63 74 73 20 74 6f 20 62 65 20 6c 69 6d 69 74 65  cts to be limite
27c10 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65 63  d.** on a connec
27c20 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74 69  tion by connecti
27c30 6f 6e 20 62 61 73 69 73 2e 20 20 54 68 65 20 66  on basis.  The f
27c40 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69  irst parameter i
27c50 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61  s the.** [databa
27c60 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77  se connection] w
27c70 68 6f 73 65 20 6c 69 6d 69 74 20 69 73 20 74 6f  hose limit is to
27c80 20 62 65 20 73 65 74 20 6f 72 20 71 75 65 72 69   be set or queri
27c90 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f  ed.  The.** seco
27ca0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
27cb0 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d 69  one of the [limi
27cc0 74 20 63 61 74 65 67 6f 72 69 65 73 5d 20 74 68  t categories] th
27cd0 61 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20 63  at define a.** c
27ce0 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74 72 75 63  lass of construc
27cf0 74 73 20 74 6f 20 62 65 20 73 69 7a 65 20 6c 69  ts to be size li
27d00 6d 69 74 65 64 2e 20 20 54 68 65 20 74 68 69 72  mited.  The thir
27d10 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  d parameter is t
27d20 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74 20  he.** new limit 
27d30 66 6f 72 20 74 68 61 74 20 63 6f 6e 73 74 72 75  for that constru
27d40 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ct.)^.**.** ^If 
27d50 74 68 65 20 6e 65 77 20 6c 69 6d 69 74 20 69 73  the new limit is
27d60 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62   a negative numb
27d70 65 72 2c 20 74 68 65 20 6c 69 6d 69 74 20 69 73  er, the limit is
27d80 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 5e   unchanged..** ^
27d90 28 46 6f 72 20 65 61 63 68 20 6c 69 6d 69 74 20  (For each limit 
27da0 63 61 74 65 67 6f 72 79 20 53 51 4c 49 54 45 5f  category SQLITE_
27db0 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45 3c 2f 69  LIMIT_<i>NAME</i
27dc0 3e 20 74 68 65 72 65 20 69 73 20 61 20 0a 2a 2a  > there is a .**
27dd0 20 5b 6c 69 6d 69 74 73 20 7c 20 68 61 72 64 20   [limits | hard 
27de0 75 70 70 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20  upper bound].** 
27df0 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74  set at compile-t
27e00 69 6d 65 20 62 79 20 61 20 43 20 70 72 65 70 72  ime by a C prepr
27e10 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 63 61  ocessor macro ca
27e20 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20  lled.** [limits 
27e30 7c 20 53 51 4c 49 54 45 5f 4d 41 58 5f 3c 69 3e  | SQLITE_MAX_<i>
27e40 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28 54  NAME</i>]..** (T
27e50 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69 6e 20  he "_LIMIT_" in 
27e60 74 68 65 20 6e 61 6d 65 20 69 73 20 63 68 61 6e  the name is chan
27e70 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29  ged to "_MAX_".)
27e80 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70 74 73 20  )^.** ^Attempts 
27e90 74 6f 20 69 6e 63 72 65 61 73 65 20 61 20 6c 69  to increase a li
27ea0 6d 69 74 20 61 62 6f 76 65 20 69 74 73 20 68 61  mit above its ha
27eb0 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61  rd upper bound a
27ec0 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 74  re.** silently t
27ed0 72 75 6e 63 61 74 65 64 20 74 6f 20 74 68 65 20  runcated to the 
27ee0 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64  hard upper bound
27ef0 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61 72 64 6c  ..**.** ^Regardl
27f00 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f  ess of whether o
27f10 72 20 6e 6f 74 20 74 68 65 20 6c 69 6d 69 74 20  r not the limit 
27f20 77 61 73 20 63 68 61 6e 67 65 64 2c 20 74 68 65  was changed, the
27f30 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 69   .** [sqlite3_li
27f40 6d 69 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65  mit()] interface
27f50 20 72 65 74 75 72 6e 73 20 74 68 65 20 70 72 69   returns the pri
27f60 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  or value of the 
27f70 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65 6e 63 65  limit..** ^Hence
27f80 2c 20 74 6f 20 66 69 6e 64 20 74 68 65 20 63 75  , to find the cu
27f90 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 20 61  rrent value of a
27fa0 20 6c 69 6d 69 74 20 77 69 74 68 6f 75 74 20 63   limit without c
27fb0 68 61 6e 67 69 6e 67 20 69 74 2c 0a 2a 2a 20 73  hanging it,.** s
27fc0 69 6d 70 6c 79 20 69 6e 76 6f 6b 65 20 74 68 69  imply invoke thi
27fd0 73 20 69 6e 74 65 72 66 61 63 65 20 77 69 74 68  s interface with
27fe0 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
27ff0 65 74 65 72 20 73 65 74 20 74 6f 20 2d 31 2e 0a  eter set to -1..
28000 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d 65 20 6c  **.** Run-time l
28010 69 6d 69 74 73 20 61 72 65 20 69 6e 74 65 6e 64  imits are intend
28020 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 61 70  ed for use in ap
28030 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
28040 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 20 74  manage.** both t
28050 68 65 69 72 20 6f 77 6e 20 69 6e 74 65 72 6e 61  heir own interna
28060 6c 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 61  l database and a
28070 6c 73 6f 20 64 61 74 61 62 61 73 65 73 20 74 68  lso databases th
28080 61 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c 6c 65  at are controlle
28090 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73 74 65  d.** by untruste
280a0 64 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63  d external sourc
280b0 65 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20  es.  An example 
280c0 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68  application migh
280d0 74 20 62 65 20 61 0a 2a 2a 20 77 65 62 20 62 72  t be a.** web br
280e0 6f 77 73 65 72 20 74 68 61 74 20 68 61 73 20 69  owser that has i
280f0 74 73 20 6f 77 6e 20 64 61 74 61 62 61 73 65 73  ts own databases
28100 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 68 69 73   for storing his
28110 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65 70 61  tory and.** sepa
28120 72 61 74 65 20 64 61 74 61 62 61 73 65 73 20 63  rate databases c
28130 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a 61 76  ontrolled by Jav
28140 61 53 63 72 69 70 74 20 61 70 70 6c 69 63 61 74  aScript applicat
28150 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 64 0a  ions downloaded.
28160 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e 74 65 72  ** off the Inter
28170 6e 65 74 2e 20 20 54 68 65 20 69 6e 74 65 72 6e  net.  The intern
28180 61 6c 20 64 61 74 61 62 61 73 65 73 20 63 61 6e  al databases can
28190 20 62 65 20 67 69 76 65 6e 20 74 68 65 0a 2a 2a   be given the.**
281a0 20 6c 61 72 67 65 2c 20 64 65 66 61 75 6c 74 20   large, default 
281b0 6c 69 6d 69 74 73 2e 20 20 44 61 74 61 62 61 73  limits.  Databas
281c0 65 73 20 6d 61 6e 61 67 65 64 20 62 79 20 65 78  es managed by ex
281d0 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 20 63  ternal sources c
281e0 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e 20 6d  an.** be given m
281f0 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69 6d 69  uch smaller limi
28200 74 73 20 64 65 73 69 67 6e 65 64 20 74 6f 20 70  ts designed to p
28210 72 65 76 65 6e 74 20 61 20 64 65 6e 69 61 6c 20  revent a denial 
28220 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a 20 61 74  of service.** at
28230 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70 65 72  tack.  Developer
28240 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 77 61 6e  s might also wan
28250 74 20 74 6f 20 75 73 65 20 74 68 65 20 5b 73 71  t to use the [sq
28260 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
28270 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 65 72  izer()].** inter
28280 66 61 63 65 20 74 6f 20 66 75 72 74 68 65 72 20  face to further 
28290 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73 74 65  control untruste
282a0 64 20 53 51 4c 2e 20 20 54 68 65 20 73 69 7a 65  d SQL.  The size
282b0 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
282c0 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 61  .** created by a
282d0 6e 20 75 6e 74 72 75 73 74 65 64 20 73 63 72 69  n untrusted scri
282e0 70 74 20 63 61 6e 20 62 65 20 63 6f 6e 74 61 69  pt can be contai
282f0 6e 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a  ned using the.**
28300 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74   [max_page_count
28310 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a  ] [PRAGMA]..**.*
28320 2a 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65 20 6c  * New run-time l
28330 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 20  imit categories 
28340 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
28350 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e  future releases.
28360 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
28370 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  nt sqlite3_limit
28380 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69  (sqlite3*, int i
28390 64 2c 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a  d, int newVal);.
283a0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
283b0 20 52 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20   Run-Time Limit 
283c0 43 61 74 65 67 6f 72 69 65 73 0a 2a 2a 20 4b 45  Categories.** KE
283d0 59 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63  YWORDS: {limit c
283e0 61 74 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74  ategory} {*limit
283f0 20 63 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a   categories}.**.
28400 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
28410 74 73 20 64 65 66 69 6e 65 20 76 61 72 69 6f 75  ts define variou
28420 73 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6c 69  s performance li
28430 6d 69 74 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e  mits.** that can
28440 20 62 65 20 6c 6f 77 65 72 65 64 20 61 74 20 72   be lowered at r
28450 75 6e 2d 74 69 6d 65 20 75 73 69 6e 67 20 5b 73  un-time using [s
28460 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e  qlite3_limit()].
28470 0a 2a 2a 20 54 68 65 20 73 79 6e 6f 70 73 69 73  .** The synopsis
28480 20 6f 66 20 74 68 65 20 6d 65 61 6e 69 6e 67 73   of the meanings
28490 20 6f 66 20 74 68 65 20 76 61 72 69 6f 75 73 20   of the various 
284a0 6c 69 6d 69 74 73 20 69 73 20 73 68 6f 77 6e 20  limits is shown 
284b0 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69 74 69  below..** Additi
284c0 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
284d0 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 61 74   is available at
284e0 20 5b 6c 69 6d 69 74 73 20 7c 20 4c 69 6d 69 74   [limits | Limit
284f0 73 20 69 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a  s in SQLite]..**
28500 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51  .** <dl>.** [[SQ
28510 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54  LITE_LIMIT_LENGT
28520 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  H]] ^(<dt>SQLITE
28530 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64  _LIMIT_LENGTH</d
28540 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
28550 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e  ximum size of an
28560 79 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42  y string or BLOB
28570 20 6f 72 20 74 61 62 6c 65 20 72 6f 77 2c 20 69   or table row, i
28580 6e 20 62 79 74 65 73 2e 3c 64 64 3e 29 5e 0a 2a  n bytes.<dd>)^.*
28590 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
285a0 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 5d 5d  MIT_SQL_LENGTH]]
285b0 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
285c0 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f  MIT_SQL_LENGTH</
285d0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
285e0 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
285f0 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
28600 74 2c 20 69 6e 20 62 79 74 65 73 2e 3c 2f 64 64  t, in bytes.</dd
28610 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
28620 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 5d  TE_LIMIT_COLUMN]
28630 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
28640 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e  IMIT_COLUMN</dt>
28650 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
28660 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  mum number of co
28670 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c 65  lumns in a table
28680 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69   definition or i
28690 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20  n the.** result 
286a0 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54  set of a [SELECT
286b0 5d 20 6f 72 20 74 68 65 20 6d 61 78 69 6d 75 6d  ] or the maximum
286c0 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
286d0 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a  ns in an index.*
286e0 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45 52  * or in an ORDER
286f0 20 42 59 20 6f 72 20 47 52 4f 55 50 20 42 59 20   BY or GROUP BY 
28700 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a  clause.</dd>)^.*
28710 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
28720 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 5d 5d  MIT_EXPR_DEPTH]]
28730 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
28740 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f  MIT_EXPR_DEPTH</
28750 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
28760 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20  aximum depth of 
28770 74 68 65 20 70 61 72 73 65 20 74 72 65 65 20 6f  the parse tree o
28780 6e 20 61 6e 79 20 65 78 70 72 65 73 73 69 6f 6e  n any expression
28790 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
287a0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f  [SQLITE_LIMIT_CO
287b0 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 5d 5d 20  MPOUND_SELECT]] 
287c0 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
287d0 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45  IT_COMPOUND_SELE
287e0 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  CT</dt>.** <dd>T
287f0 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
28800 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 61 20  r of terms in a 
28810 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54 20  compound SELECT 
28820 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29  statement.</dd>)
28830 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
28840 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 5d 5d  _LIMIT_VDBE_OP]]
28850 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
28860 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 3e  MIT_VDBE_OP</dt>
28870 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
28880 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e  mum number of in
28890 73 74 72 75 63 74 69 6f 6e 73 20 69 6e 20 61 20  structions in a 
288a0 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20  virtual machine 
288b0 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 64 20  program.** used 
288c0 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 6e 20  to implement an 
288d0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  SQL statement.  
288e0 54 68 69 73 20 6c 69 6d 69 74 20 69 73 20 6e 6f  This limit is no
288f0 74 20 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 65  t currently.** e
28900 6e 66 6f 72 63 65 64 2c 20 74 68 6f 75 67 68 20  nforced, though 
28910 74 68 61 74 20 6d 69 67 68 74 20 62 65 20 61 64  that might be ad
28920 64 65 64 20 69 6e 20 73 6f 6d 65 20 66 75 74 75  ded in some futu
28930 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a  re release of.**
28940 20 53 51 4c 69 74 65 2e 3c 2f 64 64 3e 29 5e 0a   SQLite.</dd>)^.
28950 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
28960 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52  IMIT_FUNCTION_AR
28970 47 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  G]] ^(<dt>SQLITE
28980 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f  _LIMIT_FUNCTION_
28990 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ARG</dt>.** <dd>
289a0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
289b0 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20  er of arguments 
289c0 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f  on a function.</
289d0 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
289e0 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43  LITE_LIMIT_ATTAC
289f0 48 45 44 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  HED]] ^(<dt>SQLI
28a00 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45  TE_LIMIT_ATTACHE
28a10 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
28a20 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
28a30 20 6f 66 20 5b 41 54 54 41 43 48 20 7c 20 61 74   of [ATTACH | at
28a40 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 73  tached databases
28a50 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ].)^</dd>.**.** 
28a60 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  [[SQLITE_LIMIT_L
28a70 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47  IKE_PATTERN_LENG
28a80 54 48 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51  TH]].** ^(<dt>SQ
28a90 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f  LITE_LIMIT_LIKE_
28aa0 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f  PATTERN_LENGTH</
28ab0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
28ac0 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
28ad0 20 74 68 65 20 70 61 74 74 65 72 6e 20 61 72 67   the pattern arg
28ae0 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 4c 49  ument to the [LI
28af0 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d  KE] or.** [GLOB]
28b00 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e   operators.</dd>
28b10 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
28b20 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45  E_LIMIT_VARIABLE
28b30 5f 4e 55 4d 42 45 52 5d 5d 0a 2a 2a 20 5e 28 3c  _NUMBER]].** ^(<
28b40 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
28b50 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c  VARIABLE_NUMBER<
28b60 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
28b70 6d 61 78 69 6d 75 6d 20 69 6e 64 65 78 20 6e 75  maximum index nu
28b80 6d 62 65 72 20 6f 66 20 61 6e 79 20 5b 70 61 72  mber of any [par
28b90 61 6d 65 74 65 72 5d 20 69 6e 20 61 6e 20 53 51  ameter] in an SQ
28ba0 4c 20 73 74 61 74 65 6d 65 6e 74 2e 29 5e 0a 2a  L statement.)^.*
28bb0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
28bc0 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54  MIT_TRIGGER_DEPT
28bd0 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  H]] ^(<dt>SQLITE
28be0 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44  _LIMIT_TRIGGER_D
28bf0 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  EPTH</dt>.** <dd
28c00 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70  >The maximum dep
28c10 74 68 20 6f 66 20 72 65 63 75 72 73 69 6f 6e 20  th of recursion 
28c20 66 6f 72 20 74 72 69 67 67 65 72 73 2e 3c 2f 64  for triggers.</d
28c30 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f  d>)^.** </dl>.*/
28c40 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
28c50 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20 20 20  LIMIT_LENGTH    
28c60 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
28c70 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
28c80 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54  _LIMIT_SQL_LENGT
28c90 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  H               
28ca0 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
28cb0 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20  E_LIMIT_COLUMN  
28cc0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
28cd0 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
28ce0 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45  TE_LIMIT_EXPR_DE
28cf0 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20  PTH             
28d00 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c     3.#define SQL
28d10 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55  ITE_LIMIT_COMPOU
28d20 4e 44 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20  ND_SELECT       
28d30 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51      4.#define SQ
28d40 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f  LITE_LIMIT_VDBE_
28d50 4f 50 20 20 20 20 20 20 20 20 20 20 20 20 20 20  OP              
28d60 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53       5.#define S
28d70 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43  QLITE_LIMIT_FUNC
28d80 54 49 4f 4e 5f 41 52 47 20 20 20 20 20 20 20 20  TION_ARG        
28d90 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20        6.#define 
28da0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54  SQLITE_LIMIT_ATT
28db0 41 43 48 45 44 20 20 20 20 20 20 20 20 20 20 20  ACHED           
28dc0 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65         7.#define
28dd0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49   SQLITE_LIMIT_LI
28de0 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54  KE_PATTERN_LENGT
28df0 48 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e  H       8.#defin
28e00 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  e SQLITE_LIMIT_V
28e10 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20 20  ARIABLE_NUMBER  
28e20 20 20 20 20 20 20 20 20 20 39 0a 23 64 65 66 69           9.#defi
28e30 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
28e40 54 52 49 47 47 45 52 5f 44 45 50 54 48 20 20 20  TRIGGER_DEPTH   
28e50 20 20 20 20 20 20 20 20 20 31 30 0a 0a 2f 2a 0a           10../*.
28e60 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d  ** CAPI3REF: Com
28e70 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53 74  piling An SQL St
28e80 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45 59 57 4f  atement.** KEYWO
28e90 52 44 53 3a 20 7b 53 51 4c 20 73 74 61 74 65 6d  RDS: {SQL statem
28ea0 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a  ent compiler}.**
28eb0 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 65 20 61  .** To execute a
28ec0 6e 20 53 51 4c 20 71 75 65 72 79 2c 20 69 74 20  n SQL query, it 
28ed0 6d 75 73 74 20 66 69 72 73 74 20 62 65 20 63 6f  must first be co
28ee0 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61 20 62 79  mpiled into a by
28ef0 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f 67 72  te-code.** progr
28f00 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20  am using one of 
28f10 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a  these routines..
28f20 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
28f30 61 72 67 75 6d 65 6e 74 2c 20 22 64 62 22 2c 20  argument, "db", 
28f40 69 73 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  is a [database c
28f50 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74 61 69  onnection] obtai
28f60 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 70 72  ned from a.** pr
28f70 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20 63  ior successful c
28f80 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
28f90 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
28fa0 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6f 72 0a  3_open_v2()] or.
28fb0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ** [sqlite3_open
28fc0 31 36 28 29 5d 2e 20 20 54 68 65 20 64 61 74 61  16()].  The data
28fd0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
28fe0 6d 75 73 74 20 6e 6f 74 20 68 61 76 65 20 62 65  must not have be
28ff0 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a  en closed..**.**
29000 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
29010 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20 69 73  ment, "zSql", is
29020 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74   the statement t
29030 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20 65  o be compiled, e
29040 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69 74  ncoded.** as eit
29050 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46  her UTF-8 or UTF
29060 2d 31 36 2e 20 20 54 68 65 20 73 71 6c 69 74 65  -16.  The sqlite
29070 33 5f 70 72 65 70 61 72 65 28 29 20 61 6e 64 20  3_prepare() and 
29080 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
29090 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  v2().** interfac
290a0 65 73 20 75 73 65 20 55 54 46 2d 38 2c 20 61 6e  es use UTF-8, an
290b0 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  d sqlite3_prepar
290c0 65 31 36 28 29 20 61 6e 64 20 73 71 6c 69 74 65  e16() and sqlite
290d0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
290e0 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31 36 2e 0a  .** use UTF-16..
290f0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 42  **.** ^If the nB
29100 79 74 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  yte argument is 
29110 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 6f 2c 20  less than zero, 
29120 74 68 65 6e 20 7a 53 71 6c 20 69 73 20 72 65 61  then zSql is rea
29130 64 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20 66  d up to the.** f
29140 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e  irst zero termin
29150 61 74 6f 72 2e 20 5e 49 66 20 6e 42 79 74 65 20  ator. ^If nByte 
29160 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c  is non-negative,
29170 20 74 68 65 6e 20 69 74 20 69 73 20 74 68 65 20   then it is the 
29180 6d 61 78 69 6d 75 6d 0a 2a 2a 20 6e 75 6d 62 65  maximum.** numbe
29190 72 20 6f 66 20 20 62 79 74 65 73 20 72 65 61 64  r of  bytes read
291a0 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e 57 68   from zSql.  ^Wh
291b0 65 6e 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d  en nByte is non-
291c0 6e 65 67 61 74 69 76 65 2c 20 74 68 65 0a 2a 2a  negative, the.**
291d0 20 7a 53 71 6c 20 73 74 72 69 6e 67 20 65 6e 64   zSql string end
291e0 73 20 61 74 20 65 69 74 68 65 72 20 74 68 65 20  s at either the 
291f0 66 69 72 73 74 20 27 5c 30 30 30 27 20 6f 72 20  first '\000' or 
29200 27 5c 75 30 30 30 30 27 20 63 68 61 72 61 63 74  '\u0000' charact
29210 65 72 20 6f 72 0a 2a 2a 20 74 68 65 20 6e 42 79  er or.** the nBy
29220 74 65 2d 74 68 20 62 79 74 65 2c 20 77 68 69 63  te-th byte, whic
29230 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72 73  hever comes firs
29240 74 2e 20 49 66 20 74 68 65 20 63 61 6c 6c 65 72  t. If the caller
29250 20 6b 6e 6f 77 73 0a 2a 2a 20 74 68 61 74 20 74   knows.** that t
29260 68 65 20 73 75 70 70 6c 69 65 64 20 73 74 72 69  he supplied stri
29270 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e  ng is nul-termin
29280 61 74 65 64 2c 20 74 68 65 6e 20 74 68 65 72 65  ated, then there
29290 20 69 73 20 61 20 73 6d 61 6c 6c 0a 2a 2a 20 70   is a small.** p
292a0 65 72 66 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e  erformance advan
292b0 74 61 67 65 20 74 6f 20 62 65 20 67 61 69 6e 65  tage to be gaine
292c0 64 20 62 79 20 70 61 73 73 69 6e 67 20 61 6e 20  d by passing an 
292d0 6e 42 79 74 65 20 70 61 72 61 6d 65 74 65 72 20  nByte parameter 
292e0 74 68 61 74 0a 2a 2a 20 69 73 20 65 71 75 61 6c  that.** is equal
292f0 20 74 6f 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   to the number o
29300 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 69  f bytes in the i
29310 6e 70 75 74 20 73 74 72 69 6e 67 20 3c 69 3e 69  nput string <i>i
29320 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20  ncluding</i>.** 
29330 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74  the nul-terminat
29340 6f 72 20 62 79 74 65 73 20 61 73 20 74 68 69 73  or bytes as this
29350 20 73 61 76 65 73 20 53 51 4c 69 74 65 20 66 72   saves SQLite fr
29360 6f 6d 20 68 61 76 69 6e 67 20 74 6f 0a 2a 2a 20  om having to.** 
29370 6d 61 6b 65 20 61 20 63 6f 70 79 20 6f 66 20 74  make a copy of t
29380 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 2e  he input string.
29390 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a 54 61 69  .**.** ^If pzTai
293a0 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68  l is not NULL th
293b0 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61  en *pzTail is ma
293c0 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74  de to point to t
293d0 68 65 20 66 69 72 73 74 20 62 79 74 65 0a 2a 2a  he first byte.**
293e0 20 70 61 73 74 20 74 68 65 20 65 6e 64 20 6f 66   past the end of
293f0 20 74 68 65 20 66 69 72 73 74 20 53 51 4c 20 73   the first SQL s
29400 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c  tatement in zSql
29410 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  .  These routine
29420 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c  s only.** compil
29430 65 20 74 68 65 20 66 69 72 73 74 20 73 74 61 74  e the first stat
29440 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73  ement in zSql, s
29450 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65 66  o *pzTail is lef
29460 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a  t pointing to.**
29470 20 77 68 61 74 20 72 65 6d 61 69 6e 73 20 75 6e   what remains un
29480 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20  compiled..**.** 
29490 5e 2a 70 70 53 74 6d 74 20 69 73 20 6c 65 66 74  ^*ppStmt is left
294a0 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20 63   pointing to a c
294b0 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70 61 72 65  ompiled [prepare
294c0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
294d0 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63  t can be.** exec
294e0 75 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  uted using [sqli
294f0 74 65 33 5f 73 74 65 70 28 29 5d 2e 20 20 5e 49  te3_step()].  ^I
29500 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 65 72  f there is an er
29510 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69 73 20  ror, *ppStmt is 
29520 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20  set.** to NULL. 
29530 20 5e 49 66 20 74 68 65 20 69 6e 70 75 74 20 74   ^If the input t
29540 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20  ext contains no 
29550 53 51 4c 20 28 69 66 20 74 68 65 20 69 6e 70 75  SQL (if the inpu
29560 74 20 69 73 20 61 6e 20 65 6d 70 74 79 0a 2a 2a  t is an empty.**
29570 20 73 74 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d   string or a com
29580 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70 70 53 74  ment) then *ppSt
29590 6d 74 20 69 73 20 73 65 74 20 74 6f 20 4e 55 4c  mt is set to NUL
295a0 4c 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 69 6e  L..** The callin
295b0 67 20 70 72 6f 63 65 64 75 72 65 20 69 73 20 72  g procedure is r
295c0 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64  esponsible for d
295d0 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6d 70  eleting the comp
295e0 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74  iled.** SQL stat
295f0 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c  ement using [sql
29600 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
29610 20 61 66 74 65 72 20 69 74 20 68 61 73 20 66 69   after it has fi
29620 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 0a  nished with it..
29630 2a 2a 20 70 70 53 74 6d 74 20 6d 61 79 20 6e 6f  ** ppStmt may no
29640 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  t be NULL..**.**
29650 20 5e 4f 6e 20 73 75 63 63 65 73 73 2c 20 74 68   ^On success, th
29660 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  e sqlite3_prepar
29670 65 28 29 20 66 61 6d 69 6c 79 20 6f 66 20 72 6f  e() family of ro
29680 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53  utines return [S
29690 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74  QLITE_OK];.** ot
296a0 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f  herwise an [erro
296b0 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72  r code] is retur
296c0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ned..**.** The s
296d0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
296e0 32 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  2() and sqlite3_
296f0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 20 69  prepare16_v2() i
29700 6e 74 65 72 66 61 63 65 73 20 61 72 65 0a 2a 2a  nterfaces are.**
29710 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72   recommended for
29720 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d   all new program
29730 73 2e 20 54 68 65 20 74 77 6f 20 6f 6c 64 65 72  s. The two older
29740 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
29750 72 65 74 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20  retained.** for 
29760 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
29770 69 62 69 6c 69 74 79 2c 20 62 75 74 20 74 68 65  ibility, but the
29780 69 72 20 75 73 65 20 69 73 20 64 69 73 63 6f 75  ir use is discou
29790 72 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68  raged..** ^In th
297a0 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
297b0 73 2c 20 74 68 65 20 70 72 65 70 61 72 65 64 20  s, the prepared 
297c0 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61  statement.** tha
297d0 74 20 69 73 20 72 65 74 75 72 6e 65 64 20 28 74  t is returned (t
297e0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74  he [sqlite3_stmt
297f0 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61 69  ] object) contai
29800 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  ns a copy of the
29810 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c  .** original SQL
29820 20 74 65 78 74 2e 20 54 68 69 73 20 63 61 75 73   text. This caus
29830 65 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  es the [sqlite3_
29840 73 74 65 70 28 29 5d 20 69 6e 74 65 72 66 61 63  step()] interfac
29850 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20 64  e to.** behave d
29860 69 66 66 65 72 65 6e 74 6c 79 20 69 6e 20 74 68  ifferently in th
29870 72 65 65 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20  ree ways:.**.** 
29880 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20  <ol>.** <li>.** 
29890 5e 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65  ^If the database
298a0 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 73 2c   schema changes,
298b0 20 69 6e 73 74 65 61 64 20 6f 66 20 72 65 74 75   instead of retu
298c0 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43  rning [SQLITE_SC
298d0 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61  HEMA] as it.** a
298e0 6c 77 61 79 73 20 75 73 65 64 20 74 6f 20 64 6f  lways used to do
298f0 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  , [sqlite3_step(
29900 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69  )] will automati
29910 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20  cally recompile 
29920 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65  the SQL.** state
29930 6d 65 6e 74 20 61 6e 64 20 74 72 79 20 74 6f 20  ment and try to 
29940 72 75 6e 20 69 74 20 61 67 61 69 6e 2e 0a 2a 2a  run it again..**
29950 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69   </li>.**.** <li
29960 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61 6e 20 65 72  >.** ^When an er
29970 72 6f 72 20 6f 63 63 75 72 73 2c 20 5b 73 71 6c  ror occurs, [sql
29980 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c  ite3_step()] wil
29990 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20  l return one of 
299a0 74 68 65 20 64 65 74 61 69 6c 65 64 0a 2a 2a 20  the detailed.** 
299b0 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 6f 72  [error codes] or
299c0 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72   [extended error
299d0 20 63 6f 64 65 73 5d 2e 20 20 5e 54 68 65 20 6c   codes].  ^The l
299e0 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 20 77  egacy behavior w
299f0 61 73 20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c 69  as that.** [sqli
29a00 74 65 33 5f 73 74 65 70 28 29 5d 20 77 6f 75 6c  te3_step()] woul
29a10 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61 20  d only return a 
29a20 67 65 6e 65 72 69 63 20 5b 53 51 4c 49 54 45 5f  generic [SQLITE_
29a30 45 52 52 4f 52 5d 20 72 65 73 75 6c 74 20 63 6f  ERROR] result co
29a40 64 65 0a 2a 2a 20 61 6e 64 20 74 68 65 20 61 70  de.** and the ap
29a50 70 6c 69 63 61 74 69 6f 6e 20 77 6f 75 6c 64 20  plication would 
29a60 68 61 76 65 20 74 6f 20 6d 61 6b 65 20 61 20 73  have to make a s
29a70 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 20 5b 73  econd call to [s
29a80 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 0a  qlite3_reset()].
29a90 2a 2a 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66  ** in order to f
29aa0 69 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69  ind the underlyi
29ab0 6e 67 20 63 61 75 73 65 20 6f 66 20 74 68 65 20  ng cause of the 
29ac0 70 72 6f 62 6c 65 6d 2e 20 57 69 74 68 20 74 68  problem. With th
29ad0 65 20 22 76 32 22 20 70 72 65 70 61 72 65 0a 2a  e "v2" prepare.*
29ae0 2a 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68  * interfaces, th
29af0 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 72 65 61  e underlying rea
29b00 73 6f 6e 20 66 6f 72 20 74 68 65 20 65 72 72 6f  son for the erro
29b10 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d  r is returned im
29b20 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f  mediately..** </
29b30 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a  li>.**.** <li>.*
29b40 2a 20 5e 49 66 20 74 68 65 20 73 70 65 63 69 66  * ^If the specif
29b50 69 63 20 76 61 6c 75 65 20 62 6f 75 6e 64 20 74  ic value bound t
29b60 6f 20 5b 70 61 72 61 6d 65 74 65 72 20 7c 20 68  o [parameter | h
29b70 6f 73 74 20 70 61 72 61 6d 65 74 65 72 5d 20 69  ost parameter] i
29b80 6e 20 74 68 65 20 0a 2a 2a 20 57 48 45 52 45 20  n the .** WHERE 
29b90 63 6c 61 75 73 65 20 6d 69 67 68 74 20 69 6e 66  clause might inf
29ba0 6c 75 65 6e 63 65 20 74 68 65 20 63 68 6f 69 63  luence the choic
29bb0 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20  e of query plan 
29bc0 66 6f 72 20 61 20 73 74 61 74 65 6d 65 6e 74 2c  for a statement,
29bd0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 73 74 61  .** then the sta
29be0 74 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 61  tement will be a
29bf0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63  utomatically rec
29c00 6f 6d 70 69 6c 65 64 2c 20 61 73 20 69 66 20 74  ompiled, as if t
29c10 68 65 72 65 20 68 61 64 20 62 65 65 6e 20 0a 2a  here had been .*
29c20 2a 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67  * a schema chang
29c30 65 2c 20 6f 6e 20 74 68 65 20 66 69 72 73 74 20  e, on the first 
29c40 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
29c50 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77 69 6e 67  ] call following
29c60 20 61 6e 79 20 63 68 61 6e 67 65 0a 2a 2a 20 74   any change.** t
29c70 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62  o the [sqlite3_b
29c80 69 6e 64 5f 74 65 78 74 20 7c 20 62 69 6e 64 69  ind_text | bindi
29c90 6e 67 73 5d 20 6f 66 20 74 68 61 74 20 5b 70 61  ngs] of that [pa
29ca0 72 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a 20 5e 54  rameter]. .** ^T
29cb0 68 65 20 73 70 65 63 69 66 69 63 20 76 61 6c 75  he specific valu
29cc0 65 20 6f 66 20 57 48 45 52 45 2d 63 6c 61 75 73  e of WHERE-claus
29cd0 65 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 6d 69  e [parameter] mi
29ce0 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68  ght influence th
29cf0 65 20 0a 2a 2a 20 63 68 6f 69 63 65 20 6f 66 20  e .** choice of 
29d00 71 75 65 72 79 20 70 6c 61 6e 20 69 66 20 74 68  query plan if th
29d10 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  e parameter is t
29d20 68 65 20 6c 65 66 74 2d 68 61 6e 64 20 73 69 64  he left-hand sid
29d30 65 20 6f 66 20 61 20 5b 4c 49 4b 45 5d 0a 2a 2a  e of a [LIKE].**
29d40 20 6f 72 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61   or [GLOB] opera
29d50 74 6f 72 20 6f 72 20 69 66 20 74 68 65 20 70 61  tor or if the pa
29d60 72 61 6d 65 74 65 72 20 69 73 20 63 6f 6d 70 61  rameter is compa
29d70 72 65 64 20 74 6f 20 61 6e 20 69 6e 64 65 78 65  red to an indexe
29d80 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e 64 20  d column.** and 
29d90 74 68 65 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42  the [SQLITE_ENAB
29da0 4c 45 5f 53 54 41 54 33 5d 20 63 6f 6d 70 69 6c  LE_STAT3] compil
29db0 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73  e-time option is
29dc0 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 74 68 65   enabled..** the
29dd0 20 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f   .** </li>.** </
29de0 6f 6c 3e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ol>.*/.SQLITE_AP
29df0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72  I int sqlite3_pr
29e00 65 70 61 72 65 28 0a 20 20 73 71 6c 69 74 65 33  epare(.  sqlite3
29e10 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
29e20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
29e30 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
29e40 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  har *zSql,      
29e50 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
29e60 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64  t, UTF-8 encoded
29e70 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
29e80 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
29e90 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
29ea0 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
29eb0 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
29ec0 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
29ed0 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
29ee0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
29ef0 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c  st char **pzTail
29f00 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
29f10 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
29f20 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
29f30 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  /.);.SQLITE_API 
29f40 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70  int sqlite3_prep
29f50 61 72 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65  are_v2(.  sqlite
29f60 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
29f70 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
29f80 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
29f90 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20  char *zSql,     
29fa0 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
29fb0 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  nt, UTF-8 encode
29fc0 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
29fd0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
29fe0 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
29ff0 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
2a000 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
2a010 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
2a020 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
2a030 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
2a040 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69  nst char **pzTai
2a050 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
2a060 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
2a070 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
2a080 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  */.);.SQLITE_API
2a090 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65   int sqlite3_pre
2a0a0 70 61 72 65 31 36 28 0a 20 20 73 71 6c 69 74 65  pare16(.  sqlite
2a0b0 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
2a0c0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
2a0d0 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
2a0e0 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20  void *zSql,     
2a0f0 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
2a100 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64  nt, UTF-16 encod
2a110 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
2a120 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
2a130 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
2a140 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
2a150 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  es. */.  sqlite3
2a160 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
2a170 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
2a180 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
2a190 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61  onst void **pzTa
2a1a0 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
2a1b0 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
2a1c0 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
2a1d0 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50   */.);.SQLITE_AP
2a1e0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72  I int sqlite3_pr
2a1f0 65 70 61 72 65 31 36 5f 76 32 28 0a 20 20 73 71  epare16_v2(.  sq
2a200 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
2a210 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
2a220 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
2a230 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20  nst void *zSql, 
2a240 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
2a250 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65  tement, UTF-16 e
2a260 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
2a270 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
2a280 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
2a290 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
2a2a0 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
2a2b0 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
2a2c0 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
2a2d0 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
2a2e0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a  .  const void **
2a2f0 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
2a300 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
2a310 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
2a320 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a  zSql */.);../*.*
2a330 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 74 72  * CAPI3REF: Retr
2a340 69 65 76 69 6e 67 20 53 74 61 74 65 6d 65 6e 74  ieving Statement
2a350 20 53 51 4c 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73   SQL.**.** ^This
2a360 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62   interface can b
2a370 65 20 75 73 65 64 20 74 6f 20 72 65 74 72 69 65  e used to retrie
2a380 76 65 20 61 20 73 61 76 65 64 20 63 6f 70 79 20  ve a saved copy 
2a390 6f 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a  of the original.
2a3a0 2a 2a 20 53 51 4c 20 74 65 78 74 20 75 73 65 64  ** SQL text used
2a3b0 20 74 6f 20 63 72 65 61 74 65 20 61 20 5b 70 72   to create a [pr
2a3c0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2a3d0 5d 20 69 66 20 74 68 61 74 20 73 74 61 74 65 6d  ] if that statem
2a3e0 65 6e 74 20 77 61 73 0a 2a 2a 20 63 6f 6d 70 69  ent was.** compi
2a3f0 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72  led using either
2a400 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2a410 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69  e_v2()] or [sqli
2a420 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
2a430 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ()]..*/.SQLITE_A
2a440 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  PI const char *s
2a450 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 74  qlite3_sql(sqlit
2a460 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
2a470 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2a480 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41  : Determine If A
2a490 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20  n SQL Statement 
2a4a0 57 72 69 74 65 73 20 54 68 65 20 44 61 74 61 62  Writes The Datab
2a4b0 61 73 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ase.**.** ^The s
2a4c0 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64  qlite3_stmt_read
2a4d0 6f 6e 6c 79 28 58 29 20 69 6e 74 65 72 66 61 63  only(X) interfac
2a4e0 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28  e returns true (
2a4f0 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 0a 2a 2a 20  non-zero) if.** 
2a500 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20  and only if the 
2a510 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2a520 65 6e 74 5d 20 58 20 6d 61 6b 65 73 20 6e 6f 20  ent] X makes no 
2a530 64 69 72 65 63 74 20 63 68 61 6e 67 65 73 20 74  direct changes t
2a540 6f 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74  o.** the content
2a550 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
2a560 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74   file..**.** Not
2a570 65 20 74 68 61 74 20 5b 61 70 70 6c 69 63 61 74  e that [applicat
2a580 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
2a590 66 75 6e 63 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a  functions] or.**
2a5a0 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73   [virtual tables
2a5b0 5d 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 74  ] might change t
2a5c0 68 65 20 64 61 74 61 62 61 73 65 20 69 6e 64 69  he database indi
2a5d0 72 65 63 74 6c 79 20 61 73 20 61 20 73 69 64 65  rectly as a side
2a5e0 20 65 66 66 65 63 74 2e 20 20 0a 2a 2a 20 5e 28   effect.  .** ^(
2a5f0 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 66 20  For example, if 
2a600 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  an application d
2a610 65 66 69 6e 65 73 20 61 20 66 75 6e 63 74 69 6f  efines a functio
2a620 6e 20 22 65 76 61 6c 28 29 22 20 74 68 61 74 20  n "eval()" that 
2a630 0a 2a 2a 20 63 61 6c 6c 73 20 5b 73 71 6c 69 74  .** calls [sqlit
2a640 65 33 5f 65 78 65 63 28 29 5d 2c 20 74 68 65 6e  e3_exec()], then
2a650 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53   the following S
2a660 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 6f 75  QL statement wou
2a670 6c 64 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65  ld.** change the
2a680 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74   database file t
2a690 68 72 6f 75 67 68 20 73 69 64 65 2d 65 66 66 65  hrough side-effe
2a6a0 63 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  cts:.**.** <bloc
2a6b0 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
2a6c0 20 20 20 53 45 4c 45 43 54 20 65 76 61 6c 28 27     SELECT eval('
2a6d0 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 31 27 29  DELETE FROM t1')
2a6e0 20 46 52 4f 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70   FROM t2;.** </p
2a6f0 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
2a700 0a 2a 2a 0a 2a 2a 20 42 75 74 20 62 65 63 61 75  .**.** But becau
2a710 73 65 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20  se the [SELECT] 
2a720 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e  statement does n
2a730 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 64 61  ot change the da
2a740 74 61 62 61 73 65 20 66 69 6c 65 0a 2a 2a 20 64  tabase file.** d
2a750 69 72 65 63 74 6c 79 2c 20 73 71 6c 69 74 65 33  irectly, sqlite3
2a760 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29  _stmt_readonly()
2a770 20 77 6f 75 6c 64 20 73 74 69 6c 6c 20 72 65 74   would still ret
2a780 75 72 6e 20 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a  urn true.)^.**.*
2a790 2a 20 5e 54 72 61 6e 73 61 63 74 69 6f 6e 20 63  * ^Transaction c
2a7a0 6f 6e 74 72 6f 6c 20 73 74 61 74 65 6d 65 6e 74  ontrol statement
2a7b0 73 20 73 75 63 68 20 61 73 20 5b 42 45 47 49 4e  s such as [BEGIN
2a7c0 5d 2c 20 5b 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f  ], [COMMIT], [RO
2a7d0 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56  LLBACK],.** [SAV
2a7e0 45 50 4f 49 4e 54 5d 2c 20 61 6e 64 20 5b 52 45  EPOINT], and [RE
2a7f0 4c 45 41 53 45 5d 20 63 61 75 73 65 20 73 71 6c  LEASE] cause sql
2a800 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e  ite3_stmt_readon
2a810 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74  ly() to return t
2a820 72 75 65 2c 0a 2a 2a 20 73 69 6e 63 65 20 74 68  rue,.** since th
2a830 65 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 65  e statements the
2a840 6d 73 65 6c 76 65 73 20 64 6f 20 6e 6f 74 20 61  mselves do not a
2a850 63 74 75 61 6c 6c 79 20 6d 6f 64 69 66 79 20 74  ctually modify t
2a860 68 65 20 64 61 74 61 62 61 73 65 20 62 75 74 0a  he database but.
2a870 2a 2a 20 72 61 74 68 65 72 20 74 68 65 79 20 63  ** rather they c
2a880 6f 6e 74 72 6f 6c 20 74 68 65 20 74 69 6d 69 6e  ontrol the timin
2a890 67 20 6f 66 20 77 68 65 6e 20 6f 74 68 65 72 20  g of when other 
2a8a0 73 74 61 74 65 6d 65 6e 74 73 20 6d 6f 64 69 66  statements modif
2a8b0 79 20 74 68 65 20 0a 2a 2a 20 64 61 74 61 62 61  y the .** databa
2a8c0 73 65 2e 20 20 5e 54 68 65 20 5b 41 54 54 41 43  se.  ^The [ATTAC
2a8d0 48 5d 20 61 6e 64 20 5b 44 45 54 41 43 48 5d 20  H] and [DETACH] 
2a8e0 73 74 61 74 65 6d 65 6e 74 73 20 61 6c 73 6f 20  statements also 
2a8f0 63 61 75 73 65 0a 2a 2a 20 73 71 6c 69 74 65 33  cause.** sqlite3
2a900 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29  _stmt_readonly()
2a910 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65 20   to return true 
2a920 73 69 6e 63 65 2c 20 77 68 69 6c 65 20 74 68 6f  since, while tho
2a930 73 65 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  se statements.**
2a940 20 63 68 61 6e 67 65 20 74 68 65 20 63 6f 6e 66   change the conf
2a950 69 67 75 72 61 74 69 6f 6e 20 6f 66 20 61 20 64  iguration of a d
2a960 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2a970 6f 6e 2c 20 74 68 65 79 20 64 6f 20 6e 6f 74 20  on, they do not 
2a980 6d 61 6b 65 20 0a 2a 2a 20 63 68 61 6e 67 65 73  make .** changes
2a990 20 74 6f 20 74 68 65 20 63 6f 6e 74 65 6e 74 20   to the content 
2a9a0 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
2a9b0 66 69 6c 65 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a  files on disk..*
2a9c0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
2a9d0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65   sqlite3_stmt_re
2a9e0 61 64 6f 6e 6c 79 28 73 71 6c 69 74 65 33 5f 73  adonly(sqlite3_s
2a9f0 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
2aa00 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
2aa10 74 65 72 6d 69 6e 65 20 49 66 20 41 20 50 72 65  termine If A Pre
2aa20 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20  pared Statement 
2aa30 48 61 73 20 42 65 65 6e 20 52 65 73 65 74 0a 2a  Has Been Reset.*
2aa40 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2aa50 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 20 69  3_stmt_busy(S) i
2aa60 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
2aa70 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29   true (non-zero)
2aa80 20 69 66 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70   if the.** [prep
2aa90 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2aaa0 53 20 68 61 73 20 62 65 65 6e 20 73 74 65 70 70  S has been stepp
2aab0 65 64 20 61 74 20 6c 65 61 73 74 20 6f 6e 63 65  ed at least once
2aac0 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69   using .** [sqli
2aad0 74 65 33 5f 73 74 65 70 28 53 29 5d 20 62 75 74  te3_step(S)] but
2aae0 20 68 61 73 20 6e 6f 74 20 72 75 6e 20 74 6f 20   has not run to 
2aaf0 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 6e 64 2f 6f  completion and/o
2ab00 72 20 68 61 73 20 6e 6f 74 20 0a 2a 2a 20 62 65  r has not .** be
2ab10 65 6e 20 72 65 73 65 74 20 75 73 69 6e 67 20 5b  en reset using [
2ab20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
2ab30 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  ].  ^The sqlite3
2ab40 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 0a 2a 2a  _stmt_busy(S).**
2ab50 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2ab60 6e 73 20 66 61 6c 73 65 20 69 66 20 53 20 69 73  ns false if S is
2ab70 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
2ab80 20 20 49 66 20 53 20 69 73 20 6e 6f 74 20 61 20    If S is not a 
2ab90 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  .** NULL pointer
2aba0 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 6f   and is not a po
2abb0 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c 69 64  inter to a valid
2abc0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2abd0 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2c  ment].** object,
2abe0 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
2abf0 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20  or is undefined 
2ac00 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 75 6e 64  and probably und
2ac10 65 73 69 72 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20  esirable..**.** 
2ac20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63  This interface c
2ac30 61 6e 20 62 65 20 75 73 65 64 20 69 6e 20 63 6f  an be used in co
2ac40 6d 62 69 6e 61 74 69 6f 6e 20 5b 73 71 6c 69 74  mbination [sqlit
2ac50 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 29 5d 0a  e3_next_stmt()].
2ac60 2a 2a 20 74 6f 20 6c 6f 63 61 74 65 20 61 6c 6c  ** to locate all
2ac70 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2ac80 65 6e 74 73 20 61 73 73 6f 63 69 61 74 65 64 20  ents associated 
2ac90 77 69 74 68 20 61 20 64 61 74 61 62 61 73 65 20  with a database 
2aca0 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  .** connection t
2acb0 68 61 74 20 61 72 65 20 69 6e 20 6e 65 65 64 20  hat are in need 
2acc0 6f 66 20 62 65 69 6e 67 20 72 65 73 65 74 2e 20  of being reset. 
2acd0 20 54 68 69 73 20 63 61 6e 20 62 65 20 75 73 65   This can be use
2ace0 64 2c 0a 2a 2a 20 66 6f 72 20 65 78 61 6d 70 6c  d,.** for exampl
2acf0 65 2c 20 69 6e 20 64 69 61 67 6e 6f 73 74 69 63  e, in diagnostic
2ad00 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 73 65 61   routines to sea
2ad10 72 63 68 20 66 6f 72 20 70 72 65 70 61 72 65 64  rch for prepared
2ad20 20 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20   .** statements 
2ad30 74 68 61 74 20 61 72 65 20 68 6f 6c 64 69 6e 67  that are holding
2ad40 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 6f   a transaction o
2ad50 70 65 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  pen..*/.SQLITE_A
2ad60 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  PI int sqlite3_s
2ad70 74 6d 74 5f 62 75 73 79 28 73 71 6c 69 74 65 33  tmt_busy(sqlite3
2ad80 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _stmt*);../*.** 
2ad90 43 41 50 49 33 52 45 46 3a 20 44 79 6e 61 6d 69  CAPI3REF: Dynami
2ada0 63 61 6c 6c 79 20 54 79 70 65 64 20 56 61 6c 75  cally Typed Valu
2adb0 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57  e Object.** KEYW
2adc0 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63 74 65 64  ORDS: {protected
2add0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 20   sqlite3_value} 
2ade0 7b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  {unprotected sql
2adf0 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a  ite3_value}.**.*
2ae00 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 74 68  * SQLite uses th
2ae10 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  e sqlite3_value 
2ae20 6f 62 6a 65 63 74 20 74 6f 20 72 65 70 72 65 73  object to repres
2ae30 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a  ent all values.*
2ae40 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 73 74  * that can be st
2ae50 6f 72 65 64 20 69 6e 20 61 20 64 61 74 61 62 61  ored in a databa
2ae60 73 65 20 74 61 62 6c 65 2e 20 53 51 4c 69 74 65  se table. SQLite
2ae70 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 74 79   uses dynamic ty
2ae80 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 68 65 20  ping.** for the 
2ae90 76 61 6c 75 65 73 20 69 74 20 73 74 6f 72 65 73  values it stores
2aea0 2e 20 20 5e 56 61 6c 75 65 73 20 73 74 6f 72 65  .  ^Values store
2aeb0 64 20 69 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c  d in sqlite3_val
2aec0 75 65 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 63 61  ue objects.** ca
2aed0 6e 20 62 65 20 69 6e 74 65 67 65 72 73 2c 20 66  n be integers, f
2aee0 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61  loating point va
2aef0 6c 75 65 73 2c 20 73 74 72 69 6e 67 73 2c 20 42  lues, strings, B
2af00 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a  LOBs, or NULL..*
2af10 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33 5f  *.** An sqlite3_
2af20 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61 79  value object may
2af30 20 62 65 20 65 69 74 68 65 72 20 22 70 72 6f 74   be either "prot
2af40 65 63 74 65 64 22 20 6f 72 20 22 75 6e 70 72 6f  ected" or "unpro
2af50 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65  tected"..** Some
2af60 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75   interfaces requ
2af70 69 72 65 20 61 20 70 72 6f 74 65 63 74 65 64 20  ire a protected 
2af80 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20  sqlite3_value.  
2af90 4f 74 68 65 72 20 69 6e 74 65 72 66 61 63 65 73  Other interfaces
2afa0 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70 74 20  .** will accept 
2afb0 65 69 74 68 65 72 20 61 20 70 72 6f 74 65 63 74  either a protect
2afc0 65 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65  ed or an unprote
2afd0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2afe0 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e 74  ue..** Every int
2aff0 65 72 66 61 63 65 20 74 68 61 74 20 61 63 63 65  erface that acce
2b000 70 74 73 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  pts sqlite3_valu
2b010 65 20 61 72 67 75 6d 65 6e 74 73 20 73 70 65 63  e arguments spec
2b020 69 66 69 65 73 0a 2a 2a 20 77 68 65 74 68 65 72  ifies.** whether
2b030 20 6f 72 20 6e 6f 74 20 69 74 20 72 65 71 75 69   or not it requi
2b040 72 65 73 20 61 20 70 72 6f 74 65 63 74 65 64 20  res a protected 
2b050 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a  sqlite3_value..*
2b060 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73 20 22  *.** The terms "
2b070 70 72 6f 74 65 63 74 65 64 22 20 61 6e 64 20 22  protected" and "
2b080 75 6e 70 72 6f 74 65 63 74 65 64 22 20 72 65 66  unprotected" ref
2b090 65 72 20 74 6f 20 77 68 65 74 68 65 72 20 6f 72  er to whether or
2b0a0 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20   not.** a mutex 
2b0b0 69 73 20 68 65 6c 64 2e 20 20 41 6e 20 69 6e 74  is held.  An int
2b0c0 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 73 20 68  ernal mutex is h
2b0d0 65 6c 64 20 66 6f 72 20 61 20 70 72 6f 74 65 63  eld for a protec
2b0e0 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  ted.** sqlite3_v
2b0f0 61 6c 75 65 20 6f 62 6a 65 63 74 20 62 75 74 20  alue object but 
2b100 6e 6f 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64  no mutex is held
2b110 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63   for an unprotec
2b120 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  ted.** sqlite3_v
2b130 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20 49 66  alue object.  If
2b140 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
2b150 6c 65 64 20 74 6f 20 62 65 20 73 69 6e 67 6c 65  led to be single
2b160 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 28 77 69  -threaded.** (wi
2b170 74 68 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  th [SQLITE_THREA
2b180 44 53 41 46 45 3d 30 5d 20 61 6e 64 20 77 69 74  DSAFE=0] and wit
2b190 68 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61  h [sqlite3_threa
2b1a0 64 73 61 66 65 28 29 5d 20 72 65 74 75 72 6e 69  dsafe()] returni
2b1b0 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53  ng 0).** or if S
2b1c0 51 4c 69 74 65 20 69 73 20 72 75 6e 20 69 6e 20  QLite is run in 
2b1d0 6f 6e 65 20 6f 66 20 72 65 64 75 63 65 64 20 6d  one of reduced m
2b1e0 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b  utex modes .** [
2b1f0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
2b200 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f 72 20 5b  NGLETHREAD] or [
2b210 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
2b220 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68  LTITHREAD].** th
2b230 65 6e 20 74 68 65 72 65 20 69 73 20 6e 6f 20 64  en there is no d
2b240 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65  istinction betwe
2b250 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64  en protected and
2b260 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20   unprotected.** 
2b270 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
2b280 6a 65 63 74 73 20 61 6e 64 20 74 68 65 79 20 63  jects and they c
2b290 61 6e 20 62 65 20 75 73 65 64 20 69 6e 74 65 72  an be used inter
2b2a0 63 68 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77  changeably.  How
2b2b0 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78  ever,.** for max
2b2c0 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74 61 62  imum code portab
2b2d0 69 6c 69 74 79 20 69 74 20 69 73 20 72 65 63 6f  ility it is reco
2b2e0 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70  mmended that app
2b2f0 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69  lications.** sti
2b300 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74  ll make the dist
2b310 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20  inction between 
2b320 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e  protected and un
2b330 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
2b340 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
2b350 74 73 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74  ts even when not
2b360 20 73 74 72 69 63 74 6c 79 20 72 65 71 75 69 72   strictly requir
2b370 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
2b380 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
2b390 65 63 74 73 20 74 68 61 74 20 61 72 65 20 70 61  ects that are pa
2b3a0 73 73 65 64 20 61 73 20 70 61 72 61 6d 65 74 65  ssed as paramete
2b3b0 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69  rs into the.** i
2b3c0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
2b3d0 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   [application-de
2b3e0 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
2b3f0 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74 65 63 74  ons] are protect
2b400 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  ed..** ^The sqli
2b410 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
2b420 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
2b430 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2b440 76 61 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 72  value()] is unpr
2b450 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72  otected..** Unpr
2b460 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2b470 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d 61  value objects ma
2b480 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77  y only be used w
2b490 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ith.** [sqlite3_
2b4a0 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20  result_value()] 
2b4b0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  and [sqlite3_bin
2b4c0 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54  d_value()]..** T
2b4d0 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
2b4e0 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33  e_blob | sqlite3
2b4f0 5f 76 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 66  _value_type()] f
2b500 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65  amily of.** inte
2b510 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20 70  rfaces require p
2b520 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2b530 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a  _value objects..
2b540 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
2b550 74 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76 61  t Mem sqlite3_va
2b560 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  lue;../*.** CAPI
2b570 33 52 45 46 3a 20 53 51 4c 20 46 75 6e 63 74 69  3REF: SQL Functi
2b580 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63  on Context Objec
2b590 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74  t.**.** The cont
2b5a0 65 78 74 20 69 6e 20 77 68 69 63 68 20 61 6e 20  ext in which an 
2b5b0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78 65  SQL function exe
2b5c0 63 75 74 65 73 20 69 73 20 73 74 6f 72 65 64 20  cutes is stored 
2b5d0 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33  in an.** sqlite3
2b5e0 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e  _context object.
2b5f0 20 20 5e 41 20 70 6f 69 6e 74 65 72 20 74 6f 20    ^A pointer to 
2b600 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  an sqlite3_conte
2b610 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20  xt object.** is 
2b620 61 6c 77 61 79 73 20 66 69 72 73 74 20 70 61 72  always first par
2b630 61 6d 65 74 65 72 20 74 6f 20 5b 61 70 70 6c 69  ameter to [appli
2b640 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
2b650 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a  QL functions]..*
2b660 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
2b670 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
2b680 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
2b690 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20  ation will pass 
2b6a0 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  this.** pointer 
2b6b0 74 68 72 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c  through into cal
2b6c0 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  ls to [sqlite3_r
2b6d0 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69  esult_int | sqli
2b6e0 74 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a  te3_result()],.*
2b6f0 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65  * [sqlite3_aggre
2b700 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c  gate_context()],
2b710 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64   [sqlite3_user_d
2b720 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ata()],.** [sqli
2b730 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68  te3_context_db_h
2b740 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74  andle()], [sqlit
2b750 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29  e3_get_auxdata()
2b760 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71  ],.** and/or [sq
2b770 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
2b780 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  a()]..*/.typedef
2b790 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
2b7a0 63 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 33 5f  context sqlite3_
2b7b0 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20  context;../*.** 
2b7c0 43 41 50 49 33 52 45 46 3a 20 42 69 6e 64 69 6e  CAPI3REF: Bindin
2b7d0 67 20 56 61 6c 75 65 73 20 54 6f 20 50 72 65 70  g Values To Prep
2b7e0 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 73 0a  ared Statements.
2b7f0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68 6f  ** KEYWORDS: {ho
2b800 73 74 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 68  st parameter} {h
2b810 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 7d 20  ost parameters} 
2b820 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20  {host parameter 
2b830 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  name}.** KEYWORD
2b840 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65  S: {SQL paramete
2b850 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65  r} {SQL paramete
2b860 72 73 7d 20 7b 70 61 72 61 6d 65 74 65 72 20 62  rs} {parameter b
2b870 69 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20 5e 28  inding}.**.** ^(
2b880 49 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  In the SQL state
2b890 6d 65 6e 74 20 74 65 78 74 20 69 6e 70 75 74 20  ment text input 
2b8a0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  to [sqlite3_prep
2b8b0 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 69 74  are_v2()] and it
2b8c0 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c  s variants,.** l
2b8d0 69 74 65 72 61 6c 73 20 6d 61 79 20 62 65 20 72  iterals may be r
2b8e0 65 70 6c 61 63 65 64 20 62 79 20 61 20 5b 70 61  eplaced by a [pa
2b8f0 72 61 6d 65 74 65 72 5d 20 74 68 61 74 20 6d 61  rameter] that ma
2b900 74 63 68 65 73 20 6f 6e 65 20 6f 66 20 66 6f 6c  tches one of fol
2b910 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61  lowing.** templa
2b920 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  tes:.**.** <ul>.
2b930 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c  ** <li>  ?.** <l
2b940 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e  i>  ?NNN.** <li>
2b950 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20    :VVV.** <li>  
2b960 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56  @VVV.** <li>  $V
2b970 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  VV.** </ul>.**.*
2b980 2a 20 49 6e 20 74 68 65 20 74 65 6d 70 6c 61 74  * In the templat
2b990 65 73 20 61 62 6f 76 65 2c 20 4e 4e 4e 20 72 65  es above, NNN re
2b9a0 70 72 65 73 65 6e 74 73 20 61 6e 20 69 6e 74 65  presents an inte
2b9b0 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20  ger literal,.** 
2b9c0 61 6e 64 20 56 56 56 20 72 65 70 72 65 73 65 6e  and VVV represen
2b9d0 74 73 20 61 6e 20 61 6c 70 68 61 6e 75 6d 65 72  ts an alphanumer
2b9e0 69 63 20 69 64 65 6e 74 69 66 69 65 72 2e 29 5e  ic identifier.)^
2b9f0 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20 6f 66    ^The values of
2ba00 20 74 68 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65   these.** parame
2ba10 74 65 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65  ters (also calle
2ba20 64 20 22 68 6f 73 74 20 70 61 72 61 6d 65 74 65  d "host paramete
2ba30 72 20 6e 61 6d 65 73 22 20 6f 72 20 22 53 51 4c  r names" or "SQL
2ba40 20 70 61 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a   parameters").**
2ba50 20 63 61 6e 20 62 65 20 73 65 74 20 75 73 69 6e   can be set usin
2ba60 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  g the sqlite3_bi
2ba70 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20  nd_*() routines 
2ba80 64 65 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a  defined here..**
2ba90 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61  .** ^The first a
2baa0 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73  rgument to the s
2bab0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
2bac0 72 6f 75 74 69 6e 65 73 20 69 73 20 61 6c 77 61  routines is alwa
2bad0 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20  ys.** a pointer 
2bae0 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
2baf0 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65 74  stmt] object ret
2bb00 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73  urned from.** [s
2bb10 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2bb20 32 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69  2()] or its vari
2bb30 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ants..**.** ^The
2bb40 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
2bb50 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66   is the index of
2bb60 20 74 68 65 20 53 51 4c 20 70 61 72 61 6d 65 74   the SQL paramet
2bb70 65 72 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a 2a  er to be set..**
2bb80 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 53   ^The leftmost S
2bb90 51 4c 20 70 61 72 61 6d 65 74 65 72 20 68 61 73  QL parameter has
2bba0 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e 20   an index of 1. 
2bbb0 20 5e 57 68 65 6e 20 74 68 65 20 73 61 6d 65 20   ^When the same 
2bbc0 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61 72  named.** SQL par
2bbd0 61 6d 65 74 65 72 20 69 73 20 75 73 65 64 20 6d  ameter is used m
2bbe0 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73  ore than once, s
2bbf0 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71  econd and subseq
2bc00 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e  uent.** occurren
2bc10 63 65 73 20 68 61 76 65 20 74 68 65 20 73 61 6d  ces have the sam
2bc20 65 20 69 6e 64 65 78 20 61 73 20 74 68 65 20 66  e index as the f
2bc30 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63 65 2e  irst occurrence.
2bc40 0a 2a 2a 20 5e 54 68 65 20 69 6e 64 65 78 20 66  .** ^The index f
2bc50 6f 72 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74  or named paramet
2bc60 65 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65  ers can be looke
2bc70 64 20 75 70 20 75 73 69 6e 67 20 74 68 65 0a 2a  d up using the.*
2bc80 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
2bc90 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
2bca0 29 5d 20 41 50 49 20 69 66 20 64 65 73 69 72 65  )] API if desire
2bcb0 64 2e 20 20 5e 54 68 65 20 69 6e 64 65 78 0a 2a  d.  ^The index.*
2bcc0 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72  * for "?NNN" par
2bcd0 61 6d 65 74 65 72 73 20 69 73 20 74 68 65 20 76  ameters is the v
2bce0 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20  alue of NNN..** 
2bcf0 5e 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d  ^The NNN value m
2bd00 75 73 74 20 62 65 20 62 65 74 77 65 65 6e 20 31  ust be between 1
2bd10 20 61 6e 64 20 74 68 65 20 5b 73 71 6c 69 74 65   and the [sqlite
2bd20 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 70 61  3_limit()].** pa
2bd30 72 61 6d 65 74 65 72 20 5b 53 51 4c 49 54 45 5f  rameter [SQLITE_
2bd40 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e  LIMIT_VARIABLE_N
2bd50 55 4d 42 45 52 5d 20 28 64 65 66 61 75 6c 74 20  UMBER] (default 
2bd60 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a  value: 999)..**.
2bd70 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61 72  ** ^The third ar
2bd80 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 76 61  gument is the va
2bd90 6c 75 65 20 74 6f 20 62 69 6e 64 20 74 6f 20 74  lue to bind to t
2bda0 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  he parameter..**
2bdb0 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f 73 65 20 72  .** ^(In those r
2bdc0 6f 75 74 69 6e 65 73 20 74 68 61 74 20 68 61 76  outines that hav
2bdd0 65 20 61 20 66 6f 75 72 74 68 20 61 72 67 75 6d  e a fourth argum
2bde0 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 65 20 69  ent, its value i
2bdf0 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20  s the.** number 
2be00 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  of bytes in the 
2be10 70 61 72 61 6d 65 74 65 72 2e 20 20 54 6f 20 62  parameter.  To b
2be20 65 20 63 6c 65 61 72 3a 20 74 68 65 20 76 61 6c  e clear: the val
2be30 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d  ue is the.** num
2be40 62 65 72 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c  ber of <u>bytes<
2be50 2f 75 3e 20 69 6e 20 74 68 65 20 76 61 6c 75 65  /u> in the value
2be60 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72  , not the number
2be70 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 29   of characters.)
2be80 5e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 6f 75  ^.** ^If the fou
2be90 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
2bea0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
2beb0 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  xt() or sqlite3_
2bec0 62 69 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a  bind_text16().**
2bed0 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
2bee0 65 6e 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66  en the length of
2bef0 20 74 68 65 20 73 74 72 69 6e 67 20 69 73 0a 2a   the string is.*
2bf00 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
2bf10 62 79 74 65 73 20 75 70 20 74 6f 20 74 68 65 20  bytes up to the 
2bf20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69  first zero termi
2bf30 6e 61 74 6f 72 2e 0a 2a 2a 20 49 66 20 74 68 65  nator..** If the
2bf40 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
2bf50 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  r to sqlite3_bin
2bf60 64 5f 62 6c 6f 62 28 29 20 69 73 20 6e 65 67 61  d_blob() is nega
2bf70 74 69 76 65 2c 20 74 68 65 6e 0a 2a 2a 20 74 68  tive, then.** th
2bf80 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e  e behavior is un
2bf90 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 61  defined..** If a
2bfa0 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 66 6f   non-negative fo
2bfb0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
2bfc0 73 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 71  s provided to sq
2bfd0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
2bfe0 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  ).** or sqlite3_
2bff0 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 74 68  bind_text16() th
2c000 65 6e 20 74 68 61 74 20 70 61 72 61 6d 65 74 65  en that paramete
2c010 72 20 6d 75 73 74 20 62 65 20 74 68 65 20 62 79  r must be the by
2c020 74 65 20 6f 66 66 73 65 74 0a 2a 2a 20 77 68 65  te offset.** whe
2c030 72 65 20 74 68 65 20 4e 55 4c 20 74 65 72 6d 69  re the NUL termi
2c040 6e 61 74 6f 72 20 77 6f 75 6c 64 20 6f 63 63 75  nator would occu
2c050 72 20 61 73 73 75 6d 69 6e 67 20 74 68 65 20 73  r assuming the s
2c060 74 72 69 6e 67 20 77 65 72 65 20 4e 55 4c 0a 2a  tring were NUL.*
2c070 2a 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 49  * terminated.  I
2c080 66 20 61 6e 79 20 4e 55 4c 20 63 68 61 72 61 63  f any NUL charac
2c090 74 65 72 73 20 6f 63 63 75 72 20 61 74 20 62 79  ters occur at by
2c0a0 74 65 20 6f 66 66 73 65 74 73 20 6c 65 73 73 20  te offsets less 
2c0b0 74 68 61 6e 20 0a 2a 2a 20 74 68 65 20 76 61 6c  than .** the val
2c0c0 75 65 20 6f 66 20 74 68 65 20 66 6f 75 72 74 68  ue of the fourth
2c0d0 20 70 61 72 61 6d 65 74 65 72 20 74 68 65 6e 20   parameter then 
2c0e0 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74  the resulting st
2c0f0 72 69 6e 67 20 76 61 6c 75 65 20 77 69 6c 6c 0a  ring value will.
2c100 2a 2a 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64  ** contain embed
2c110 64 65 64 20 4e 55 4c 73 2e 20 20 54 68 65 20 72  ded NULs.  The r
2c120 65 73 75 6c 74 20 6f 66 20 65 78 70 72 65 73 73  esult of express
2c130 69 6f 6e 73 20 69 6e 76 6f 6c 76 69 6e 67 20 73  ions involving s
2c140 74 72 69 6e 67 73 0a 2a 2a 20 77 69 74 68 20 65  trings.** with e
2c150 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 69 73 20  mbedded NULs is 
2c160 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
2c170 20 5e 54 68 65 20 66 69 66 74 68 20 61 72 67 75   ^The fifth argu
2c180 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
2c190 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 20 73 71 6c  bind_blob(), sql
2c1a0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29  ite3_bind_text()
2c1b0 2c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33  , and.** sqlite3
2c1c0 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 69  _bind_text16() i
2c1d0 73 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 75  s a destructor u
2c1e0 73 65 64 20 74 6f 20 64 69 73 70 6f 73 65 20 6f  sed to dispose o
2c1f0 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a  f the BLOB or.**
2c200 20 73 74 72 69 6e 67 20 61 66 74 65 72 20 53 51   string after SQ
2c210 4c 69 74 65 20 68 61 73 20 66 69 6e 69 73 68 65  Lite has finishe
2c220 64 20 77 69 74 68 20 69 74 2e 20 20 5e 54 68 65  d with it.  ^The
2c230 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 63   destructor is c
2c240 61 6c 6c 65 64 0a 2a 2a 20 74 6f 20 64 69 73 70  alled.** to disp
2c250 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20  ose of the BLOB 
2c260 6f 72 20 73 74 72 69 6e 67 20 65 76 65 6e 20 69  or string even i
2c270 66 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 73 71  f the call to sq
2c280 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28  lite3_bind_blob(
2c290 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69  ),.** sqlite3_bi
2c2a0 6e 64 5f 74 65 78 74 28 29 2c 20 6f 72 20 73 71  nd_text(), or sq
2c2b0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
2c2c0 36 28 29 20 66 61 69 6c 73 2e 20 20 0a 2a 2a 20  6() fails.  .** 
2c2d0 5e 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72  ^If the fifth ar
2c2e0 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65  gument is.** the
2c2f0 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 20 5b   special value [
2c300 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20  SQLITE_STATIC], 
2c310 74 68 65 6e 20 53 51 4c 69 74 65 20 61 73 73 75  then SQLite assu
2c320 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  mes that the.** 
2c330 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69  information is i
2c340 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61  n static, unmana
2c350 67 65 64 20 73 70 61 63 65 20 61 6e 64 20 64 6f  ged space and do
2c360 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62  es not need to b
2c370 65 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20  e freed..** ^If 
2c380 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65  the fifth argume
2c390 6e 74 20 68 61 73 20 74 68 65 20 76 61 6c 75 65  nt has the value
2c3a0 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45   [SQLITE_TRANSIE
2c3b0 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c  NT], then.** SQL
2c3c0 69 74 65 20 6d 61 6b 65 73 20 69 74 73 20 6f 77  ite makes its ow
2c3d0 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f  n private copy o
2c3e0 66 20 74 68 65 20 64 61 74 61 20 69 6d 6d 65 64  f the data immed
2c3f0 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a  iately, before.*
2c400 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  * the sqlite3_bi
2c410 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20 72  nd_*() routine r
2c420 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  eturns..**.** ^T
2c430 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
2c440 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69  zeroblob() routi
2c450 6e 65 20 62 69 6e 64 73 20 61 20 42 4c 4f 42 20  ne binds a BLOB 
2c460 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74 68 61 74  of length N that
2c470 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20 77 69  .** is filled wi
2c480 74 68 20 7a 65 72 6f 65 73 2e 20 20 5e 41 20 7a  th zeroes.  ^A z
2c490 65 72 6f 62 6c 6f 62 20 75 73 65 73 20 61 20 66  eroblob uses a f
2c4a0 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d  ixed amount of m
2c4b0 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61  emory.** (just a
2c4c0 6e 20 69 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c  n integer to hol
2c4d0 64 20 69 74 73 20 73 69 7a 65 29 20 77 68 69 6c  d its size) whil
2c4e0 65 20 69 74 20 69 73 20 62 65 69 6e 67 20 70 72  e it is being pr
2c4f0 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f  ocessed..** Zero
2c500 62 6c 6f 62 73 20 61 72 65 20 69 6e 74 65 6e 64  blobs are intend
2c510 65 64 20 74 6f 20 73 65 72 76 65 20 61 73 20 70  ed to serve as p
2c520 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20  laceholders for 
2c530 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63  BLOBs whose.** c
2c540 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74 65 72 20  ontent is later 
2c550 77 72 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a  written using.**
2c560 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f   [sqlite3_blob_o
2c570 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61  pen | incrementa
2c580 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74  l BLOB I/O] rout
2c590 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61  ines..** ^A nega
2c5a0 74 69 76 65 20 76 61 6c 75 65 20 66 6f 72 20 74  tive value for t
2c5b0 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75  he zeroblob resu
2c5c0 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65  lts in a zero-le
2c5d0 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a  ngth BLOB..**.**
2c5e0 20 5e 49 66 20 61 6e 79 20 6f 66 20 74 68 65 20   ^If any of the 
2c5f0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
2c600 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61   routines are ca
2c610 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c  lled with a NULL
2c620 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f 72 20   pointer.** for 
2c630 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
2c640 61 74 65 6d 65 6e 74 5d 20 6f 72 20 77 69 74 68  atement] or with
2c650 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74   a prepared stat
2c660 65 6d 65 6e 74 20 66 6f 72 20 77 68 69 63 68 0a  ement for which.
2c670 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
2c680 28 29 5d 20 68 61 73 20 62 65 65 6e 20 63 61 6c  ()] has been cal
2c690 6c 65 64 20 6d 6f 72 65 20 72 65 63 65 6e 74 6c  led more recentl
2c6a0 79 20 74 68 61 6e 20 5b 73 71 6c 69 74 65 33 5f  y than [sqlite3_
2c6b0 72 65 73 65 74 28 29 5d 2c 0a 2a 2a 20 74 68 65  reset()],.** the
2c6c0 6e 20 74 68 65 20 63 61 6c 6c 20 77 69 6c 6c 20  n the call will 
2c6d0 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4d  return [SQLITE_M
2c6e0 49 53 55 53 45 5d 2e 20 20 49 66 20 61 6e 79 20  ISUSE].  If any 
2c6f0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 28 29 0a  sqlite3_bind_().
2c700 2a 2a 20 72 6f 75 74 69 6e 65 20 69 73 20 70 61  ** routine is pa
2c710 73 73 65 64 20 61 20 5b 70 72 65 70 61 72 65 64  ssed a [prepared
2c720 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
2c730 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69   has been finali
2c740 7a 65 64 2c 20 74 68 65 0a 2a 2a 20 72 65 73 75  zed, the.** resu
2c750 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20  lt is undefined 
2c760 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 68 61 72  and probably har
2c770 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e  mful..**.** ^Bin
2c780 64 69 6e 67 73 20 61 72 65 20 6e 6f 74 20 63 6c  dings are not cl
2c790 65 61 72 65 64 20 62 79 20 74 68 65 20 5b 73 71  eared by the [sq
2c7a0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 72  lite3_reset()] r
2c7b0 6f 75 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f  outine..** ^Unbo
2c7c0 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73 20 61  und parameters a
2c7d0 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  re interpreted a
2c7e0 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54  s NULL..**.** ^T
2c7f0 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
2c800 2a 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  * routines retur
2c810 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e  n [SQLITE_OK] on
2c820 20 73 75 63 63 65 73 73 20 6f 72 20 61 6e 0a 2a   success or an.*
2c830 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  * [error code] i
2c840 66 20 61 6e 79 74 68 69 6e 67 20 67 6f 65 73 20  f anything goes 
2c850 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49  wrong..** ^[SQLI
2c860 54 45 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 74  TE_RANGE] is ret
2c870 75 72 6e 65 64 20 69 66 20 74 68 65 20 70 61 72  urned if the par
2c880 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20  ameter.** index 
2c890 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e  is out of range.
2c8a0 20 20 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d    ^[SQLITE_NOMEM
2c8b0 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66  ] is returned if
2c8c0 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e   malloc() fails.
2c8d0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
2c8e0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
2c8f0 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29  arameter_count()
2c900 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
2c910 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
2c920 6d 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69  me()], and [sqli
2c930 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
2c940 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a  er_index()]..*/.
2c950 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
2c960 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
2c970 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2c980 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  int, const void*
2c990 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29  , int n, void(*)
2c9a0 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45  (void*));.SQLITE
2c9b0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
2c9c0 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73 71 6c  _bind_double(sql
2c9d0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
2c9e0 20 64 6f 75 62 6c 65 29 3b 0a 53 51 4c 49 54 45   double);.SQLITE
2c9f0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
2ca00 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65  _bind_int(sqlite
2ca10 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e  3_stmt*, int, in
2ca20 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  t);.SQLITE_API i
2ca30 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
2ca40 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74  int64(sqlite3_st
2ca50 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65  mt*, int, sqlite
2ca60 33 5f 69 6e 74 36 34 29 3b 0a 53 51 4c 49 54 45  3_int64);.SQLITE
2ca70 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
2ca80 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69 74  _bind_null(sqlit
2ca90 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a  e3_stmt*, int);.
2caa0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
2cab0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
2cac0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2cad0 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a  int, const char*
2cae0 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29  , int n, void(*)
2caf0 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45  (void*));.SQLITE
2cb00 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
2cb10 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 73 71 6c  _bind_text16(sql
2cb20 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
2cb30 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
2cb40 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  t, void(*)(void*
2cb50 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  ));.SQLITE_API i
2cb60 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
2cb70 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74  value(sqlite3_st
2cb80 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
2cb90 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
2cba0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2cbb0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72  sqlite3_bind_zer
2cbc0 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74  oblob(sqlite3_st
2cbd0 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29  mt*, int, int n)
2cbe0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2cbf0 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c  F: Number Of SQL
2cc00 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a   Parameters.**.*
2cc10 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20  * ^This routine 
2cc20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 66  can be used to f
2cc30 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ind the number o
2cc40 66 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  f [SQL parameter
2cc50 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 72 65 70  s].** in a [prep
2cc60 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
2cc70 20 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73    SQL parameters
2cc80 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74   are tokens of t
2cc90 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20  he.** form "?", 
2cca0 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20  "?NNN", ":AAA", 
2ccb0 22 24 41 41 41 22 2c 20 6f 72 20 22 40 41 41 41  "$AAA", or "@AAA
2ccc0 22 20 74 68 61 74 20 73 65 72 76 65 20 61 73 0a  " that serve as.
2ccd0 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20  ** placeholders 
2cce0 66 6f 72 20 76 61 6c 75 65 73 20 74 68 61 74 20  for values that 
2ccf0 61 72 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  are [sqlite3_bin
2cd00 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a  d_blob | bound].
2cd10 2a 2a 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65  ** to the parame
2cd20 74 65 72 73 20 61 74 20 61 20 6c 61 74 65 72 20  ters at a later 
2cd30 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  time..**.** ^(Th
2cd40 69 73 20 72 6f 75 74 69 6e 65 20 61 63 74 75 61  is routine actua
2cd50 6c 6c 79 20 72 65 74 75 72 6e 73 20 74 68 65 20  lly returns the 
2cd60 69 6e 64 65 78 20 6f 66 20 74 68 65 20 6c 61 72  index of the lar
2cd70 67 65 73 74 20 28 72 69 67 68 74 6d 6f 73 74 29  gest (rightmost)
2cd80 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 46  .** parameter. F
2cd90 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63  or all forms exc
2cda0 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77  ept ?NNN, this w
2cdb0 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20 74  ill correspond t
2cdc0 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20  o the.** number 
2cdd0 6f 66 20 75 6e 69 71 75 65 20 70 61 72 61 6d 65  of unique parame
2cde0 74 65 72 73 2e 20 20 49 66 20 70 61 72 61 6d 65  ters.  If parame
2cdf0 74 65 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e  ters of the ?NNN
2ce00 20 66 6f 72 6d 20 61 72 65 20 75 73 65 64 2c 0a   form are used,.
2ce10 2a 2a 20 74 68 65 72 65 20 6d 61 79 20 62 65 20  ** there may be 
2ce20 67 61 70 73 20 69 6e 20 74 68 65 20 6c 69 73 74  gaps in the list
2ce30 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  .)^.**.** See al
2ce40 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  so: [sqlite3_bin
2ce50 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62  d_blob|sqlite3_b
2ce60 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ind()],.** [sqli
2ce70 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
2ce80 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a  er_name()], and.
2ce90 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
2cea0 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
2ceb0 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ()]..*/.SQLITE_A
2cec0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  PI int sqlite3_b
2ced0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f  ind_parameter_co
2cee0 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  unt(sqlite3_stmt
2cef0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
2cf00 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48  REF: Name Of A H
2cf10 6f 73 74 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a  ost Parameter.**
2cf20 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2cf30 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2cf40 6e 61 6d 65 28 50 2c 4e 29 20 69 6e 74 65 72 66  name(P,N) interf
2cf50 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74  ace returns.** t
2cf60 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e  he name of the N
2cf70 2d 74 68 20 5b 53 51 4c 20 70 61 72 61 6d 65 74  -th [SQL paramet
2cf80 65 72 5d 20 69 6e 20 74 68 65 20 5b 70 72 65 70  er] in the [prep
2cf90 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2cfa0 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20 70 61 72 61  P..** ^(SQL para
2cfb0 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f  meters of the fo
2cfc0 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41  rm "?NNN" or ":A
2cfd0 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72  AA" or "@AAA" or
2cfe0 20 22 24 41 41 41 22 0a 2a 2a 20 68 61 76 65 20   "$AAA".** have 
2cff0 61 20 6e 61 6d 65 20 77 68 69 63 68 20 69 73 20  a name which is 
2d000 74 68 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e  the string "?NNN
2d010 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22  " or ":AAA" or "
2d020 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a  @AAA" or "$AAA".
2d030 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  ** respectively.
2d040 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  .** In other wor
2d050 64 73 2c 20 74 68 65 20 69 6e 69 74 69 61 6c 20  ds, the initial 
2d060 22 3a 22 20 6f 72 20 22 24 22 20 6f 72 20 22 40  ":" or "$" or "@
2d070 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69  " or "?".** is i
2d080 6e 63 6c 75 64 65 64 20 61 73 20 70 61 72 74 20  ncluded as part 
2d090 6f 66 20 74 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a  of the name.)^.*
2d0a0 2a 20 5e 50 61 72 61 6d 65 74 65 72 73 20 6f 66  * ^Parameters of
2d0b0 20 74 68 65 20 66 6f 72 6d 20 22 3f 22 20 77 69   the form "?" wi
2d0c0 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e  thout a followin
2d0d0 67 20 69 6e 74 65 67 65 72 20 68 61 76 65 20 6e  g integer have n
2d0e0 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72  o name.** and ar
2d0f0 65 20 72 65 66 65 72 72 65 64 20 74 6f 20 61 73  e referred to as
2d100 20 22 6e 61 6d 65 6c 65 73 73 22 20 6f 72 20 22   "nameless" or "
2d110 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65  anonymous parame
2d120 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ters"..**.** ^Th
2d130 65 20 66 69 72 73 74 20 68 6f 73 74 20 70 61 72  e first host par
2d140 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e  ameter has an in
2d150 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e  dex of 1, not 0.
2d160 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 76  .**.** ^If the v
2d170 61 6c 75 65 20 4e 20 69 73 20 6f 75 74 20 6f 66  alue N is out of
2d180 20 72 61 6e 67 65 20 6f 72 20 69 66 20 74 68 65   range or if the
2d190 20 4e 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20   N-th parameter 
2d1a0 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20  is.** nameless, 
2d1b0 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74  then NULL is ret
2d1c0 75 72 6e 65 64 2e 20 20 5e 54 68 65 20 72 65 74  urned.  ^The ret
2d1d0 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 0a  urned string is.
2d1e0 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20 55 54 46  ** always in UTF
2d1f0 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e  -8 encoding even
2d200 20 69 66 20 74 68 65 20 6e 61 6d 65 64 20 70 61   if the named pa
2d210 72 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f  rameter was.** o
2d220 72 69 67 69 6e 61 6c 6c 79 20 73 70 65 63 69 66  riginally specif
2d230 69 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e  ied as UTF-16 in
2d240 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2d250 65 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  e16()] or.** [sq
2d260 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
2d270 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  v2()]..**.** See
2d280 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
2d290 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
2d2a0 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73  3_bind()],.** [s
2d2b0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2d2c0 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20  meter_count()], 
2d2d0 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
2d2e0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
2d2f0 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49  ndex()]..*/.SQLI
2d300 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61  TE_API const cha
2d310 72 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  r *sqlite3_bind_
2d320 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73  parameter_name(s
2d330 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2d340 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
2d350 52 45 46 3a 20 49 6e 64 65 78 20 4f 66 20 41 20  REF: Index Of A 
2d360 50 61 72 61 6d 65 74 65 72 20 57 69 74 68 20 41  Parameter With A
2d370 20 47 69 76 65 6e 20 4e 61 6d 65 0a 2a 2a 0a 2a   Given Name.**.*
2d380 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20 69 6e  * ^Return the in
2d390 64 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 70 61  dex of an SQL pa
2d3a0 72 61 6d 65 74 65 72 20 67 69 76 65 6e 20 69 74  rameter given it
2d3b0 73 20 6e 61 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a  s name.  ^The.**
2d3c0 20 69 6e 64 65 78 20 76 61 6c 75 65 20 72 65 74   index value ret
2d3d0 75 72 6e 65 64 20 69 73 20 73 75 69 74 61 62 6c  urned is suitabl
2d3e0 65 20 66 6f 72 20 75 73 65 20 61 73 20 74 68 65  e for use as the
2d3f0 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d   second.** param
2d400 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
2d410 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74  _bind_blob|sqlit
2d420 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20 5e 41 20  e3_bind()].  ^A 
2d430 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72  zero.** is retur
2d440 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74 63 68 69  ned if no matchi
2d450 6e 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  ng parameter is 
2d460 66 6f 75 6e 64 2e 20 20 5e 54 68 65 20 70 61 72  found.  ^The par
2d470 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d  ameter.** name m
2d480 75 73 74 20 62 65 20 67 69 76 65 6e 20 69 6e 20  ust be given in 
2d490 55 54 46 2d 38 20 65 76 65 6e 20 69 66 20 74 68  UTF-8 even if th
2d4a0 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65  e original state
2d4b0 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65 70  ment.** was prep
2d4c0 61 72 65 64 20 66 72 6f 6d 20 55 54 46 2d 31 36  ared from UTF-16
2d4d0 20 74 65 78 74 20 75 73 69 6e 67 20 5b 73 71 6c   text using [sql
2d4e0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
2d4f0 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  2()]..**.** See 
2d500 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62  also: [sqlite3_b
2d510 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33  ind_blob|sqlite3
2d520 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71  _bind()],.** [sq
2d530 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2d540 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61  eter_count()], a
2d550 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  nd.** [sqlite3_b
2d560 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
2d570 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54  dex()]..*/.SQLIT
2d580 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
2d590 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2d5a0 5f 69 6e 64 65 78 28 73 71 6c 69 74 65 33 5f 73  _index(sqlite3_s
2d5b0 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  tmt*, const char
2d5c0 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a   *zName);../*.**
2d5d0 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74   CAPI3REF: Reset
2d5e0 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e   All Bindings On
2d5f0 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74   A Prepared Stat
2d600 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e  ement.**.** ^Con
2d610 74 72 61 72 79 20 74 6f 20 74 68 65 20 69 6e 74  trary to the int
2d620 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20  uition of many, 
2d630 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2d640 5d 20 64 6f 65 73 20 6e 6f 74 20 72 65 73 65 74  ] does not reset
2d650 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33  .** the [sqlite3
2d660 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e  _bind_blob | bin
2d670 64 69 6e 67 73 5d 20 6f 6e 20 61 20 5b 70 72 65  dings] on a [pre
2d680 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2d690 2e 0a 2a 2a 20 5e 55 73 65 20 74 68 69 73 20 72  ..** ^Use this r
2d6a0 6f 75 74 69 6e 65 20 74 6f 20 72 65 73 65 74 20  outine to reset 
2d6b0 61 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d 65 74  all host paramet
2d6c0 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a  ers to NULL..*/.
2d6d0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
2d6e0 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e  qlite3_clear_bin
2d6f0 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74  dings(sqlite3_st
2d700 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  mt*);../*.** CAP
2d710 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66  I3REF: Number Of
2d720 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65   Columns In A Re
2d730 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e  sult Set.**.** ^
2d740 52 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65  Return the numbe
2d750 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
2d760 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 72  the result set r
2d770 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a  eturned by the.*
2d780 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
2d790 65 6d 65 6e 74 5d 2e 20 5e 54 68 69 73 20 72 6f  ement]. ^This ro
2d7a0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20  utine returns 0 
2d7b0 69 66 20 70 53 74 6d 74 20 69 73 20 61 6e 20 53  if pStmt is an S
2d7c0 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  QL.** statement 
2d7d0 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 72 65  that does not re
2d7e0 74 75 72 6e 20 64 61 74 61 20 28 66 6f 72 20 65  turn data (for e
2d7f0 78 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41 54  xample an [UPDAT
2d800 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  E])..**.** See a
2d810 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61  lso: [sqlite3_da
2d820 74 61 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 53  ta_count()].*/.S
2d830 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
2d840 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75  lite3_column_cou
2d850 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  nt(sqlite3_stmt 
2d860 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
2d870 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e  CAPI3REF: Column
2d880 20 4e 61 6d 65 73 20 49 6e 20 41 20 52 65 73 75   Names In A Resu
2d890 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  lt Set.**.** ^Th
2d8a0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ese routines ret
2d8b0 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 61 73 73  urn the name ass
2d8c0 69 67 6e 65 64 20 74 6f 20 61 20 70 61 72 74 69  igned to a parti
2d8d0 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  cular column.** 
2d8e0 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  in the result se
2d8f0 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20  t of a [SELECT] 
2d900 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 54 68 65  statement.  ^The
2d910 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2d920 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66  name().** interf
2d930 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
2d940 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d  inter to a zero-
2d950 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
2d960 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 73   string.** and s
2d970 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
2d980 6d 65 31 36 28 29 20 72 65 74 75 72 6e 73 20 61  me16() returns a
2d990 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65   pointer to a ze
2d9a0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
2d9b0 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20   UTF-16 string. 
2d9c0 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61   ^The first para
2d9d0 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 70 72  meter is the [pr
2d9e0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2d9f0 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70 6c 65 6d  ].** that implem
2da00 65 6e 74 73 20 74 68 65 20 5b 53 45 4c 45 43 54  ents the [SELECT
2da10 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 5e 54 68  ] statement. ^Th
2da20 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
2da30 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6c  er is the.** col
2da40 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 5e 54 68  umn number.  ^Th
2da50 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d  e leftmost colum
2da60 6e 20 69 73 20 6e 75 6d 62 65 72 20 30 2e 0a 2a  n is number 0..*
2da70 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e  *.** ^The return
2da80 65 64 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65  ed string pointe
2da90 72 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c  r is valid until
2daa0 20 65 69 74 68 65 72 20 74 68 65 20 5b 70 72 65   either the [pre
2dab0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2dac0 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f 79 65 64  .** is destroyed
2dad0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   by [sqlite3_fin
2dae0 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69  alize()] or unti
2daf0 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  l the statement 
2db00 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  is automatically
2db10 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20 62  .** reprepared b
2db20 79 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c  y the first call
2db30 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
2db40 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69  p()] for a parti
2db50 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20  cular run.** or 
2db60 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20 63  until the next c
2db70 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  all to.** sqlite
2db80 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20  3_column_name() 
2db90 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  or sqlite3_colum
2dba0 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20 74 68  n_name16() on th
2dbb0 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a  e same column..*
2dbc0 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33  *.** ^If sqlite3
2dbd0 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 20  _malloc() fails 
2dbe0 64 75 72 69 6e 67 20 74 68 65 20 70 72 6f 63 65  during the proce
2dbf0 73 73 69 6e 67 20 6f 66 20 65 69 74 68 65 72 20  ssing of either 
2dc00 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 20  routine.** (for 
2dc10 65 78 61 6d 70 6c 65 20 64 75 72 69 6e 67 20 61  example during a
2dc20 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d   conversion from
2dc30 20 55 54 46 2d 38 20 74 6f 20 55 54 46 2d 31 36   UTF-8 to UTF-16
2dc40 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c  ) then a.** NULL
2dc50 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75   pointer is retu
2dc60 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  rned..**.** ^The
2dc70 20 6e 61 6d 65 20 6f 66 20 61 20 72 65 73 75 6c   name of a resul
2dc80 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20  t column is the 
2dc90 76 61 6c 75 65 20 6f 66 20 74 68 65 20 22 41 53  value of the "AS
2dca0 22 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a 2a 20  " clause for.** 
2dcb0 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 66 20  that column, if 
2dcc0 74 68 65 72 65 20 69 73 20 61 6e 20 41 53 20 63  there is an AS c
2dcd0 6c 61 75 73 65 2e 20 20 49 66 20 74 68 65 72 65  lause.  If there
2dce0 20 69 73 20 6e 6f 20 41 53 20 63 6c 61 75 73 65   is no AS clause
2dcf0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e 61 6d  .** then the nam
2dd00 65 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20  e of the column 
2dd10 69 73 20 75 6e 73 70 65 63 69 66 69 65 64 20 61  is unspecified a
2dd20 6e 64 20 6d 61 79 20 63 68 61 6e 67 65 20 66 72  nd may change fr
2dd30 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 61 73  om.** one releas
2dd40 65 20 6f 66 20 53 51 4c 69 74 65 20 74 6f 20 74  e of SQLite to t
2dd50 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a 53 51 4c 49  he next..*/.SQLI
2dd60 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61  TE_API const cha
2dd70 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
2dd80 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  n_name(sqlite3_s
2dd90 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 53 51  tmt*, int N);.SQ
2dda0 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76  LITE_API const v
2ddb0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
2ddc0 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  umn_name16(sqlit
2ddd0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29  e3_stmt*, int N)
2dde0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2ddf0 46 3a 20 53 6f 75 72 63 65 20 4f 66 20 44 61 74  F: Source Of Dat
2de00 61 20 49 6e 20 41 20 51 75 65 72 79 20 52 65 73  a In A Query Res
2de10 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  ult.**.** ^These
2de20 20 72 6f 75 74 69 6e 65 73 20 70 72 6f 76 69 64   routines provid
2de30 65 20 61 20 6d 65 61 6e 73 20 74 6f 20 64 65 74  e a means to det
2de40 65 72 6d 69 6e 65 20 74 68 65 20 64 61 74 61 62  ermine the datab
2de50 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 0a  ase, table, and.
2de60 2a 2a 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20  ** table column 
2de70 74 68 61 74 20 69 73 20 74 68 65 20 6f 72 69 67  that is the orig
2de80 69 6e 20 6f 66 20 61 20 70 61 72 74 69 63 75 6c  in of a particul
2de90 61 72 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  ar result column
2dea0 20 69 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d 20   in.** [SELECT] 
2deb0 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54  statement..** ^T
2dec0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64  he name of the d
2ded0 61 74 61 62 61 73 65 20 6f 72 20 74 61 62 6c 65  atabase or table
2dee0 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62   or column can b
2def0 65 20 72 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a  e returned as.**
2df00 20 65 69 74 68 65 72 20 61 20 55 54 46 2d 38 20   either a UTF-8 
2df10 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67  or UTF-16 string
2df20 2e 20 20 5e 54 68 65 20 5f 64 61 74 61 62 61 73  .  ^The _databas
2df30 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  e_ routines retu
2df40 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  rn.** the databa
2df50 73 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61  se name, the _ta
2df60 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65  ble_ routines re
2df70 74 75 72 6e 20 74 68 65 20 74 61 62 6c 65 20 6e  turn the table n
2df80 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20  ame, and.** the 
2df90 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73  origin_ routines
2dfa0 20 72 65 74 75 72 6e 20 74 68 65 20 63 6f 6c 75   return the colu
2dfb0 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65  mn name..** ^The
2dfc0 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
2dfd0 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20   is valid until 
2dfe0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
2dff0 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65 73 74  atement] is dest
2e000 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b  royed.** using [
2e010 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2e020 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65  ()] or until the
2e030 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75   statement is au
2e040 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72  tomatically.** r
2e050 65 70 72 65 70 61 72 65 64 20 62 79 20 74 68 65  eprepared by the
2e060 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b   first call to [
2e070 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2e080 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72  for a particular
2e090 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c   run.** or until
2e0a0 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d   the same inform
2e0b0 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74  ation is request
2e0c0 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61  ed.** again in a
2e0d0 20 64 69 66 66 65 72 65 6e 74 20 65 6e 63 6f 64   different encod
2e0e0 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ing..**.** ^The 
2e0f0 6e 61 6d 65 73 20 72 65 74 75 72 6e 65 64 20 61  names returned a
2e100 72 65 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  re the original 
2e110 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65 73  un-aliased names
2e120 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74 61 62   of the.** datab
2e130 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20  ase, table, and 
2e140 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54  column..**.** ^T
2e150 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
2e160 74 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72  t to these inter
2e170 66 61 63 65 73 20 69 73 20 61 20 5b 70 72 65 70  faces is a [prep
2e180 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
2e190 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74  .** ^These funct
2e1a0 69 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e 66 6f  ions return info
2e1b0 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68  rmation about th
2e1c0 65 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c  e Nth result col
2e1d0 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 0a  umn returned by.
2e1e0 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  ** the statement
2e1f0 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  , where N is the
2e200 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e   second function
2e210 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54   argument..** ^T
2e220 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c  he left-most col
2e230 75 6d 6e 20 69 73 20 63 6f 6c 75 6d 6e 20 30 20  umn is column 0 
2e240 66 6f 72 20 74 68 65 73 65 20 72 6f 75 74 69 6e  for these routin
2e250 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  es..**.** ^If th
2e260 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74  e Nth column ret
2e270 75 72 6e 65 64 20 62 79 20 74 68 65 20 73 74 61  urned by the sta
2e280 74 65 6d 65 6e 74 20 69 73 20 61 6e 20 65 78 70  tement is an exp
2e290 72 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75  ression or.** su
2e2a0 62 71 75 65 72 79 20 61 6e 64 20 69 73 20 6e 6f  bquery and is no
2e2b0 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65  t a column value
2e2c0 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68  , then all of th
2e2d0 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65  ese functions re
2e2e0 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e  turn.** NULL.  ^
2e2f0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 20 6d 69  These routine mi
2e300 67 68 74 20 61 6c 73 6f 20 72 65 74 75 72 6e 20  ght also return 
2e310 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79  NULL if a memory
2e320 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f   allocation erro
2e330 72 0a 2a 2a 20 6f 63 63 75 72 73 2e 20 20 5e 4f  r.** occurs.  ^O
2e340 74 68 65 72 77 69 73 65 2c 20 74 68 65 79 20 72  therwise, they r
2e350 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 6f  eturn the name o
2e360 66 20 74 68 65 20 61 74 74 61 63 68 65 64 20 64  f the attached d
2e370 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 0a  atabase, table,.
2e380 2a 2a 20 6f 72 20 63 6f 6c 75 6d 6e 20 74 68 61  ** or column tha
2e390 74 20 71 75 65 72 79 20 72 65 73 75 6c 74 20 63  t query result c
2e3a0 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74 72 61 63  olumn was extrac
2e3b0 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20  ted from..**.** 
2e3c0 5e 41 73 20 77 69 74 68 20 61 6c 6c 20 6f 74 68  ^As with all oth
2e3d0 65 72 20 53 51 4c 69 74 65 20 41 50 49 73 2c 20  er SQLite APIs, 
2e3e0 74 68 6f 73 65 20 77 68 6f 73 65 20 6e 61 6d 65  those whose name
2e3f0 73 20 65 6e 64 20 77 69 74 68 20 22 31 36 22 20  s end with "16" 
2e400 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36  return.** UTF-16
2e410 20 65 6e 63 6f 64 65 64 20 73 74 72 69 6e 67 73   encoded strings
2e420 20 61 6e 64 20 74 68 65 20 6f 74 68 65 72 20 66   and the other f
2e430 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20  unctions return 
2e440 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  UTF-8..**.** ^Th
2e450 65 73 65 20 41 50 49 73 20 61 72 65 20 6f 6e 6c  ese APIs are onl
2e460 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74  y available if t
2e470 68 65 20 6c 69 62 72 61 72 79 20 77 61 73 20 63  he library was c
2e480 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65  ompiled with the
2e490 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42  .** [SQLITE_ENAB
2e4a0 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41  LE_COLUMN_METADA
2e4b0 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 73  TA] C-preprocess
2e4c0 6f 72 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a  or symbol..**.**
2e4d0 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20   If two or more 
2e4e0 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65  threads call one
2e4f0 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 73   or more of thes
2e500 65 20 72 6f 75 74 69 6e 65 73 20 61 67 61 69 6e  e routines again
2e510 73 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70  st the same.** p
2e520 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2e530 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20  t and column at 
2e540 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68  the same time th
2e550 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  en the results a
2e560 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e  re.** undefined.
2e570 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72  .**.** If two or
2e580 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61   more threads ca
2e590 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a  ll one or more.*
2e5a0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
2e5b0 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 20  n_database_name 
2e5c0 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74  | column metadat
2e5d0 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a  a interfaces].**
2e5e0 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 5b 70   for the same [p
2e5f0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2e600 74 5d 20 61 6e 64 20 72 65 73 75 6c 74 20 63 6f  t] and result co
2e610 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74 68 65 20 73  lumn.** at the s
2e620 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68  ame time then th
2e630 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
2e640 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 53 51 4c 49  defined..*/.SQLI
2e650 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61  TE_API const cha
2e660 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
2e670 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 28  n_database_name(
2e680 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
2e690 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  t);.SQLITE_API c
2e6a0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
2e6b0 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61  e3_column_databa
2e6c0 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65  se_name16(sqlite
2e6d0 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51  3_stmt*,int);.SQ
2e6e0 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63  LITE_API const c
2e6f0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
2e700 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73  umn_table_name(s
2e710 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
2e720 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
2e730 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
2e740 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e  3_column_table_n
2e750 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
2e760 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45  mt*,int);.SQLITE
2e770 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20  _API const char 
2e780 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
2e790 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69  origin_name(sqli
2e7a0 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
2e7b0 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
2e7c0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
2e7d0 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d  olumn_origin_nam
2e7e0 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
2e7f0 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  *,int);../*.** C
2e800 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61 72 65  API3REF: Declare
2e810 64 20 44 61 74 61 74 79 70 65 20 4f 66 20 41 20  d Datatype Of A 
2e820 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a  Query Result.**.
2e830 2a 2a 20 5e 28 54 68 65 20 66 69 72 73 74 20 70  ** ^(The first p
2e840 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 5b 70  arameter is a [p
2e850 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2e860 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 73  t]..** If this s
2e870 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 53  tatement is a [S
2e880 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
2e890 20 61 6e 64 20 74 68 65 20 4e 74 68 20 63 6f 6c   and the Nth col
2e8a0 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65  umn of the.** re
2e8b0 74 75 72 6e 65 64 20 72 65 73 75 6c 74 20 73 65  turned result se
2e8c0 74 20 6f 66 20 74 68 61 74 20 5b 53 45 4c 45 43  t of that [SELEC
2e8d0 54 5d 20 69 73 20 61 20 74 61 62 6c 65 20 63 6f  T] is a table co
2e8e0 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20  lumn (not an.** 
2e8f0 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75  expression or su
2e900 62 71 75 65 72 79 29 20 74 68 65 6e 20 74 68 65  bquery) then the
2e910 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 20 6f   declared type o
2e920 66 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63  f the table.** c
2e930 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75 72 6e 65  olumn is returne
2e940 64 2e 29 5e 20 20 5e 49 66 20 74 68 65 20 4e 74  d.)^  ^If the Nt
2e950 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  h column of the 
2e960 72 65 73 75 6c 74 20 73 65 74 20 69 73 20 61 6e  result set is an
2e970 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f  .** expression o
2e980 72 20 73 75 62 71 75 65 72 79 2c 20 74 68 65 6e  r subquery, then
2e990 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
2e9a0 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20  is returned..** 
2e9b0 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74  ^The returned st
2e9c0 72 69 6e 67 20 69 73 20 61 6c 77 61 79 73 20 55  ring is always U
2e9d0 54 46 2d 38 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a  TF-8 encoded..**
2e9e0 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c  .** ^(For exampl
2e9f0 65 2c 20 67 69 76 65 6e 20 74 68 65 20 64 61 74  e, given the dat
2ea00 61 62 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a  abase schema:.**
2ea10 0a 2a 2a 20 43 52 45 41 54 45 20 54 41 42 4c 45  .** CREATE TABLE
2ea20 20 74 31 28 63 31 20 56 41 52 49 41 4e 54 29 3b   t1(c1 VARIANT);
2ea30 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66  .**.** and the f
2ea40 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d 65  ollowing stateme
2ea50 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65  nt to be compile
2ea60 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20  d:.**.** SELECT 
2ea70 63 31 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20  c1 + 1, c1 FROM 
2ea80 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72  t1;.**.** this r
2ea90 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20 72 65 74  outine would ret
2eaa0 75 72 6e 20 74 68 65 20 73 74 72 69 6e 67 20 22  urn the string "
2eab0 56 41 52 49 41 4e 54 22 20 66 6f 72 20 74 68 65  VARIANT" for the
2eac0 20 73 65 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a   second result.*
2ead0 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c  * column (i==1),
2eae0 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e   and a NULL poin
2eaf0 74 65 72 20 66 6f 72 20 74 68 65 20 66 69 72 73  ter for the firs
2eb00 74 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  t result column 
2eb10 28 69 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20  (i==0).)^.**.** 
2eb20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e  ^SQLite uses dyn
2eb30 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20 74 79  amic run-time ty
2eb40 70 69 6e 67 2e 20 20 5e 53 6f 20 6a 75 73 74 20  ping.  ^So just 
2eb50 62 65 63 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e  because a column
2eb60 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72 65 64 20  .** is declared 
2eb70 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70 61 72  to contain a par
2eb80 74 69 63 75 6c 61 72 20 74 79 70 65 20 64 6f 65  ticular type doe
2eb90 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74 20  s not mean that 
2eba0 74 68 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72  the.** data stor
2ebb0 65 64 20 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d  ed in that colum
2ebc0 6e 20 69 73 20 6f 66 20 74 68 65 20 64 65 63 6c  n is of the decl
2ebd0 61 72 65 64 20 74 79 70 65 2e 20 20 53 51 4c 69  ared type.  SQLi
2ebe0 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c  te is.** strongl
2ebf0 79 20 74 79 70 65 64 2c 20 62 75 74 20 74 68 65  y typed, but the
2ec00 20 74 79 70 69 6e 67 20 69 73 20 64 79 6e 61 6d   typing is dynam
2ec10 69 63 20 6e 6f 74 20 73 74 61 74 69 63 2e 20 20  ic not static.  
2ec20 5e 54 79 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f  ^Type.** is asso
2ec30 63 69 61 74 65 64 20 77 69 74 68 20 69 6e 64 69  ciated with indi
2ec40 76 69 64 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e  vidual values, n
2ec50 6f 74 20 77 69 74 68 20 74 68 65 20 63 6f 6e 74  ot with the cont
2ec60 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64 20 74  ainers.** used t
2ec70 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c  o hold those val
2ec80 75 65 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ues..*/.SQLITE_A
2ec90 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  PI const char *s
2eca0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65  qlite3_column_de
2ecb0 63 6c 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73  cltype(sqlite3_s
2ecc0 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54  tmt*,int);.SQLIT
2ecd0 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64  E_API const void
2ece0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2ecf0 5f 64 65 63 6c 74 79 70 65 31 36 28 73 71 6c 69  _decltype16(sqli
2ed00 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
2ed10 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2ed20 20 45 76 61 6c 75 61 74 65 20 41 6e 20 53 51 4c   Evaluate An SQL
2ed30 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a   Statement.**.**
2ed40 20 41 66 74 65 72 20 61 20 5b 70 72 65 70 61 72   After a [prepar
2ed50 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 68 61  ed statement] ha
2ed60 73 20 62 65 65 6e 20 70 72 65 70 61 72 65 64 20  s been prepared 
2ed70 75 73 69 6e 67 20 65 69 74 68 65 72 0a 2a 2a 20  using either.** 
2ed80 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2ed90 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  _v2()] or [sqlit
2eda0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
2edb0 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65  )] or one of the
2edc0 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72   legacy.** inter
2edd0 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 70  faces [sqlite3_p
2ede0 72 65 70 61 72 65 28 29 5d 20 6f 72 20 5b 73 71  repare()] or [sq
2edf0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
2ee00 29 5d 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f  )], this functio
2ee10 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 20 63 61 6c  n.** must be cal
2ee20 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  led one or more 
2ee30 74 69 6d 65 73 20 74 6f 20 65 76 61 6c 75 61 74  times to evaluat
2ee40 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2e  e the statement.
2ee50 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61 69  .**.** The detai
2ee60 6c 73 20 6f 66 20 74 68 65 20 62 65 68 61 76 69  ls of the behavi
2ee70 6f 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  or of the sqlite
2ee80 33 5f 73 74 65 70 28 29 20 69 6e 74 65 72 66 61  3_step() interfa
2ee90 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20  ce depend.** on 
2eea0 77 68 65 74 68 65 72 20 74 68 65 20 73 74 61 74  whether the stat
2eeb0 65 6d 65 6e 74 20 77 61 73 20 70 72 65 70 61 72  ement was prepar
2eec0 65 64 20 75 73 69 6e 67 20 74 68 65 20 6e 65 77  ed using the new
2eed0 65 72 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  er "v2" interfac
2eee0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  e.** [sqlite3_pr
2eef0 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
2ef00 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2ef10 31 36 5f 76 32 28 29 5d 20 6f 72 20 74 68 65 20  16_v2()] or the 
2ef20 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20  older legacy.** 
2ef30 69 6e 74 65 72 66 61 63 65 20 5b 73 71 6c 69 74  interface [sqlit
2ef40 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e  e3_prepare()] an
2ef50 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  d [sqlite3_prepa
2ef60 72 65 31 36 28 29 5d 2e 20 20 54 68 65 20 75 73  re16()].  The us
2ef70 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20  e of the.** new 
2ef80 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 69  "v2" interface i
2ef90 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f  s recommended fo
2efa0 72 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f  r new applicatio
2efb0 6e 73 20 62 75 74 20 74 68 65 20 6c 65 67 61 63  ns but the legac
2efc0 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 77  y.** interface w
2efd0 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20  ill continue to 
2efe0 62 65 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a  be supported..**
2eff0 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 6c 65 67 61  .** ^In the lega
2f000 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68  cy interface, th
2f010 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 77  e return value w
2f020 69 6c 6c 20 62 65 20 65 69 74 68 65 72 20 5b 53  ill be either [S
2f030 51 4c 49 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20  QLITE_BUSY],.** 
2f040 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b  [SQLITE_DONE], [
2f050 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51  SQLITE_ROW], [SQ
2f060 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20  LITE_ERROR], or 
2f070 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e  [SQLITE_MISUSE].
2f080 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 22 76  .** ^With the "v
2f090 32 22 20 69 6e 74 65 72 66 61 63 65 2c 20 61 6e  2" interface, an
2f0a0 79 20 6f 66 20 74 68 65 20 6f 74 68 65 72 20 5b  y of the other [
2f0b0 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6f 72  result codes] or
2f0c0 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
2f0d0 73 75 6c 74 20 63 6f 64 65 73 5d 20 6d 69 67 68  sult codes] migh
2f0e0 74 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73  t be returned as
2f0f0 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53   well..**.** ^[S
2f100 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65 61 6e  QLITE_BUSY] mean
2f110 73 20 74 68 61 74 20 74 68 65 20 64 61 74 61 62  s that the datab
2f120 61 73 65 20 65 6e 67 69 6e 65 20 77 61 73 20 75  ase engine was u
2f130 6e 61 62 6c 65 20 74 6f 20 61 63 71 75 69 72 65  nable to acquire
2f140 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
2f150 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64 73 20   locks it needs 
2f160 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e 20 20  to do its job.  
2f170 5e 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e  ^If the statemen
2f180 74 20 69 73 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a  t is a [COMMIT].
2f190 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f 75 74  ** or occurs out
2f1a0 73 69 64 65 20 6f 66 20 61 6e 20 65 78 70 6c 69  side of an expli
2f1b0 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c  cit transaction,
2f1c0 20 74 68 65 6e 20 79 6f 75 20 63 61 6e 20 72 65   then you can re
2f1d0 74 72 79 20 74 68 65 0a 2a 2a 20 73 74 61 74 65  try the.** state
2f1e0 6d 65 6e 74 2e 20 20 49 66 20 74 68 65 20 73 74  ment.  If the st
2f1f0 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20 61  atement is not a
2f200 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f 63   [COMMIT] and oc
2f210 63 75 72 73 20 77 69 74 68 69 6e 20 61 6e 0a 2a  curs within an.*
2f220 2a 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73  * explicit trans
2f230 61 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f 75 20  action then you 
2f240 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 6b 20  should rollback 
2f250 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  the transaction 
2f260 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e  before.** contin
2f270 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51  uing..**.** ^[SQ
2f280 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73  LITE_DONE] means
2f290 20 74 68 61 74 20 74 68 65 20 73 74 61 74 65 6d   that the statem
2f2a0 65 6e 74 20 68 61 73 20 66 69 6e 69 73 68 65 64  ent has finished
2f2b0 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20 73 75   executing.** su
2f2c0 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 73 71 6c  ccessfully.  sql
2f2d0 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75  ite3_step() shou
2f2e0 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64  ld not be called
2f2f0 20 61 67 61 69 6e 20 6f 6e 20 74 68 69 73 20 76   again on this v
2f300 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e  irtual.** machin
2f310 65 20 77 69 74 68 6f 75 74 20 66 69 72 73 74 20  e without first 
2f320 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
2f330 5f 72 65 73 65 74 28 29 5d 20 74 6f 20 72 65 73  _reset()] to res
2f340 65 74 20 74 68 65 20 76 69 72 74 75 61 6c 0a 2a  et the virtual.*
2f350 2a 20 6d 61 63 68 69 6e 65 20 62 61 63 6b 20 74  * machine back t
2f360 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74  o its initial st
2f370 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ate..**.** ^If t
2f380 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
2f390 20 62 65 69 6e 67 20 65 78 65 63 75 74 65 64 20   being executed 
2f3a0 72 65 74 75 72 6e 73 20 61 6e 79 20 64 61 74 61  returns any data
2f3b0 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 52  , then [SQLITE_R
2f3c0 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e  OW].** is return
2f3d0 65 64 20 65 61 63 68 20 74 69 6d 65 20 61 20 6e  ed each time a n
2f3e0 65 77 20 72 6f 77 20 6f 66 20 64 61 74 61 20 69  ew row of data i
2f3f0 73 20 72 65 61 64 79 20 66 6f 72 20 70 72 6f 63  s ready for proc
2f400 65 73 73 69 6e 67 20 62 79 20 74 68 65 0a 2a 2a  essing by the.**
2f410 20 63 61 6c 6c 65 72 2e 20 54 68 65 20 76 61 6c   caller. The val
2f420 75 65 73 20 6d 61 79 20 62 65 20 61 63 63 65 73  ues may be acces
2f430 73 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 63  sed using the [c
2f440 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e  olumn access fun
2f450 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69  ctions]..** sqli
2f460 74 65 33 5f 73 74 65 70 28 29 20 69 73 20 63 61  te3_step() is ca
2f470 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f 20 72 65  lled again to re
2f480 74 72 69 65 76 65 20 74 68 65 20 6e 65 78 74 20  trieve the next 
2f490 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a  row of data..**.
2f4a0 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 45 52 52 4f  ** ^[SQLITE_ERRO
2f4b0 52 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 61 20  R] means that a 
2f4c0 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20 28  run-time error (
2f4d0 73 75 63 68 20 61 73 20 61 20 63 6f 6e 73 74 72  such as a constr
2f4e0 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f  aint.** violatio
2f4f0 6e 29 20 68 61 73 20 6f 63 63 75 72 72 65 64 2e  n) has occurred.
2f500 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29    sqlite3_step()
2f510 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63   should not be c
2f520 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a  alled again on.*
2f530 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69  * the VM. More i
2f540 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62  nformation may b
2f550 65 20 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69  e found by calli
2f560 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  ng [sqlite3_errm
2f570 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20  sg()]..** ^With 
2f580 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72  the legacy inter
2f590 66 61 63 65 2c 20 61 20 6d 6f 72 65 20 73 70 65  face, a more spe
2f5a0 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65  cific error code
2f5b0 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a   (for example,.*
2f5c0 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52  * [SQLITE_INTERR
2f5d0 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 43  UPT], [SQLITE_SC
2f5e0 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f 43  HEMA], [SQLITE_C
2f5f0 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f 20  ORRUPT], and so 
2f600 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62 65  forth).** can be
2f610 20 6f 62 74 61 69 6e 65 64 20 62 79 20 63 61 6c   obtained by cal
2f620 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  ling [sqlite3_re
2f630 73 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a  set()] on the.**
2f640 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2f650 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20 74 68 65 20  ment].  ^In the 
2f660 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 0a  "v2" interface,.
2f670 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63  ** the more spec
2f680 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20  ific error code 
2f690 69 73 20 72 65 74 75 72 6e 65 64 20 64 69 72 65  is returned dire
2f6a0 63 74 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f  ctly by sqlite3_
2f6b0 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53  step()..**.** [S
2f6c0 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65  QLITE_MISUSE] me
2f6d0 61 6e 73 20 74 68 61 74 20 74 68 65 20 74 68 69  ans that the thi
2f6e0 73 20 72 6f 75 74 69 6e 65 20 77 61 73 20 63 61  s routine was ca
2f6f0 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70 72 69 61  lled inappropria
2f700 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73  tely..** Perhaps
2f710 20 69 74 20 77 61 73 20 63 61 6c 6c 65 64 20 6f   it was called o
2f720 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  n a [prepared st
2f730 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61  atement] that ha
2f740 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62 65 65  s.** already bee
2f750 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  n [sqlite3_final
2f760 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d  ize | finalized]
2f770 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20   or on one that 
2f780 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  had.** previousl
2f790 79 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49  y returned [SQLI
2f7a0 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51  TE_ERROR] or [SQ
2f7b0 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20  LITE_DONE].  Or 
2f7c0 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74  it could.** be t
2f7d0 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65  he case that the
2f7e0 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
2f7f0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62 65 69  onnection is bei
2f800 6e 67 20 75 73 65 64 20 62 79 20 74 77 6f 20 6f  ng used by two o
2f810 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61 64  r.** more thread
2f820 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 6d 6f  s at the same mo
2f830 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a  ment in time..**
2f840 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20 76 65 72 73  .** For all vers
2f850 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 75  ions of SQLite u
2f860 70 20 74 6f 20 61 6e 64 20 69 6e 63 6c 75 64 69  p to and includi
2f870 6e 67 20 33 2e 36 2e 32 33 2e 31 2c 20 61 20 63  ng 3.6.23.1, a c
2f880 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
2f890 65 33 5f 72 65 73 65 74 28 29 5d 20 77 61 73 20  e3_reset()] was 
2f8a0 72 65 71 75 69 72 65 64 20 61 66 74 65 72 20 73  required after s
2f8b0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 72 65  qlite3_step() re
2f8c0 74 75 72 6e 65 64 20 61 6e 79 74 68 69 6e 67 0a  turned anything.
2f8d0 2a 2a 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  ** other than [S
2f8e0 51 4c 49 54 45 5f 52 4f 57 5d 20 62 65 66 6f 72  QLITE_ROW] befor
2f8f0 65 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e 74  e any subsequent
2f900 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a   invocation of.*
2f910 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  * sqlite3_step()
2f920 2e 20 20 46 61 69 6c 75 72 65 20 74 6f 20 72 65  .  Failure to re
2f930 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65 64  set the prepared
2f940 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67   statement using
2f950 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65   .** [sqlite3_re
2f960 73 65 74 28 29 5d 20 77 6f 75 6c 64 20 72 65 73  set()] would res
2f970 75 6c 74 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54  ult in an [SQLIT
2f980 45 5f 4d 49 53 55 53 45 5d 20 72 65 74 75 72 6e  E_MISUSE] return
2f990 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33   from.** sqlite3
2f9a0 5f 73 74 65 70 28 29 2e 20 20 42 75 74 20 61 66  _step().  But af
2f9b0 74 65 72 20 76 65 72 73 69 6f 6e 20 33 2e 36 2e  ter version 3.6.
2f9c0 32 33 2e 31 2c 20 73 71 6c 69 74 65 33 5f 73 74  23.1, sqlite3_st
2f9d0 65 70 28 29 20 62 65 67 61 6e 0a 2a 2a 20 63 61  ep() began.** ca
2f9e0 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  lling [sqlite3_r
2f9f0 65 73 65 74 28 29 5d 20 61 75 74 6f 6d 61 74 69  eset()] automati
2fa00 63 61 6c 6c 79 20 69 6e 20 74 68 69 73 20 63 69  cally in this ci
2fa10 72 63 75 6d 73 74 61 6e 63 65 20 72 61 74 68 65  rcumstance rathe
2fa20 72 0a 2a 2a 20 74 68 61 6e 20 72 65 74 75 72 6e  r.** than return
2fa30 69 6e 67 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  ing [SQLITE_MISU
2fa40 53 45 5d 2e 20 20 54 68 69 73 20 69 73 20 6e 6f  SE].  This is no
2fa50 74 20 63 6f 6e 73 69 64 65 72 65 64 20 61 20 63  t considered a c
2fa60 6f 6d 70 61 74 69 62 69 6c 69 74 79 0a 2a 2a 20  ompatibility.** 
2fa70 62 72 65 61 6b 20 62 65 63 61 75 73 65 20 61 6e  break because an
2fa80 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 68  y application th
2fa90 61 74 20 65 76 65 72 20 72 65 63 65 69 76 65 73  at ever receives
2faa0 20 61 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53   an SQLITE_MISUS
2fab0 45 20 65 72 72 6f 72 0a 2a 2a 20 69 73 20 62 72  E error.** is br
2fac0 6f 6b 65 6e 20 62 79 20 64 65 66 69 6e 69 74 69  oken by definiti
2fad0 6f 6e 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45  on.  The [SQLITE
2fae0 5f 4f 4d 49 54 5f 41 55 54 4f 52 45 53 45 54 5d  _OMIT_AUTORESET]
2faf0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
2fb00 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20 62 65 20 75  tion.** can be u
2fb10 73 65 64 20 74 6f 20 72 65 73 74 6f 72 65 20 74  sed to restore t
2fb20 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69  he legacy behavi
2fb30 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f  or..**.** <b>Goo
2fb40 66 79 20 49 6e 74 65 72 66 61 63 65 20 41 6c 65  fy Interface Ale
2fb50 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 20 6c  rt:</b> In the l
2fb60 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c  egacy interface,
2fb70 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65   the sqlite3_ste
2fb80 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c 77 61 79  p().** API alway
2fb90 73 20 72 65 74 75 72 6e 73 20 61 20 67 65 6e 65  s returns a gene
2fba0 72 69 63 20 65 72 72 6f 72 20 63 6f 64 65 2c 20  ric error code, 
2fbb0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20  [SQLITE_ERROR], 
2fbc0 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a  following any.**
2fbd0 20 65 72 72 6f 72 20 6f 74 68 65 72 20 74 68 61   error other tha
2fbe0 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  n [SQLITE_BUSY] 
2fbf0 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  and [SQLITE_MISU
2fc00 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20 63  SE].  You must c
2fc10 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  all.** [sqlite3_
2fc20 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c  reset()] or [sql
2fc30 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
2fc40 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e   in order to fin
2fc50 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20  d one of the.** 
2fc60 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20  specific [error 
2fc70 63 6f 64 65 73 5d 20 74 68 61 74 20 62 65 74 74  codes] that bett
2fc80 65 72 20 64 65 73 63 72 69 62 65 73 20 74 68 65  er describes the
2fc90 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64   error..** We ad
2fca0 6d 69 74 20 74 68 61 74 20 74 68 69 73 20 69 73  mit that this is
2fcb0 20 61 20 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e   a goofy design.
2fcc0 20 20 54 68 65 20 70 72 6f 62 6c 65 6d 20 68 61    The problem ha
2fcd0 73 20 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20  s been fixed.** 
2fce0 77 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e  with the "v2" in
2fcf0 74 65 72 66 61 63 65 2e 20 20 49 66 20 79 6f 75  terface.  If you
2fd00 20 70 72 65 70 61 72 65 20 61 6c 6c 20 6f 66 20   prepare all of 
2fd10 79 6f 75 72 20 53 51 4c 20 73 74 61 74 65 6d 65  your SQL stateme
2fd20 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20 65 69 74  nts.** using eit
2fd30 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  her [sqlite3_pre
2fd40 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73  pare_v2()] or [s
2fd50 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2fd60 5f 76 32 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a  _v2()] instead.*
2fd70 2a 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 20  * of the legacy 
2fd80 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2fd90 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
2fda0 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 69 6e  _prepare16()] in
2fdb0 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20 74 68 65  terfaces,.** the
2fdc0 6e 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69  n the more speci
2fdd0 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73  fic [error codes
2fde0 5d 20 61 72 65 20 72 65 74 75 72 6e 65 64 20 64  ] are returned d
2fdf0 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71  irectly.** by sq
2fe00 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 54  lite3_step().  T
2fe10 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 22 76  he use of the "v
2fe20 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  2" interface is 
2fe30 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f 0a  recommended..*/.
2fe40 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
2fe50 71 6c 69 74 65 33 5f 73 74 65 70 28 73 71 6c 69  qlite3_step(sqli
2fe60 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
2fe70 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d  ** CAPI3REF: Num
2fe80 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
2fe90 6e 20 61 20 72 65 73 75 6c 74 20 73 65 74 0a 2a  n a result set.*
2fea0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2feb0 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20  3_data_count(P) 
2fec0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2fed0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
2fee0 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a 2a  columns in the.*
2fef0 2a 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66  * current row of
2ff00 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
2ff10 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  of [prepared sta
2ff20 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 49  tement] P..** ^I
2ff30 66 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  f prepared state
2ff40 6d 65 6e 74 20 50 20 64 6f 65 73 20 6e 6f 74 20  ment P does not 
2ff50 68 61 76 65 20 72 65 73 75 6c 74 73 20 72 65 61  have results rea
2ff60 64 79 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20  dy to return.** 
2ff70 28 76 69 61 20 63 61 6c 6c 73 20 74 6f 20 74 68  (via calls to th
2ff80 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e [sqlite3_colum
2ff90 6e 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f  n_int | sqlite3_
2ffa0 63 6f 6c 75 6d 6e 5f 2a 28 29 5d 20 6f 66 0a 2a  column_*()] of.*
2ffb0 2a 20 69 6e 74 65 72 66 61 63 65 73 29 20 74 68  * interfaces) th
2ffc0 65 6e 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  en sqlite3_data_
2ffd0 63 6f 75 6e 74 28 50 29 20 72 65 74 75 72 6e 73  count(P) returns
2ffe0 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69   0..** ^The sqli
2fff0 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50  te3_data_count(P
30000 29 20 72 6f 75 74 69 6e 65 20 61 6c 73 6f 20 72  ) routine also r
30010 65 74 75 72 6e 73 20 30 20 69 66 20 50 20 69 73  eturns 0 if P is
30020 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
30030 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
30040 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72  _data_count(P) r
30050 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30  outine returns 0
30060 20 69 66 20 74 68 65 20 70 72 65 76 69 6f 75 73   if the previous
30070 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
30080 69 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72 65  ite3_step](P) re
30090 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 44  turned [SQLITE_D
300a0 4f 4e 45 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69  ONE].  ^The sqli
300b0 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50  te3_data_count(P
300c0 29 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75 72 6e  ).** will return
300d0 20 6e 6f 6e 2d 7a 65 72 6f 20 69 66 20 70 72 65   non-zero if pre
300e0 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 5b 73  vious call to [s
300f0 71 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29 20  qlite3_step](P) 
30100 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c  returned.** [SQL
30110 49 54 45 5f 52 4f 57 5d 2c 20 65 78 63 65 70 74  ITE_ROW], except
30120 20 69 6e 20 74 68 65 20 63 61 73 65 20 6f 66 20   in the case of 
30130 74 68 65 20 5b 50 52 41 47 4d 41 20 69 6e 63 72  the [PRAGMA incr
30140 65 6d 65 6e 74 61 6c 5f 76 61 63 75 75 6d 5d 0a  emental_vacuum].
30150 2a 2a 20 77 68 65 72 65 20 69 74 20 61 6c 77 61  ** where it alwa
30160 79 73 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20  ys returns zero 
30170 73 69 6e 63 65 20 65 61 63 68 20 73 74 65 70 20  since each step 
30180 6f 66 20 74 68 61 74 20 6d 75 6c 74 69 2d 73 74  of that multi-st
30190 65 70 0a 2a 2a 20 70 72 61 67 6d 61 20 72 65 74  ep.** pragma ret
301a0 75 72 6e 73 20 30 20 63 6f 6c 75 6d 6e 73 20 6f  urns 0 columns o
301b0 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 65  f data..**.** Se
301c0 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
301d0 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d  _column_count()]
301e0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
301f0 6e 74 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  nt sqlite3_data_
30200 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  count(sqlite3_st
30210 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
30220 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e  ** CAPI3REF: Fun
30230 64 61 6d 65 6e 74 61 6c 20 44 61 74 61 74 79 70  damental Datatyp
30240 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  es.** KEYWORDS: 
30250 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a  SQLITE_TEXT.**.*
30260 2a 20 5e 28 45 76 65 72 79 20 76 61 6c 75 65 20  * ^(Every value 
30270 69 6e 20 53 51 4c 69 74 65 20 68 61 73 20 6f 6e  in SQLite has on
30280 65 20 6f 66 20 66 69 76 65 20 66 75 6e 64 61 6d  e of five fundam
30290 65 6e 74 61 6c 20 64 61 74 61 74 79 70 65 73 3a  ental datatypes:
302a0 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
302b0 6c 69 3e 20 36 34 2d 62 69 74 20 73 69 67 6e 65  li> 64-bit signe
302c0 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69  d integer.** <li
302d0 3e 20 36 34 2d 62 69 74 20 49 45 45 45 20 66 6c  > 64-bit IEEE fl
302e0 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d  oating point num
302f0 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69  ber.** <li> stri
30300 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a  ng.** <li> BLOB.
30310 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20  ** <li> NULL.** 
30320 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  </ul>)^.**.** Th
30330 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ese constants ar
30340 65 20 63 6f 64 65 73 20 66 6f 72 20 65 61 63 68  e codes for each
30350 20 6f 66 20 74 68 6f 73 65 20 74 79 70 65 73 2e   of those types.
30360 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
30370 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45 58 54   the SQLITE_TEXT
30380 20 63 6f 6e 73 74 61 6e 74 20 77 61 73 20 61 6c   constant was al
30390 73 6f 20 75 73 65 64 20 69 6e 20 53 51 4c 69 74  so used in SQLit
303a0 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66  e version 2.** f
303b0 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20  or a completely 
303c0 64 69 66 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e  different meanin
303d0 67 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68 61  g.  Software tha
303e0 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20  t links against 
303f0 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76  both.** SQLite v
30400 65 72 73 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c  ersion 2 and SQL
30410 69 74 65 20 76 65 72 73 69 6f 6e 20 33 20 73 68  ite version 3 sh
30420 6f 75 6c 64 20 75 73 65 20 53 51 4c 49 54 45 33  ould use SQLITE3
30430 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51  _TEXT, not.** SQ
30440 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64  LITE_TEXT..*/.#d
30450 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54  efine SQLITE_INT
30460 45 47 45 52 20 20 31 0a 23 64 65 66 69 6e 65 20  EGER  1.#define 
30470 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 20  SQLITE_FLOAT    
30480 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
30490 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 66  _BLOB     4.#def
304a0 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20  ine SQLITE_NULL 
304b0 20 20 20 20 35 0a 23 69 66 64 65 66 20 53 51 4c      5.#ifdef SQL
304c0 49 54 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 66  ITE_TEXT.# undef
304d0 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c   SQLITE_TEXT.#el
304e0 73 65 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  se.# define SQLI
304f0 54 45 5f 54 45 58 54 20 20 20 20 20 33 0a 23 65  TE_TEXT     3.#e
30500 6e 64 69 66 0a 23 64 65 66 69 6e 65 20 53 51 4c  ndif.#define SQL
30510 49 54 45 33 5f 54 45 58 54 20 20 20 20 20 33 0a  ITE3_TEXT     3.
30520 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
30530 20 52 65 73 75 6c 74 20 56 61 6c 75 65 73 20 46   Result Values F
30540 72 6f 6d 20 41 20 51 75 65 72 79 0a 2a 2a 20 4b  rom A Query.** K
30550 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e  EYWORDS: {column
30560 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e   access function
30570 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  s}.**.** These r
30580 6f 75 74 69 6e 65 73 20 66 6f 72 6d 20 74 68 65  outines form the
30590 20 22 72 65 73 75 6c 74 20 73 65 74 22 20 69 6e   "result set" in
305a0 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e  terface..**.** ^
305b0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
305c0 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f  eturn informatio
305d0 6e 20 61 62 6f 75 74 20 61 20 73 69 6e 67 6c 65  n about a single
305e0 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63   column of the c
305f0 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74  urrent.** result
30600 20 72 6f 77 20 6f 66 20 61 20 71 75 65 72 79 2e   row of a query.
30610 20 20 5e 49 6e 20 65 76 65 72 79 20 63 61 73 65    ^In every case
30620 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
30630 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ent is a pointer
30640 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72 65 70  .** to the [prep
30650 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
30660 74 68 61 74 20 69 73 20 62 65 69 6e 67 20 65 76  that is being ev
30670 61 6c 75 61 74 65 64 20 28 74 68 65 20 5b 73 71  aluated (the [sq
30680 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20  lite3_stmt*].** 
30690 74 68 61 74 20 77 61 73 20 72 65 74 75 72 6e 65  that was returne
306a0 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
306b0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
306c0 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69   one of its vari
306d0 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65  ants).** and the
306e0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
306f0 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66   is the index of
30700 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20   the column for 
30710 77 68 69 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f  which informatio
30720 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72  n.** should be r
30730 65 74 75 72 6e 65 64 2e 20 5e 54 68 65 20 6c 65  eturned. ^The le
30740 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66  ftmost column of
30750 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
30760 68 61 73 20 74 68 65 20 69 6e 64 65 78 20 30 2e  has the index 0.
30770 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d 62 65 72 20  .** ^The number 
30780 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68  of columns in th
30790 65 20 72 65 73 75 6c 74 20 63 61 6e 20 62 65 20  e result can be 
307a0 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67  determined using
307b0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
307c0 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a  umn_count()]..**
307d0 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73  .** If the SQL s
307e0 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f  tatement does no
307f0 74 20 63 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e  t currently poin
30800 74 20 74 6f 20 61 20 76 61 6c 69 64 20 72 6f 77  t to a valid row
30810 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 63  , or if the.** c
30820 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f  olumn index is o
30830 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65  ut of range, the
30840 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66   result is undef
30850 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72  ined..** These r
30860 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79  outines may only
30870 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20   be called when 
30880 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
30890 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
308a0 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20  te3_step()] has 
308b0 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45  returned [SQLITE
308c0 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68 65  _ROW] and neithe
308d0 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  r.** [sqlite3_re
308e0 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69  set()] nor [sqli
308f0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
30900 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64  have been called
30910 20 73 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a   subsequently..*
30920 2a 20 49 66 20 61 6e 79 20 6f 66 20 74 68 65 73  * If any of thes
30930 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63  e routines are c
30940 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c  alled after [sql
30950 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
30960 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  .** [sqlite3_fin
30970 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65  alize()] or afte
30980 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  r [sqlite3_step(
30990 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 0a  )] has returned.
309a0 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68  ** something oth
309b0 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
309c0 52 4f 57 5d 2c 20 74 68 65 20 72 65 73 75 6c 74  ROW], the result
309d0 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
309e0 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 5f  .** If [sqlite3_
309f0 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69  step()] or [sqli
30a00 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20  te3_reset()] or 
30a10 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
30a20 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c  e()].** are call
30a30 65 64 20 66 72 6f 6d 20 61 20 64 69 66 66 65 72  ed from a differ
30a40 65 6e 74 20 74 68 72 65 61 64 20 77 68 69 6c 65  ent thread while
30a50 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f   any of these ro
30a60 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65  utines.** are pe
30a70 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20  nding, then the 
30a80 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
30a90 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  fined..**.** ^Th
30aa0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
30ab0 5f 74 79 70 65 28 29 20 72 6f 75 74 69 6e 65 20  _type() routine 
30ac0 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b  returns the.** [
30ad0 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c  SQLITE_INTEGER |
30ae0 20 64 61 74 61 74 79 70 65 20 63 6f 64 65 5d 20   datatype code] 
30af0 66 6f 72 20 74 68 65 20 69 6e 69 74 69 61 6c 20  for the initial 
30b00 64 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20  data type.** of 
30b10 74 68 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  the result colum
30b20 6e 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65  n.  ^The returne
30b30 64 20 76 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f  d value is one o
30b40 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  f [SQLITE_INTEGE
30b50 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46  R],.** [SQLITE_F
30b60 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54  LOAT], [SQLITE_T
30b70 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c  EXT], [SQLITE_BL
30b80 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  OB], or [SQLITE_
30b90 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75  NULL].  The valu
30ba0 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79  e.** returned by
30bb0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
30bc0 74 79 70 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d  type() is only m
30bd0 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20  eaningful if no 
30be0 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69  type.** conversi
30bf0 6f 6e 73 20 68 61 76 65 20 6f 63 63 75 72 72 65  ons have occurre
30c00 64 20 61 73 20 64 65 73 63 72 69 62 65 64 20 62  d as described b
30c10 65 6c 6f 77 2e 20 20 41 66 74 65 72 20 61 20 74  elow.  After a t
30c20 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a  ype conversion,.
30c30 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  ** the value ret
30c40 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
30c50 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69  _column_type() i
30c60 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 46 75  s undefined.  Fu
30c70 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73  ture.** versions
30c80 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 63   of SQLite may c
30c90 68 61 6e 67 65 20 74 68 65 20 62 65 68 61 76 69  hange the behavi
30ca0 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f  or of sqlite3_co
30cb0 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66  lumn_type().** f
30cc0 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70 65 20  ollowing a type 
30cd0 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a  conversion..**.*
30ce0 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
30cf0 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54   is a BLOB or UT
30d00 46 2d 38 20 73 74 72 69 6e 67 20 74 68 65 6e 20  F-8 string then 
30d10 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  the sqlite3_colu
30d20 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f  mn_bytes().** ro
30d30 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
30d40 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
30d50 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f  s in that BLOB o
30d60 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66  r string..** ^If
30d70 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
30d80 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2c 20   UTF-16 string, 
30d90 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
30da0 75 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e 76  umn_bytes() conv
30db0 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69  erts.** the stri
30dc0 6e 67 20 74 6f 20 55 54 46 2d 38 20 61 6e 64 20  ng to UTF-8 and 
30dd0 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65  then returns the
30de0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
30df0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
30e00 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63  ult is a numeric
30e10 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69   value then sqli
30e20 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
30e30 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69  () uses.** [sqli
30e40 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20  te3_snprintf()] 
30e50 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20  to convert that 
30e60 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 38  value to a UTF-8
30e70 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75   string and retu
30e80 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65  rns.** the numbe
30e90 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
30ea0 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49  at string..** ^I
30eb0 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
30ec0 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74  NULL, then sqlit
30ed0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
30ee0 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a  ) returns zero..
30ef0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  **.** ^If the re
30f00 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f  sult is a BLOB o
30f10 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20  r UTF-16 string 
30f20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33  then the sqlite3
30f30 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
30f40 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74  ).** routine ret
30f50 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
30f60 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74  of bytes in that
30f70 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e   BLOB or string.
30f80 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
30f90 6c 74 20 69 73 20 61 20 55 54 46 2d 38 20 73 74  lt is a UTF-8 st
30fa0 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74  ring, then sqlit
30fb0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
30fc0 36 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20  6() converts.** 
30fd0 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54  the string to UT
30fe0 46 2d 31 36 20 61 6e 64 20 74 68 65 6e 20 72 65  F-16 and then re
30ff0 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
31000 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49   of bytes..** ^I
31010 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
31020 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20  a numeric value 
31030 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
31040 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 75 73  umn_bytes16() us
31050 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  es.** [sqlite3_s
31060 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f  nprintf()] to co
31070 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 65  nvert that value
31080 20 74 6f 20 61 20 55 54 46 2d 31 36 20 73 74 72   to a UTF-16 str
31090 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a  ing and returns.
310a0 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
310b0 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 73   bytes in that s
310c0 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68  tring..** ^If th
310d0 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c  e result is NULL
310e0 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  , then sqlite3_c
310f0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
31100 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a  returns zero..**
31110 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 73 20  .** ^The values 
31120 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
31130 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
31140 73 28 29 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73 71  s()] and .** [sq
31150 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
31160 65 73 31 36 28 29 5d 20 64 6f 20 6e 6f 74 20 69  es16()] do not i
31170 6e 63 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20  nclude the zero 
31180 74 65 72 6d 69 6e 61 74 6f 72 73 20 61 74 20 74  terminators at t
31190 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65  he end.** of the
311a0 20 73 74 72 69 6e 67 2e 20 20 5e 46 6f 72 20 63   string.  ^For c
311b0 6c 61 72 69 74 79 3a 20 74 68 65 20 76 61 6c 75  larity: the valu
311c0 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  es returned by.*
311d0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
311e0 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20 5b  n_bytes()] and [
311f0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
31200 79 74 65 73 31 36 28 29 5d 20 61 72 65 20 74 68  ytes16()] are th
31210 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62  e number of.** b
31220 79 74 65 73 20 69 6e 20 74 68 65 20 73 74 72 69  ytes in the stri
31230 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62  ng, not the numb
31240 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73  er of characters
31250 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67 73  ..**.** ^Strings
31260 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
31270 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
31280 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  () and sqlite3_c
31290 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a  olumn_text16(),.
312a0 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79 20 73 74  ** even empty st
312b0 72 69 6e 67 73 2c 20 61 72 65 20 61 6c 77 61 79  rings, are alway
312c0 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  s zero-terminate
312d0 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 0a  d.  ^The return.
312e0 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71  ** value from sq
312f0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
31300 62 28 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c  b() for a zero-l
31310 65 6e 67 74 68 20 42 4c 4f 42 20 69 73 20 61 20  ength BLOB is a 
31320 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
31330 0a 2a 2a 20 5e 54 68 65 20 6f 62 6a 65 63 74 20  .** ^The object 
31340 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
31350 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
31360 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75  e()] is an.** [u
31370 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
31380 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
31390 2e 20 20 41 6e 20 75 6e 70 72 6f 74 65 63 74 65  .  An unprotecte
313a0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  d sqlite3_value 
313b0 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e  object.** may on
313c0 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68 20  ly be used with 
313d0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61  [sqlite3_bind_va
313e0 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  lue()] and [sqli
313f0 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
31400 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b  ()]..** If the [
31410 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
31420 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
31430 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  t returned by.**
31440 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
31450 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 73 65  _value()] is use
31460 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 72 20 77  d in any other w
31470 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63 61  ay, including ca
31480 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e  lls.** to routin
31490 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33  es like [sqlite3
314a0 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b  _value_int()], [
314b0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
314c0 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71  xt()],.** or [sq
314d0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
314e0 73 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 62  s()], then the b
314f0 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66  ehavior is undef
31500 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ined..**.** Thes
31510 65 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d  e routines attem
31520 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68  pt to convert th
31530 65 20 76 61 6c 75 65 20 77 68 65 72 65 20 61 70  e value where ap
31540 70 72 6f 70 72 69 61 74 65 2e 20 20 5e 46 6f 72  propriate.  ^For
31550 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66 20  .** example, if 
31560 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70  the internal rep
31570 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 46  resentation is F
31580 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 78 74 20  LOAT and a text 
31590 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71  result.** is req
315a0 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 33  uested, [sqlite3
315b0 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 20  _snprintf()] is 
315c0 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20  used internally 
315d0 74 6f 20 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a  to perform the.*
315e0 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74  * conversion aut
315f0 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 5e 28 54  omatically.  ^(T
31600 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62  he following tab
31610 6c 65 20 64 65 74 61 69 6c 73 20 74 68 65 20 63  le details the c
31620 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68  onversions.** th
31630 61 74 20 61 72 65 20 61 70 70 6c 69 65 64 3a 0a  at are applied:.
31640 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
31650 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72  e>.** <table bor
31660 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e  der="1">.** <tr>
31670 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72  <th> Internal<br
31680 3e 54 79 70 65 20 3c 74 68 3e 20 52 65 71 75 65  >Type <th> Reque
31690 73 74 65 64 3c 62 72 3e 54 79 70 65 20 3c 74 68  sted<br>Type <th
316a0 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a  >  Conversion.**
316b0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
316c0 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  LL    <td> INTEG
316d0 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  ER   <td> Result
316e0 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64   is 0.** <tr><td
316f0 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
31700 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 52   FLOAT    <td> R
31710 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20  esult is 0.0.** 
31720 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
31730 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20    <td>   TEXT   
31740 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
31750 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
31760 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
31770 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
31780 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
31790 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
317a0 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52  <tr><td> INTEGER
317b0 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
317c0 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72   <td> Convert fr
317d0 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f 20 66 6c  om integer to fl
317e0 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  oat.** <tr><td> 
317f0 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20  INTEGER  <td>   
31800 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43  TEXT    <td> ASC
31810 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20  II rendering of 
31820 74 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c  the integer.** <
31830 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20  tr><td> INTEGER 
31840 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20   <td>   BLOB    
31850 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 49 4e 54  <td> Same as INT
31860 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74  EGER->TEXT.** <t
31870 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20  r><td>  FLOAT   
31880 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c  <td> INTEGER   <
31890 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d  td> Convert from
318a0 20 66 6c 6f 61 74 20 74 6f 20 69 6e 74 65 67 65   float to intege
318b0 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46  r.** <tr><td>  F
318c0 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 54 45  LOAT   <td>   TE
318d0 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49  XT    <td> ASCII
318e0 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68   rendering of th
318f0 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c  e float.** <tr><
31900 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64  td>  FLOAT   <td
31910 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  >   BLOB    <td>
31920 20 53 61 6d 65 20 61 73 20 46 4c 4f 41 54 2d 3e   Same as FLOAT->
31930 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  TEXT.** <tr><td>
31940 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 49    TEXT    <td> I
31950 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 55 73  NTEGER   <td> Us
31960 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e  e atoi().** <tr>
31970 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74  <td>  TEXT    <t
31980 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64  d>  FLOAT    <td
31990 3e 20 55 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20  > Use atof().** 
319a0 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20  <tr><td>  TEXT  
319b0 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
319c0 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a   <td> No change.
319d0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f  ** <tr><td>  BLO
319e0 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45  B    <td> INTEGE
319f0 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74  R   <td> Convert
31a00 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20 75 73   to TEXT then us
31a10 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e  e atoi().** <tr>
31a20 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74  <td>  BLOB    <t
31a30 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64  d>  FLOAT    <td
31a40 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45 58  > Convert to TEX
31a50 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f 66 28  T then use atof(
31a60 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42  ).** <tr><td>  B
31a70 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 20 54 45  LOB    <td>   TE
31a80 58 54 20 20 20 20 3c 74 64 3e 20 41 64 64 20 61  XT    <td> Add a
31a90 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
31aa0 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f   if needed.** </
31ab0 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63  table>.** </bloc
31ac0 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20  kquote>)^.**.** 
31ad0 54 68 65 20 74 61 62 6c 65 20 61 62 6f 76 65 20  The table above 
31ae0 6d 61 6b 65 73 20 72 65 66 65 72 65 6e 63 65 20  makes reference 
31af0 74 6f 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  to standard C li
31b00 62 72 61 72 79 20 66 75 6e 63 74 69 6f 6e 73 20  brary functions 
31b10 61 74 6f 69 28 29 0a 2a 2a 20 61 6e 64 20 61 74  atoi().** and at
31b20 6f 66 28 29 2e 20 20 53 51 4c 69 74 65 20 64 6f  of().  SQLite do
31b30 65 73 20 6e 6f 74 20 72 65 61 6c 6c 79 20 75 73  es not really us
31b40 65 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  e these function
31b50 73 2e 20 20 49 74 20 68 61 73 20 69 74 73 0a 2a  s.  It has its.*
31b60 2a 20 6f 77 6e 20 65 71 75 69 76 61 6c 65 6e 74  * own equivalent
31b70 20 69 6e 74 65 72 6e 61 6c 20 72 6f 75 74 69 6e   internal routin
31b80 65 73 2e 20 20 54 68 65 20 61 74 6f 69 28 29 20  es.  The atoi() 
31b90 61 6e 64 20 61 74 6f 66 28 29 20 6e 61 6d 65 73  and atof() names
31ba0 20 61 72 65 0a 2a 2a 20 75 73 65 64 20 69 6e 20   are.** used in 
31bb0 74 68 65 20 74 61 62 6c 65 20 66 6f 72 20 62 72  the table for br
31bc0 65 76 69 74 79 20 61 6e 64 20 62 65 63 61 75 73  evity and becaus
31bd0 65 20 74 68 65 79 20 61 72 65 20 66 61 6d 69 6c  e they are famil
31be0 69 61 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43  iar to most.** C
31bf0 20 70 72 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a   programmers..**
31c00 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 77 68  .** Note that wh
31c10 65 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69  en type conversi
31c20 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74  ons occur, point
31c30 65 72 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ers returned by 
31c40 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74  prior.** calls t
31c50 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  o sqlite3_column
31c60 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33  _blob(), sqlite3
31c70 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20  _column_text(), 
31c80 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  and/or.** sqlite
31c90 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
31ca0 29 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 69 64  ) may be invalid
31cb0 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f  ated..** Type co
31cc0 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f  nversions and po
31cd0 69 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 74 69  inter invalidati
31ce0 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a  ons might occur.
31cf0 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77  ** in the follow
31d00 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a  ing cases:.**.**
31d10 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68   <ul>.** <li> Th
31d20 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e  e initial conten
31d30 74 20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 20  t is a BLOB and 
31d40 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
31d50 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20  ext() or.**     
31d60 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
31d70 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c  text16() is call
31d80 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d  ed.  A zero-term
31d90 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20  inator might.** 
31da0 20 20 20 20 20 6e 65 65 64 20 74 6f 20 62 65 20       need to be 
31db0 61 64 64 65 64 20 74 6f 20 74 68 65 20 73 74 72  added to the str
31dc0 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69  ing.</li>.** <li
31dd0 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f  > The initial co
31de0 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 38 20 74  ntent is UTF-8 t
31df0 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  ext and sqlite3_
31e00 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
31e10 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69   or.**      sqli
31e20 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
31e30 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20  6() is called.  
31e40 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74  The content must
31e50 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a   be converted.**
31e60 20 20 20 20 20 20 74 6f 20 55 54 46 2d 31 36 2e        to UTF-16.
31e70 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68  </li>.** <li> Th
31e80 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e  e initial conten
31e90 74 20 69 73 20 55 54 46 2d 31 36 20 74 65 78 74  t is UTF-16 text
31ea0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
31eb0 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a  umn_bytes() or.*
31ec0 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63  *      sqlite3_c
31ed0 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 20  olumn_text() is 
31ee0 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e  called.  The con
31ef0 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e  tent must be con
31f00 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74  verted.**      t
31f10 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a  o UTF-8.</li>.**
31f20 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f   </ul>.**.** ^Co
31f30 6e 76 65 72 73 69 6f 6e 73 20 62 65 74 77 65 65  nversions betwee
31f40 6e 20 55 54 46 2d 31 36 62 65 20 61 6e 64 20 55  n UTF-16be and U
31f50 54 46 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 61  TF-16le are alwa
31f60 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65  ys done in place
31f70 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69   and do.** not i
31f80 6e 76 61 6c 69 64 61 74 65 20 61 20 70 72 69 6f  nvalidate a prio
31f90 72 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67  r pointer, thoug
31fa0 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68 65 20  h of course the 
31fb0 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 62  content of the b
31fc0 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 68  uffer.** that th
31fd0 65 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 20  e prior pointer 
31fe0 72 65 66 65 72 65 6e 63 65 73 20 77 69 6c 6c 20  references will 
31ff0 68 61 76 65 20 62 65 65 6e 20 6d 6f 64 69 66 69  have been modifi
32000 65 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64 73  ed.  Other kinds
32010 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f  .** of conversio
32020 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c  n are done in pl
32030 61 63 65 20 77 68 65 6e 20 69 74 20 69 73 20 70  ace when it is p
32040 6f 73 73 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d  ossible, but som
32050 65 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61  etimes they.** a
32060 72 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  re not possible 
32070 61 6e 64 20 69 6e 20 74 68 6f 73 65 20 63 61 73  and in those cas
32080 65 73 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72  es prior pointer
32090 73 20 61 72 65 20 69 6e 76 61 6c 69 64 61 74 65  s are invalidate
320a0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66  d..**.** The saf
320b0 65 73 74 20 61 6e 64 20 65 61 73 69 65 73 74 20  est and easiest 
320c0 74 6f 20 72 65 6d 65 6d 62 65 72 20 70 6f 6c 69  to remember poli
320d0 63 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20  cy is to invoke 
320e0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a  these routines.*
320f0 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20  * in one of the 
32100 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a  following ways:.
32110 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c  **.** <ul>.**  <
32120 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  li>sqlite3_colum
32130 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65  n_text() followe
32140 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
32150 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e  umn_bytes()</li>
32160 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33  .**  <li>sqlite3
32170 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66  _column_blob() f
32180 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74  ollowed by sqlit
32190 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
321a0 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73  )</li>.**  <li>s
321b0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
321c0 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20  xt16() followed 
321d0 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
321e0 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e  n_bytes16()</li>
321f0 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
32200 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
32210 79 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20  you should call 
32220 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
32230 65 78 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65  ext(),.** sqlite
32240 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c  3_column_blob(),
32250 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   or sqlite3_colu
32260 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 69 72 73  mn_text16() firs
32270 74 20 74 6f 20 66 6f 72 63 65 20 74 68 65 20 72  t to force the r
32280 65 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68  esult.** into th
32290 65 20 64 65 73 69 72 65 64 20 66 6f 72 6d 61 74  e desired format
322a0 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71  , then invoke sq
322b0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
322c0 65 73 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74  es() or.** sqlit
322d0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
322e0 36 28 29 20 74 6f 20 66 69 6e 64 20 74 68 65 20  6() to find the 
322f0 73 69 7a 65 20 6f 66 20 74 68 65 20 72 65 73 75  size of the resu
32300 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20  lt.  Do not mix 
32310 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69  calls.** to sqli
32320 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
32330 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ) or sqlite3_col
32340 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68 20  umn_blob() with 
32350 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69  calls to.** sqli
32360 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
32370 31 36 28 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74  16(), and do not
32380 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20 73 71   mix calls to sq
32390 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
323a0 74 31 36 28 29 0a 2a 2a 20 77 69 74 68 20 63 61  t16().** with ca
323b0 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lls to sqlite3_c
323c0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a  olumn_bytes()..*
323d0 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f 69 6e 74 65  *.** ^The pointe
323e0 72 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20  rs returned are 
323f0 76 61 6c 69 64 20 75 6e 74 69 6c 20 61 20 74 79  valid until a ty
32400 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63  pe conversion oc
32410 63 75 72 73 20 61 73 0a 2a 2a 20 64 65 73 63 72  curs as.** descr
32420 69 62 65 64 20 61 62 6f 76 65 2c 20 6f 72 20 75  ibed above, or u
32430 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74  ntil [sqlite3_st
32440 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ep()] or [sqlite
32450 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a  3_reset()] or.**
32460 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
32470 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e  ze()] is called.
32480 20 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 73 70    ^The memory sp
32490 61 63 65 20 75 73 65 64 20 74 6f 20 68 6f 6c 64  ace used to hold
324a0 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20   strings.** and 
324b0 42 4c 4f 42 73 20 69 73 20 66 72 65 65 64 20 61  BLOBs is freed a
324c0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44  utomatically.  D
324d0 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73  o <b>not</b> pas
324e0 73 20 74 68 65 20 70 6f 69 6e 74 65 72 73 20 72  s the pointers r
324f0 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 73 71 6c 69  eturned.** [sqli
32500 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
32510 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  )], [sqlite3_col
32520 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74 63  umn_text()], etc
32530 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  . into.** [sqlit
32540 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a  e3_free()]..**.*
32550 2a 20 5e 28 49 66 20 61 20 6d 65 6d 6f 72 79 20  * ^(If a memory 
32560 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72  allocation error
32570 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 74   occurs during t
32580 68 65 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66  he evaluation of
32590 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65   any.** of these
325a0 20 72 6f 75 74 69 6e 65 73 2c 20 61 20 64 65 66   routines, a def
325b0 61 75 6c 74 20 76 61 6c 75 65 20 69 73 20 72 65  ault value is re
325c0 74 75 72 6e 65 64 2e 20 20 54 68 65 20 64 65 66  turned.  The def
325d0 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73  ault value.** is
325e0 20 65 69 74 68 65 72 20 74 68 65 20 69 6e 74 65   either the inte
325f0 67 65 72 20 30 2c 20 74 68 65 20 66 6c 6f 61 74  ger 0, the float
32600 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72  ing point number
32610 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a   0.0, or a NULL.
32620 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53 75 62  ** pointer.  Sub
32630 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
32640 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64   [sqlite3_errcod
32650 65 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  e()] will return
32660 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45  .** [SQLITE_NOME
32670 4d 5d 2e 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  M].)^.*/.SQLITE_
32680 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  API const void *
32690 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
326a0 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lob(sqlite3_stmt
326b0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51  *, int iCol);.SQ
326c0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
326d0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
326e0 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  s(sqlite3_stmt*,
326f0 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49   int iCol);.SQLI
32700 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
32710 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
32720 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
32730 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49   int iCol);.SQLI
32740 54 45 5f 41 50 49 20 64 6f 75 62 6c 65 20 73 71  TE_API double sq
32750 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75  lite3_column_dou
32760 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ble(sqlite3_stmt
32770 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51  *, int iCol);.SQ
32780 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
32790 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28  ite3_column_int(
327a0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
327b0 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45  nt iCol);.SQLITE
327c0 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74  _API sqlite3_int
327d0 36 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  64 sqlite3_colum
327e0 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f  n_int64(sqlite3_
327f0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
32800 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  ;.SQLITE_API con
32810 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72  st unsigned char
32820 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
32830 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74  _text(sqlite3_st
32840 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
32850 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
32860 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
32870 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 73 71 6c  olumn_text16(sql
32880 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
32890 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50  iCol);.SQLITE_AP
328a0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  I int sqlite3_co
328b0 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74 65  lumn_type(sqlite
328c0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
328d0 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73  l);.SQLITE_API s
328e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 73 71  qlite3_value *sq
328f0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c  lite3_column_val
32900 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ue(sqlite3_stmt*
32910 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a  , int iCol);../*
32920 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
32930 73 74 72 6f 79 20 41 20 50 72 65 70 61 72 65 64  stroy A Prepared
32940 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63   Statement Objec
32950 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  t.**.** ^The sql
32960 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20  ite3_finalize() 
32970 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c  function is call
32980 65 64 20 74 6f 20 64 65 6c 65 74 65 20 61 20 5b  ed to delete a [
32990 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
329a0 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  nt]..** ^If the 
329b0 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c  most recent eval
329c0 75 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 74  uation of the st
329d0 61 74 65 6d 65 6e 74 20 65 6e 63 6f 75 6e 74 65  atement encounte
329e0 72 65 64 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a  red no errors.**
329f0 20 6f 72 20 69 66 20 74 68 65 20 73 74 61 74 65   or if the state
32a00 6d 65 6e 74 20 69 73 20 6e 65 76 65 72 20 62 65  ment is never be
32a10 65 6e 20 65 76 61 6c 75 61 74 65 64 2c 20 74 68  en evaluated, th
32a20 65 6e 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  en sqlite3_final
32a30 69 7a 65 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a  ize() returns.**
32a40 20 53 51 4c 49 54 45 5f 4f 4b 2e 20 20 5e 49 66   SQLITE_OK.  ^If
32a50 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
32a60 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 73   evaluation of s
32a70 74 61 74 65 6d 65 6e 74 20 53 20 66 61 69 6c 65  tatement S faile
32a80 64 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74  d, then.** sqlit
32a90 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72  e3_finalize(S) r
32aa0 65 74 75 72 6e 73 20 74 68 65 20 61 70 70 72 6f  eturns the appro
32ab0 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f  priate [error co
32ac0 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e  de] or.** [exten
32ad0 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 2e  ded error code].
32ae0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
32af0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20  te3_finalize(S) 
32b00 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 63  routine can be c
32b10 61 6c 6c 65 64 20 61 74 20 61 6e 79 20 70 6f 69  alled at any poi
32b20 6e 74 20 64 75 72 69 6e 67 0a 2a 2a 20 74 68 65  nt during.** the
32b30 20 6c 69 66 65 20 63 79 63 6c 65 20 6f 66 20 5b   life cycle of [
32b40 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
32b50 6e 74 5d 20 53 3a 0a 2a 2a 20 62 65 66 6f 72 65  nt] S:.** before
32b60 20 73 74 61 74 65 6d 65 6e 74 20 53 20 69 73 20   statement S is 
32b70 65 76 65 72 20 65 76 61 6c 75 61 74 65 64 2c 20  ever evaluated, 
32b80 61 66 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20  after.** one or 
32b90 6d 6f 72 65 20 63 61 6c 6c 73 20 74 6f 20 5b 73  more calls to [s
32ba0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c  qlite3_reset()],
32bb0 20 6f 72 20 61 66 74 65 72 20 61 6e 79 20 63 61   or after any ca
32bc0 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65  ll.** to [sqlite
32bd0 33 5f 73 74 65 70 28 29 5d 20 72 65 67 61 72 64  3_step()] regard
32be0 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20  less of whether 
32bf0 6f 72 20 6e 6f 74 20 74 68 65 20 73 74 61 74 65  or not the state
32c00 6d 65 6e 74 20 68 61 73 0a 2a 2a 20 63 6f 6d 70  ment has.** comp
32c10 6c 65 74 65 64 20 65 78 65 63 75 74 69 6f 6e 2e  leted execution.
32c20 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b 69 6e 67  .**.** ^Invoking
32c30 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
32c40 65 28 29 20 6f 6e 20 61 20 4e 55 4c 4c 20 70 6f  e() on a NULL po
32c50 69 6e 74 65 72 20 69 73 20 61 20 68 61 72 6d 6c  inter is a harml
32c60 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a  ess no-op..**.**
32c70 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
32c80 20 6d 75 73 74 20 66 69 6e 61 6c 69 7a 65 20 65   must finalize e
32c90 76 65 72 79 20 5b 70 72 65 70 61 72 65 64 20 73  very [prepared s
32ca0 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 6f 72 64  tatement] in ord
32cb0 65 72 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 72  er to avoid.** r
32cc0 65 73 6f 75 72 63 65 20 6c 65 61 6b 73 2e 20 20  esource leaks.  
32cd0 49 74 20 69 73 20 61 20 67 72 69 65 76 6f 75 73  It is a grievous
32ce0 20 65 72 72 6f 72 20 66 6f 72 20 74 68 65 20 61   error for the a
32cf0 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 74 72  pplication to tr
32d00 79 20 74 6f 20 75 73 65 0a 2a 2a 20 61 20 70 72  y to use.** a pr
32d10 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
32d20 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65   after it has be
32d30 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 20 20 41  en finalized.  A
32d40 6e 79 20 75 73 65 20 6f 66 20 61 20 70 72 65 70  ny use of a prep
32d50 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  ared.** statemen
32d60 74 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62  t after it has b
32d70 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 20 63 61  een finalized ca
32d80 6e 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65  n result in unde
32d90 66 69 6e 65 64 20 61 6e 64 0a 2a 2a 20 75 6e 64  fined and.** und
32da0 65 73 69 72 61 62 6c 65 20 62 65 68 61 76 69 6f  esirable behavio
32db0 72 20 73 75 63 68 20 61 73 20 73 65 67 66 61 75  r such as segfau
32dc0 6c 74 73 20 61 6e 64 20 68 65 61 70 20 63 6f 72  lts and heap cor
32dd0 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49  ruption..*/.SQLI
32de0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
32df0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c 69  e3_finalize(sqli
32e00 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
32e10 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
32e20 46 3a 20 52 65 73 65 74 20 41 20 50 72 65 70 61  F: Reset A Prepa
32e30 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62  red Statement Ob
32e40 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ject.**.** The s
32e50 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 20 66  qlite3_reset() f
32e60 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65  unction is calle
32e70 64 20 74 6f 20 72 65 73 65 74 20 61 20 5b 70 72  d to reset a [pr
32e80 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
32e90 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 62 61 63 6b  ].** object back
32ea0 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20   to its initial 
32eb0 73 74 61 74 65 2c 20 72 65 61 64 79 20 74 6f 20  state, ready to 
32ec0 62 65 20 72 65 2d 65 78 65 63 75 74 65 64 2e 0a  be re-executed..
32ed0 2a 2a 20 5e 41 6e 79 20 53 51 4c 20 73 74 61 74  ** ^Any SQL stat
32ee0 65 6d 65 6e 74 20 76 61 72 69 61 62 6c 65 73 20  ement variables 
32ef0 74 68 61 74 20 68 61 64 20 76 61 6c 75 65 73 20  that had values 
32f00 62 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20 75 73  bound to them us
32f10 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69  ing.** the [sqli
32f20 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20  te3_bind_blob | 
32f30 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
32f40 20 41 50 49 5d 20 72 65 74 61 69 6e 20 74 68 65   API] retain the
32f50 69 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 55 73  ir values..** Us
32f60 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61 72  e [sqlite3_clear
32f70 5f 62 69 6e 64 69 6e 67 73 28 29 5d 20 74 6f 20  _bindings()] to 
32f80 72 65 73 65 74 20 74 68 65 20 62 69 6e 64 69 6e  reset the bindin
32f90 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b  gs..**.** ^The [
32fa0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
32fb0 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 73 65  ] interface rese
32fc0 74 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  ts the [prepared
32fd0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a   statement] S.**
32fe0 20 62 61 63 6b 20 74 6f 20 74 68 65 20 62 65 67   back to the beg
32ff0 69 6e 6e 69 6e 67 20 6f 66 20 69 74 73 20 70 72  inning of its pr
33000 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  ogram..**.** ^If
33010 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
33020 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
33030 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74  3_step(S)] for t
33040 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
33050 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 72 65 74  statement] S ret
33060 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f  urned [SQLITE_RO
33070 57 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f  W] or [SQLITE_DO
33080 4e 45 5d 2c 0a 2a 2a 20 6f 72 20 69 66 20 5b 73  NE],.** or if [s
33090 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
330a0 68 61 73 20 6e 65 76 65 72 20 62 65 66 6f 72 65  has never before
330b0 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20   been called on 
330c0 53 2c 0a 2a 2a 20 74 68 65 6e 20 5b 73 71 6c 69  S,.** then [sqli
330d0 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65  te3_reset(S)] re
330e0 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
330f0 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  ]..**.** ^If the
33100 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c   most recent cal
33110 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  l to [sqlite3_st
33120 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a  ep(S)] for the.*
33130 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
33140 65 6d 65 6e 74 5d 20 53 20 69 6e 64 69 63 61 74  ement] S indicat
33150 65 64 20 61 6e 20 65 72 72 6f 72 2c 20 74 68 65  ed an error, the
33160 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  n.** [sqlite3_re
33170 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20  set(S)] returns 
33180 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b  an appropriate [
33190 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a  error code]..**.
331a0 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33  ** ^The [sqlite3
331b0 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72  _reset(S)] inter
331c0 66 61 63 65 20 64 6f 65 73 20 6e 6f 74 20 63 68  face does not ch
331d0 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 73 0a  ange the values.
331e0 2a 2a 20 6f 66 20 61 6e 79 20 5b 73 71 6c 69 74  ** of any [sqlit
331f0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e  e3_bind_blob|bin
33200 64 69 6e 67 73 5d 20 6f 6e 20 74 68 65 20 5b 70  dings] on the [p
33210 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
33220 74 5d 20 53 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  t] S..*/.SQLITE_
33230 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
33240 72 65 73 65 74 28 73 71 6c 69 74 65 33 5f 73 74  reset(sqlite3_st
33250 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
33260 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 72 65  ** CAPI3REF: Cre
33270 61 74 65 20 4f 72 20 52 65 64 65 66 69 6e 65 20  ate Or Redefine 
33280 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  SQL Functions.**
33290 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63   KEYWORDS: {func
332a0 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f  tion creation ro
332b0 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f  utines}.** KEYWO
332c0 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f  RDS: {applicatio
332d0 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
332e0 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f  nction}.** KEYWO
332f0 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f  RDS: {applicatio
33300 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
33310 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 5e  nctions}.**.** ^
33320 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
33330 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e  (collectively kn
33340 6f 77 6e 20 61 73 20 22 66 75 6e 63 74 69 6f 6e  own as "function
33350 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e   creation routin
33360 65 73 22 29 0a 2a 2a 20 61 72 65 20 75 73 65 64  es").** are used
33370 20 74 6f 20 61 64 64 20 53 51 4c 20 66 75 6e 63   to add SQL func
33380 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61  tions or aggrega
33390 74 65 73 20 6f 72 20 74 6f 20 72 65 64 65 66 69  tes or to redefi
333a0 6e 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a  ne the behavior.
333b0 2a 2a 20 6f 66 20 65 78 69 73 74 69 6e 67 20 53  ** of existing S
333c0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20  QL functions or 
333d0 61 67 67 72 65 67 61 74 65 73 2e 20 20 54 68 65  aggregates.  The
333e0 20 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65   only difference
333f0 73 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65  s between.** the
33400 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
33410 74 68 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  the text encodin
33420 67 20 65 78 70 65 63 74 65 64 20 66 6f 72 0a 2a  g expected for.*
33430 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  * the second par
33440 61 6d 65 74 65 72 20 28 74 68 65 20 6e 61 6d 65  ameter (the name
33450 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e   of the function
33460 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 29 0a   being created).
33470 2a 2a 20 61 6e 64 20 74 68 65 20 70 72 65 73 65  ** and the prese
33480 6e 63 65 20 6f 72 20 61 62 73 65 6e 63 65 20 6f  nce or absence o
33490 66 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 63  f a destructor c
334a0 61 6c 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a 20 74  allback for.** t
334b0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
334c0 61 74 61 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ata pointer..**.
334d0 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70 61  ** ^The first pa
334e0 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b  rameter is the [
334f0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
33500 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20 74 68  ion] to which th
33510 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f  e SQL.** functio
33520 6e 20 69 73 20 74 6f 20 62 65 20 61 64 64 65 64  n is to be added
33530 2e 20 20 5e 49 66 20 61 6e 20 61 70 70 6c 69 63  .  ^If an applic
33540 61 74 69 6f 6e 20 75 73 65 73 20 6d 6f 72 65 20  ation uses more 
33550 74 68 61 6e 20 6f 6e 65 20 64 61 74 61 62 61 73  than one databas
33560 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  e.** connection 
33570 74 68 65 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  then application
33580 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
33590 63 74 69 6f 6e 73 20 6d 75 73 74 20 62 65 20 61  ctions must be a
335a0 64 64 65 64 0a 2a 2a 20 74 6f 20 65 61 63 68 20  dded.** to each 
335b0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
335c0 69 6f 6e 20 73 65 70 61 72 61 74 65 6c 79 2e 0a  ion separately..
335d0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e  **.** ^The secon
335e0 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  d parameter is t
335f0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53  he name of the S
33600 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  QL function to b
33610 65 20 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20  e created or.** 
33620 72 65 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65  redefined.  ^The
33630 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 6e   length of the n
33640 61 6d 65 20 69 73 20 6c 69 6d 69 74 65 64 20 74  ame is limited t
33650 6f 20 32 35 35 20 62 79 74 65 73 20 69 6e 20 61  o 255 bytes in a
33660 20 55 54 46 2d 38 0a 2a 2a 20 72 65 70 72 65 73   UTF-8.** repres
33670 65 6e 74 61 74 69 6f 6e 2c 20 65 78 63 6c 75 73  entation, exclus
33680 69 76 65 20 6f 66 20 74 68 65 20 7a 65 72 6f 2d  ive of the zero-
33690 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f  terminator.  ^No
336a0 74 65 20 74 68 61 74 20 74 68 65 20 6e 61 6d 65  te that the name
336b0 0a 2a 2a 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74  .** length limit
336c0 20 69 73 20 69 6e 20 55 54 46 2d 38 20 62 79 74   is in UTF-8 byt
336d0 65 73 2c 20 6e 6f 74 20 63 68 61 72 61 63 74 65  es, not characte
336e0 72 73 20 6e 6f 72 20 55 54 46 2d 31 36 20 62 79  rs nor UTF-16 by
336f0 74 65 73 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20 61  tes.  .** ^Any a
33700 74 74 65 6d 70 74 20 74 6f 20 63 72 65 61 74 65  ttempt to create
33710 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68   a function with
33720 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a   a longer name.*
33730 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e  * will result in
33740 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
33750 20 62 65 69 6e 67 20 72 65 74 75 72 6e 65 64 2e   being returned.
33760 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72  .**.** ^The thir
33770 64 20 70 61 72 61 6d 65 74 65 72 20 28 6e 41 72  d parameter (nAr
33780 67 29 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d  g).** is the num
33790 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73  ber of arguments
337a0 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 66 75   that the SQL fu
337b0 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67  nction or.** agg
337c0 72 65 67 61 74 65 20 74 61 6b 65 73 2e 20 5e 49  regate takes. ^I
337d0 66 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 72  f this parameter
337e0 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 74 68 65   is -1, then the
337f0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
33800 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61  .** aggregate ma
33810 79 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65  y take any numbe
33820 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 62  r of arguments b
33830 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68 65  etween 0 and the
33840 20 6c 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62 79   limit.** set by
33850 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d   [sqlite3_limit]
33860 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46  ([SQLITE_LIMIT_F
33870 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20 20  UNCTION_ARG]).  
33880 49 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20  If the third.** 
33890 70 61 72 61 6d 65 74 65 72 20 69 73 20 6c 65 73  parameter is les
338a0 73 20 74 68 61 6e 20 2d 31 20 6f 72 20 67 72 65  s than -1 or gre
338b0 61 74 65 72 20 74 68 61 6e 20 31 32 37 20 74 68  ater than 127 th
338c0 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
338d0 69 73 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e  is.** undefined.
338e0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72  .**.** ^The four
338f0 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20 65 54  th parameter, eT
33900 65 78 74 52 65 70 2c 20 73 70 65 63 69 66 69 65  extRep, specifie
33910 73 20 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54  s what.** [SQLIT
33920 45 5f 55 54 46 38 20 7c 20 74 65 78 74 20 65 6e  E_UTF8 | text en
33930 63 6f 64 69 6e 67 5d 20 74 68 69 73 20 53 51 4c  coding] this SQL
33940 20 66 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 72   function prefer
33950 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72  s for.** its par
33960 61 6d 65 74 65 72 73 2e 20 20 45 76 65 72 79 20  ameters.  Every 
33970 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70  SQL function imp
33980 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74  lementation must
33990 20 62 65 20 61 62 6c 65 20 74 6f 20 77 6f 72 6b   be able to work
339a0 0a 2a 2a 20 77 69 74 68 20 55 54 46 2d 38 2c 20  .** with UTF-8, 
339b0 55 54 46 2d 31 36 6c 65 2c 20 6f 72 20 55 54 46  UTF-16le, or UTF
339c0 2d 31 36 62 65 2e 20 20 42 75 74 20 73 6f 6d 65  -16be.  But some
339d0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
339e0 20 6d 61 79 20 62 65 0a 2a 2a 20 6d 6f 72 65 20   may be.** more 
339f0 65 66 66 69 63 69 65 6e 74 20 77 69 74 68 20 6f  efficient with o
33a00 6e 65 20 65 6e 63 6f 64 69 6e 67 20 74 68 61 6e  ne encoding than
33a10 20 61 6e 6f 74 68 65 72 2e 20 20 5e 41 6e 20 61   another.  ^An a
33a20 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 0a 2a  pplication may.*
33a30 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33  * invoke sqlite3
33a40 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
33a50 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 72  () or sqlite3_cr
33a60 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
33a70 29 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 74 69  ) multiple.** ti
33a80 6d 65 73 20 77 69 74 68 20 74 68 65 20 73 61 6d  mes with the sam
33a90 65 20 66 75 6e 63 74 69 6f 6e 20 62 75 74 20 77  e function but w
33aa0 69 74 68 20 64 69 66 66 65 72 65 6e 74 20 76 61  ith different va
33ab0 6c 75 65 73 20 6f 66 20 65 54 65 78 74 52 65 70  lues of eTextRep
33ac0 2e 0a 2a 2a 20 5e 57 68 65 6e 20 6d 75 6c 74 69  ..** ^When multi
33ad0 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ple implementati
33ae0 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ons of the same 
33af0 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 61 76 61  function are ava
33b00 69 6c 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a  ilable, SQLite.*
33b10 2a 20 77 69 6c 6c 20 70 69 63 6b 20 74 68 65 20  * will pick the 
33b20 6f 6e 65 20 74 68 61 74 20 69 6e 76 6f 6c 76 65  one that involve
33b30 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75  s the least amou
33b40 6e 74 20 6f 66 20 64 61 74 61 20 63 6f 6e 76 65  nt of data conve
33b50 72 73 69 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65  rsion..** If the
33b60 72 65 20 69 73 20 6f 6e 6c 79 20 61 20 73 69 6e  re is only a sin
33b70 67 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  gle implementati
33b80 6f 6e 20 77 68 69 63 68 20 64 6f 65 73 20 6e 6f  on which does no
33b90 74 20 63 61 72 65 20 77 68 61 74 20 74 65 78 74  t care what text
33ba0 0a 2a 2a 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  .** encoding is 
33bb0 75 73 65 64 2c 20 74 68 65 6e 20 74 68 65 20 66  used, then the f
33bc0 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 73  ourth argument s
33bd0 68 6f 75 6c 64 20 62 65 20 5b 53 51 4c 49 54 45  hould be [SQLITE
33be0 5f 41 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  _ANY]..**.** ^(T
33bf0 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74  he fifth paramet
33c00 65 72 20 69 73 20 61 6e 20 61 72 62 69 74 72 61  er is an arbitra
33c10 72 79 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65  ry pointer.  The
33c20 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
33c30 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69  of the.** functi
33c40 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61 63 63 65  on can gain acce
33c50 73 73 20 74 6f 20 74 68 69 73 20 70 6f 69 6e 74  ss to this point
33c60 65 72 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  er using [sqlite
33c70 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2e 29  3_user_data()].)
33c80 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78  ^.**.** ^The six
33c90 74 68 2c 20 73 65 76 65 6e 74 68 20 61 6e 64 20  th, seventh and 
33ca0 65 69 67 68 74 68 20 70 61 72 61 6d 65 74 65 72  eighth parameter
33cb0 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 70 20  s, xFunc, xStep 
33cc0 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a  and xFinal, are.
33cd0 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 43  ** pointers to C
33ce0 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 74 69  -language functi
33cf0 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65  ons that impleme
33d00 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  nt the SQL funct
33d10 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67  ion or.** aggreg
33d20 61 74 65 2e 20 5e 41 20 73 63 61 6c 61 72 20 53  ate. ^A scalar S
33d30 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75  QL function requ
33d40 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e  ires an implemen
33d50 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 46  tation of the xF
33d60 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  unc.** callback 
33d70 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74  only; NULL point
33d80 65 72 73 20 6d 75 73 74 20 62 65 20 70 61 73 73  ers must be pass
33d90 65 64 20 61 73 20 74 68 65 20 78 53 74 65 70 20  ed as the xStep 
33da0 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61  and xFinal.** pa
33db0 72 61 6d 65 74 65 72 73 2e 20 5e 41 6e 20 61 67  rameters. ^An ag
33dc0 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63  gregate SQL func
33dd0 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e  tion requires an
33de0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
33df0 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20  of xStep.** and 
33e00 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20  xFinal and NULL 
33e10 70 6f 69 6e 74 65 72 20 6d 75 73 74 20 62 65 20  pointer must be 
33e20 70 61 73 73 65 64 20 66 6f 72 20 78 46 75 6e 63  passed for xFunc
33e30 2e 20 5e 54 6f 20 64 65 6c 65 74 65 20 61 6e 20  . ^To delete an 
33e40 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20  existing.** SQL 
33e50 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72  function or aggr
33e60 65 67 61 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c  egate, pass NULL
33e70 20 70 6f 69 6e 74 65 72 73 20 66 6f 72 20 61 6c   pointers for al
33e80 6c 20 74 68 72 65 65 20 66 75 6e 63 74 69 6f 6e  l three function
33e90 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a  .** callbacks..*
33ea0 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20 6e 69  *.** ^(If the ni
33eb0 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  nth parameter to
33ec0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
33ed0 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 69 73  function_v2() is
33ee0 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68   not NULL,.** th
33ef0 65 6e 20 69 74 20 69 73 20 64 65 73 74 72 75 63  en it is destruc
33f00 74 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c  tor for the appl
33f10 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69  ication data poi
33f20 6e 74 65 72 2e 20 0a 2a 2a 20 54 68 65 20 64 65  nter. .** The de
33f30 73 74 72 75 63 74 6f 72 20 69 73 20 69 6e 76 6f  structor is invo
33f40 6b 65 64 20 77 68 65 6e 20 74 68 65 20 66 75 6e  ked when the fun
33f50 63 74 69 6f 6e 20 69 73 20 64 65 6c 65 74 65 64  ction is deleted
33f60 2c 20 65 69 74 68 65 72 20 62 79 20 62 65 69 6e  , either by bein
33f70 67 0a 2a 2a 20 6f 76 65 72 6c 6f 61 64 65 64 20  g.** overloaded 
33f80 6f 72 20 77 68 65 6e 20 74 68 65 20 64 61 74 61  or when the data
33f90 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
33fa0 63 6c 6f 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68  closes.)^.** ^Th
33fb0 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20  e destructor is 
33fc0 61 6c 73 6f 20 69 6e 76 6f 6b 65 64 20 69 66 20  also invoked if 
33fd0 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73  the call to.** s
33fe0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
33ff0 6e 63 74 69 6f 6e 5f 76 32 28 29 20 66 61 69 6c  nction_v2() fail
34000 73 2e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20  s..** ^When the 
34010 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62  destructor callb
34020 61 63 6b 20 6f 66 20 74 68 65 20 74 65 6e 74 68  ack of the tenth
34030 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 69 6e   parameter is in
34040 76 6f 6b 65 64 2c 20 69 74 0a 2a 2a 20 69 73 20  voked, it.** is 
34050 70 61 73 73 65 64 20 61 20 73 69 6e 67 6c 65 20  passed a single 
34060 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
34070 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
34080 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61  application data
34090 20 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 77 68 69   .** pointer whi
340a0 63 68 20 77 61 73 20 74 68 65 20 66 69 66 74 68  ch was the fifth
340b0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
340c0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
340d0 63 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a  ction_v2()..**.*
340e0 2a 20 5e 49 74 20 69 73 20 70 65 72 6d 69 74 74  * ^It is permitt
340f0 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d  ed to register m
34100 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e  ultiple implemen
34110 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  tations of the s
34120 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73  ame.** functions
34130 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e   with the same n
34140 61 6d 65 20 62 75 74 20 77 69 74 68 20 65 69 74  ame but with eit
34150 68 65 72 20 64 69 66 66 65 72 69 6e 67 20 6e 75  her differing nu
34160 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75  mbers of.** argu
34170 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 65 72 69  ments or differi
34180 6e 67 20 70 72 65 66 65 72 72 65 64 20 74 65 78  ng preferred tex
34190 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 5e 53  t encodings.  ^S
341a0 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a  QLite will use.*
341b0 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  * the implementa
341c0 74 69 6f 6e 20 74 68 61 74 20 6d 6f 73 74 20 63  tion that most c
341d0 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 20 74  losely matches t
341e0 68 65 20 77 61 79 20 69 6e 20 77 68 69 63 68 20  he way in which 
341f0 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74  the.** SQL funct
34200 69 6f 6e 20 69 73 20 75 73 65 64 2e 20 20 5e 41  ion is used.  ^A
34210 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
34220 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 20 61 20  entation with a 
34230 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20  non-negative.** 
34240 6e 41 72 67 20 70 61 72 61 6d 65 74 65 72 20 69  nArg parameter i
34250 73 20 61 20 62 65 74 74 65 72 20 6d 61 74 63 68  s a better match
34260 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e   than a function
34270 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
34280 77 69 74 68 0a 2a 2a 20 61 20 6e 65 67 61 74 69  with.** a negati
34290 76 65 20 6e 41 72 67 2e 20 20 5e 41 20 66 75 6e  ve nArg.  ^A fun
342a0 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20  ction where the 
342b0 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65  preferred text e
342c0 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 68  ncoding.** match
342d0 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  es the database 
342e0 65 6e 63 6f 64 69 6e 67 20 69 73 20 61 20 62 65  encoding is a be
342f0 74 74 65 72 0a 2a 2a 20 6d 61 74 63 68 20 74 68  tter.** match th
34300 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68  an a function wh
34310 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67  ere the encoding
34320 20 69 73 20 64 69 66 66 65 72 65 6e 74 2e 20 20   is different.  
34330 0a 2a 2a 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20  .** ^A function 
34340 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69  where the encodi
34350 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 73  ng difference is
34360 20 62 65 74 77 65 65 6e 20 55 54 46 31 36 6c 65   between UTF16le
34370 20 61 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a 20   and UTF16be.** 
34380 69 73 20 61 20 63 6c 6f 73 65 72 20 6d 61 74 63  is a closer matc
34390 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f  h than a functio
343a0 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f  n where the enco
343b0 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20  ding difference 
343c0 69 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55 54  is.** between UT
343d0 46 38 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a 2a  F8 and UTF16..**
343e0 0a 2a 2a 20 5e 42 75 69 6c 74 2d 69 6e 20 66 75  .** ^Built-in fu
343f0 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f  nctions may be o
34400 76 65 72 6c 6f 61 64 65 64 20 62 79 20 6e 65 77  verloaded by new
34410 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
34420 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a  ined functions..
34430 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c 69 63  **.** ^An applic
34440 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
34450 6e 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74  nction is permit
34460 74 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65  ted to call othe
34470 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65  r.** SQLite inte
34480 72 66 61 63 65 73 2e 20 20 48 6f 77 65 76 65 72  rfaces.  However
34490 2c 20 73 75 63 68 20 63 61 6c 6c 73 20 6d 75 73  , such calls mus
344a0 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74  t not.** close t
344b0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
344c0 65 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c  ection nor final
344d0 69 7a 65 20 6f 72 20 72 65 73 65 74 20 74 68 65  ize or reset the
344e0 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61   prepared.** sta
344f0 74 65 6d 65 6e 74 20 69 6e 20 77 68 69 63 68 20  tement in which 
34500 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  the function is 
34510 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49  running..*/.SQLI
34520 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
34530 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
34540 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  on(.  sqlite3 *d
34550 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  b,.  const char 
34560 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a  *zFunctionName,.
34570 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e    int nArg,.  in
34580 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f  t eTextRep,.  vo
34590 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64  id *pApp,.  void
345a0 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65   (*xFunc)(sqlite
345b0 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
345c0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
345d0 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29  .  void (*xStep)
345e0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
345f0 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
34600 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
34610 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33  *xFinal)(sqlite3
34620 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 53 51  _context*).);.SQ
34630 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
34640 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
34650 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65  tion16(.  sqlite
34660 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 76  3 *db,.  const v
34670 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61  oid *zFunctionNa
34680 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a  me,.  int nArg,.
34690 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a    int eTextRep,.
346a0 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20    void *pApp,.  
346b0 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71  void (*xFunc)(sq
346c0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
346d0 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
346e0 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53  **),.  void (*xS
346f0 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  tep)(sqlite3_con
34700 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
34710 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
34720 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c  id (*xFinal)(sql
34730 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29  ite3_context*).)
34740 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
34750 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
34760 66 75 6e 63 74 69 6f 6e 5f 76 32 28 0a 20 20 73  function_v2(.  s
34770 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f  qlite3 *db,.  co
34780 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74  nst char *zFunct
34790 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e  ionName,.  int n
347a0 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74  Arg,.  int eText
347b0 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70  Rep,.  void *pAp
347c0 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e  p,.  void (*xFun
347d0 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  c)(sqlite3_conte
347e0 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
347f0 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
34800 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65   (*xStep)(sqlite
34810 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
34820 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
34830 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c  .  void (*xFinal
34840 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
34850 74 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65  t*),.  void(*xDe
34860 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b  stroy)(void*).);
34870 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
34880 3a 20 54 65 78 74 20 45 6e 63 6f 64 69 6e 67 73  : Text Encodings
34890 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
348a0 73 74 61 6e 74 20 64 65 66 69 6e 65 20 69 6e 74  stant define int
348b0 65 67 65 72 20 63 6f 64 65 73 20 74 68 61 74 20  eger codes that 
348c0 72 65 70 72 65 73 65 6e 74 20 74 68 65 20 76 61  represent the va
348d0 72 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e  rious.** text en
348e0 63 6f 64 69 6e 67 73 20 73 75 70 70 6f 72 74 65  codings supporte
348f0 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  d by SQLite..*/.
34900 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
34910 54 46 38 20 20 20 20 20 20 20 20 20 20 20 31 0a  TF8           1.
34920 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
34930 54 46 31 36 4c 45 20 20 20 20 20 20 20 20 32 0a  TF16LE        2.
34940 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
34950 54 46 31 36 42 45 20 20 20 20 20 20 20 20 33 0a  TF16BE        3.
34960 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
34970 54 46 31 36 20 20 20 20 20 20 20 20 20 20 34 20  TF16          4 
34980 20 20 20 2f 2a 20 55 73 65 20 6e 61 74 69 76 65     /* Use native
34990 20 62 79 74 65 20 6f 72 64 65 72 20 2a 2f 0a 23   byte order */.#
349a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e  define SQLITE_AN
349b0 59 20 20 20 20 20 20 20 20 20 20 20 20 35 20 20  Y            5  
349c0 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65    /* sqlite3_cre
349d0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 20 6f 6e 6c  ate_function onl
349e0 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
349f0 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45  ITE_UTF16_ALIGNE
34a00 44 20 20 38 20 20 20 20 2f 2a 20 73 71 6c 69 74  D  8    /* sqlit
34a10 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
34a20 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a  ion only */../*.
34a30 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 70  ** CAPI3REF: Dep
34a40 72 65 63 61 74 65 64 20 46 75 6e 63 74 69 6f 6e  recated Function
34a50 73 0a 2a 2a 20 44 45 50 52 45 43 41 54 45 44 0a  s.** DEPRECATED.
34a60 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63  **.** These func
34a70 74 69 6f 6e 73 20 61 72 65 20 5b 64 65 70 72 65  tions are [depre
34a80 63 61 74 65 64 5d 2e 20 20 49 6e 20 6f 72 64 65  cated].  In orde
34a90 72 20 74 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a  r to maintain.**
34aa0 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
34ab0 74 69 62 69 6c 69 74 79 20 77 69 74 68 20 6f 6c  tibility with ol
34ac0 64 65 72 20 63 6f 64 65 2c 20 74 68 65 73 65 20  der code, these 
34ad0 66 75 6e 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e  functions contin
34ae0 75 65 20 0a 2a 2a 20 74 6f 20 62 65 20 73 75 70  ue .** to be sup
34af0 70 6f 72 74 65 64 2e 20 20 48 6f 77 65 76 65 72  ported.  However
34b00 2c 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f  , new applicatio
34b10 6e 73 20 73 68 6f 75 6c 64 20 61 76 6f 69 64 0a  ns should avoid.
34b20 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20 74 68  ** the use of th
34b30 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20  ese functions.  
34b40 54 6f 20 68 65 6c 70 20 65 6e 63 6f 75 72 61 67  To help encourag
34b50 65 20 70 65 6f 70 6c 65 20 74 6f 20 61 76 6f 69  e people to avoi
34b60 64 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65 73 65  d.** using these
34b70 20 66 75 6e 63 74 69 6f 6e 73 2c 20 77 65 20 61   functions, we a
34b80 72 65 20 6e 6f 74 20 67 6f 69 6e 67 20 74 6f 20  re not going to 
34b90 74 65 6c 6c 20 79 6f 75 20 77 68 61 74 20 74 68  tell you what th
34ba0 65 79 20 64 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65  ey do..*/.#ifnde
34bb0 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 44 45  f SQLITE_OMIT_DE
34bc0 50 52 45 43 41 54 45 44 0a 53 51 4c 49 54 45 5f  PRECATED.SQLITE_
34bd0 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45  API SQLITE_DEPRE
34be0 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65  CATED int sqlite
34bf0 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 75 6e  3_aggregate_coun
34c00 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t(sqlite3_contex
34c10 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  t*);.SQLITE_API 
34c20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
34c30 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78  D int sqlite3_ex
34c40 70 69 72 65 64 28 73 71 6c 69 74 65 33 5f 73 74  pired(sqlite3_st
34c50 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  mt*);.SQLITE_API
34c60 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54   SQLITE_DEPRECAT
34c70 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 74  ED int sqlite3_t
34c80 72 61 6e 73 66 65 72 5f 62 69 6e 64 69 6e 67 73  ransfer_bindings
34c90 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
34ca0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
34cb0 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54  SQLITE_API SQLIT
34cc0 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74  E_DEPRECATED int
34cd0 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f   sqlite3_global_
34ce0 72 65 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a 53  recover(void);.S
34cf0 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45  QLITE_API SQLITE
34d00 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f 69 64  _DEPRECATED void
34d10 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 5f   sqlite3_thread_
34d20 63 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a 53  cleanup(void);.S
34d30 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45  QLITE_API SQLITE
34d40 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20  _DEPRECATED int 
34d50 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61  sqlite3_memory_a
34d60 6c 61 72 6d 28 76 6f 69 64 28 2a 29 28 76 6f 69  larm(void(*)(voi
34d70 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  d*,sqlite3_int64
34d80 2c 69 6e 74 29 2c 76 6f 69 64 2a 2c 73 71 6c 69  ,int),void*,sqli
34d90 74 65 33 5f 69 6e 74 36 34 29 3b 0a 23 65 6e 64  te3_int64);.#end
34da0 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  if../*.** CAPI3R
34db0 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53 51  EF: Obtaining SQ
34dc0 4c 20 46 75 6e 63 74 69 6f 6e 20 50 61 72 61 6d  L Function Param
34dd0 65 74 65 72 20 56 61 6c 75 65 73 0a 2a 2a 0a 2a  eter Values.**.*
34de0 2a 20 54 68 65 20 43 2d 6c 61 6e 67 75 61 67 65  * The C-language
34df0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
34e00 6f 66 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  of SQL functions
34e10 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 20   and aggregates 
34e20 75 73 65 73 0a 2a 2a 20 74 68 69 73 20 73 65 74  uses.** this set
34e30 20 6f 66 20 69 6e 74 65 72 66 61 63 65 20 72 6f   of interface ro
34e40 75 74 69 6e 65 73 20 74 6f 20 61 63 63 65 73 73  utines to access
34e50 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 76   the parameter v
34e60 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74 68 65 20  alues on.** the 
34e70 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72  function or aggr
34e80 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  egate..**.** The
34e90 20 78 46 75 6e 63 20 28 66 6f 72 20 73 63 61 6c   xFunc (for scal
34ea0 61 72 20 66 75 6e 63 74 69 6f 6e 73 29 20 6f 72  ar functions) or
34eb0 20 78 53 74 65 70 20 28 66 6f 72 20 61 67 67 72   xStep (for aggr
34ec0 65 67 61 74 65 73 29 20 70 61 72 61 6d 65 74 65  egates) paramete
34ed0 72 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65  rs.** to [sqlite
34ee0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
34ef0 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  n()] and [sqlite
34f00 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
34f10 6e 31 36 28 29 5d 0a 2a 2a 20 64 65 66 69 6e 65  n16()].** define
34f20 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 20   callbacks that 
34f30 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51  implement the SQ
34f40 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20  L functions and 
34f50 61 67 67 72 65 67 61 74 65 73 2e 0a 2a 2a 20 54  aggregates..** T
34f60 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  he 3rd parameter
34f70 20 74 6f 20 74 68 65 73 65 20 63 61 6c 6c 62 61   to these callba
34f80 63 6b 73 20 69 73 20 61 6e 20 61 72 72 61 79 20  cks is an array 
34f90 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 0a 2a  of pointers to.*
34fa0 2a 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  * [protected sql
34fb0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
34fc0 63 74 73 2e 20 20 54 68 65 72 65 20 69 73 20 6f  cts.  There is o
34fd0 6e 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ne [sqlite3_valu
34fe0 65 5d 20 6f 62 6a 65 63 74 20 66 6f 72 0a 2a 2a  e] object for.**
34ff0 20 65 61 63 68 20 70 61 72 61 6d 65 74 65 72 20   each parameter 
35000 74 6f 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  to the SQL funct
35010 69 6f 6e 2e 20 20 54 68 65 73 65 20 72 6f 75 74  ion.  These rout
35020 69 6e 65 73 20 61 72 65 20 75 73 65 64 20 74 6f  ines are used to
35030 0a 2a 2a 20 65 78 74 72 61 63 74 20 76 61 6c 75  .** extract valu
35040 65 73 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c  es from the [sql
35050 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
35060 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  cts..**.** These
35070 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6f   routines work o
35080 6e 6c 79 20 77 69 74 68 20 5b 70 72 6f 74 65 63  nly with [protec
35090 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
350a0 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 41  e] objects..** A
350b0 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73  ny attempt to us
350c0 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  e these routines
350d0 20 6f 6e 20 61 6e 20 5b 75 6e 70 72 6f 74 65 63   on an [unprotec
350e0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
350f0 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 73  e].** object res
35100 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65  ults in undefine
35110 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a  d behavior..**.*
35120 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
35130 73 20 77 6f 72 6b 20 6a 75 73 74 20 6c 69 6b 65  s work just like
35140 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
35150 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73  ng [column acces
35160 73 20 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a 20  s functions].** 
35170 65 78 63 65 70 74 20 74 68 61 74 20 20 74 68 65  except that  the
35180 73 65 20 72 6f 75 74 69 6e 65 73 20 74 61 6b 65  se routines take
35190 20 61 20 73 69 6e 67 6c 65 20 5b 70 72 6f 74 65   a single [prote
351a0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
351b0 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 6f  ue] object.** po
351c0 69 6e 74 65 72 20 69 6e 73 74 65 61 64 20 6f 66  inter instead of
351d0 20 61 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74   a [sqlite3_stmt
351e0 2a 5d 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 61  *] pointer and a
351f0 6e 20 69 6e 74 65 67 65 72 20 63 6f 6c 75 6d 6e  n integer column
35200 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e   number..**.** ^
35210 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  The sqlite3_valu
35220 65 5f 74 65 78 74 31 36 28 29 20 69 6e 74 65 72  e_text16() inter
35230 66 61 63 65 20 65 78 74 72 61 63 74 73 20 61 20  face extracts a 
35240 55 54 46 2d 31 36 20 73 74 72 69 6e 67 0a 2a 2a  UTF-16 string.**
35250 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62   in the native b
35260 79 74 65 2d 6f 72 64 65 72 20 6f 66 20 74 68 65  yte-order of the
35270 20 68 6f 73 74 20 6d 61 63 68 69 6e 65 2e 20 20   host machine.  
35280 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ^The.** sqlite3_
35290 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 29  value_text16be()
352a0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 61 6c   and sqlite3_val
352b0 75 65 5f 74 65 78 74 31 36 6c 65 28 29 20 69 6e  ue_text16le() in
352c0 74 65 72 66 61 63 65 73 0a 2a 2a 20 65 78 74 72  terfaces.** extr
352d0 61 63 74 20 55 54 46 2d 31 36 20 73 74 72 69 6e  act UTF-16 strin
352e0 67 73 20 61 73 20 62 69 67 2d 65 6e 64 69 61 6e  gs as big-endian
352f0 20 61 6e 64 20 6c 69 74 74 6c 65 2d 65 6e 64 69   and little-endi
35300 61 6e 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  an respectively.
35310 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c  .**.** ^(The sql
35320 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72  ite3_value_numer
35330 69 63 5f 74 79 70 65 28 29 20 69 6e 74 65 72 66  ic_type() interf
35340 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20  ace attempts to 
35350 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69 63  apply.** numeric
35360 20 61 66 66 69 6e 69 74 79 20 74 6f 20 74 68 65   affinity to the
35370 20 76 61 6c 75 65 2e 20 20 54 68 69 73 20 6d 65   value.  This me
35380 61 6e 73 20 74 68 61 74 20 61 6e 20 61 74 74 65  ans that an atte
35390 6d 70 74 20 69 73 0a 2a 2a 20 6d 61 64 65 20 74  mpt is.** made t
353a0 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61  o convert the va
353b0 6c 75 65 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  lue to an intege
353c0 72 20 6f 72 20 66 6c 6f 61 74 69 6e 67 20 70 6f  r or floating po
353d0 69 6e 74 2e 20 20 49 66 0a 2a 2a 20 73 75 63 68  int.  If.** such
353e0 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73   a conversion is
353f0 20 70 6f 73 73 69 62 6c 65 20 77 69 74 68 6f 75   possible withou
35400 74 20 6c 6f 73 73 20 6f 66 20 69 6e 66 6f 72 6d  t loss of inform
35410 61 74 69 6f 6e 20 28 69 6e 20 6f 74 68 65 72 0a  ation (in other.
35420 2a 2a 20 77 6f 72 64 73 2c 20 69 66 20 74 68 65  ** words, if the
35430 20 76 61 6c 75 65 20 69 73 20 61 20 73 74 72 69   value is a stri
35440 6e 67 20 74 68 61 74 20 6c 6f 6f 6b 73 20 6c 69  ng that looks li
35450 6b 65 20 61 20 6e 75 6d 62 65 72 29 0a 2a 2a 20  ke a number).** 
35460 74 68 65 6e 20 74 68 65 20 63 6f 6e 76 65 72 73  then the convers
35470 69 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d 65 64  ion is performed
35480 2e 20 20 4f 74 68 65 72 77 69 73 65 20 6e 6f 20  .  Otherwise no 
35490 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72  conversion occur
354a0 73 2e 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  s..** The [SQLIT
354b0 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61  E_INTEGER | data
354c0 74 79 70 65 5d 20 61 66 74 65 72 20 63 6f 6e 76  type] after conv
354d0 65 72 73 69 6f 6e 20 69 73 20 72 65 74 75 72 6e  ersion is return
354e0 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61  ed.)^.**.** Plea
354f0 73 65 20 70 61 79 20 70 61 72 74 69 63 75 6c 61  se pay particula
35500 72 20 61 74 74 65 6e 74 69 6f 6e 20 74 6f 20 74  r attention to t
35510 68 65 20 66 61 63 74 20 74 68 61 74 20 74 68 65  he fact that the
35520 20 70 6f 69 6e 74 65 72 20 72 65 74 75 72 6e 65   pointer returne
35530 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74  d.** from [sqlit
35540 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 29 5d  e3_value_blob()]
35550 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  , [sqlite3_value
35560 5f 74 65 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20  _text()], or.** 
35570 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
35580 65 78 74 31 36 28 29 5d 20 63 61 6e 20 62 65 20  ext16()] can be 
35590 69 6e 76 61 6c 69 64 61 74 65 64 20 62 79 20 61  invalidated by a
355a0 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
355b0 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
355c0 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20  value_bytes()], 
355d0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
355e0 79 74 65 73 31 36 28 29 5d 2c 20 5b 73 71 6c 69  ytes16()], [sqli
355f0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29  te3_value_text()
35600 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65  ],.** or [sqlite
35610 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29  3_value_text16()
35620 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  ]..**.** These r
35630 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20  outines must be 
35640 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
35650 73 61 6d 65 20 74 68 72 65 61 64 20 61 73 0a 2a  same thread as.*
35660 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  * the SQL functi
35670 6f 6e 20 74 68 61 74 20 73 75 70 70 6c 69 65 64  on that supplied
35680 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   the [sqlite3_va
35690 6c 75 65 2a 5d 20 70 61 72 61 6d 65 74 65 72 73  lue*] parameters
356a0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
356b0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
356c0 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73  te3_value_blob(s
356d0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
356e0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
356f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
35700 65 73 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  es(sqlite3_value
35710 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  *);.SQLITE_API i
35720 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt sqlite3_value
35730 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65 33  _bytes16(sqlite3
35740 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45  _value*);.SQLITE
35750 5f 41 50 49 20 64 6f 75 62 6c 65 20 73 71 6c 69  _API double sqli
35760 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65  te3_value_double
35770 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
35780 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
35790 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69   sqlite3_value_i
357a0 6e 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt(sqlite3_value
357b0 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73  *);.SQLITE_API s
357c0 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
357d0 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34  ite3_value_int64
357e0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
357f0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  ;.SQLITE_API con
35800 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72  st unsigned char
35810 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   *sqlite3_value_
35820 74 65 78 74 28 73 71 6c 69 74 65 33 5f 76 61 6c  text(sqlite3_val
35830 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ue*);.SQLITE_API
35840 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c   const void *sql
35850 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
35860 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  6(sqlite3_value*
35870 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
35880 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
35890 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65  3_value_text16le
358a0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
358b0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  ;.SQLITE_API con
358c0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
358d0 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28  _value_text16be(
358e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
358f0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
35900 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79  sqlite3_value_ty
35910 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  pe(sqlite3_value
35920 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  *);.SQLITE_API i
35930 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt sqlite3_value
35940 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 73 71  _numeric_type(sq
35950 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a  lite3_value*);..
35960 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
35970 4f 62 74 61 69 6e 20 41 67 67 72 65 67 61 74 65  Obtain Aggregate
35980 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78   Function Contex
35990 74 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c 65 6d 65 6e  t.**.** Implemen
359a0 74 61 74 69 6f 6e 73 20 6f 66 20 61 67 67 72 65  tations of aggre
359b0 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  gate SQL functio
359c0 6e 73 20 75 73 65 20 74 68 69 73 0a 2a 2a 20 72  ns use this.** r
359d0 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61  outine to alloca
359e0 74 65 20 6d 65 6d 6f 72 79 20 66 6f 72 20 73 74  te memory for st
359f0 6f 72 69 6e 67 20 74 68 65 69 72 20 73 74 61 74  oring their stat
35a00 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  e..**.** ^The fi
35a10 72 73 74 20 74 69 6d 65 20 74 68 65 20 73 71 6c  rst time the sql
35a20 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
35a30 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74  ontext(C,N) rout
35a40 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 0a 2a  ine is called .*
35a50 2a 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c  * for a particul
35a60 61 72 20 61 67 67 72 65 67 61 74 65 20 66 75 6e  ar aggregate fun
35a70 63 74 69 6f 6e 2c 20 53 51 4c 69 74 65 0a 2a 2a  ction, SQLite.**
35a80 20 61 6c 6c 6f 63 61 74 65 73 20 4e 20 6f 66 20   allocates N of 
35a90 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f 65 73 20 6f  memory, zeroes o
35aa0 75 74 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c 20  ut that memory, 
35ab0 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f  and returns a po
35ac0 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  inter.** to the 
35ad0 6e 65 77 20 6d 65 6d 6f 72 79 2e 20 5e 4f 6e 20  new memory. ^On 
35ae0 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65  second and subse
35af0 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a  quent calls to.*
35b00 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  * sqlite3_aggreg
35b10 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 66 6f  ate_context() fo
35b20 72 20 74 68 65 20 73 61 6d 65 20 61 67 67 72 65  r the same aggre
35b30 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e  gate function in
35b40 73 74 61 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 73  stance,.** the s
35b50 61 6d 65 20 62 75 66 66 65 72 20 69 73 20 72 65  ame buffer is re
35b60 74 75 72 6e 65 64 2e 20 20 53 71 6c 69 74 65 33  turned.  Sqlite3
35b70 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
35b80 78 74 28 29 20 69 73 20 6e 6f 72 6d 61 6c 6c 79  xt() is normally
35b90 0a 2a 2a 20 63 61 6c 6c 65 64 20 6f 6e 63 65 20  .** called once 
35ba0 66 6f 72 20 65 61 63 68 20 69 6e 76 6f 63 61 74  for each invocat
35bb0 69 6f 6e 20 6f 66 20 74 68 65 20 78 53 74 65 70  ion of the xStep
35bc0 20 63 61 6c 6c 62 61 63 6b 20 61 6e 64 20 74 68   callback and th
35bd0 65 6e 20 6f 6e 65 0a 2a 2a 20 6c 61 73 74 20 74  en one.** last t
35be0 69 6d 65 20 77 68 65 6e 20 74 68 65 20 78 46 69  ime when the xFi
35bf0 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  nal callback is 
35c00 69 6e 76 6f 6b 65 64 2e 20 20 5e 28 57 68 65 6e  invoked.  ^(When
35c10 20 6e 6f 20 72 6f 77 73 20 6d 61 74 63 68 0a 2a   no rows match.*
35c20 2a 20 61 6e 20 61 67 67 72 65 67 61 74 65 20 71  * an aggregate q
35c30 75 65 72 79 2c 20 74 68 65 20 78 53 74 65 70 28  uery, the xStep(
35c40 29 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68  ) callback of th
35c50 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63  e aggregate func
35c60 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  tion.** implemen
35c70 74 61 74 69 6f 6e 20 69 73 20 6e 65 76 65 72 20  tation is never 
35c80 63 61 6c 6c 65 64 20 61 6e 64 20 78 46 69 6e 61  called and xFina
35c90 6c 28 29 20 69 73 20 63 61 6c 6c 65 64 20 65 78  l() is called ex
35ca0 61 63 74 6c 79 20 6f 6e 63 65 2e 0a 2a 2a 20 49  actly once..** I
35cb0 6e 20 74 68 6f 73 65 20 63 61 73 65 73 2c 20 73  n those cases, s
35cc0 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
35cd0 5f 63 6f 6e 74 65 78 74 28 29 20 6d 69 67 68 74  _context() might
35ce0 20 62 65 20 63 61 6c 6c 65 64 20 66 6f 72 20 74   be called for t
35cf0 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 69 6d 65  he.** first time
35d00 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 78 46 69   from within xFi
35d10 6e 61 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  nal().)^.**.** ^
35d20 54 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72  The sqlite3_aggr
35d30 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c  egate_context(C,
35d40 4e 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  N) routine retur
35d50 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ns a NULL pointe
35d60 72 20 69 66 20 4e 20 69 73 0a 2a 2a 20 6c 65 73  r if N is.** les
35d70 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20  s than or equal 
35d80 74 6f 20 7a 65 72 6f 20 6f 72 20 69 66 20 61 20  to zero or if a 
35d90 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65 20  memory allocate 
35da0 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a 2a 2a  error occurs..**
35db0 0a 2a 2a 20 5e 28 54 68 65 20 61 6d 6f 75 6e 74  .** ^(The amount
35dc0 20 6f 66 20 73 70 61 63 65 20 61 6c 6c 6f 63 61   of space alloca
35dd0 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 61  ted by sqlite3_a
35de0 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
35df0 28 43 2c 4e 29 20 69 73 0a 2a 2a 20 64 65 74 65  (C,N) is.** dete
35e00 72 6d 69 6e 65 64 20 62 79 20 74 68 65 20 4e 20  rmined by the N 
35e10 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 66 69 72  parameter on fir
35e20 73 74 20 73 75 63 63 65 73 73 66 75 6c 20 63 61  st successful ca
35e30 6c 6c 2e 20 20 43 68 61 6e 67 69 6e 67 20 74 68  ll.  Changing th
35e40 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 4e 20  e.** value of N 
35e50 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  in subsequent ca
35e60 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 61 67  ll to sqlite3_ag
35e70 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
35e80 29 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20  ) within.** the 
35e90 73 61 6d 65 20 61 67 67 72 65 67 61 74 65 20 66  same aggregate f
35ea0 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65  unction instance
35eb0 20 77 69 6c 6c 20 6e 6f 74 20 72 65 73 69 7a 65   will not resize
35ec0 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61   the memory.** a
35ed0 6c 6c 6f 63 61 74 69 6f 6e 2e 29 5e 0a 2a 2a 0a  llocation.)^.**.
35ee0 2a 2a 20 5e 53 51 4c 69 74 65 20 61 75 74 6f 6d  ** ^SQLite autom
35ef0 61 74 69 63 61 6c 6c 79 20 66 72 65 65 73 20 74  atically frees t
35f00 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
35f10 74 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74  ted by .** sqlit
35f20 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
35f30 74 65 78 74 28 29 20 77 68 65 6e 20 74 68 65 20  text() when the 
35f40 61 67 67 72 65 67 61 74 65 20 71 75 65 72 79 20  aggregate query 
35f50 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a  concludes..**.**
35f60 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   The first param
35f70 65 74 65 72 20 6d 75 73 74 20 62 65 20 61 20 63  eter must be a c
35f80 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73  opy of the.** [s
35f90 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c  qlite3_context |
35fa0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f   SQL function co
35fb0 6e 74 65 78 74 5d 20 74 68 61 74 20 69 73 20 74  ntext] that is t
35fc0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
35fd0 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 78 53 74  er.** to the xSt
35fe0 65 70 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c  ep or xFinal cal
35ff0 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 74 68  lback routine th
36000 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68  at implements th
36010 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a 20 66  e aggregate.** f
36020 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54  unction..**.** T
36030 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74  his routine must
36040 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
36050 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20  the same thread 
36060 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20  in which.** the 
36070 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75  aggregate SQL fu
36080 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e  nction is runnin
36090 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  g..*/.SQLITE_API
360a0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 61   void *sqlite3_a
360b0 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
360c0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
360d0 2a 2c 20 69 6e 74 20 6e 42 79 74 65 73 29 3b 0a  *, int nBytes);.
360e0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
360f0 20 55 73 65 72 20 44 61 74 61 20 46 6f 72 20 46   User Data For F
36100 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e  unctions.**.** ^
36110 54 68 65 20 73 71 6c 69 74 65 33 5f 75 73 65 72  The sqlite3_user
36120 5f 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63  _data() interfac
36130 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79  e returns a copy
36140 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74   of.** the point
36150 65 72 20 74 68 61 74 20 77 61 73 20 74 68 65 20  er that was the 
36160 70 55 73 65 72 44 61 74 61 20 70 61 72 61 6d 65  pUserData parame
36170 74 65 72 20 28 74 68 65 20 35 74 68 20 70 61 72  ter (the 5th par
36180 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68  ameter).** of th
36190 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  e [sqlite3_creat
361a0 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a  e_function()].**
361b0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72   and [sqlite3_cr
361c0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
361d0 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74  )] routines that
361e0 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72   originally.** r
361f0 65 67 69 73 74 65 72 65 64 20 74 68 65 20 61 70  egistered the ap
36200 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65  plication define
36210 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a  d function..**.*
36220 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d  * This routine m
36230 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72  ust be called fr
36240 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65  om the same thre
36250 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74  ad in which.** t
36260 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
36270 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
36280 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53  is running..*/.S
36290 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a  QLITE_API void *
362a0 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74  sqlite3_user_dat
362b0 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  a(sqlite3_contex
362c0 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
362d0 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43  3REF: Database C
362e0 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46 75  onnection For Fu
362f0 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54  nctions.**.** ^T
36300 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  he sqlite3_conte
36310 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20 69  xt_db_handle() i
36320 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
36330 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68   a copy of.** th
36340 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  e pointer to the
36350 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
36360 63 74 69 6f 6e 5d 20 28 74 68 65 20 31 73 74 20  ction] (the 1st 
36370 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66  parameter).** of
36380 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72   the [sqlite3_cr
36390 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
363a0 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
363b0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
363c0 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74  16()] routines t
363d0 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a  hat originally.*
363e0 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65  * registered the
363f0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66   application def
36400 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  ined function..*
36410 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c  /.SQLITE_API sql
36420 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 63 6f  ite3 *sqlite3_co
36430 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28  ntext_db_handle(
36440 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
36450 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
36460 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75 78  EF: Function Aux
36470 69 6c 69 61 72 79 20 44 61 74 61 0a 2a 2a 0a 2a  iliary Data.**.*
36480 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  * The following 
36490 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61  two functions ma
364a0 79 20 62 65 20 75 73 65 64 20 62 79 20 73 63 61  y be used by sca
364b0 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  lar SQL function
364c0 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74  s to.** associat
364d0 65 20 6d 65 74 61 64 61 74 61 20 77 69 74 68 20  e metadata with 
364e0 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e  argument values.
364f0 20 49 66 20 74 68 65 20 73 61 6d 65 20 76 61 6c   If the same val
36500 75 65 20 69 73 20 70 61 73 73 65 64 20 74 6f 0a  ue is passed to.
36510 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f  ** multiple invo
36520 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  cations of the s
36530 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ame SQL function
36540 20 64 75 72 69 6e 67 20 71 75 65 72 79 20 65 78   during query ex
36550 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a  ecution, under.*
36560 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d 73 74 61  * some circumsta
36570 6e 63 65 73 20 74 68 65 20 61 73 73 6f 63 69 61  nces the associa
36580 74 65 64 20 6d 65 74 61 64 61 74 61 20 6d 61 79  ted metadata may
36590 20 62 65 20 70 72 65 73 65 72 76 65 64 2e 20 54   be preserved. T
365a0 68 69 73 20 6d 61 79 0a 2a 2a 20 62 65 20 75 73  his may.** be us
365b0 65 64 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c  ed, for example,
365c0 20 74 6f 20 61 64 64 20 61 20 72 65 67 75 6c 61   to add a regula
365d0 72 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d 61 74  r-expression mat
365e0 63 68 69 6e 67 20 73 63 61 6c 61 72 0a 2a 2a 20  ching scalar.** 
365f0 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f  function. The co
36600 6d 70 69 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f  mpiled version o
36610 66 20 74 68 65 20 72 65 67 75 6c 61 72 20 65 78  f the regular ex
36620 70 72 65 73 73 69 6f 6e 20 69 73 20 73 74 6f 72  pression is stor
36630 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61 64 61 74  ed as.** metadat
36640 61 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  a associated wit
36650 68 20 74 68 65 20 53 51 4c 20 76 61 6c 75 65 20  h the SQL value 
36660 70 61 73 73 65 64 20 61 73 20 74 68 65 20 72 65  passed as the re
36670 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e  gular expression
36680 0a 2a 2a 20 70 61 74 74 65 72 6e 2e 20 20 54 68  .** pattern.  Th
36690 65 20 63 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c  e compiled regul
366a0 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61  ar expression ca
366b0 6e 20 62 65 20 72 65 75 73 65 64 20 6f 6e 20 6d  n be reused on m
366c0 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63  ultiple.** invoc
366d0 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61  ations of the sa
366e0 6d 65 20 66 75 6e 63 74 69 6f 6e 20 73 6f 20 74  me function so t
366f0 68 61 74 20 74 68 65 20 6f 72 69 67 69 6e 61 6c  hat the original
36700 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67 0a   pattern string.
36710 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  ** does not need
36720 20 74 6f 20 62 65 20 72 65 63 6f 6d 70 69 6c 65   to be recompile
36730 64 20 6f 6e 20 65 61 63 68 20 69 6e 76 6f 63 61  d on each invoca
36740 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  tion..**.** ^The
36750 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78   sqlite3_get_aux
36760 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65  data() interface
36770 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
36780 65 72 20 74 6f 20 74 68 65 20 6d 65 74 61 64 61  er to the metada
36790 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64  ta.** associated
367a0 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f   by the sqlite3_
367b0 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 66 75  set_auxdata() fu
367c0 6e 63 74 69 6f 6e 20 77 69 74 68 20 74 68 65 20  nction with the 
367d0 4e 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  Nth argument.** 
367e0 76 61 6c 75 65 20 74 6f 20 74 68 65 20 61 70 70  value to the app
367f0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
36800 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 49 66 20 6e   function. ^If n
36810 6f 20 6d 65 74 61 64 61 74 61 20 68 61 73 20 62  o metadata has b
36820 65 65 6e 20 65 76 65 72 0a 2a 2a 20 62 65 65 6e  een ever.** been
36830 20 73 65 74 20 66 6f 72 20 74 68 65 20 4e 74 68   set for the Nth
36840 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65   argument of the
36850 20 66 75 6e 63 74 69 6f 6e 2c 20 6f 72 20 69 66   function, or if
36860 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
36870 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70  ng.** function p
36880 61 72 61 6d 65 74 65 72 20 68 61 73 20 63 68 61  arameter has cha
36890 6e 67 65 64 20 73 69 6e 63 65 20 74 68 65 20 6d  nged since the m
368a0 65 74 61 2d 64 61 74 61 20 77 61 73 20 73 65 74  eta-data was set
368b0 2c 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74 65  ,.** then sqlite
368c0 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_get_auxdata() 
368d0 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70  returns a NULL p
368e0 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ointer..**.** ^T
368f0 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  he sqlite3_set_a
36900 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61  uxdata() interfa
36910 63 65 20 73 61 76 65 73 20 74 68 65 20 6d 65 74  ce saves the met
36920 61 64 61 74 61 0a 2a 2a 20 70 6f 69 6e 74 65 64  adata.** pointed
36930 20 74 6f 20 62 79 20 69 74 73 20 33 72 64 20 70   to by its 3rd p
36940 61 72 61 6d 65 74 65 72 20 61 73 20 74 68 65 20  arameter as the 
36950 6d 65 74 61 64 61 74 61 20 66 6f 72 20 74 68 65  metadata for the
36960 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e   N-th.** argumen
36970 74 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  t of the applica
36980 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
36990 63 74 69 6f 6e 2e 20 20 53 75 62 73 65 71 75 65  ction.  Subseque
369a0 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73  nt.** calls to s
369b0 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61  qlite3_get_auxda
369c0 74 61 28 29 20 6d 69 67 68 74 20 72 65 74 75 72  ta() might retur
369d0 6e 20 74 68 69 73 20 64 61 74 61 2c 20 69 66 20  n this data, if 
369e0 69 74 20 68 61 73 0a 2a 2a 20 6e 6f 74 20 62 65  it has.** not be
369f0 65 6e 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a  en destroyed..**
36a00 20 5e 49 66 20 69 74 20 69 73 20 6e 6f 74 20 4e   ^If it is not N
36a10 55 4c 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c  ULL, SQLite will
36a20 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74   invoke the dest
36a30 72 75 63 74 6f 72 0a 2a 2a 20 66 75 6e 63 74 69  ructor.** functi
36a40 6f 6e 20 67 69 76 65 6e 20 62 79 20 74 68 65 20  on given by the 
36a50 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
36a60 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
36a70 64 61 74 61 28 29 20 6f 6e 0a 2a 2a 20 74 68 65  data() on.** the
36a80 20 6d 65 74 61 64 61 74 61 20 77 68 65 6e 20 74   metadata when t
36a90 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
36aa0 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65   function parame
36ab0 74 65 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20 6f  ter changes.** o
36ac0 72 20 77 68 65 6e 20 74 68 65 20 53 51 4c 20 73  r when the SQL s
36ad0 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 6c 65 74  tatement complet
36ae0 65 73 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f  es, whichever co
36af0 6d 65 73 20 66 69 72 73 74 2e 0a 2a 2a 0a 2a 2a  mes first..**.**
36b00 20 53 51 4c 69 74 65 20 69 73 20 66 72 65 65 20   SQLite is free 
36b10 74 6f 20 63 61 6c 6c 20 74 68 65 20 64 65 73 74  to call the dest
36b20 72 75 63 74 6f 72 20 61 6e 64 20 64 72 6f 70 20  ructor and drop 
36b30 6d 65 74 61 64 61 74 61 20 6f 6e 20 61 6e 79 0a  metadata on any.
36b40 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  ** parameter of 
36b50 61 6e 79 20 66 75 6e 63 74 69 6f 6e 20 61 74 20  any function at 
36b60 61 6e 79 20 74 69 6d 65 2e 20 20 5e 54 68 65 20  any time.  ^The 
36b70 6f 6e 6c 79 20 67 75 61 72 61 6e 74 65 65 20 69  only guarantee i
36b80 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 64 65  s that.** the de
36b90 73 74 72 75 63 74 6f 72 20 77 69 6c 6c 20 62 65  structor will be
36ba0 20 63 61 6c 6c 65 64 20 62 65 66 6f 72 65 20 74   called before t
36bb0 68 65 20 6d 65 74 61 64 61 74 61 20 69 73 20 64  he metadata is d
36bc0 72 6f 70 70 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ropped..**.** ^(
36bd0 49 6e 20 70 72 61 63 74 69 63 65 2c 20 6d 65 74  In practice, met
36be0 61 64 61 74 61 20 69 73 20 70 72 65 73 65 72 76  adata is preserv
36bf0 65 64 20 62 65 74 77 65 65 6e 20 66 75 6e 63 74  ed between funct
36c00 69 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a  ion calls for.**
36c10 20 65 78 70 72 65 73 73 69 6f 6e 73 20 74 68 61   expressions tha
36c20 74 20 61 72 65 20 63 6f 6e 73 74 61 6e 74 20 61  t are constant a
36c30 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20  t compile time. 
36c40 54 68 69 73 20 69 6e 63 6c 75 64 65 73 20 6c 69  This includes li
36c50 74 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73 20  teral.** values 
36c60 61 6e 64 20 5b 70 61 72 61 6d 65 74 65 72 73 5d  and [parameters]
36c70 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  .)^.**.** These 
36c80 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65  routines must be
36c90 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
36ca0 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20   same thread in 
36cb0 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 53 51 4c  which.** the SQL
36cc0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
36cd0 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  ning..*/.SQLITE_
36ce0 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  API void *sqlite
36cf0 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 73 71  3_get_auxdata(sq
36d00 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
36d10 69 6e 74 20 4e 29 3b 0a 53 51 4c 49 54 45 5f 41  int N);.SQLITE_A
36d20 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  PI void sqlite3_
36d30 73 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69  set_auxdata(sqli
36d40 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
36d50 74 20 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f 69 64  t N, void*, void
36d60 20 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a   (*)(void*));...
36d70 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
36d80 43 6f 6e 73 74 61 6e 74 73 20 44 65 66 69 6e 69  Constants Defini
36d90 6e 67 20 53 70 65 63 69 61 6c 20 44 65 73 74 72  ng Special Destr
36da0 75 63 74 6f 72 20 42 65 68 61 76 69 6f 72 0a 2a  uctor Behavior.*
36db0 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 73  *.** These are s
36dc0 70 65 63 69 61 6c 20 76 61 6c 75 65 73 20 66 6f  pecial values fo
36dd0 72 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  r the destructor
36de0 20 74 68 61 74 20 69 73 20 70 61 73 73 65 64 20   that is passed 
36df0 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66 69 6e  in as the.** fin
36e00 61 6c 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 72  al argument to r
36e10 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71  outines like [sq
36e20 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
36e30 62 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 20 64  b()].  ^If the d
36e40 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67  estructor.** arg
36e50 75 6d 65 6e 74 20 69 73 20 53 51 4c 49 54 45 5f  ument is SQLITE_
36e60 53 54 41 54 49 43 2c 20 69 74 20 6d 65 61 6e 73  STATIC, it means
36e70 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e   that the conten
36e80 74 20 70 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e  t pointer is con
36e90 73 74 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c  stant.** and wil
36ea0 6c 20 6e 65 76 65 72 20 63 68 61 6e 67 65 2e 20  l never change. 
36eb0 20 49 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65   It does not nee
36ec0 64 20 74 6f 20 62 65 20 64 65 73 74 72 6f 79 65  d to be destroye
36ed0 64 2e 20 20 5e 54 68 65 0a 2a 2a 20 53 51 4c 49  d.  ^The.** SQLI
36ee0 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 76 61 6c  TE_TRANSIENT val
36ef0 75 65 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  ue means that th
36f00 65 20 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 6c  e content will l
36f10 69 6b 65 6c 79 20 63 68 61 6e 67 65 20 69 6e 0a  ikely change in.
36f20 2a 2a 20 74 68 65 20 6e 65 61 72 20 66 75 74 75  ** the near futu
36f30 72 65 20 61 6e 64 20 74 68 61 74 20 53 51 4c 69  re and that SQLi
36f40 74 65 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20 69  te should make i
36f50 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63  ts own private c
36f60 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f  opy of.** the co
36f70 6e 74 65 6e 74 20 62 65 66 6f 72 65 20 72 65 74  ntent before ret
36f80 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68  urning..**.** Th
36f90 65 20 74 79 70 65 64 65 66 20 69 73 20 6e 65 63  e typedef is nec
36fa0 65 73 73 61 72 79 20 74 6f 20 77 6f 72 6b 20 61  essary to work a
36fb0 72 6f 75 6e 64 20 70 72 6f 62 6c 65 6d 73 20 69  round problems i
36fc0 6e 20 63 65 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b  n certain.** C++
36fd0 20 63 6f 6d 70 69 6c 65 72 73 2e 20 20 53 65 65   compilers.  See
36fe0 20 74 69 63 6b 65 74 20 23 32 31 39 31 2e 0a 2a   ticket #2191..*
36ff0 2f 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20 28  /.typedef void (
37000 2a 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63  *sqlite3_destruc
37010 74 6f 72 5f 74 79 70 65 29 28 76 6f 69 64 2a 29  tor_type)(void*)
37020 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ;.#define SQLITE
37030 5f 53 54 41 54 49 43 20 20 20 20 20 20 28 28 73  _STATIC      ((s
37040 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f  qlite3_destructo
37050 72 5f 74 79 70 65 29 30 29 0a 23 64 65 66 69 6e  r_type)0).#defin
37060 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45  e SQLITE_TRANSIE
37070 4e 54 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64  NT   ((sqlite3_d
37080 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 2d  estructor_type)-
37090 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  1)../*.** CAPI3R
370a0 45 46 3a 20 53 65 74 74 69 6e 67 20 54 68 65 20  EF: Setting The 
370b0 52 65 73 75 6c 74 20 4f 66 20 41 6e 20 53 51 4c  Result Of An SQL
370c0 20 46 75 6e 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20   Function.**.** 
370d0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
370e0 72 65 20 75 73 65 64 20 62 79 20 74 68 65 20 78  re used by the x
370f0 46 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20 63  Func or xFinal c
37100 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a  allbacks that.**
37110 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66   implement SQL f
37120 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67  unctions and agg
37130 72 65 67 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a  regates.  See.**
37140 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
37150 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64  _function()] and
37160 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
37170 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a  _function16()].*
37180 2a 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  * for additional
37190 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
371a0 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69  .** These functi
371b0 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79 20 6d 75  ons work very mu
371c0 63 68 20 6c 69 6b 65 20 74 68 65 20 5b 70 61 72  ch like the [par
371d0 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 5d 20  ameter binding] 
371e0 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e  family of.** fun
371f0 63 74 69 6f 6e 73 20 75 73 65 64 20 74 6f 20 62  ctions used to b
37200 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 68 6f  ind values to ho
37210 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e  st parameters in
37220 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
37230 65 6e 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74  ents..** Refer t
37240 6f 20 74 68 65 20 5b 53 51 4c 20 70 61 72 61 6d  o the [SQL param
37250 65 74 65 72 5d 20 64 6f 63 75 6d 65 6e 74 61 74  eter] documentat
37260 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  ion for addition
37270 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  al information..
37280 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
37290 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29  e3_result_blob()
372a0 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
372b0 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a  the result from.
372c0 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  ** an applicatio
372d0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
372e0 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 42 4c 4f  on to be the BLO
372f0 42 20 77 68 6f 73 65 20 63 6f 6e 74 65 6e 74 20  B whose content 
37300 69 73 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f  is pointed.** to
37310 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 70   by the second p
37320 61 72 61 6d 65 74 65 72 20 61 6e 64 20 77 68 69  arameter and whi
37330 63 68 20 69 73 20 4e 20 62 79 74 65 73 20 6c 6f  ch is N bytes lo
37340 6e 67 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  ng where N is th
37350 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d  e.** third param
37360 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  eter..**.** ^The
37370 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
37380 7a 65 72 6f 62 6c 6f 62 28 29 20 69 6e 74 65 72  zeroblob() inter
37390 66 61 63 65 73 20 73 65 74 20 74 68 65 20 72 65  faces set the re
373a0 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61  sult of.** the a
373b0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
373c0 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
373d0 65 20 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69 6e  e a BLOB contain
373e0 69 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20  ing all zero.** 
373f0 62 79 74 65 73 20 61 6e 64 20 4e 20 62 79 74 65  bytes and N byte
37400 73 20 69 6e 20 73 69 7a 65 2c 20 77 68 65 72 65  s in size, where
37410 20 4e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20   N is the value 
37420 6f 66 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  of the 2nd param
37430 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  eter..**.** ^The
37440 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
37450 64 6f 75 62 6c 65 28 29 20 69 6e 74 65 72 66 61  double() interfa
37460 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75  ce sets the resu
37470 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70  lt from.** an ap
37480 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
37490 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
374a0 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e   a floating poin
374b0 74 20 76 61 6c 75 65 20 73 70 65 63 69 66 69 65  t value specifie
374c0 64 0a 2a 2a 20 62 79 20 69 74 73 20 32 6e 64 20  d.** by its 2nd 
374d0 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
374e0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
374f0 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20  ult_error() and 
37500 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
37510 72 72 6f 72 31 36 28 29 20 66 75 6e 63 74 69 6f  rror16() functio
37520 6e 73 0a 2a 2a 20 63 61 75 73 65 20 74 68 65 20  ns.** cause the 
37530 69 6d 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20  implemented SQL 
37540 66 75 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f  function to thro
37550 77 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a  w an exception..
37560 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20  ** ^SQLite uses 
37570 74 68 65 20 73 74 72 69 6e 67 20 70 6f 69 6e 74  the string point
37580 65 64 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a 20  ed to by the.** 
37590 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66  2nd parameter of
375a0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
375b0 65 72 72 6f 72 28 29 20 6f 72 20 73 71 6c 69 74  error() or sqlit
375c0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
375d0 36 28 29 0a 2a 2a 20 61 73 20 74 68 65 20 74 65  6().** as the te
375e0 78 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d  xt of an error m
375f0 65 73 73 61 67 65 2e 20 20 5e 53 51 4c 69 74 65  essage.  ^SQLite
37600 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20   interprets the 
37610 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65  error.** message
37620 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c   string from sql
37630 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
37640 72 28 29 20 61 73 20 55 54 46 2d 38 2e 20 5e 53  r() as UTF-8. ^S
37650 51 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70 72  QLite.** interpr
37660 65 74 73 20 74 68 65 20 73 74 72 69 6e 67 20 66  ets the string f
37670 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75  rom sqlite3_resu
37680 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 61 73 20  lt_error16() as 
37690 55 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65  UTF-16 in native
376a0 0a 2a 2a 20 62 79 74 65 20 6f 72 64 65 72 2e 20  .** byte order. 
376b0 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 70   ^If the third p
376c0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
376d0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
376e0 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  ().** or sqlite3
376f0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
37700 29 20 69 73 20 6e 65 67 61 74 69 76 65 20 74 68  ) is negative th
37710 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20  en SQLite takes 
37720 61 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20  as the error.** 
37730 6d 65 73 73 61 67 65 20 61 6c 6c 20 74 65 78 74  message all text
37740 20 75 70 20 74 68 72 6f 75 67 68 20 74 68 65 20   up through the 
37750 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61  first zero chara
37760 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  cter..** ^If the
37770 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
37780 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75   to sqlite3_resu
37790 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 0a 2a 2a  lt_error() or.**
377a0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
377b0 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e 6f 6e  error16() is non
377c0 2d 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 53  -negative then S
377d0 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68 61 74  QLite takes that
377e0 20 6d 61 6e 79 0a 2a 2a 20 62 79 74 65 73 20 28   many.** bytes (
377f0 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 29 20  not characters) 
37800 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72  from the 2nd par
37810 61 6d 65 74 65 72 20 61 73 20 74 68 65 20 65 72  ameter as the er
37820 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 20  ror message..** 
37830 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
37840 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20  ult_error() and 
37850 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
37860 72 72 6f 72 31 36 28 29 0a 2a 2a 20 72 6f 75 74  rror16().** rout
37870 69 6e 65 73 20 6d 61 6b 65 20 61 20 70 72 69 76  ines make a priv
37880 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20  ate copy of the 
37890 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65  error message te
378a0 78 74 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65  xt before.** the
378b0 79 20 72 65 74 75 72 6e 2e 20 20 48 65 6e 63 65  y return.  Hence
378c0 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75  , the calling fu
378d0 6e 63 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c  nction can deall
378e0 6f 63 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69  ocate or.** modi
378f0 66 79 20 74 68 65 20 74 65 78 74 20 61 66 74 65  fy the text afte
37900 72 20 74 68 65 79 20 72 65 74 75 72 6e 20 77 69  r they return wi
37910 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e  thout harm..** ^
37920 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
37930 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 29 20  lt_error_code() 
37940 66 75 6e 63 74 69 6f 6e 20 63 68 61 6e 67 65 73  function changes
37950 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 0a   the error code.
37960 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 53  ** returned by S
37970 51 4c 69 74 65 20 61 73 20 61 20 72 65 73 75 6c  QLite as a resul
37980 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 69 6e  t of an error in
37990 20 61 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 42   a function.  ^B
379a0 79 20 64 65 66 61 75 6c 74 2c 0a 2a 2a 20 74 68  y default,.** th
379b0 65 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20  e error code is 
379c0 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20 5e  SQLITE_ERROR.  ^
379d0 41 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  A subsequent cal
379e0 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73  l to sqlite3_res
379f0 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f  ult_error().** o
37a00 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
37a10 5f 65 72 72 6f 72 31 36 28 29 20 72 65 73 65 74  _error16() reset
37a20 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65  s the error code
37a30 20 74 6f 20 53 51 4c 49 54 45 5f 45 52 52 4f 52   to SQLITE_ERROR
37a40 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
37a50 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
37a60 72 5f 74 6f 6f 62 69 67 28 29 20 69 6e 74 65 72  r_toobig() inter
37a70 66 61 63 65 20 63 61 75 73 65 73 20 53 51 4c 69  face causes SQLi
37a80 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 0a 2a  te to throw an.*
37a90 2a 20 65 72 72 6f 72 20 69 6e 64 69 63 61 74 69  * error indicati
37aa0 6e 67 20 74 68 61 74 20 61 20 73 74 72 69 6e 67  ng that a string
37ab0 20 6f 72 20 42 4c 4f 42 20 69 73 20 74 6f 6f 20   or BLOB is too 
37ac0 6c 6f 6e 67 20 74 6f 20 72 65 70 72 65 73 65 6e  long to represen
37ad0 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  t..**.** ^The sq
37ae0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
37af0 6f 72 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74 65 72  or_nomem() inter
37b00 66 61 63 65 20 63 61 75 73 65 73 20 53 51 4c 69  face causes SQLi
37b10 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 0a 2a  te to throw an.*
37b20 2a 20 65 72 72 6f 72 20 69 6e 64 69 63 61 74 69  * error indicati
37b30 6e 67 20 74 68 61 74 20 61 20 6d 65 6d 6f 72 79  ng that a memory
37b40 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c   allocation fail
37b50 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
37b60 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
37b70 74 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65  t() interface se
37b80 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  ts the return va
37b90 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70  lue.** of the ap
37ba0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
37bb0 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
37bc0 20 74 68 65 20 33 32 2d 62 69 74 20 73 69 67 6e   the 32-bit sign
37bd0 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61  ed integer.** va
37be0 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65  lue given in the
37bf0 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a   2nd argument..*
37c00 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
37c10 65 73 75 6c 74 5f 69 6e 74 36 34 28 29 20 69 6e  esult_int64() in
37c20 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
37c30 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a   return value.**
37c40 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
37c50 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
37c60 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 36  tion to be the 6
37c70 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74  4-bit signed int
37c80 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69  eger.** value gi
37c90 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61  ven in the 2nd a
37ca0 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e  rgument..**.** ^
37cb0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
37cc0 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e 74 65 72 66  lt_null() interf
37cd0 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74  ace sets the ret
37ce0 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20  urn value.** of 
37cf0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
37d00 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
37d10 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a   to be NULL..**.
37d20 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
37d30 72 65 73 75 6c 74 5f 74 65 78 74 28 29 2c 20 73  result_text(), s
37d40 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
37d50 78 74 31 36 28 29 2c 0a 2a 2a 20 73 71 6c 69 74  xt16(),.** sqlit
37d60 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
37d70 6c 65 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65  le(), and sqlite
37d80 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62  3_result_text16b
37d90 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  e() interfaces.*
37da0 2a 20 73 65 74 20 74 68 65 20 72 65 74 75 72 6e  * set the return
37db0 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 61 70   value of the ap
37dc0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
37dd0 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
37de0 0a 2a 2a 20 61 20 74 65 78 74 20 73 74 72 69 6e  .** a text strin
37df0 67 20 77 68 69 63 68 20 69 73 20 72 65 70 72 65  g which is repre
37e00 73 65 6e 74 65 64 20 61 73 20 55 54 46 2d 38 2c  sented as UTF-8,
37e10 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62   UTF-16 native b
37e20 79 74 65 20 6f 72 64 65 72 2c 0a 2a 2a 20 55 54  yte order,.** UT
37e30 46 2d 31 36 20 6c 69 74 74 6c 65 20 65 6e 64 69  F-16 little endi
37e40 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 62 69  an, or UTF-16 bi
37e50 67 20 65 6e 64 69 61 6e 2c 20 72 65 73 70 65 63  g endian, respec
37e60 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 53 51 4c 69  tively..** ^SQLi
37e70 74 65 20 74 61 6b 65 73 20 74 68 65 20 74 65 78  te takes the tex
37e80 74 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 74 68  t result from th
37e90 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 66 72  e application fr
37ea0 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e 64 20 70 61  om.** the 2nd pa
37eb0 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20 73  rameter of the s
37ec0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
37ed0 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 2e 0a  xt* interfaces..
37ee0 2a 2a 20 5e 49 66 20 74 68 65 20 33 72 64 20 70  ** ^If the 3rd p
37ef0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
37f00 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
37f10 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a  ext* interfaces.
37f20 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  ** is negative, 
37f30 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65  then SQLite take
37f40 73 20 72 65 73 75 6c 74 20 74 65 78 74 20 66 72  s result text fr
37f50 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  om the 2nd param
37f60 65 74 65 72 0a 2a 2a 20 74 68 72 6f 75 67 68 20  eter.** through 
37f70 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63  the first zero c
37f80 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66  haracter..** ^If
37f90 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74   the 3rd paramet
37fa0 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
37fb0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69  3_result_text* i
37fc0 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20  nterfaces.** is 
37fd0 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68  non-negative, th
37fe0 65 6e 20 61 73 20 6d 61 6e 79 20 62 79 74 65 73  en as many bytes
37ff0 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73   (not characters
38000 29 20 6f 66 20 74 68 65 20 74 65 78 74 0a 2a 2a  ) of the text.**
38010 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74   pointed to by t
38020 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
38030 20 61 72 65 20 74 61 6b 65 6e 20 61 73 20 74 68   are taken as th
38040 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
38050 66 69 6e 65 64 0a 2a 2a 20 66 75 6e 63 74 69 6f  fined.** functio
38060 6e 20 72 65 73 75 6c 74 2e 20 20 49 66 20 74 68  n result.  If th
38070 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  e 3rd parameter 
38080 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c  is non-negative,
38090 20 74 68 65 6e 20 69 74 0a 2a 2a 20 6d 75 73 74   then it.** must
380a0 20 62 65 20 74 68 65 20 62 79 74 65 20 6f 66 66   be the byte off
380b0 73 65 74 20 69 6e 74 6f 20 74 68 65 20 73 74 72  set into the str
380c0 69 6e 67 20 77 68 65 72 65 20 74 68 65 20 4e 55  ing where the NU
380d0 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f 75  L terminator wou
380e0 6c 64 0a 2a 2a 20 61 70 70 65 61 72 20 69 66 20  ld.** appear if 
380f0 74 68 65 20 73 74 72 69 6e 67 20 77 68 65 72 65  the string where
38100 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 65 64 2e   NUL terminated.
38110 20 20 49 66 20 61 6e 79 20 4e 55 4c 20 63 68 61    If any NUL cha
38120 72 61 63 74 65 72 73 20 6f 63 63 75 72 0a 2a 2a  racters occur.**
38130 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 20 61   in the string a
38140 74 20 61 20 62 79 74 65 20 6f 66 66 73 65 74 20  t a byte offset 
38150 74 68 61 74 20 69 73 20 6c 65 73 73 20 74 68 61  that is less tha
38160 6e 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  n the value of t
38170 68 65 20 33 72 64 0a 2a 2a 20 70 61 72 61 6d 65  he 3rd.** parame
38180 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 72 65  ter, then the re
38190 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 20 77  sulting string w
381a0 69 6c 6c 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65  ill contain embe
381b0 64 64 65 64 20 4e 55 4c 73 20 61 6e 64 20 74 68  dded NULs and th
381c0 65 0a 2a 2a 20 72 65 73 75 6c 74 20 6f 66 20 65  e.** result of e
381d0 78 70 72 65 73 73 69 6f 6e 73 20 6f 70 65 72 61  xpressions opera
381e0 74 69 6e 67 20 6f 6e 20 73 74 72 69 6e 67 73 20  ting on strings 
381f0 77 69 74 68 20 65 6d 62 65 64 64 65 64 20 4e 55  with embedded NU
38200 4c 73 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  Ls is undefined.
38210 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20  .** ^If the 4th 
38220 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
38230 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
38240 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
38250 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  .** or sqlite3_r
38260 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 61 20  esult_blob is a 
38270 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  non-NULL pointer
38280 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 63 61  , then SQLite ca
38290 6c 6c 73 20 74 68 61 74 0a 2a 2a 20 66 75 6e 63  lls that.** func
382a0 74 69 6f 6e 20 61 73 20 74 68 65 20 64 65 73 74  tion as the dest
382b0 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 74 65  ructor on the te
382c0 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c  xt or BLOB resul
382d0 74 20 77 68 65 6e 20 69 74 20 68 61 73 0a 2a 2a  t when it has.**
382e0 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20   finished using 
382f0 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20  that result..** 
38300 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61  ^If the 4th para
38310 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
38320 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
38330 2a 20 69 6e 74 65 72 66 61 63 65 73 20 6f 72 20  * interfaces or 
38340 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65  to.** sqlite3_re
38350 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65  sult_blob is the
38360 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e   special constan
38370 74 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c  t SQLITE_STATIC,
38380 20 74 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20   then SQLite.** 
38390 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65  assumes that the
383a0 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65   text or BLOB re
383b0 73 75 6c 74 20 69 73 20 69 6e 20 63 6f 6e 73 74  sult is in const
383c0 61 6e 74 20 73 70 61 63 65 20 61 6e 64 20 64 6f  ant space and do
383d0 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79 20 74  es not.** copy t
383e0 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
383f0 65 20 70 61 72 61 6d 65 74 65 72 20 6e 6f 72 20  e parameter nor 
38400 63 61 6c 6c 20 61 20 64 65 73 74 72 75 63 74 6f  call a destructo
38410 72 20 6f 6e 20 74 68 65 20 63 6f 6e 74 65 6e 74  r on the content
38420 0a 2a 2a 20 77 68 65 6e 20 69 74 20 68 61 73 20  .** when it has 
38430 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74  finished using t
38440 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e  hat result..** ^
38450 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d  If the 4th param
38460 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
38470 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
38480 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f   interfaces.** o
38490 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
384a0 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65  _blob is the spe
384b0 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51  cial constant SQ
384c0 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 0a 2a  LITE_TRANSIENT.*
384d0 2a 20 74 68 65 6e 20 53 51 4c 69 74 65 20 6d 61  * then SQLite ma
384e0 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  kes a copy of th
384f0 65 20 72 65 73 75 6c 74 20 69 6e 74 6f 20 73 70  e result into sp
38500 61 63 65 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ace obtained fro
38510 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74  m.** from [sqlit
38520 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 65 66  e3_malloc()] bef
38530 6f 72 65 20 69 74 20 72 65 74 75 72 6e 73 2e 0a  ore it returns..
38540 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
38550 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
38560 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
38570 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a   the result of.*
38580 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * the applicatio
38590 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
385a0 6f 6e 20 74 6f 20 62 65 20 61 20 63 6f 70 79 20  on to be a copy 
385b0 74 68 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63  the.** [unprotec
385c0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
385d0 65 5d 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66  e] object specif
385e0 69 65 64 20 62 79 20 74 68 65 20 32 6e 64 20 70  ied by the 2nd p
385f0 61 72 61 6d 65 74 65 72 2e 20 20 5e 54 68 65 0a  arameter.  ^The.
38600 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  ** sqlite3_resul
38610 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66  t_value() interf
38620 61 63 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79  ace makes a copy
38630 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
38640 5f 76 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74 68  _value].** so th
38650 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  at the [sqlite3_
38660 76 61 6c 75 65 5d 20 73 70 65 63 69 66 69 65 64  value] specified
38670 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65   in the paramete
38680 72 20 6d 61 79 20 63 68 61 6e 67 65 20 6f 72 0a  r may change or.
38690 2a 2a 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65  ** be deallocate
386a0 64 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f  d after sqlite3_
386b0 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 72  result_value() r
386c0 65 74 75 72 6e 73 20 77 69 74 68 6f 75 74 20 68  eturns without h
386d0 61 72 6d 2e 0a 2a 2a 20 5e 41 20 5b 70 72 6f 74  arm..** ^A [prot
386e0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
386f0 6c 75 65 5d 20 6f 62 6a 65 63 74 20 6d 61 79 20  lue] object may 
38700 61 6c 77 61 79 73 20 62 65 20 75 73 65 64 20 77  always be used w
38710 68 65 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72  here an.** [unpr
38720 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
38730 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 69 73  value] object is
38740 20 72 65 71 75 69 72 65 64 2c 20 73 6f 20 65 69   required, so ei
38750 74 68 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20  ther.** kind of 
38760 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20  [sqlite3_value] 
38770 6f 62 6a 65 63 74 20 63 61 6e 20 62 65 20 75 73  object can be us
38780 65 64 20 77 69 74 68 20 74 68 69 73 20 69 6e 74  ed with this int
38790 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66  erface..**.** If
387a0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
387b0 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20  are called from 
387c